NodeWire.Handler behaviour (NodeWire v0.1.0)

Copy Markdown View Source

Application callbacks for a connection owner process.

use NodeWire.Handler installs the behaviour and overridable defaults. Implement init/1 and handle_message/3, plus server authenticate/3 or client handshake_data/2. Override validate_message/4 for every inbound message: the default rejects all messages. Outgoing validation passes through by default. Other installed lifecycle hooks do nothing.

Callbacks execute sequentially in the connection process. Keep them short; slow callbacks delay socket processing and timers. Server authentication is bounded by the handshake deadline. Delegate long work and return results with NodeWire.Connection.notify/3 from a different process. Never synchronously send or notify your own connection from a callback.

Results and ordered actions

Ordinary callbacks return {:noreply, state}, {:noreply, state, actions} or {:stop, reason, state}. Actions execute in order:

{:noreply, state, [{:send, {:ready, %{}}}, {:phase, :ready}]}

{:send, message, tag: tag} invokes handle_sent/3 after the local write. {:phase, phase} must follow the configured transition graph. {:close, reason} must be the final action. Shapes and phase paths are checked before execution, but writes already performed cannot be rolled back if a later action fails. handle_sent/3 and handle_phase_change/4 cannot return actions.

Exceptions and invalid returns close the connection. Arbitrary rejection data is sanitized. Ordinary {:stop, reason, state} reasons become :application_rejected unless the reason is an atom configured in :reconnect_policy; trust/authentication failures remain permanent.

Summary

Types

Ordered sends, phase transitions and a terminal close.

Callbacks

Authenticates server-side HELLO credentials; required on servers.

Best-effort cleanup on session closure. Defaults to :ok; may be skipped on forced process death.

Handles admitted notifications and ordinary mailbox messages; transport events are intercepted.

Handles a validated application message. Controls never reach this callback.

Runs after ACCEPT, before active application reads; return actions to begin initialization.

Runs before a phase change is published, with a snapshot containing the new phase.

Commits a tracking tag after a local SSL write, before the next frame or send response.

Supplies client HELLO credentials and updated state; required on clients.

Initializes fresh handler state for a connection attempt using :handler_args.

Validates decoded inbound payloads after the phase allowlist check.

Validates or transforms outbound payloads before encoding; defaults to {:ok, payload}.

Types

action()

@type action() ::
  {:send, NodeWire.message()}
  | {:send, NodeWire.message(), [{:tag, term()}]}
  | {:phase, NodeWire.phase()}
  | {:close, atom()}

Ordered sends, phase transitions and a terminal close.

credentials()

@type credentials() :: %{optional(String.t()) => String.t()}

hook_result()

@type hook_result() :: {:noreply, state()} | {:stop, term(), state()}

result()

@type result() :: hook_result() | {:noreply, state(), [action()]}

state()

@type state() :: term()

validation_result()

@type validation_result() :: {:ok, term()} | {:error, term()}

Callbacks

authenticate(credentials, t, state)

(optional)
@callback authenticate(credentials(), NodeWire.Conn.t(), state()) ::
  {:ok, String.t(), state()} | {:error, term(), state()}

Authenticates server-side HELLO credentials; required on servers.

Return a nonempty UTF-8 identity of at most 128 bytes and updated state. Identities must be unique among live connections. Rejection or an invalid result is reported as authentication failure. The snapshot is not negotiated.

handle_disconnect(term, t, state)

@callback handle_disconnect(term(), NodeWire.Conn.t(), state()) :: :ok

Best-effort cleanup on session closure. Defaults to :ok; may be skipped on forced process death.

handle_info(term, t, state)

@callback handle_info(term(), NodeWire.Conn.t(), state()) :: result()

Handles admitted notifications and ordinary mailbox messages; transport events are intercepted.

handle_message(message, t, state)

@callback handle_message(NodeWire.message(), NodeWire.Conn.t(), state()) :: result()

Handles a validated application message. Controls never reach this callback.

handle_negotiated(t, state)

@callback handle_negotiated(NodeWire.Conn.t(), state()) :: result()

Runs after ACCEPT, before active application reads; return actions to begin initialization.

handle_phase_change(phase, phase, t, state)

@callback handle_phase_change(
  NodeWire.phase(),
  NodeWire.phase(),
  NodeWire.Conn.t(),
  state()
) ::
  hook_result()

Runs before a phase change is published, with a snapshot containing the new phase.

Defaults to keeping state. Return no actions. A stop, exception or invalid result closes the connection without publishing the transition.

handle_sent(term, t, state)

@callback handle_sent(term(), NodeWire.Conn.t(), state()) :: hook_result()

Commits a tracking tag after a local SSL write, before the next frame or send response.

Defaults to keeping state. Return no actions. A stop, exception or invalid result closes the connection and makes the send outcome unknown: bytes may already have reached the peer. This is not a remote acknowledgment.

handshake_data(t, state)

(optional)
@callback handshake_data(NodeWire.Conn.t(), state()) ::
  {:ok, credentials(), state()} | {:error, term(), state()}

Supplies client HELLO credentials and updated state; required on clients.

Credentials have at most 16 string fields, 64-byte nonempty keys, 1,024-byte values and 4,096 encoded bytes. Failure rejects the attempt. The connection snapshot is not yet negotiated.

init(term)

@callback init(term()) :: {:ok, state()} | {:stop, term()}

Initializes fresh handler state for a connection attempt using :handler_args.

validate_message(atom, term, t, state)

@callback validate_message(atom(), term(), NodeWire.Conn.t(), state()) ::
  validation_result()

Validates decoded inbound payloads after the phase allowlist check.

Return {:ok, normalized_payload} or reject. Default: {:error, :unvalidated_message}. Codecs do not validate domain semantics; bound sizes and shapes here.

validate_outgoing(atom, term, t, state)

@callback validate_outgoing(atom(), term(), NodeWire.Conn.t(), state()) ::
  validation_result()

Validates or transforms outbound payloads before encoding; defaults to {:ok, payload}.