Errors & Diagnostics

Nalix uses a structured signaling system to communicate runtime failures and protocol violations back to the client. Errors are reported using specialized signal packets (Directive, Handshake, or SessionResume) depending on where the failure occurs in the processing pipeline.

1. Directive Signaling#

The Directive packet is the primary mechanism for reporting errors during packet dispatch and middleware execution. It is one of the built-in signal packet types used by the runtime when the failure happens after normal packet flow has started.

Runtime Dispatch Errors#

When a packet fails to execute at the dispatch level, the runtime can map the failure into a Directive response depending on the handler path and error type.

Trigger Source	Protocol Reason	Advice	Flags
Packet runtime type mismatch	REQUEST_INVALID	FIX_AND_RETRY	NONE
descriptor.CanExecute == false	RATE_LIMITED	RETRY	IS_TRANSIENT
OperationCanceledException	TIMEOUT	RETRY	IS_TRANSIENT
ValidationException / ArgumentException	REQUEST_INVALID	FIX_AND_RETRY	NONE
UnauthorizedAccessException	UNAUTHORIZED	NONE	NONE
CipherException	DECRYPTION_FAILED	REAUTHENTICATE	NONE
NotSupportedException	OPERATION_UNSUPPORTED	NONE	NONE
SocketError.TimedOut	TIMEOUT	RETRY	IS_TRANSIENT
SocketError.ConnectionReset	CONNECTION_RESET	RETRY	IS_TRANSIENT
SocketError.ConnectionRefused	CONNECTION_REFUSED	RETRY	IS_TRANSIENT
SocketError.ConnectionAborted	REMOTE_CLOSED	RETRY	IS_TRANSIENT
SocketError.Shutdown	LOCAL_CLOSED	NONE	NONE
DNS socket errors	DNS_FAILURE	RETRY	IS_TRANSIENT
SocketError.MessageSize	MESSAGE_TOO_LARGE	FIX_AND_RETRY	NONE
Fallback/Unknown Exception	INTERNAL_ERROR	NONE	NONE

---

2. Middleware Errors#

Middlewares can intercept packets and return failure directives before the handler logic is reached. This is used for policy enforcement regarding security, performance, and stability.

PermissionMiddleware#

If a client attempts to send an opcode they are not authorized for:

• Reason: UNAUTHORIZED
• Metadata: arg2 contains the denied opcode value.

RateLimitMiddleware#

If a client exceeds their allocated throughput for a specific opcode or the global connection:

• Reason: RATE_LIMITED
• Advice: RETRY
• Flags: IS_TRANSIENT
• Metadata: -arg0: Target opcode -arg1: RetryAfterMs (milliseconds to wait) -arg2: Remaining credit (if applicable)

TimeoutMiddleware#

If a handler takes longer than the configured maximum execution time:

• Type: TIMEOUT
• Reason: TIMEOUT
• Advice: RETRY
• Flags: IS_TRANSIENT
• Metadata: arg0 contains the timeout duration (divided by 100 for storage).

---

3. Protocol Flow Errors#

Some errors occur during the initial connection setup (Handshake) or session recovery (Session Resume). These use their respective packet types to signal failure before the server terminates the connection.

Handshake Rejection#

Failures during the handshake process use the Handshake packet with Stage = ERROR.

Reason	Meaning
STATE_VIOLATION	Client attempted a handshake on an already authenticated connection.
UNEXPECTED_MESSAGE	Received a handshake packet out of order for the current stage.
MALFORMED_PACKET	The handshake packet could not be parsed (binary corruption).
DECRYPTION_FAILED	Failed to decrypt the proof or cryptographic payload.
SIGNATURE_INVALID	Handshake signature verification failed.
CHECKSUM_FAILED	Integrity check failed for the handshake frame.

Session Resume Rejection#

Failures during session resumption use the SessionResume packet with Stage = RESPONSE.

Reason	Meaning
SERVICE_UNAVAILABLE	Session resumption is disabled or the state store is unavailable.
STATE_VIOLATION	Invalid state transition for resumption (e.g., resuming a non-existent session).
TOKEN_REVOKED	The provided resumption token has been explicitly revoked.
SESSION_EXPIRED	The session state has expired and cannot be recovered.

---

5. Zero-Allocation Transport Exceptions#

To minimize GC pressure during high-frequency network events (including failures), Nalix uses the Throw utility (an internal class in Nalix.Network.Internal) to provide cached, zero-allocation exception instances for common transport scenarios.

Cached Exceptions#

Standard .NET exceptions capture a full stack trace upon instantiation, which is a significant allocation and CPU cost. Throw overrides this behavior for its internal types:

• Overridden StackTrace: Cached instances return a static string (“at Nalix.Network.Internal.Transport (Cached Exception)”) instead of performing a stack crawl.
• Static Reusability: Instances like Throw.GetConnectionReset() and Throw.GetSendFailed() are pre-allocated and reused across all connections. Note that Throw is internal — these cached exceptions are consumed by the framework’s transport layer, not exposed to application code.

Socket Error Mapping#

The Throw.GetSocketError(SocketError) method provides a fast lookup for common SocketError codes, returning cached SocketException instances for:

• ConnectionReset
• ConnectionAborted
• OperationAborted
• Shutdown
• MessageSize
• ProtocolNotSupported

This ensures that even when the underlying OS reports a connection failure, the Nalix runtime remains allocation-free.

---

4. Technical Constants#

• OpCode Normalization: Directive packets always use OpCode = ProtocolOpCode.SYSTEM_CONTROL (0x0001).
• Mapping Logic: Exception-to-reason mapping is part of the runtime dispatch execution path.
• Advice Flags: -RETRY: Suggests the client should attempt the request again. -FIX_AND_RETRY: Suggests the request was malformed and needs correction. -REAUTHENTICATE: Suggests the security context is lost (e.g., session key rotation failed).

Recommended Next Steps#

• Packet System — Serialization and wire format
• Packet Lifecycle — Request path from socket to handler
• Middleware — Buffer vs. packet middleware
• Security Model — Authentication and encryption