bk_set_update.rs

Overview

This file provides the API structures, serialization/deserialization logic, data handling, and HTTP request handling related to the management and updating of a "Backup Key Set" (BkSet) within the system. The BkSet represents collections of backup keys involved in some form of blockchain or distributed system consensus or staking mechanism.

Key functionalities include:

• Representing cryptographic keys and addresses in API-friendly formats.

• Managing sets of backup keys, including updating current and future keys based on sequence numbers.

• Defining the lifecycle status of backup keys.

• Providing a thread-safe snapshot mechanism for the BkSet state.

• Handling HTTP requests to serve the current BkSet state, respecting HTTP caching headers.

• Serializing error responses for API consumers.

Data Structures and Classes

ApiUInt256

• Purpose: Represents a 256-bit unsigned integer as a 32-byte array for API communication.

• Implements Serialize and Deserialize traits to convert between raw bytes and hex-encoded strings.

• Serialization: Converts the byte array to a lowercase hex string.

• Deserialization: Converts a hex string back into a 32-byte array, validating length.

Example usage:

let raw_bytes = [0u8; 32];
let api_uint = ApiUInt256(raw_bytes);
let json_string = serde_json::to_string(&api_uint).unwrap();
// json_string is a hex string representing the 32 bytes.

ApiPubKey

• Purpose: Represents a public key as a 48-byte array in API format.

• Similar serialization/deserialization behavior as ApiUInt256 but for 48 bytes.

• Validates that deserialized hex strings have exactly 48 bytes.

ApiBk

• Represents a single backup key with associated metadata.

• Fields:

  • pubkey: ApiPubKey — The public key for this backup key.

  • epoch_finish_seq_no: Option<u64> — Optional sequence number indicating when the epoch finishes.

  • wait_step: u64 — Duration to wait before expiring the key if not updated.

  • status: ApiBkStatus — The current lifecycle status of the backup key.

  • address: String — String representation of the key's address.

  • stake: String — Amount of stake held by this key (as a string, possibly due to large number).

  • owner_address: ApiUInt256 — Owner's address as a 256-bit API type.

  • signer_index: usize — Index of the signer.

  • owner_pubkey: ApiUInt256 — Owner's public key.

  • ttl_seq_no: Option<u64> (skipped in serialization) — Sequence number indicating expiration time-to-live.

• Method:

  • expired(&self, seq_no: u64) -> bool: Returns true if the backup key is expired with respect to the provided sequence number.

ApiBkStatus

• Enum representing the lifecycle status of a backup key.

• Variants:

  • PreEpoch

  • Active

  • CalledToFinish

  • Expired

ApiBkSet

• Represents a set of backup keys, divided into current and future keys.

• Fields:

  • seq_no: u64 — Sequence number representing the version of this backup key set.

  • current: Vec<ApiBk> — List of current active backup keys.

  • future: Vec<ApiBk> — List of backup keys planned for future activation.

• Methods:

  • update(&mut self, other: &ApiBkSet) -> bool:

    • Updates the current set with values from another ApiBkSet.

    • Only updates if the incoming sequence number is greater or equal.

    • Updates both current and future keys using update_bks.

    • Returns true if an update occurred, false otherwise.

  • update_bks(old_bks: &mut Vec<ApiBk>, new_bks: &[ApiBk], seq_no: u64) (private):

    • Updates the list of backup keys old_bks with new_bks based on owner address.

    • Marks keys as expiring by setting ttl_seq_no if they are missing in the new list.

    • Removes expired keys.

    • Adds new keys that were not previously present.

ApiBkSetSnapshot

• Thread-safe snapshot container for the current ApiBkSet.

• Fields:

  • update_time: SystemTime — Timestamp of the last update.

  • bk_set: ApiBkSet — The backup key set snapshot.

• Methods:

  • new() -> Self: Creates a new snapshot with default values (seq_no 0, empty vectors).

  • replace(&mut self, bk_set: ApiBkSet): Replaces the stored backup key set and updates the timestamp to now.

ApiBkSetResponse

• Structure for API responses related to backup key sets.

• Fields:

  • result: Option<ApiBkSet> — The successful result, if any.

  • error: Option<ApiBkSetError> — Error information, if any.

ApiBkSetError

• Structure representing errors in API responses.

• Fields:

  • code: String — Error code.

  • message: String — Human-readable error message.

ApiBkSetHandler

• Generic HTTP request handler for serving the backup key set state.

• Uses generic parameters to abstract over message types, converters, resolvers, and getters.

• Implements Handler trait asynchronously.

• Key methods:

  • new() -> Self: Constructs a new handler instance with placeholders.

  • handle(&self, req: &mut Request, depot: &mut Depot, res: &mut Response, _ctrl: &mut FlowCtrl) -> impl Future:

    • Handles incoming HTTP requests.

    • Retrieves the shared WebServer state from the Depot.

    • Parses If-Modified-Since header for HTTP caching.

    • If the BkSet state has not been updated since the provided timestamp, returns 304 Not Modified.

    • Otherwise, returns the current BkSet as JSON with 200 OK.

    • Sets Last-Modified header with the snapshot timestamp.

    • On errors (e.g., missing state), returns 500 Internal Server Error with JSON error response.

render_error_response

• Utility function to render an error JSON response.

• Parameters:

  • res: &mut Response — The HTTP response object to modify.

  • code: &str — Error code string.

  • message: Option<&str> — Optional error message; defaults to code if None.

• Sets the response body to a JSON-encoded ApiBkSetResponse with an error.

Important Implementation Details

• Serialization of cryptographic types uses hex-encoded strings for compact and readable API representation.

• Backup key expiration logic is handled using sequence numbers (seq_no) and optional TTL (ttl_seq_no). Keys are marked to expire after a waiting period (wait_step) if not refreshed.

• Update algorithm (ApiBkSet::update_bks):

  • Uses a HashMap to efficiently match backup keys by owner address.

  • Updates existing keys by overwriting with the new version and clearing TTL.

  • Marks absent keys with a TTL sequence number, after which they will be removed.

  • Adds new keys from the incoming set.

  • Removes expired keys based on TTL and current seq_no.

• HTTP caching support:

  • Uses If-Modified-Since and Last-Modified headers to reduce unnecessary data transfer.

  • Returns HTTP status 304 Not Modified when appropriate.

• Generic handler design:

  • Makes the handler adaptable to different message and resolver implementations.

  • Enforces trait bounds for concurrency and error handling.

Interaction with Other System Components

• Interacts with the WebServer state structure (generic over message and resolver types), which holds the current ApiBkSetSnapshot.

• Requests handled by ApiBkSetHandler expect WebServer state to be present in the request Depot.

• The ApiBkSetHandler is an HTTP API endpoint handler serving backup key set information to clients.

• Utilizes external crates for HTTP handling (salvo), serialization (serde), and hex encoding (hex).

• The generic parameters imply integration with message conversion (TMsgConverter), blockchain state resolving (TBPResolver), and sequence number providers (TSeqnoGetter).

Visual Diagram: Class and Structure Relationships

classDiagram
class ApiUInt256 {
+[u8; 32]
+serialize()
+deserialize()
}
class ApiPubKey {
+[u8; 48]
+serialize()
+deserialize()
}
class ApiBkStatus {
<<enum>>
+PreEpoch
+Active
+CalledToFinish
+Expired
}
class ApiBk {
+ApiPubKey pubkey
+Option<u64> epoch_finish_seq_no
+u64 wait_step
+ApiBkStatus status
+String address
+String stake
+ApiUInt256 owner_address
+usize signer_index
+ApiUInt256 owner_pubkey
+Option<u64> ttl_seq_no
+expired()
}
class ApiBkSet {
+u64 seq_no
+Vec<ApiBk> current
+Vec<ApiBk> future
+update()
-update_bks()
}
class ApiBkSetSnapshot {
-SystemTime update_time
-ApiBkSet bk_set
+new()
+replace()
}
class ApiBkSetResponse {
+Option<ApiBkSet> result
+Option<ApiBkSetError> error
}
class ApiBkSetError {
+String code
+String message
}
class ApiBkSetHandler {
+new()
+handle()
}
ApiBkSet "1" --> "*" ApiBk : contains
ApiBkSetSnapshot "1" --> "1" ApiBkSet : holds
ApiBkSetResponse "1" --> "0..1" ApiBkSet : result
ApiBkSetResponse "1" --> "0..1" ApiBkSetError : error
ApiBkSetHandler ..> ApiBkSetSnapshot : reads
ApiBk ..|> ApiBkStatus : uses
ApiBk ..> ApiUInt256 : uses
ApiBk ..> ApiPubKey : uses

This diagram illustrates the main data structures' relationships, showing how ApiBkSet aggregates multiple ApiBk entries, the snapshot mechanism around ApiBkSet, and the handler's role in accessing and serving this data. Serialization-related types (ApiUInt256 and ApiPubKey) are used within ApiBk. The handler interacts with the snapshot to provide HTTP responses.