adapter

Discovery Adapter contract and utilities.

This module defines the behaviour contract that all discovery adapters must implement, along with helper functions for creating default options.

Adapter Contract

A discovery adapter handles peer discovery and membership tracking. It provides:

Lifecycle management (start/stop)
Event-driven membership updates (subscribe/unsubscribe)
Membership queries (snapshot/lookup)
Health monitoring

Implementing an Adapter

To implement a custom adapter, create a module that provides a function returning a DiscoveryAdapter record with all required functions:

pub fn new() -> DiscoveryAdapter {
  DiscoveryAdapter(
    start: my_start,
    stop: my_stop,
    subscribe: my_subscribe,
    unsubscribe: my_unsubscribe,
    snapshot: my_snapshot,
    lookup: my_lookup,
    health: my_health,
  )
}

See distribute/discovery/beam_adapter for a reference implementation.

Types

DiscoveryAdapter

</>

Discovery adapter behaviour contract.

All discovery implementations must provide these 7 core functions.

start - Initialize and start the adapter
stop - Graceful shutdown with timeout
subscribe - Register callback for membership events
unsubscribe - Remove a subscription
snapshot - Get current membership state
lookup - Get metadata for a specific peer
health - Get current adapter health status

pub type DiscoveryAdapter {
  DiscoveryAdapter(
    start: fn(types.AdapterOptions) -> Result(
      types.AdapterHandle,
      types.DiscoveryError,
    ),
    stop: fn(types.AdapterHandle, Int) -> Result(
      Nil,
      types.DiscoveryError,
    ),
    subscribe: fn(
      types.AdapterHandle,
      fn(types.DiscoveryEvent) -> Nil,
    ) -> Result(types.SubscriptionId, types.DiscoveryError),
    unsubscribe: fn(types.AdapterHandle, types.SubscriptionId) -> Result(
      Nil,
      types.DiscoveryError,
    ),
    snapshot: fn(types.AdapterHandle) -> Result(
      List(types.PeerInfo),
      types.DiscoveryError,
    ),
    lookup: fn(types.AdapterHandle, String) -> Result(
      types.PeerInfo,
      types.DiscoveryError,
    ),
    health: fn(types.AdapterHandle) -> types.HealthStatus,
    metrics: fn(types.AdapterHandle) -> types.DiscoveryMetrics,
  )
}

Constructors

```
DiscoveryAdapter(
  start: fn(types.AdapterOptions) -> Result(
    types.AdapterHandle,
    types.DiscoveryError,
  ),
  stop: fn(types.AdapterHandle, Int) -> Result(
    Nil,
    types.DiscoveryError,
  ),
  subscribe: fn(
    types.AdapterHandle,
    fn(types.DiscoveryEvent) -> Nil,
  ) -> Result(types.SubscriptionId, types.DiscoveryError),
  unsubscribe: fn(types.AdapterHandle, types.SubscriptionId) -> Result(
    Nil,
    types.DiscoveryError,
  ),
  snapshot: fn(types.AdapterHandle) -> Result(
    List(types.PeerInfo),
    types.DiscoveryError,
  ),
  lookup: fn(types.AdapterHandle, String) -> Result(
    types.PeerInfo,
    types.DiscoveryError,
  ),
  health: fn(types.AdapterHandle) -> types.HealthStatus,
  metrics: fn(types.AdapterHandle) -> types.DiscoveryMetrics,
)
```
Arguments

start

Start the adapter with provided options. Returns an opaque handle for subsequent operations.

stop

Stop the adapter gracefully within the timeout period (milliseconds).

The adapter should cancel background tasks and ensure no further events are delivered after completion.

subscribe

Subscribe to membership events.

Register a callback to receive PeerUp, PeerUpdate, and PeerDown events. Callbacks must execute quickly; heavy processing should be async.

unsubscribe

Unsubscribe from membership events.

snapshot

Get a consistent snapshot of currently known peers.

Returns a list of all peers with their current metadata.

lookup

Lookup metadata for a specific peer.

Returns the peer’s metadata if known, PeerNotFound otherwise.

health

Get current health status.

Returns lightweight snapshot: Up, Degraded(reason), or Down(reason).

metrics

Get adapter metrics for observability.

Returns current metrics snapshot including sync stats and error rates.

Values

default_options

</>

pub fn default_options(name: String) -> types.AdapterOptions

Create default adapter options.

Provides sensible defaults:

sync_interval_ms: 5000 (5 seconds)
sync_timeout_ms: 10000 (10 seconds)
telemetry_prefix: “discovery”
retry_config: 3 attempts with exponential backoff