chore: BlockAccessors Hardening & Improved Error Handling

* BlockAccessors are now Autocloseable
* BlockAccessors now create hard links for the duration of their
  lifespan
  * This allows us to ensure data is accessible for the duration of the
    accessor's life
* Tests are updated and migrated
* Deleted redundant configuration tests
* Added tests:
  * Tests for subsequent reads to ensure that closing an accessor does
    not affect the data or the ability for a new accessor to access it

Signed-off-by: Atanas Atanasov <a.v.atanasov98@gmail.com>

Author: ata-nas

block-node/app/src/test/resources/app-test.properties

@@ -1,8 +1,9 @@
 # SPDX-License-Identifier: Apache-2.0
-
 # Test Properties File
 prometheus.endpointEnabled=false
 mediator.ringBufferSize=1024
 notifier.ringBufferSize=1024
 files.recent.liveRootPath=build/tmp/data/liveRootPath
+files.recent.linksRootPath=build/tmp/data/liveLinks
 files.historic.rootPath=build/tmp/data/historic
+files.historic.linksRootPath=build/tmp/data/historicLinks

block-node/app/src/testFixtures/java/org/hiero/block/node/app/fixtures/blocks/InMemoryBlockAccessor.java

@@ -85,4 +85,7 @@ public Bytes blockBytes(final Format format) {
     private Bytes zstdCompressBytes(final Bytes bytes) {
         return Bytes.wrap(Zstd.compress(bytes.toByteArray()));
     }
+
+    @Override
+    public void close() {}
 }

block-node/app/src/testFixtures/java/org/hiero/block/node/app/fixtures/blocks/MinimalBlockAccessor.java

@@ -32,4 +32,7 @@ public Bytes blockBytes(final Format format) {
     private Bytes zstdCompressBytes(final Bytes bytes) {
         return Bytes.wrap(Zstd.compress(bytes.toByteArray()));
     }
+
+    @Override
+    public void close() {}
 }

block-node/base/src/main/java/org/hiero/block/node/base/tar/TaredBlockIterator.java

@@ -1,12 +1,14 @@
 // SPDX-License-Identifier: Apache-2.0
 package org.hiero.block.node.base.tar;
 
+import edu.umd.cs.findbugs.annotations.NonNull;
 import java.nio.charset.StandardCharsets;
 import java.text.DecimalFormat;
 import java.text.NumberFormat;
 import java.util.Arrays;
 import java.util.Iterator;
 import java.util.NoSuchElementException;
+import java.util.Objects;
 import org.hiero.block.node.spi.historicalblocks.BlockAccessor;
 import org.hiero.block.node.spi.historicalblocks.BlockAccessor.Format;
 
@@ -59,13 +61,14 @@ enum State {
      * @param format the format of the block data files written to the tar file
      * @param blockIterator the iterator over the blocks to be written into the tar file
      */
-    public TaredBlockIterator(Format format, Iterator<BlockAccessor> blockIterator) {
-        this.format = format;
+    public TaredBlockIterator(@NonNull final Format format, @NonNull final Iterator<BlockAccessor> blockIterator) {
+        this.format = Objects.requireNonNull(format);
         this.extension = switch (format) {
             case Format.JSON -> ".json";
             case Format.PROTOBUF -> ".blk";
-            case Format.ZSTD_PROTOBUF -> ".blk.zstd";};
-        this.blockIterator = blockIterator;
+            case Format.ZSTD_PROTOBUF -> ".blk.zstd";
+        };
+        this.blockIterator = Objects.requireNonNull(blockIterator);
         this.currentBuffer = new byte[CHUNK_SIZE];
         this.bufferPosition = 0;
     }
@@ -98,9 +101,13 @@ public byte[] next() {
                 case NEXT_FILE:
                     if (blockIterator.hasNext()) {
                         // get the next block from the iterator
-                        final BlockAccessor currentBlock = blockIterator.next();
-                        currentBlockBytes = currentBlock.blockBytes(format).toByteArray();
-                        currentBlockName = BLOCK_NUMBER_FORMAT.format(currentBlock.blockNumber()) + extension;
+                        final BlockAccessor currentBlockAccessor = blockIterator.next();
+                        currentBlockName = BLOCK_NUMBER_FORMAT.format(currentBlockAccessor.blockNumber()) + extension;
+                        currentBlockBytes =
+                                currentBlockAccessor.blockBytes(format).toByteArray();
+                        // close the accessor as we are done with it and we need
+                        // to free resources
+                        currentBlockAccessor.close();
                         filePosition = 0;
                         state = State.WRITE_HEADER;
                     } else {

block-node/block-access/src/main/java/org/hiero/block/node/access/service/BlockAccessServicePlugin.java

@@ -5,7 +5,6 @@
 import static java.lang.System.Logger.Level.INFO;
 import static java.lang.System.Logger.Level.TRACE;
 
-import com.hedera.hapi.block.stream.Block;
 import com.swirlds.metrics.api.Counter;
 import org.hiero.block.api.BlockAccessServiceInterface;
 import org.hiero.block.api.BlockRequest;
@@ -14,6 +13,7 @@
 import org.hiero.block.node.spi.BlockNodeContext;
 import org.hiero.block.node.spi.BlockNodePlugin;
 import org.hiero.block.node.spi.ServiceBuilder;
+import org.hiero.block.node.spi.historicalblocks.BlockAccessor;
 import org.hiero.block.node.spi.historicalblocks.HistoricalBlockFacility;
 
 /**
@@ -44,12 +44,10 @@ public class BlockAccessServicePlugin implements BlockNodePlugin, BlockAccessSer
      */
     public BlockResponse getBlock(BlockRequest request) {
         requestCounter.increment();
-
         try {
             long blockNumberToRetrieve;
             // The block number and retrieve latest are mutually exclusive in
             // the proto definition, so no need to check for that here.
-
             // if retrieveLatest is set, or the request is for the largest possible block number, get the latest block.
             if (request.hasBlockNumber() && request.blockNumber() >= 0) {
                 blockNumberToRetrieve = request.blockNumber();
@@ -63,7 +61,6 @@ public BlockResponse getBlock(BlockRequest request) {
                 LOGGER.log(INFO, "Invalid request, 'retrieve_latest' or a valid 'block number' is required.");
                 return new BlockResponse(Code.INVALID_REQUEST, null);
             }
-
             // Check if block is within the available range
             if (!blockProvider.availableBlocks().contains(blockNumberToRetrieve)) {
                 long lowestBlockNumber = blockProvider.availableBlocks().min();
@@ -77,14 +74,21 @@ public BlockResponse getBlock(BlockRequest request) {
                 responseCounterNotAvailable.increment();
                 return new BlockResponse(Code.NOT_AVAILABLE, null);
             }
-
             // Retrieve the block
-            Block block = blockProvider.block(blockNumberToRetrieve).block();
-            responseCounterSuccess.increment();
-            return new BlockResponse(Code.SUCCESS, block);
-
-        } catch (RuntimeException e) {
-            String message = "Failed to retrieve block number %d.".formatted(request.blockNumber());
+            try (final BlockAccessor accessor = blockProvider.block(blockNumberToRetrieve)) {
+                if (accessor != null) {
+                    // even though we have checked for the existence of the block
+                    // it may not be available anymore, so we have to ensure the accessor
+                    // still exists
+                    final BlockResponse response = new BlockResponse(Code.SUCCESS, accessor.block());
+                    responseCounterSuccess.increment();
+                    return response;
+                } else {
+                    return new BlockResponse(Code.NOT_FOUND, null);
+                }
+            }
+        } catch (final RuntimeException e) {
+            final String message = "Failed to retrieve block number %d.".formatted(request.blockNumber());
             LOGGER.log(ERROR, message, e);
             responseCounterNotFound.increment(); // Should this be a failure counter?
             return new BlockResponse(Code.NOT_FOUND, null);

block-node/block-providers/files.historic/src/main/java/org/hiero/block/node/blocks/files/historic/FilesHistoricConfig.java

@@ -6,15 +6,15 @@
 import com.swirlds.config.api.validation.annotation.Max;
 import com.swirlds.config.api.validation.annotation.Min;
 import java.nio.file.Path;
-import java.util.Objects;
-import org.hiero.block.common.utils.Preconditions;
 import org.hiero.block.node.base.CompressionType;
 import org.hiero.block.node.base.Loggable;
 
 /**
  * Use this configuration across the files recent plugin.
  *
  * @param rootPath provides the root path for saving historic blocks
+ * @param linksRootPath provides the root path for saving hard links when issuing
+ * accessors
  * @param compression compression type to use for the storage. It is assumed this never changes while a node is running
  * and has existing files.
  * @param powersOfTenPerZipFileContents the number files in a zip file specified in powers of ten. Can can be one of
@@ -30,16 +30,7 @@
 @ConfigData("files.historic")
 public record FilesHistoricConfig(
         @Loggable @ConfigProperty(defaultValue = "/opt/hiero/block-node/data/historic") Path rootPath,
+        @Loggable @ConfigProperty(defaultValue = "/opt/hiero/block-node/data/links") Path linksRootPath,
         @Loggable @ConfigProperty(defaultValue = "ZSTD") CompressionType compression,
         @Loggable @ConfigProperty(defaultValue = "4") @Min(1) @Max(6) int powersOfTenPerZipFileContents,
-        @Loggable @ConfigProperty(defaultValue = "0") long blockRetentionThreshold) {
-    /**
-     * Constructor.
-     */
-    public FilesHistoricConfig {
-        Objects.requireNonNull(rootPath);
-        Objects.requireNonNull(compression);
-        Preconditions.requireInRange(powersOfTenPerZipFileContents, 1, 6);
-        Preconditions.requireGreaterOrEqual(blockRetentionThreshold, 0L);
-    }
-}
+        @Loggable @ConfigProperty(defaultValue = "0") long blockRetentionThreshold) {}

block-node/block-providers/files.historic/src/main/java/org/hiero/block/node/blocks/files/historic/ZipBlockAccessor.java

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 package org.hiero.block.node.blocks.files.historic;
 
+import static java.lang.System.Logger.Level.INFO;
 import static java.lang.System.Logger.Level.WARNING;
 
 import com.hedera.hapi.block.stream.Block;
@@ -15,6 +16,7 @@
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.util.Objects;
+import java.util.UUID;
 import org.hiero.block.node.base.CompressionType;
 import org.hiero.block.node.spi.historicalblocks.BlockAccessor;
 
@@ -28,25 +30,44 @@ final class ZipBlockAccessor implements BlockAccessor {
     private static final String FAILED_TO_PARSE_MESSAGE = "Failed to parse block from file %s.";
     /** Message logged when data cannot be read from a block file */
     private static final String FAILED_TO_READ_MESSAGE = "Failed to read block from file %s.";
-    /** The block path. */
-    private final BlockPath blockPath;
+    /** Message logged when the provided path to a zip file is not a regular file or does not exist. */
+    private static final String INVALID_ZIP_FILE_PATH_MESSAGE =
+            "Provided path to zip file is not a regular file or does not exist: %s";
+    /** The block number. */
+    private final long blockNumber;
+    /** The compression type. */
+    private final CompressionType compressionType;
+    /** The zip entry name. */
+    private final String zipEntryName;
+    /** The zip path. */
+    private final Path zipFileLink;
 
     /**
      * Constructs a ZipBlockAccessor with the specified block path.
      *
      * @param blockPath the block path
+     * @param config the configuration for the block provider
      */
-    ZipBlockAccessor(@NonNull final BlockPath blockPath) {
-        this.blockPath = Objects.requireNonNull(blockPath);
+    ZipBlockAccessor(@NonNull final BlockPath blockPath, @NonNull final FilesHistoricConfig config) throws IOException {
+        this.blockNumber = Long.parseLong(blockPath.blockNumStr());
+        this.compressionType = blockPath.compressionType();
+        this.zipEntryName = blockPath.blockFileName();
+        final Path zipFilePath = blockPath.zipFilePath();
+        if (!Files.isRegularFile(zipFilePath)) {
+            final String msg = INVALID_ZIP_FILE_PATH_MESSAGE.formatted(zipFilePath);
+            throw new IOException(msg);
+        }
+        // create a hard link to the block file for the duration of the accessor's life
+        final Path link = config.linksRootPath().resolve(UUID.randomUUID().toString());
+        this.zipFileLink = Files.createLink(link, zipFilePath);
     }
 
     /**
      * {@inheritDoc}
      */
     @Override
     public long blockNumber() {
-        // TODO maybe there is nice option here than having to parse the string
-        return Long.parseLong(blockPath.blockNumStr());
+        return blockNumber;
     }
 
     /**
@@ -55,12 +76,11 @@ public long blockNumber() {
     @Override
     public Bytes blockBytes(@NonNull final Format format) {
         Objects.requireNonNull(format);
-        CompressionType compressionType = blockPath.compressionType();
-        try (final FileSystem zipFs = FileSystems.newFileSystem(blockPath.zipFilePath())) {
-            final Path entry = zipFs.getPath(blockPath.blockFileName());
+        try (final FileSystem zipFs = FileSystems.newFileSystem(zipFileLink)) {
+            final Path entry = zipFs.getPath(zipEntryName);
             return getBytesFromPath(format, entry, compressionType);
         } catch (final UncheckedIOException | IOException e) {
-            LOGGER.log(WARNING, FAILED_TO_READ_MESSAGE.formatted(blockPath), e);
+            LOGGER.log(WARNING, FAILED_TO_READ_MESSAGE.formatted(zipFileLink), e);
             return null;
         }
     }
@@ -112,12 +132,24 @@ private Bytes getJsonBytesFromProtobufBytes(final Bytes sourceData) {
             try {
                 return Block.JSON.toBytes(Block.PROTOBUF.parse(sourceData));
             } catch (final UncheckedIOException | ParseException e) {
-                final String message = FAILED_TO_PARSE_MESSAGE.formatted(blockPath);
+                final String message = FAILED_TO_PARSE_MESSAGE.formatted(zipFileLink);
                 LOGGER.log(WARNING, message, e);
                 return null;
             }
         } else {
             return null;
         }
     }
+
+    /**
+     * This method deletes the link to the zip file.
+     */
+    @Override
+    public void close() {
+        try {
+            Files.delete(zipFileLink);
+        } catch (final IOException e) {
+            LOGGER.log(INFO, "Failed to delete accessor link for block: {0}, path: {0}", blockNumber, zipFileLink);
+        }
+    }
 }

block-node/block-providers/files.historic/src/main/java/org/hiero/block/node/blocks/files/historic/ZipBlockArchive.java

@@ -2,6 +2,7 @@
 package org.hiero.block.node.blocks.files.historic;
 
 import static java.lang.System.Logger.Level.ERROR;
+import static java.lang.System.Logger.Level.INFO;
 import static java.lang.System.Logger.Level.WARNING;
 import static org.hiero.block.node.base.BlockFile.blockNumberFromFile;
 import static org.hiero.block.node.blocks.files.historic.BlockPath.computeBlockPath;
@@ -86,6 +87,9 @@ long writeNewZipFile(List<BlockAccessor> batch) throws IOException {
                 // it is here possible that the accessor will no longer be able to access the block
                 // because it is possible that the block has been deleted or has been moved
                 final Bytes bytes = blockAccessor.blockBytes(format);
+                // close the accessor as we are done with it and we need to free
+                // resources
+                blockAccessor.close();
                 // calculate CRC-32 checksum
                 final CRC32 crc = new CRC32();
                 crc.update(bytes.toByteArray());
@@ -121,11 +125,12 @@ long writeNewZipFile(List<BlockAccessor> batch) throws IOException {
      */
     BlockAccessor blockAccessor(long blockNumber) {
         try {
-            // get existing block path or null if we cannot find it
+            // get existing block path or null if we cannot find it or create accessor for
             final BlockPath blockPath = computeExistingBlockPath(config, blockNumber);
-            return blockPath == null ? null : new ZipBlockAccessor(blockPath);
+            return blockPath == null ? null : new ZipBlockAccessor(blockPath, config);
         } catch (final IOException e) {
-            throw new UncheckedIOException(e);
+            LOGGER.log(INFO, "Could not create zip block accessor", e);
+            return null;
         }
     }
 

block-node/block-providers/files.historic/src/test/java/org/hiero/block/node/blocks/files/historic/BlockFileHistoricPluginTest.java

@@ -53,8 +53,10 @@
  */
 @DisplayName("BlockFileHistoricPlugin Tests")
 class BlockFileHistoricPluginTest {
-    /** TempDir for the current test */
-    private final Path testTempDir;
+    /** Data TempDir for the current test */
+    private final Path dataRoot;
+    /** Links TempDir for the current test */
+    private final Path linksRoot;
     /** The test block messaging facility to use for testing. */
     private final SimpleInMemoryHistoricalBlockFacility testHistoricalBlockFacility;
     /** The test config to use for the plugin, overridable. */
@@ -65,13 +67,14 @@ class BlockFileHistoricPluginTest {
     /**
      * Construct test environment.
      */
-    BlockFileHistoricPluginTest(@TempDir final Path tempDir) {
-        this.testTempDir = Objects.requireNonNull(tempDir);
+    BlockFileHistoricPluginTest(@TempDir final Path dataRoot, @TempDir final Path linksRoot) {
+        this.dataRoot = Objects.requireNonNull(dataRoot);
+        this.linksRoot = Objects.requireNonNull(linksRoot);
         // generate test config, for the purposes of this test, we will always
         // use 10 blocks per zip, assuming that the first zip file will contain
         // for example blocks 0-9, the second zip file will contain blocks 10-19
         // also we will not use compression, and we will use the jUnit temp dir
-        testConfig = new FilesHistoricConfig(this.testTempDir, CompressionType.NONE, 1, 10L);
+        testConfig = new FilesHistoricConfig(this.dataRoot, this.linksRoot, CompressionType.NONE, 1, 10L);
         // build the plugin using the test environment
         toTest = new BlockFileHistoricPlugin();
         // initialize an in memory historical block facility to use for testing
@@ -159,14 +162,17 @@ final class PluginTests extends PluginTestBase<BlockFileHistoricPlugin, Blocking
         private Map<String, String> getConfigOverrides() {
             final Entry<String, String> rootPath =
                     Map.entry("files.historic.rootPath", testConfig.rootPath().toString());
+            final Entry<String, String> linksRootPath = Map.entry(
+                    "files.historic.linksRootPath", testConfig.linksRootPath().toString());
             final Entry<String, String> compression = Map.entry(
                     "files.historic.compression", testConfig.compression().name());
             final Entry<String, String> powersOfTenPerZipFileContents = Map.entry(
                     "files.historic.powersOfTenPerZipFileContents",
                     String.valueOf(testConfig.powersOfTenPerZipFileContents()));
             final Entry<String, String> blockRetentionThreshold = Map.entry(
                     "files.historic.blockRetentionThreshold", String.valueOf(testConfig.blockRetentionThreshold()));
-            return Map.ofEntries(rootPath, compression, powersOfTenPerZipFileContents, blockRetentionThreshold);
+            return Map.ofEntries(
+                    rootPath, linksRootPath, compression, powersOfTenPerZipFileContents, blockRetentionThreshold);
         }
 
         /**
@@ -942,7 +948,7 @@ void testRetentionPolicyThresholdHappyPath() throws IOException {
         @DisplayName("Test retention policy threshold disabled")
         void testRetentionPolicyThresholdDisabled() throws IOException {
             // change the retention policy to be disabled
-            testConfig = new FilesHistoricConfig(testTempDir, CompressionType.NONE, 1, 0L);
+            testConfig = new FilesHistoricConfig(dataRoot, linksRoot, CompressionType.NONE, 1, 0L);
             // override the config in the plugin
             start(toTest, testHistoricalBlockFacility, getConfigOverrides());
             // generate first 150 blocks from numbers 0-149 and add them to the