Outcomes and ACKs

Explicitly choose between an ACK, a caller event, no reply, or connection closure as an action outcome.

A message action returns Result<O, WebSocketActionError>. O is an explicit outcome determining what the framework sends. () or Result<(), _> is not an implicit reply for a message action.

Choose an outcome#

Outcome	Behavior
`Ack::new(dto)`	Correlated JSON ACK
`Ack::text(text)`	Typed text ACK
`Ack::binary(bytes)`	Typed binary ACK
`Emit::new("chat:received", dto)`	A new event to the caller
`NoReply`	Finish without an additional terminal application frame
`CloseConnection::normal(reason)`	Normal connection closure
`CloseConnection::policy(reason)`	Closure due to policy

Emit does not broadcast. Use client targets inside the action to send to other clients. NoReply does not undo earlier sends or database operations.

ACK authority#

The incoming event must carry an ack_id. The framework replies with the same ID; if it is missing, WS_MISSING_ACK_AUTHORITY occurs and a healthy connection may remain open. The server does not invent a new ACK ID.

#[message("confirm")]
async fn confirm(&self, Payload(input): Payload<Greeting>)
    -> Result<Ack<Greeting>, WebSocketActionError>
{
    Ok(Ack::new(input))
}

The complete imports and DTO are in the first application. An ACK is a correlated response for the action outcome you chose; it is not delivery confirmation from every recipient of every server broadcast.

Binary content versus event transport#

Ack::new(Vec<u8>) produces a JSON array of numbers. Choose Ack::binary for byte content. ClientProxy::send_binary carries the envelope inside a WebSocket Binary frame. These choices operate at different layers.

Emit::new accepts a full route; it cannot send an event to another namespace. Target namespace validation is enforced at the outbound boundary as well. Envelopes and codecs explain how content is transported.

Which milestone does success establish?#

Preparing an action result, normal middleware exits, scope cleanup, terminal-frame admission, and peer delivery are separate milestones. Serialization, encoding, or sending may fail even after the action returns Ok.

An ACK can be lost after a successful database commit. If the client resends the operation, the application must rely on its request-ID/idempotency model. The framework does not guarantee exactly one business effect or that the peer processed the message. Choose error and Close behavior together with the errors page.