NodeWire.Server (NodeWire v0.1.0)

Copy Markdown View Source

Supervised TLS server with monitored, identity-addressed connections.

Summary

Functions

Builds a supervisor child spec, validating the endpoint options. See NodeWire.

Looks up an authenticated identity; returns :error if absent or unavailable.

Lists connection snapshots, including connections still initializing.

Requests CLOSE and disconnects an identity (default reason :normal).

Returns the bound TCP port, useful with port 0. Exits if the listener is unavailable.

Sends a declared message to an authenticated identity.

Starts a linked TLS server supervisor. Accepts the endpoint options in NodeWire.

Functions

child_spec(init_arg)

@spec child_spec(NodeWire.options()) :: Supervisor.child_spec()

Builds a supervisor child spec, validating the endpoint options. See NodeWire.

connection(server, identity)

@spec connection(Supervisor.supervisor(), String.t()) ::
  {:ok, NodeWire.Conn.t()} | :error

Looks up an authenticated identity; returns :error if absent or unavailable.

connections(server)

@spec connections(Supervisor.supervisor()) :: [NodeWire.Conn.t()]

Lists connection snapshots, including connections still initializing.

Filter by the configured ready phase before dispatching work. Snapshots can become stale immediately. Exits if the server or registry is unavailable.

disconnect(server, identity, reason \\ :normal)

@spec disconnect(Supervisor.supervisor(), String.t(), atom()) ::
  :ok | {:error, :not_connected | {:outcome_unknown, :timeout}}

Requests CLOSE and disconnects an identity (default reason :normal).

Reasons outside the wire allowlist become :protocol_error. The local close call waits up to 5,000 ms; a timeout has an unknown outcome. Remote receipt of CLOSE is not acknowledged. Returns :not_connected when absent.

port(server)

Returns the bound TCP port, useful with port 0. Exits if the listener is unavailable.

send(server, identity, message, opts \\ [])

Sends a declared message to an authenticated identity.

Options: :timeout_ms (default 5,000) and :on_sent (an arbitrary tracking tag). A tag invokes NodeWire.Handler.handle_sent/3 after the local write. Returns {:error, :not_connected} when the identity cannot be resolved. Phase and validation checks run before writing. See NodeWire for delivery, admission and unknown-outcome semantics. Do not call synchronously from the target connection's handler; return a send action instead.

start_link(c)

@spec start_link(NodeWire.options()) :: Supervisor.on_start()

Starts a linked TLS server supervisor. Accepts the endpoint options in NodeWire.

Returns once the listener starts; peer authentication and readiness happen later. Invalid configuration raises. Listener startup failures return errors.