types

Discovery layer type definitions.

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

Type Categories

Handles - Opaque references to running adapters
Status - Health and subscription state
Errors - Structured error types for operations
Peers - Peer information and metadata

Types

AdapterHandle

opaque </>

Opaque handle representing an active discovery 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 a discovery adapter.

pub type AdapterOptions {
  AdapterOptions(
    name: String,
    sync_interval_ms: Int,
    sync_timeout_ms: Int,
    telemetry_prefix: String,
    seed_peers: List(String),
    retry_config: RetryConfig,
    on_peer_up: option.Option(
      fn(String, dict.Dict(String, String)) -> Nil,
    ),
    custom: dict.Dict(String, dynamic.Dynamic),
  )
}

Constructors

```
AdapterOptions(
  name: String,
  sync_interval_ms: Int,
  sync_timeout_ms: Int,
  telemetry_prefix: String,
  seed_peers: List(String),
  retry_config: RetryConfig,
  on_peer_up: option.Option(
    fn(String, dict.Dict(String, String)) -> Nil,
  ),
  custom: dict.Dict(String, dynamic.Dynamic),
)
```
Arguments

name

Registered name for the adapter process

sync_interval_ms

How often to sync with discovery backend (ms)

sync_timeout_ms

Timeout for sync operations (ms)

telemetry_prefix

Prefix for telemetry events

seed_peers

Initial seed peers for bootstrap

retry_config

Retry/backoff configuration for sync failures

on_peer_up

Optional hook to call on PeerUp (e.g., trigger handshake)

custom

Adapter-specific custom options

DiscoveryError

</>

Errors from discovery operations.

pub type DiscoveryError {
  StartFailed(reason: String)
  StopFailed(reason: String)
  ShutdownTimeout(elapsed_ms: Int)
  SyncFailed(reason: String)
  PeerNotFound(peer: String)
  InvalidConfiguration(reason: String)
  Timeout(elapsed_ms: Int)
  SubscriptionFailed(reason: 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
```
SyncFailed(reason: String)
```
Failed to sync with backend
```
PeerNotFound(peer: String)
```
Peer not found
```
InvalidConfiguration(reason: String)
```
Invalid configuration
```
Timeout(elapsed_ms: Int)
```
Operation timed out
```
SubscriptionFailed(reason: String)
```
Subscription error

DiscoveryEvent

</>

Events emitted by discovery adapters.

pub type DiscoveryEvent {
  PeerUp(peer: String, metadata: dict.Dict(String, String))
  PeerUpdate(peer: String, metadata: dict.Dict(String, String))
  PeerDown(peer: String, reason: String)
}

Constructors

PeerUp(peer: String, metadata: dict.Dict(String, String))

A new peer has been discovered

PeerUpdate(peer: String, metadata: dict.Dict(String, String))

A known peer’s metadata has changed

```
PeerDown(peer: String, reason: String)
```
A peer has left or become unavailable

DiscoveryMetrics

</>

Discovery metrics for observability.

pub type DiscoveryMetrics {
  DiscoveryMetrics(
    sync_count: Int,
    sync_failures: Int,
    last_sync_duration_ms: Int,
    events_emitted: Int,
    known_peers_count: Int,
    error_rate: Float,
  )
}

Constructors

```
DiscoveryMetrics(
  sync_count: Int,
  sync_failures: Int,
  last_sync_duration_ms: Int,
  events_emitted: Int,
  known_peers_count: Int,
  error_rate: Float,
)
```
Arguments

sync_count

Total sync operations performed

sync_failures

Total sync failures

last_sync_duration_ms

Last sync duration in milliseconds

events_emitted

Total events emitted

known_peers_count

Current known peers count

error_rate

Error rate (failures / total syncs)

EventCallback

</>

Callback invoked when a discovery event occurs.

pub type EventCallback =
  fn(DiscoveryEvent) -> Nil

HealthInfo

</>

Extended health info with sync details.

pub type HealthInfo {
  HealthInfo(
    status: HealthStatus,
    last_sync_time_ms: option.Option(Int),
    last_error: option.Option(String),
    known_peers_count: Int,
  )
}

Constructors

HealthInfo(
  status: HealthStatus,
  last_sync_time_ms: option.Option(Int),
  last_error: option.Option(String),
  known_peers_count: Int,
)

HealthStatus

</>

Health status of a discovery 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
```
Down(reason: String)
```
Adapter is down

PeerId

</>

Peer identifier.

pub type PeerId =
  String

PeerInfo

</>

Complete peer information.

pub type PeerInfo {
  PeerInfo(id: String, metadata: dict.Dict(String, String))
}

Constructors

PeerInfo(id: String, metadata: dict.Dict(String, String))

PeerMetadata

</>

Peer metadata as key-value pairs.

pub type PeerMetadata =
  dict.Dict(String, String)

RetryConfig

</>

Retry/backoff configuration for transient failures.

pub type RetryConfig {
  RetryConfig(
    max_attempts: Int,
    initial_backoff_ms: Int,
    max_backoff_ms: Int,
    backoff_multiplier: Float,
  )
}

Constructors

```
RetryConfig(
  max_attempts: Int,
  initial_backoff_ms: Int,
  max_backoff_ms: Int,
  backoff_multiplier: Float,
)
```
Arguments

max_attempts

Maximum number of retry attempts

initial_backoff_ms

Initial backoff delay in milliseconds

max_backoff_ms

Maximum backoff delay in milliseconds

backoff_multiplier

Multiplier for exponential backoff (e.g., 2.0 doubles each time)

SubscriptionId

opaque </>

Subscription identifier returned by subscribe().

pub opaque type SubscriptionId

Values

default_retry_config

</>

pub fn default_retry_config() -> RetryConfig

Default retry configuration.

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: DiscoveryError) -> Bool

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

is_transient_error

</>

pub fn is_transient_error(error: DiscoveryError) -> Bool

Check if an error is transient and should be retried.

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.

Type Categories

Constructors

Arguments

Constructors

Constructors

Constructors

Arguments

Constructors

Constructors

Constructors

Constructors

Arguments