distribute - v2.1.0

distribute/crypto

Crypto facade - singleton per node.

This module provides the public API for cryptographic operations in the distribute cluster. It follows the same facade pattern as transport and discovery modules.

Architecture

┌─────────────────────────────────────────────────────────┐
│                    crypto.gleam                         │
│                   (Facade/API)                          │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│                  CryptoAdapter                          │
│               (Behaviour contract)                      │
└─────────────────────────────────────────────────────────┘
                  ▲                    ▲
                  │                    │
    ┌─────────────┴────────┐   ┌──────┴───────────┐
    │    noop_adapter      │   │  (future: TLS,   │
    │    (development)     │   │   NaCl, etc.)    │
    └──────────────────────┘   └──────────────────┘

Usage

import distribute/crypto
import gleam/option.{Some}

// Start crypto layer (typically done in node_builder)
let assert Ok(handle) = crypto.start_link(crypto.default_options("my_crypto"))

// Initiate handshake with remote node
let local = "node_a@host"
let remote = "node_b@host"
let assert Ok(result) = crypto.handshake_start(local, remote, option.None)

// Encrypt message
let assert Some(ctx) = crypto.secure_context(remote)
let assert Ok(ciphertext) = crypto.encrypt(ctx, <<"hello">>)

Lifecycle

  1. Call start_link() or use child_spec() with a supervisor
  2. Provider initializes and registers with registry
  3. Use handshake_start/3 when connecting to remote nodes
  4. Use encrypt/2 and decrypt/2 for secure messaging
  5. Call shutdown() for graceful cleanup

Values

child_spec

</> 
pub fn child_spec() -> supervision.ChildSpecification(
  types.ProviderHandle,
)

Create a child specification for OTP supervision.

Uses the noop adapter by default. For production, you should use a proper crypto adapter.

child_spec_with_adapter

</> 
pub fn child_spec_with_adapter(
  provider: adapter.CryptoAdapter,
  options: types.ProviderOptions,
) -> supervision.ChildSpecification(types.ProviderHandle)

Create a child specification with a custom adapter. Note: For custom adapters, use the adapter’s own child_spec function.

child_spec_with_options

</> 
pub fn child_spec_with_options(
  options: types.ProviderOptions,
) -> supervision.ChildSpecification(types.ProviderHandle)

Create a child specification with custom options.

decrypt

</> 
pub fn decrypt(
  ctx: types.SecureContext,
  ciphertext: BitArray,
) -> Result(BitArray, types.CryptoError)

Decrypt a message using the secure context.

default_name

</> 
pub const default_name: String

Default name for the crypto provider.

default_options

</> 
pub fn default_options(name: String) -> types.ProviderOptions

Create default provider options.

development_options

</> 
pub fn development_options(name: String) -> types.ProviderOptions

Create development options with debug logging.

encrypt

</> 
pub fn encrypt(
  ctx: types.SecureContext,
  plaintext: BitArray,
) -> Result(BitArray, types.CryptoError)

Encrypt a message using the secure context.

get_handle

</> 
pub fn get_handle() -> Result(types.ProviderHandle, Nil)

Get the current provider handle.

get_handle_by_name

</> 
pub fn get_handle_by_name(
  name: String,
) -> Result(types.ProviderHandle, Nil)

Get a handle by name.

handshake_continue

</> 
pub fn handshake_continue(
  state: types.HandshakeState,
  message: types.HandshakeMessage,
) -> Result(types.HandshakeResult, types.CryptoError)

Continue a handshake with a message from the remote node.

handshake_start

</> 
pub fn handshake_start(
  local: String,
  remote: String,
  initial: option.Option(types.HandshakeMessage),
) -> Result(types.HandshakeResult, types.CryptoError)

Start a cryptographic handshake with a remote node.

Returns either:

  • InProgress(state, message) - Send message to remote, await response
  • Established(context) - Handshake complete (e.g., noop adapter)

health

</> 
pub fn health() -> types.HealthStatus

Get the health status of the crypto provider.

metrics

</> 
pub fn metrics() -> types.CryptoMetrics

Get metrics from the crypto provider.

rekey

</> 
pub fn rekey(node: String) -> Result(Nil, types.CryptoError)

Trigger a rekey operation for a node.

This rotates the session key while maintaining the connection.

secure_context

</> 
pub fn secure_context(
  node: String,
) -> option.Option(types.SecureContext)

Get the secure context for a node (if handshake completed).

shutdown

</> 
pub fn shutdown() -> Result(Nil, types.CryptoError)

Shutdown the crypto provider.

</> 
pub fn start_link(
  options: types.ProviderOptions,
) -> Result(types.ProviderHandle, types.CryptoError)

Start the crypto provider with default settings.

</> 
pub fn start_link_with_adapter(
  provider: adapter.CryptoAdapter,
  options: types.ProviderOptions,
) -> Result(types.ProviderHandle, types.CryptoError)

Start the crypto provider with a custom adapter.

✨ Search Document