mod.rs

Overview

This file defines core data structures and functions for handling external messages and their feedback within the system. It provides serialization-friendly representations of message identifiers, responses, errors, and feedback, facilitating interaction with external components or APIs. The file includes mechanisms to convert between raw data formats and structured types, encapsulates error handling, and supports rendering HTTP JSON responses.

The primary functionalities include:

• Representation and conversion of ThreadIdentifier, a fixed-size byte array uniquely identifying threads.

• Structuring responses (ExtMsgResponse) and their results or errors for external messages.

• Defining error codes and error data related to message feedback.

• Handling feedback messages (ExtMsgFeedback) which contain detailed execution results from message processing.

• Utility functions for time calculation and HTTP response rendering.

This module interacts closely with the message submodule (which is declared but not detailed here) and integrates with external authentication tokens (ext_messages_auth::auth::Token) and HTTP response handling from salvo.

Data Structures and Types

ThreadIdentifier

A wrapper over a fixed 34-byte array representing a unique thread identifier.

• Implements serialization and deserialization with hex encoding.

• Provides conversions from and to [u8; 34] and from hex string representations.

• Implements Debug by encoding its bytes as a hex string.

Usage example:

let id = ThreadIdentifier::try_from("abcdef...".to_string())?;
println!("{:?}", id); // prints hex string representation

ExtMsgResponse

Represents the HTTP response body for external message requests.

• Fields:

  • result: Option<ExtMsgResult> — Holds successful result data.

  • error: Option<ExtMsgError> — Holds error information if any.

  • ext_message_token: Option<Token> — Optional authentication token related to the message.

• Methods:

  • new_with_error(code: String, message: String, data: Option<ExtMsgErrorData>) -> Self
    Creates a new response containing an error.

  • set_producers(&mut self, producers: Vec<String>)
    Updates the list of producer IPs in both result and error data if present.

• Conversion:

  • Implements From<ExtMsgFeedback> to convert feedback data into a response, distinguishing between success and error cases.

ExtMsgResult

Contains detailed information about a successful message processing:

• message_hash: String — Hash of the message.

• block_hash: String — Hash of the block including the transaction.

• tx_hash: String — Transaction hash.

• ext_out_msgs: Vec<String> — Encoded external output messages.

• aborted: bool — Indicates if the transaction was aborted but still included in the block.

• exit_code: i32 — Exit status code of the transaction (0 means success).

• producers: Vec<String> — List of producer IPs; first is active.

• current_time: String — Timestamp in milliseconds.

• thread_id: Option<String> — Hex-encoded thread identifier.

ExtMsgErrorData

Additional context for errors related to external messages.

• Contains:

  • producers: Vec<String> — Producer IPs.

  • message_hash: String — Message hash related to the error.

  • exit_code: Option<i32> — Optional exit code.

  • current_time: String — Timestamp.

  • thread_id: Option<String> — Optional thread ID.

• Constructor:

  • new(producers, message_hash, exit_code, thread_id)

ExtMsgError

Encapsulates error information for responses.

• Fields:

  • code: String — Error code.

  • message: String — Human-readable message.

  • data: Option<ExtMsgErrorData> — Optional detailed error data.

• Methods:

  • new(code, message, data) — Constructor.

  • set_producers(producers) — Updates producer list in error data.

FeedbackErrorCode

Enumerates possible error codes from message feedback with string representations:

• Variants: Ok, TvmError, MessageExpired, TooManyRequestsInQueue, NotActiveProducer, DuplicateMessage, ThreadMismatch, InternalError, ComputeSkipped, QueueOverflow.

• Method: to_string() returns a static string representation for each variant.

FeedbackError

Contains an error from feedback processing:

• Fields:

  • code: FeedbackErrorCode

  • message: Option<String>

• Implements Display for formatted output.

ExtMsgFeedback

Represents detailed feedback from external message processing, including:

• message_hash: String

• tx_hash: Option<String>

• block_hash: Option<String>

• aborted: bool

• exit_code: i32

• thread_id: Option<[u8; 34]>

• error: Option<FeedbackError>

• ext_out_msgs: Vec<SliceData>

Implements Display for formatted debug output.

ExtMsgFeedbackList

Wraps a vector of ExtMsgFeedback with basic list operations:

• Methods:

  • new() — creates an empty list.

  • push(feedback) — adds feedback to the list.

Implements Display to output all contained feedbacks.

ResolvingResult

Holds resolution state related to block producers:

• Fields:

  • i_am_bp: bool — Whether the current node is a block producer.

  • active_bp: Vec<String> — Active block producers' IPs.

• Constructor: new(i_am_bp, active_bp)

Functions

current_time_millis(ttl: Option<u64>) -> u128

Returns the current system time plus an optional TTL (time-to-live) offset in milliseconds since UNIX epoch.

• ttl: Optional seconds to add to current time.

• Used internally for timestamping responses and errors.

render_error_response

Renders a JSON error response to an HTTP request with status code 400 BAD REQUEST.

Parameters:

• res: &mut Response — mutable HTTP response object.

• code: &str — error code string.

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

• data: Option<ExtMsgErrorData> — optional detailed error data.

• ext_message_token: Option<Token> — optional external message token.

render_error

Renders a JSON error response with a specified HTTP status code.

Parameters:

• res: &mut Response — mutable HTTP response.

• status: StatusCode — HTTP status code to set.

• message: &str — error message string.

• ext_message_token: Option<Token> — optional external message token.

Implementation Details and Algorithms

• The ThreadIdentifier uses serde_with and hex encoding for its serialization, ensuring compact and standard representation.

• Conversion from a hex string to ThreadIdentifier validates length and format, providing detailed error messages.

• ExtMsgResponse conversion from ExtMsgFeedback distinguishes between success and error states, filtering and encoding output messages as base64 strings after serializing them with write_boc.

• Error codes in FeedbackErrorCode are mapped to human-readable strings, used in responses.

• Time is consistently represented in milliseconds since epoch, with optional TTL for future timestamps.

• Producer information is included in results and errors, allowing traceability of which IPs produced or handled a message.

Interaction with Other Modules

• Uses message and v2 submodules (the latter is publicly exposed).

• Relies on ext_messages_auth::auth::Token for authentication tokens passed in responses.

• Integrates with salvo for HTTP response handling and JSON serialization.

• Uses tvm_types library for serializing TVM cells (write_boc) and base64 encoding.

• The feedback and response structures are designed to be serialized to JSON, compatible with HTTP API endpoints.

• The module uses anyhow for error handling in conversions.

Diagram: Structure of mod.rs

classDiagram
class ThreadIdentifier {
+[u8;34] bytes
+try_from(String) ThreadIdentifier
+from([u8;34]) ThreadIdentifier
+to_bytes() [u8;34]
}
class ExtMsgResponse {
-Option<ExtMsgResult> result
-Option<ExtMsgError> error
-Option<Token> ext_message_token
+new_with_error(String, String, Option<ExtMsgErrorData>)
+set_producers(Vec<String>)
}
class ExtMsgResult {
-String message_hash
-String block_hash
-String tx_hash
-Vec<String> ext_out_msgs
-bool aborted
-i32 exit_code
-Vec<String> producers
-String current_time
-Option<String> thread_id
}
class ExtMsgErrorData {
-Vec<String> producers
-String message_hash
-Option<i32> exit_code
-String current_time
-Option<String> thread_id
+new(Vec<String>, String, Option<i32>, Option<String>)
}
class ExtMsgError {
-String code
-String message
-Option<ExtMsgErrorData> data
+new(String, String, Option<ExtMsgErrorData>)
+set_producers(Vec<String>)
}
class FeedbackErrorCode {
<<enumeration>>
Ok
TvmError
MessageExpired
TooManyRequestsInQueue
NotActiveProducer
DuplicateMessage
ThreadMismatch
InternalError
ComputeSkipped
QueueOverflow
+to_string()
}
class FeedbackError {
-FeedbackErrorCode code
-Option<String> message
}
class ExtMsgFeedback {
-String message_hash
-Option<String> tx_hash
-Option<String> block_hash
-bool aborted
-i32 exit_code
-Option<[u8;34]> thread_id
-Option<FeedbackError> error
-Vec<SliceData> ext_out_msgs
}
class ExtMsgFeedbackList {
-Vec<ExtMsgFeedback> feedbacks
+new()
+push(ExtMsgFeedback)
}
class ResolvingResult {
-bool i_am_bp
-Vec<String> active_bp
+new(bool, Vec<String>)
}
ExtMsgResponse --> ExtMsgResult
ExtMsgResponse --> ExtMsgError
ExtMsgError --> ExtMsgErrorData
ExtMsgFeedback --> FeedbackError
ExtMsgResponse ..> ExtMsgFeedback : From

This diagram illustrates the main data structures, their relationships, and key methods within the file.