tests.rs

Overview

This file contains a suite of unit tests designed to validate the functionality of the MessageDurableStorage component and its interaction with message serialization, storage, retrieval, and querying. The tests focus on verifying the correctness of message persistence operations such as writing messages to durable storage, reading them back, fetching database row IDs by message hash, iterating over stored messages, and retrieving remaining messages starting from a given message identifier.

The file operates primarily with base64-encoded serialized messages, deserializing them into tvm_block::Message instances, wrapping them into WrappedMessage structures, and then storing or querying these objects through the MessageDurableStorage interface.

Details of Functions and Their Usage

setup_db

fn setup_db(db_path: PathBuf) -> MessageDurableStorage

• Purpose: Initializes a new instance of MessageDurableStorage with a specified database file path.

• Parameters:

  • db_path: A PathBuf representing the location of the database file.

• Returns: A MessageDurableStorage instance ready for read/write operations.

• Usage: Used internally by other test cases to obtain a fresh storage instance pointing to a temporary or fixed database file path.

test_write_and_read_message

#[test]
fn test_write_and_read_message()

• Purpose: Validates the ability to write a serialized message blob to durable storage and subsequently read it back by its hash.

• Process:

  1. Sets up storage at a fixed path (/tmp/db.db).

  2. Decodes a base64-encoded message blob.

  3. Constructs a tvm_block::Message from the blob.

  4. Serializes the wrapped message (WrappedMessage) into a binary format.

  5. Computes the message hash and destination account address.

  6. Writes the serialized message to storage keyed by destination account and hash.

  7. Reads the message back from storage using the hash.

  8. Asserts that the stored message matches the originally written message.

• Usage: Tests fundamental write and read operations of the storage layer.

test_get_rowid_by_hash

#[test]
fn test_get_rowid_by_hash()

• Purpose: Ensures that the storage system can return the internal database row ID corresponding to a given message hash.

• Process:

  1. Creates a temporary database.

  2. Writes a known message into storage.

  3. Queries for the row ID using the message hash.

  4. Asserts that the row ID exists (is_some()).

• Usage: Validates internal indexing functionality of the message storage.

test_next_simple

#[test]
fn test_next_simple()

• Purpose: Tests retrieval of subsequent messages in storage following a starting cursor (row ID).

• Process:

  1. Sets up temporary storage.

  2. Creates three variant messages:

     • Original message.

     • Modified message with different source address.

     • Modified message with bounced header flag set.

  3. Stores all three messages.

  4. Finds the row ID of the first message.

  5. Calls next_simple to fetch the next 10 messages after the start cursor.

  6. Asserts that the returned messages are the second and third messages in order.

• Usage: Validates iteration and pagination mechanisms for stored messages.

test_remaining

#[test]
fn test_remaining()

• Purpose: Checks the functionality of retrieving all remaining messages starting from a given message identifier.

• Process:

  1. Sets up temporary storage.

  2. Writes three messages similar to test_next_simple.

  3. Uses the MessageIdentifier built from the first message to query for all remaining messages.

  4. Asserts that all three messages are returned in the correct order.

• Usage: Tests functionality for retrieving a complete message sequence starting at a given identifier.

Important Implementation Details

• Message Encoding & Decoding: Messages are handled as base64-encoded blobs, decoded into raw bytes, then deserialized into tvm_block::Message instances via construct_from_bytes. Serialization of wrapped messages is done using bincode.

• Message Hashing: Each message's hash is computed using the hash() method from the GetRepresentationHash trait, then converted to hex string for use as keys.

• Destination Account: Extracted from the message's internal destination account ID and converted to its hex string representation.

• Storage Interface: The tests rely on the MessageDurableStorage API which provides:

  • write_message(account: &str, blob: &[u8], hash: &str) for persisting messages.

  • read_message(hash: &str) for retrieving messages by hash.

  • get_rowid_by_hash(hash: &str) for obtaining database row IDs.

  • next_simple(account: &str, start_cursor: u64, count: usize) for paginated fetching.

  • remaining_messages(identifier: &MessageIdentifier, max_count: usize) for fetching messages from a starting point.

• Message Variants for Testing: Some tests mutate the source address or the bounced header flag to create distinguishable message variants.

Interaction with Other Components

• MessageDurableStorage: The primary entity under test, responsible for persistent message storage. It likely interfaces with a database backend for durable storage.

• tvm_block::Message and WrappedMessage: Represent the message data structures serialized and stored by the storage layer.

• MessageIdentifier: Used for identifying messages uniquely to support queries like remaining messages.

• base64_decode: Utility for decoding the base64-encoded test message blobs.

• bincode: Serialization library employed for converting WrappedMessage instances to byte arrays for storage.

• MsgAddressInt and MsgAddrStd: Used to modify or inspect message addresses, specifically in tests generating message variants.

• This file is a test-only module that exercises the storage and message data layers and does not expose functionality for production use.

Visual Diagram

flowchart TD
A[setup_db] --> B[MessageDurableStorage]
subgraph Tests
TWAR[test_write_and_read_message]
TGHB[test_get_rowid_by_hash]
TNS[test_next_simple]
TR[test_remaining]
end
TWAR --> B
TGHB --> B
TNS --> B
TR --> B
B -->|write_message| C[Store message blob]
B -->|read_message| D[Retrieve message by hash]
B -->|get_rowid_by_hash| E[Lookup row ID]
B -->|next_simple| F[Fetch next messages]
B -->|remaining_messages| G[Fetch remaining messages]
TWAR -.->|uses| H[tvm_block::Message]
TWAR -.->|uses| I[WrappedMessage]
TNS -.->|mutates| J[MsgAddressInt/MsgAddrStd]
style Tests fill:#f9f,stroke:#333,stroke-width:1px
style B fill:#bbf,stroke:#333,stroke-width:1px

This flowchart illustrates the relationship between the test functions, the MessageDurableStorage component under test, and the key storage operations utilized by these tests. It also shows interactions with message data structures and address types used to prepare test inputs.