lib.rs

Overview

This file implements the core web server infrastructure for handling external messages, account data, and BK set management within the system. It provides the WebServer struct which encapsulates the server configuration, dependencies, and runtime behavior. The server exposes HTTP routes supporting authentication, message validation, and shard state retrieval. It also integrates mechanisms for handling cryptographic signing, metrics collection, and BK set updates.

The file organizes middleware for request processing (e.g., authentication and metrics reporting) and defines utility functions such as TLS configuration generation. It leverages asynchronous programming and Tokio synchronization primitives to handle concurrent message processing and BK set state synchronization.

Entities and Components

WebServer<TMessage, TMsgConverter, TBPResolver, TBocByAddrGetter, TSeqnoGetter>

A generic asynchronous web server struct parameterized by:

• TMessage: The type representing incoming messages.

• TMsgConverter: Function type converting raw messages into TMessage.

• TBPResolver: Function type resolving some form of BP (block producer?) data.

• TBocByAddrGetter: Function type obtaining BOC (Bag of Cells) data by address.

• TSeqnoGetter: Function type retrieving the default thread sequence number.

Properties

• addr: String
  Network address where the server listens.

• local_storage_dir: PathBuf
  Directory path for local shard state storage.

• incoming_message_sender: InstrumentedSender<(TMessage, Option<oneshot::Sender<ExtMsgFeedback>>)>
  Channel sender for incoming messages with optional feedback response.

• signing_pubkey_request_senber: mpsc::Sender<AccountRequest>
  Channel sender for requests to sign public keys.

• bk_set_summary: Arc<RwLock<BkSetSummarySnapshot>>
  Thread-safe snapshot of BK set summary state.

• bk_set: Arc<RwLock<ApiBkSetSnapshot>>
  Thread-safe snapshot of the full BK set state.

• into_external_message: TMsgConverter
  Message converter function.

• bp_resolver: TBPResolver
  BP resolver function.

• get_boc_by_addr: TBocByAddrGetter
  Function to get BOC by address.

• get_default_thread_seqno: TSeqnoGetter
  Function to get default thread sequence number.

• owner_wallet_pubkey: Option<String>
  Optional owner wallet public key used for token issuance.

• signing_keys: Option<KeyPair>
  Optional signing key pair loaded from file.

• metrics: Option<RoutingMetrics>
  Optional routing metrics collector.

Methods

new(...) -> Self

Creates a new instance of WebServer.

Parameters:

• addr: impl AsRef<str> - Server listen address.

• local_storage_dir: impl AsRef<Path> - Directory for local shard state.

• incoming_message_sender: InstrumentedSender<(TMessage, Option<oneshot::Sender<ExtMsgFeedback>>)> - Incoming message channel.

• signing_pubkey_request_senber: mpsc::Sender<AccountRequest> - Signing request channel.

• into_external_message: TMsgConverter - Message conversion function.

• bp_resolver: TBPResolver - BP resolver function.

• get_boc_by_addr: TBocByAddrGetter - BOC getter function.

• get_default_thread_seqno: TSeqnoGetter - Sequence number getter.

• owner_wallet_pubkey: Option<String> - Optional owner wallet public key.

• signing_keys_path: Option<String> - Optional path to signing keys.

• metrics: Option<RoutingMetrics> - Optional metrics collector.

Returns:

• A new WebServer instance initialized with provided parameters and loaded signing keys if available.

Usage example:

let server = WebServer::new(
    "127.0.0.1:8080",
    "./storage",
    incoming_sender,
    signing_request_sender,
    msg_converter,
    bp_resolver,
    boc_getter,
    seqno_getter,
    Some("owner_pubkey".to_string()),
    Some("keys.pem".to_string()),
    Some(metrics),
);

route(self) -> Router

Builds and returns the HTTP route tree for the server.

• Sets up routes with specific paths like /v2/messages, /v2/account, /v2/bk_set, /storage_latest, etc.

• Applies middleware hoops such as logging, authentication, authorization, and request validation.

• Uses sub-routers for modular route handling.

Returns:

• A configured salvo::Router instance representing all server routes.

run(self, bk_set_rx: watch::Receiver<ApiBkSet>) -> impl Future

Asynchronously runs the web server.

Behavior:

• Initializes Rustls TLS configuration using self-signed certificates.

• Sets up QUIC and TCP listeners for accepting connections.

• Spawns a task to listen for BK set updates via a Tokio watch channel and update shared BK set snapshots accordingly.

• Starts the HTTP server with the configured routes.

• Logs server startup and shutdown events.

Parameters:

• bk_set_rx: Receiver to observe BK set state updates.

Usage example:

tokio::spawn(async move {
    server.run(bk_set_receiver).await;
});

issue_token(&self) -> Option<Token>

Generates an authorization token if signing keys and owner wallet public key are set.

Returns:

• Some(Token) if token issuance succeeds.

• None if signing keys or owner wallet public key are missing.

Functions and Handlers

rustls_config() -> RustlsConfig

Generates and returns a Rustls TLS configuration with self-signed certificates.

• Uses rcgen::generate_simple_self_signed with IP addresses and localhost.

• Builds Keycert and returns RustlsConfig.

Usage:

• Used internally by WebServer::run to enable TLS.

Middleware Handlers

All handlers use the #[handler] attribute from the salvo framework and operate asynchronously.

report_block_request(req, res, depot, ctrl)

• Reports metrics for shard state requests if metrics are available in the request context.

• Calls the next middleware handler.

pass_unauthorized(req, res, depot, ctrl)

• Inserts a flag pass_unauthorized into the request context allowing bypass of authorization.

• Calls the next middleware handler.

auth(req, res, depot, ctrl)

Authentication middleware.

• Reads a token from the environment variable AUTH_TOKEN.

• Checks if the request Authorization header matches Bearer <token>.

• If authorized, inserts authorized_by_bk_token flag into the request context.

• If unauthorized and no bypass flag is set, responds with HTTP 401 Unauthorized.

validate_ext_message(req, res, depot, ctrl)

Validates incoming external messages:

• Parses JSON body as a vector of IncomingExternalMessage.

• Returns HTTP 400 if parsing fails or the vector is empty.

• Converts the first message into an ExternalMessage.

• Checks if the destination address in the message exists.

• If all validations pass, inserts the external message into the request context.

• Otherwise, returns HTTP 400 with appropriate error messages.

Implementation Details and Algorithms

• BK Set Synchronization:
  The run method spawns a dedicated Tokio task that listens on a watch channel for BK set updates. When an update occurs, it atomically replaces the shared BK set snapshot and recomputes the BK set summary. This ensures the server always serves up-to-date BK set information without blocking request handlers.

• Dynamic Route Composition:
  The route method constructs a hierarchy of routers with paths scoped under /v2, /storage_latest, /storage/{*path}, etc. Middleware hoops are applied in layers for logging, authentication, authorization, and validation, ensuring composable and modular route processing.

• Token Issuance:
  The issue_token method creates a Token signed by the server's private key, embedding the owner wallet public key as the token issuer. This token is used for authenticating external message requests.

• TLS Configuration:
  Self-signed TLS certificates are generated at startup to secure HTTP and QUIC communication channels, using rcgen and salvo's Rustls bindings.

Interaction with Other Modules

• api Module:
  Provides message handlers for external messages, BK set data, and account-related queries. The server delegates route handling to these handlers.

• ext_messages_auth Module:
  Provides authentication tokens, key pair loading, and account signing request types used for authorization and signing.

• metrics Module:
  Collects and reports routing metrics such as request counts and latencies.

• tvm_block::Message:
  Represents raw messages that are converted into the generic TMessage type for processing.

• salvo Framework:
  Provides HTTP server, routing, middleware, and connection management abstractions.

• tokio Synchronization Primitives:
  Used for asynchronous message passing (mpsc and oneshot) and state synchronization (watch).

Routing Structure Diagram

flowchart TD
WebServer -->|routes| Router_v2
Router_v2 --> Account_Route["/account"]
Router_v2 --> Messages_Route["/messages"]
Router_v2 --> BKSet_Route["/bk_set"]
Router_v2 --> BKSetUpdate_Route["/bk_set_update"]
Router_v2 --> SeqNo_Route["/default_thread_seqno"]
Router_v2 --> StorageLatest_Route["/storage_latest"]
Router_v2 --> Storage_Route["/storage/{*path}"]
Messages_Route --> Auth_Middleware
Messages_Route --> ValidateExtMsg_Middleware
Messages_Route --> ExtMessagesHandler
Account_Route --> Auth_Middleware
Account_Route --> BocByAddressHandler
SeqNo_Route --> Auth_Middleware
SeqNo_Route --> LastSeqnoHandler
Storage_Route --> ReportBlockRequest_Middleware
Storage_Route --> StaticDirHandler
subgraph Middleware
Auth_Middleware
ValidateExtMsg_Middleware
ReportBlockRequest_Middleware
end

Key Constants

Notes on Usage

• The server expects an environment variable AUTH_TOKEN for authentication unless requests carry a bypass flag.

• Signing keys are read from a PEM file if a path is provided during construction.

• The BK set state is updated asynchronously through a Tokio watch channel, which must be supplied when running the server.

• The server supports both TCP and QUIC listeners, although the TLS configuration for TCP is currently disabled pending readiness.

• Metrics collection is optional and integrated if provided.

This file is a central component for HTTP API exposure, message handling, authorization, and BK set state management within the system. It tightly integrates with other modules for cryptographic authentication, message parsing, and system metrics.