types

Transport layer type definitions.

This module contains all shared types used by transport adapters. These types form the contract between the adapter implementations and the higher-level transport facade.

Type Categories

Handles - Opaque references to running adapters
Status - Health and subscription state
Errors - Structured error types for operations
Options - Configuration for send/receive operations
Metadata - Information about messages and delivery

Types

AdapterError

</>

Generic adapter lifecycle errors.

pub type AdapterError {
  StartFailed(reason: String)
  StopFailed(reason: String)
  ShutdownTimeout(elapsed_ms: Int)
  SubscriptionFailed(reason: String)
  InvalidConfiguration(reason: String)
  ResourceExhausted(resource: String)
}

Constructors

```
StartFailed(reason: String)
```
Failed to start the adapter
```
StopFailed(reason: String)
```
Failed to stop the adapter
```
ShutdownTimeout(elapsed_ms: Int)
```
Shutdown timed out
```
SubscriptionFailed(reason: String)
```
Failed to create/manage subscription
```
InvalidConfiguration(reason: String)
```
Invalid configuration provided
```
ResourceExhausted(resource: String)
```
Resource limit reached

AdapterHandle

opaque </>

Opaque handle representing an active transport adapter instance.

Created by adapter.start() and required for all subsequent operations. The handle contains internal state that should not be accessed directly.

pub opaque type AdapterHandle

AdapterOptions

</>

Options for starting an adapter.

pub type AdapterOptions {
  AdapterOptions(
    name: String,
    bind_address: option.Option(String),
    port: option.Option(Int),
    max_payload_bytes: Int,
    connect_timeout_ms: Int,
    telemetry_prefix: String,
    custom: dict.Dict(String, dynamic.Dynamic),
  )
}

Constructors

```
AdapterOptions(
  name: String,
  bind_address: option.Option(String),
  port: option.Option(Int),
  max_payload_bytes: Int,
  connect_timeout_ms: Int,
  telemetry_prefix: String,
  custom: dict.Dict(String, dynamic.Dynamic),
)
```
Arguments

name

Registered name for the adapter process

bind_address

Optional bind address for listening

port

Optional port for network adapters

max_payload_bytes

Maximum payload size in bytes (default: 10MB)

connect_timeout_ms

Connection timeout in milliseconds

telemetry_prefix

Prefix for telemetry events

custom

Adapter-specific custom options

DeliveryCallback

</>

Callback invoked when a message is received.

Arguments:

from - The sender’s address or identifier
payload - The raw message bytes
metadata - Additional delivery information

pub type DeliveryCallback =
  fn(String, BitArray, MessageMetadata) -> Nil

HealthStatus

</>

Health status of a transport adapter.

pub type HealthStatus {
  Up
  Degraded(reason: String)
  Down(reason: String)
}

Constructors

```
Up
```
Adapter is fully operational
```
Degraded(reason: String)
```
Adapter is operational but degraded (e.g., high latency, some peers unreachable)
```
Down(reason: String)
```
Adapter is down and cannot send/receive messages

MessageMetadata

</>

Metadata associated with an incoming message.

pub type MessageMetadata {
  MessageMetadata(
    received_at_ms: Int,
    transport_latency_ms: option.Option(Int),
    peer_address: option.Option(String),
    correlation_id: option.Option(String),
  )
}

Constructors

MessageMetadata(
  received_at_ms: Int,
  transport_latency_ms: option.Option(Int),
  peer_address: option.Option(String),
  correlation_id: option.Option(String),
)

SendError

</>

Classification of send errors for retry/backoff policies.

pub type SendError {
  InvalidPeer(peer: String)
  SerializationError(reason: String)
  ConnectionClosed(peer: String)
  Backpressure(queue_size: Int)
  PayloadTooLarge(size: Int, max: Int)
  Timeout(elapsed_ms: Int)
  AdapterFailure(reason: String)
}

Constructors

```
InvalidPeer(peer: String)
```
Peer identifier is invalid or unknown
```
SerializationError(reason: String)
```
Failed to serialize payload
```
ConnectionClosed(peer: String)
```
Connection to peer is closed
```
Backpressure(queue_size: Int)
```
Transport experiencing backpressure
```
PayloadTooLarge(size: Int, max: Int)
```
Payload exceeds maximum allowed size
```
Timeout(elapsed_ms: Int)
```
Operation timed out
```
AdapterFailure(reason: String)
```
Internal adapter failure

SendOptions

</>

Options for send/broadcast operations.

pub type SendOptions {
  SendOptions(
    timeout_ms: option.Option(Int),
    priority: option.Option(Int),
    reliable: Bool,
    correlation_id: option.Option(String),
  )
}

Constructors

```
SendOptions(
  timeout_ms: option.Option(Int),
  priority: option.Option(Int),
  reliable: Bool,
  correlation_id: option.Option(String),
)
```
Arguments

timeout_ms

Operation timeout in milliseconds

priority

Message priority (higher = more urgent)

reliable

Whether to use reliable delivery

correlation_id

Correlation ID for request/response tracking

SubscriptionId

opaque </>

Subscription identifier returned by subscribe().

Use this with unsubscribe() to stop receiving messages.

pub opaque type SubscriptionId

Values

handle_id

</>

pub fn handle_id(handle: AdapterHandle) -> String

Get the handle’s identifier (the name it was registered with).

handle_state

</>

pub fn handle_state(handle: AdapterHandle) -> dynamic.Dynamic

Get the handle’s internal state.

Used by adapter implementations to retrieve their actor Subject.

is_permanent_error

</>

pub fn is_permanent_error(error: SendError) -> Bool

Check if an error is permanent and should not be retried.

Permanent errors indicate a fundamental problem that won’t be fixed by retrying, such as invalid input or configuration.

is_transient_error

</>

pub fn is_transient_error(error: SendError) -> Bool

Check if an error is transient and should be retried.

Transient errors are temporary conditions that may resolve themselves, such as network blips or temporary overload.

new_handle

</>

pub fn new_handle(
  id: String,
  state: dynamic.Dynamic,
) -> AdapterHandle

Create a new adapter handle with an identifier and internal state.

This is typically called by adapter implementations, not user code.

new_subscription_id

</>

pub fn new_subscription_id(id: String) -> SubscriptionId

Create a new subscription ID.

subscription_id_value

</>

pub fn subscription_id_value(id: SubscriptionId) -> String

Extract the string value from a subscription ID.