# `NodeWire.Handler`
[🔗](https://github.com/c2bw/nodewire/blob/v0.1.0/lib/node_wire/handler.ex#L1)

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.

# `action`

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

Ordered sends, phase transitions and a terminal close.

# `credentials`

```elixir
@type credentials() :: %{optional(String.t()) =&gt; String.t()}
```

# `hook_result`

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

# `result`

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

# `state`

```elixir
@type state() :: term()
```

# `validation_result`

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

# `authenticate`
*optional* 

```elixir
@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`

```elixir
@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`

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

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

# `handle_message`

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

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

# `handle_negotiated`

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

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

# `handle_phase_change`

```elixir
@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`

```elixir
@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`
*optional* 

```elixir
@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`

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

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

# `validate_message`

```elixir
@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`

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

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*
