message.rs

Overview

This file defines the representation and handling of external messages received by the system. It provides data structures to deserialize incoming message data, convert it into a richer internal format, and expose relevant properties and behaviors for further processing. The primary focus is on transforming raw incoming messages into validated and structured ExternalMessage instances that encapsulate message content, identifiers, and authentication tokens.

Data Structures and Types

IncomingExternalMessage

A struct designed for deserialization of raw external messages. It captures the minimal necessary fields received from an external source:

• Fields:

  • id: String — Unique identifier or hash of the message.

  • body: String — Raw serialized message content.

  • thread_id: Option<String> — Optional identifier for the message thread or conversation.

  • ext_message_token: Option<Token> — Optional authentication token associated with the message.

• Methods:

  • id(&self) -> &str
    Returns a string slice reference to the message's id.
    Usage example:

    let incoming_msg: IncomingExternalMessage = /* deserialized */;
    let message_id = incoming_msg.id();
    

ExternalMessage

Represents a fully parsed and validated message within the system, wrapping the underlying tvm_block::Message and associated metadata.

• Fields:

  • hash: String — The unique hash or identifier of the message.

  • message: Message — The parsed message object from the tvm_block crate.

  • thread_id: ThreadIdentifier — Strongly typed thread identifier.

  • ext_message_token: Option<Token> — Optional authentication token.

• Methods:

  • is_dst_exists(&self) -> bool
    Checks if the destination account ID exists in the inner message. Returns true if present, false otherwise.
    Example:

    if external_msg.is_dst_exists() {
        // Process destination-specific logic
    }
    

  • hash(&self) -> String
    Returns the hexadecimal string representation of the message hash. If the hash is unavailable, returns an empty string.

  • tvm_message(&self) -> Message
    Returns a clone of the underlying Message object for further use.

  • thread_id(&self) -> ThreadIdentifier
    Returns the thread identifier for this message.

• Trait Implementations:

  • TryFrom<&IncomingExternalMessage>
    Converts a reference to an IncomingExternalMessage into an ExternalMessage. This involves parsing the raw message body using the parse_message helper, and converting the optional thread ID string into a ThreadIdentifier. Errors during parsing are propagated using anyhow::Error.
    Usage:

    let incoming: IncomingExternalMessage = /* ... */;
    let external_msg = ExternalMessage::try_from(&incoming)?;
    

  • fmt::Debug
    Custom debug implementation that formats the hash, thread_id, and the optional ext_message_token fields for logging and debugging purposes.

Important Implementation Details

• Message Parsing:
  The conversion from IncomingExternalMessage to ExternalMessage relies on the parse_message function (imported from crate::helpers::parse_message). This function attempts to parse the raw message body into a tvm_block::Message. Errors during parsing are wrapped with contextual information including the message ID.

• Thread Identification:
  The thread ID is an optional string in the incoming message. When converting, it is transformed into a strongly typed ThreadIdentifier using its TryFrom implementation. If absent or invalid, a default ThreadIdentifier is used.

• Hash Usage:
  The hash field in ExternalMessage is initialized from the incoming message's id field and is used as a unique identifier for the message throughout the system.

• Destination Check:
  The is_dst_exists method checks for the presence of an internal destination account ID within the Message, indicating whether the message targets a specific account.

Interactions with Other Modules

• ext_messages_auth::auth::Token:
  Represents authentication tokens attached to external messages, enabling verification and authorization workflows.

• tvm_block::Message and tvm_block::GetRepresentationHash:
  Core message representation and hashing functionality used to interpret and validate message content.

• crate::api::ext_messages::ThreadIdentifier:
  Provides a strongly typed representation of message thread identifiers, ensuring consistent handling of threading in message flows.

• crate::helpers::parse_message:
  Utility function responsible for parsing raw message strings into structured Message objects, critical to the transformation pipeline.

Usage Example

use std::convert::TryFrom;

let incoming = IncomingExternalMessage {
    id: "abc123".to_string(),
    body: "...".to_string(),
    thread_id: Some("thread-42".to_string()),
    ext_message_token: None,
};

match ExternalMessage::try_from(&incoming) {
    Ok(external_msg) => {
        println!("Message hash: {}", external_msg.hash());
        if external_msg.is_dst_exists() {
            // Further processing
        }
    }
    Err(e) => eprintln!("Failed to convert message: {}", e),
}

Mermaid Class Diagram

classDiagram
class IncomingExternalMessage {
-id: String
-body: String
-thread_id: Option<String>
-ext_message_token: Option<Token>
+id(): &str
}
class ExternalMessage {
-hash: String
-message: Message
-thread_id: ThreadIdentifier
+ext_message_token: Option<Token>
+is_dst_exists(): bool
+hash(): String
+tvm_message(): Message
+thread_id(): ThreadIdentifier
}
IncomingExternalMessage <|.. ExternalMessage : TryFrom

This diagram illustrates the two main structs, their key fields and methods, and the conversion relationship between them.