|
| 1 | +# Block As Local File Persistence E2E Test Plan |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +`Block As Local File Persistence (BLFP)` is a key component of the Block Node. |
| 6 | +Mainly, it is responsible for storing and retrieving `Blocks` from a local |
| 7 | +storage. It has several moving parts, like path resolution logic, writer tasks, |
| 8 | +readers etc. which when combined, provide a robust and efficient way to store |
| 9 | +and retrieve`Blocks`. This E2E test plan aims to highlight the key scenarios |
| 10 | +that need to be tested for end results in order to ensure the correctness and |
| 11 | +proper working of the `BLFP`. |
| 12 | + |
| 13 | +## Key Considerations for `block-as-local-file` Persistence |
| 14 | + |
| 15 | +- **Path Resolution Logic**: `BLFP` relies on path resolution logic which determines |
| 16 | + the location of a given `Block`. Path resolution utilizes 3 roots: `unverified`, |
| 17 | + `live` and `archive`. |
| 18 | +- **Trie Data Structure for Path Resolution**: `BLFP` utilizes a trie data |
| 19 | + structure to resolve paths for `Block`s. This is done to ensure that the |
| 20 | + path resolution is efficient and fast. |
| 21 | +- **`unverfied` root path**: Initially all blocks are stored under the |
| 22 | + `unverified`. After verification on a given `Block` passes, the persisted |
| 23 | + `Block` is moved to the `live` root, essentially being _published_. |
| 24 | +- **`live` root path**: This is the root path where all verified `Block`s are |
| 25 | + stored. It usually will not hold on to `Block`s for a long time, as they are |
| 26 | + usually archived in groups, leaving behind only a link to the archive. Utilizing |
| 27 | + a link it means that discoverability of a `Block` is still possible under the |
| 28 | + `live` root, no matter that a given file _might_ not be physically present |
| 29 | + there. |
| 30 | +- **`archive` root path**: This is the root path where all locally archived |
| 31 | + `Block`s are stored. In groups of configurable size, `Block`s are archived, |
| 32 | + meaning that they are zipped and stored in the `archive` root. The `live` root |
| 33 | + will have a link to the zip file in place of where the parent directory of the |
| 34 | + group that was just archived would be (utilizing the trie structure) |
| 35 | +- **Writer Tasks**: `BLFP` has writer tasks that are responsible for writing |
| 36 | + `Block`s to the local storage. These tasks are run in parallel and are |
| 37 | + non-blocking. |
| 38 | +- **Persistence Response Codes**: `BLFP` publishes meaningful results at the end |
| 39 | + of each writer task. These codes are internal to the `Block Node` and any |
| 40 | + other service that might be interested in these codes, can receive them. |
| 41 | + |
| 42 | +## Test Scenarios |
| 43 | + |
| 44 | +| Test Case ID | Test Name | Scenario Description | Expected Result | |
| 45 | +|----------------:|:-----------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
| 46 | +| E2ETC_BLFP_0001 | `testBlockPersistedUnverifiedLocation` | `BLFP` will initially persist a `Block` under `unverified` root. We should be sure that the `Block` is indeed persisted in the proper location. | `Block` should be initially written to the correct location under the `unverfied` root. | |
| 47 | +| E2ETC_BLFP_0002 | `testBlockPersistedUnverifiedContents` | `BLFP` will initially persist a `Block` under `unverified` root. We should be sure that the persisted `Block`'s content is indeed what we expect it to be. | A persisted in unverified root `Block`'s content should be what is expected. | |
| 48 | +| E2ETC_BLFP_0003 | `testBlockPersistedUnverifiedOverwrite` | `BLFP` will initially persist a `Block` under `unverified` root. Unverified `Block`s can be overwritten no matter the cause of the overwrite (a failed persistence, system restart or verification could potentially trigger a rewrite). | A persisted unverified `Block` can be overwritten, file content should be verified changed. | |
| 49 | +| E2ETC_BLFP_0004 | `testBlockPersistedUnverifiedFailureCleanup` | `BLFP` will move a `Block` from `unverified` to `live` root. If persistence or verification fails, a cleanup of the written file is expected. | `Block` file and any data should be cleaned up if persistence or verification fails. | |
| 50 | +| E2ETC_BLFP_0005 | `testBlockPersistedUnverifiedDiscoverability` | `BLFP` will move a `Block` from `unverified` to `live` root. The written `Block` must not be discoverable (i.e. readable) as if it were available as data. | `Block`s persisted in unverified storage are ephemeral and are in this type of storage because they are not yet verified and not made available. They should not be discoverable as available. | |
| 51 | +| E2ETC_BLFP_0006 | `testBlockPersistedUnverifiedMoveLiveLocation` | `BLFP` will move a `Block` from `unverified` to `live` root. After verification passes, the file, persisted in unverified root must now be moved into live storage in the appropriate place. | Verify that a persisted `Block` file under the unverified root will be moved to live root (essentially published as available) to the appropriate place. | |
| 52 | +| E2ETC_BLFP_0007 | `testBlockPersistedUnverifiedMoveLiveContents` | `BLFP` will move a `Block` from `unverified` to `live` root. After verification passes, the file, persisted in unverified root must now be moved into live storage in the appropriate place. Contents of the now live file must not be changed compared to pre-move. | Verify that a moved `Block` file from the unverified root to the live root will have the same content compared to pre-move. | |
| 53 | +| E2ETC_BLFP_0008 | `testBlockPersistedUnverifiedCleanupAtSystemStartup` | `Block` files under unverified that may exist during system startup must be all deleted as they are deemed untrustworthy. It is not possible to assert the state thereof. | Verify that all `Block` files existing in unverified root during system startup will be deleted before the system is up and running, ready to operate. | |
| 54 | +| E2ETC_BLFP_0009 | `testBlockPersistedLiveDiscoverability` | A `Block` file that has been moved (published) to live storage is now deemed available, meaning that it is persisted and verified. Such files can be discovered. | Verify that a published `Block` file (meaning a file that is under the live storage, moved there from unverified once verification has passed) is now discoverable as it is now deemed available. Such file should be able to be read/queried. | |
| 55 | +| E2ETC_BLFP_0010 | `testBlockPersistedLiveNoOverwrite` | A `Block` file that has been moved (published) to live storage is now deemed available, but also final. Once published to live, it should not be possible to overwrite this file. Essentially, any attempt at overwriting should be seen as `DUPLICATE_BLOCK`. | Verify that a published `Block` file (meaning a file that is under the live storage, moved there from unverified once verification has passed) cannot be overwritten as it is deemed final. | |
| 56 | +| E2ETC_BLFP_0011 | `testBlockPersistenceFailureBadBlockNumber` | A publisher of the `BlockStream` should expect a `PERSISTENCE_FAILURE` response if it submits a `BlockHeader` that contains a `BlockNumber` that is strictly negative. This is a `BAD_BLOCK_NUMBER` persistence result. | Verify that a publisher of the `BlockStream` will receive a `PERSISTENCE_FAILURE` result if it publishes a `BlockHeader` with a strictly negative `BlockNumber`. | |
| 57 | +| E2ETC_BLFP_0012 | `testBlockPersistenceFailureIncompleteBlock` | A publisher of the `BlockStream` should expect a `PERSISTENCE_FAILURE` response if it submits a `BlockHeader` before it submits the expected `BlockProof` that would denote the end of the current streamed `Block`. | Verify that a publisher of the `BlockStream` will receive a `PERSISTENCE_FAILURE` result if it publishes a `BlockHeader` before publishing the expected `BlockProof` of the current streamed `Block` which would denote the end of the current `Block`. | |
| 58 | +| E2ETC_BLFP_0013 | `testBlockPersistenceFailureDuringIO` | A publisher of the `BlockStream` should expect a `PERSISTENCE_FAILURE` response if an IO issue occurs while the actual persistence of the current `Block` is happening. | Verify that a publisher of the `BlockStream` will receive a `PERSISTENCE_FAILURE` result if there is an IO issue during the actual persistence of the current `Block`. | |
| 59 | +| E2ETC_BLFP_0014 | `testBlockPersistenceSuccess` | A publisher of the `BlockStream` should expect a successful acknowledgement if the persistence and verification of the current streamed `Block` succeed. | Verify that a publisher of the `BlockStream` will receive a successful acknowledgement if the persistence and verification of the current streamed `Block` succeed. | |
| 60 | +| E2ETC_BLFP_0015 | `testBlockPersistedArchiveDiscoverability` | `BLFP` will periodically (based on passed persistence threshold) archive `Blocks` in groups of configurable size. The archived `Block`s are available, final and discoverable. | Verify that an archived `Block` file is discoverable in the sense that it is deemed available and can be read/queried. | |
| 61 | +| E2ETC_BLFP_0016 | `testBlockPersistedArchiveNoOverwrite` | `BLFP` will periodically (based on passed persistence threshold) archive `Blocks` in groups of configurable size. The archived `Block`s are available, final and discoverable. | Verify that an archived `Block` file cannot be overwritten as it is deemed final. | |
0 commit comments