Skip to content

errors.md

Latest commit

 

History

History
72 lines (51 loc) · 3.07 KB

errors.md

File metadata and controls

72 lines (51 loc) · 3.07 KB
Raw

Errors & degrade

magnet returns typed errors; steady state never panics. Pool exhaustion is a defined, observable event, never a crash.

Send errors (Session.SendError)

Error When
error.MessageTooLarge the serialized message exceeds max_payload (or a block exceeds max_payload × max_fragments)
error.Backpressure the channel's send window is full and the degrade policy is .backpressure 
session.send(.chat, msg) catch |e| switch (e) {
    error.Backpressure => { /* try again next tick */ },
    error.MessageTooLarge => { /* split it, or raise max_payload */ },
};

Degrade policies

When a queue fills, Config.degrade decides the behaviour instead of erroring:

  • on_send_queue_full: .backpressure (return the error), .drop_new (silently drop this message), or .drop_oldest (evict the oldest unacked to make room).
  • on_reassembly_full: .drop or .error_out.

Every drop calls tracer.onDrop(peer, reason) - so "silently fell behind" is observable, never silent. Reasons: send_queue_full, inbox_full, reassembly_full, malformed, replay, too_old.

broadcast preserves its fire-and-forget convenience contract. Use broadcastChecked / broadcastRawChecked when the caller needs counts of successful, backpressured, and oversized sends.

receiveChecked distinguishes error.Malformed from an empty typed receive queue. The nullable receive is the intentional convenience form when malformed input should be counted and discarded by the transport. Raw/block variants follow the same naming: receiveRawChecked, receiveBlockChecked, and their endpoint FromChecked forms.

Protocol violations

A protocol violation (an ack of an unsent/filtered packet number, a replayed datagram, a malformed frame) drops the datagram or closes the connection with a counted reason - it never crashes. session.isClosed() reports a closed connection; endpoint.reapClosed() frees the slot and emits a disconnected event.

Token verification (proto.conn.token.VerifyError)

error.BadProtocol · error.Expired · error.BadToken - returned when the server opens a connect token.

Identity (proto.conn.identity.VerifyError)

error.BadSignature · error.Expired - returned when verifying an Ed25519 cert.

Streams

Transfer.start reports duplicate IDs, size/metadata limits, or exhausted transfer slots. feed rejects malformed/rejected/corrupt chunks and reports StorageBusy when a retained async sink operation must finish first. error.WouldBlock from storage is temporary; drive pollStorage and retry the consumed frame. Checkpoint restore additionally rejects wrong direction/options/identity and duplicate active IDs.

Live streams use the same storage errors plus TooLarge when an unknown-length source crosses chunk_size * max_chunks. A callback error other than WouldBlock marks the transfer failed.

Resumption (proto.conn.resumption.Server.Error)

InvalidTicket · Expired · BadProtocol · MissingCapability · EarlyDataTooLarge · Replay · UnsafeEarlyData. None allocate an Endpoint slot.