default_thread_seqno.rs

Overview

The default_thread_seqno.rs file defines the LastSeqnoHandler struct and its asynchronous HTTP request handler implementation. This handler is designed to serve the last sequence number (seqno) of a default thread in the context of a web server. It integrates with the web server's internal state and returns the latest sequence number as a JSON response or an error message if retrieval fails.

This file primarily facilitates handling HTTP requests by extracting the last seqno from the web server's state and formatting it appropriately for client consumption.

Struct: LastSeqnoHandler

pub struct LastSeqnoHandler<TMessage, TMsgConverter, TBPResolver, TBocByAddrGetter, TSeqnoGetter> {
    _marker: PhantomData<(TMessage, TMsgConverter, TBPResolver, TBocByAddrGetter, TSeqnoGetter)>,
}

Description

LastSeqnoHandler is a generic struct parameterized over five types related to message processing and blockchain data retrieval:

• TMessage: Represents the message type used internally.

• TMsgConverter: Function type converting raw messages into TMessage.

• TBPResolver: Function type for blockchain parameter resolution.

• TBocByAddrGetter: Function type to retrieve serialized blockchain objects by address.

• TSeqnoGetter: Function type to retrieve sequence numbers.

The struct uses PhantomData to hold these generic types without actually storing values, ensuring type coherence without runtime overhead.

Methods

new() -> Self

Creates a new instance of LastSeqnoHandler. It initializes the struct with a default PhantomData.

Usage Example:

let handler = LastSeqnoHandler::<MyMessage, MyConverter, MyResolver, MyBocGetter, MySeqnoGetter>::new();

Trait Implementation: Handler for LastSeqnoHandler

#[async_trait]
impl<TMessage, TMsgConverter, TBPResolver, TBocByAddrGetter, TSeqnoGetter> Handler
    for LastSeqnoHandler<TMessage, TMsgConverter, TBPResolver, TBocByAddrGetter, TSeqnoGetter>
where
    TMessage: Clone + Send + Sync + 'static + std::fmt::Debug,
    TMsgConverter: Clone + Send + Sync + 'static + Fn(tvm_block::Message, [u8; 34]) -> anyhow::Result<TMessage>,
    TBPResolver: Clone + Send + Sync + 'static + FnMut([u8; 34]) -> ResolvingResult,
    TBocByAddrGetter: Clone + Send + Sync + 'static + Fn(String) -> anyhow::Result<(String, Option<String>)>,
    TSeqnoGetter: Clone + Send + Sync + 'static + Fn() -> anyhow::Result<u32>,
{
    async fn handle(
        &self,
        _req: &mut Request,
        depot: &mut Depot,
        res: &mut Response,
        _ctrl: &mut FlowCtrl,
    )
}

Description

This implementation defines the asynchronous handle method for the LastSeqnoHandler, enabling it to process HTTP requests.

handle Method

Parameters

• _req: &mut Request
  The incoming HTTP request object. Not utilized in this handler.

• depot: &mut Depot
  A container for shared state and dependencies, used to retrieve the WebServer instance.

• res: &mut Response
  The HTTP response object, used to send data back to the client.

• _ctrl: &mut FlowCtrl
  Controls flow of request handling, unused in this context.

Functionality

1. Retrieve WebServer State:
   Attempts to obtain the WebServer instance from the depot. The WebServer is parameterized over the same generic types and holds the application state relevant to message handling and sequence numbers.

2. Error Handling:
   If the WebServer instance is not found, the response status is set to 500 Internal Server Error, and a corresponding message is rendered.

3. Retrieve Sequence Number:
   Calls the get_default_thread_seqno function on the WebServer instance to obtain the latest sequence number.

4. Response Generation:

   • On success, returns a JSON object with field "last_seq_no" containing the sequence number.

   • On failure, sets the response status to 500 Internal Server Error and renders the error message.

Return Value

handle returns () as it operates via side effects on the response.

Usage Example

The handler is intended to be registered with a web server framework route to respond to HTTP GET requests for the last seqno.

router.get("/last-seqno", LastSeqnoHandler::new());

Important Implementation Details

• Generics and PhantomData:
  The use of generics allows the handler to be flexible with different message and blockchain data types. PhantomData is used to associate these generic parameters without storing actual instances.

• Error Handling:
  The handler explicitly checks for the availability of the WebServer state and handles errors from the sequence number retrieval gracefully, ensuring proper HTTP status codes and messages.

• Asynchronous Handling:
  The method is asynchronous (async fn) to integrate smoothly with asynchronous HTTP frameworks, enabling non-blocking I/O.

• Dependency Injection via Depot:
  The Depot pattern is used to inject application state (WebServer), promoting loose coupling between components.

Interaction with Other System Components

• WebServer Struct:
  The handler relies heavily on the WebServer struct instance, which encapsulates the application's core logic for message processing and blockchain interaction. The WebServer provides the method get_default_thread_seqno to fetch the last sequence number.

• Request Handling Pipeline:
  Integrated within an HTTP server framework (likely salvo), the handler acts as a middleware or endpoint handler, processing HTTP requests and generating JSON responses.

• Message and Blockchain Processing Types:
  The generic parameters (TMessage, TMsgConverter, etc.) link this handler to the broader system's message processing, blockchain resolution, and serialization logic.

Visual Diagram

flowchart TD
A[HTTP Request] --> B["LastSeqnoHandler.handle()"]
B --> C{Obtain WebServer}
C -- Success --> D["Call get_default_thread_seqno()"]
C -- Failure --> E[Respond 500: WebServer not found]
D --> F{Result}
F -- Ok(seq_no) --> G[Respond JSON {last_seq_no: seq_no}]
F -- Err(error) --> H[Respond 500: error message]

This flowchart illustrates the request handling workflow within the LastSeqnoHandler. It begins with an incoming HTTP request, attempts to access the WebServer state, retrieves the last sequence number, and sends back a JSON response or an error message accordingly.