Documentation for Redweb 0.13.3. Install that exact version when following these examples.

Understand failures before retrying

Status: included in redweb@0.13.3.

Authentication identifies a visitor. Authorization decides what that visitor may do. Validation checks an input's shape. An application failure means server code or a dependency failed; it is not evidence that the visitor supplied bad credentials.

Redweb keeps these boundaries separate. It does not automatically retry failed actions, undo application writes, or guarantee exactly-once delivery.

Reading a failed connection

Before a WebSocket opens, Redweb sends an HTTP rejection with a fixed Redweb-Error header and Cache-Control: no-store. There is no error body and no callback exception text. Node's ws client can inspect it:

import WebSocket from 'ws';

const socket = new WebSocket('ws://127.0.0.1:8181/match?redwebVersion=1');
socket.on('unexpected-response', (_request, response) => {
    console.error(response.statusCode, response.headers['redweb-error']);
    response.resume();
    socket.terminate();
});
socket.on('error', () => console.error('Connection did not open.'));

This is a Node diagnostic example, not browser code. Native browser WebSocket JavaScript cannot inspect handshake status or response headers. Use the browser network inspector during development and your application's normal HTTP sign-in/status flow for user-facing guidance. A generic browser socket error alone cannot distinguish rejected credentials from networking, origin, protocol, or server failures. Proxies may replace or strip responses.

Accepted placement redirects remain HTTP 307 with the validated Location, no error code, and no-store caching. A redirect is not proof that the destination will admit the same credentials. Never forward credentials to arbitrary redirect destinations.

Raw route authentication preserves its existing contract: only literal false rejects the identity; application-owned principal objects remain supported. Page authentication requires its documented primitive identity. Do not rely on a raw callback returning undefined to deny access.

Page requests

Page HTTP failures return { "error": { "code": "...", "message": "..." } } with Cache-Control: private, no-store. Authentication and authorization use the categories above. PAGE_CAPACITY is 503; PAGE_FAILED is a sanitized 500 for construction, loading, or rendering failures, including public pages. Unknown application error text and Express development stacks are not returned. Typed errors are reconstructed from the fixed catalogue rather than trusting mutable status/message fields.

If the response is already closed, Redweb does not write another response. If headers were already sent by application middleware, the connection is closed instead of appending a misleading JSON error. Redweb cannot retract content your middleware already sent or sanitize arbitrary HTTP routes you mount yourself.

Actions and established sockets

Once connected, failures use the existing protocol error envelope and request ID when available. Unversioned room-entry failures use { code, error }; other legacy unversioned failures retain { error } without a structured code. The client may still disconnect before receiving the response. Typed permission/input errors are normalized again at the final send boundary, so application catch/rethrow code cannot accidentally expose appended private exception text.

An input validator, identity lookup, or permission callback can itself perform external work. A “method was not invoked” result does not promise those callbacks had no side effects. Keep validators and policies free of writes where practical; use explicit idempotency keys and durable transactions for application operations that may be retried.

Those non-invocation guarantees describe failures produced by Redweb's validation and permission gates. They do not apply to application code deliberately throwing an internal typed error or sending the same diagnostic after its own work has begun.

Deadlines, cancellation, and disclosure limits

Raw admission shares the bounded-operation implementation used by other policy/validation paths. It checks the deadline between origin, identity, and placement stages, so a timed-out or cancelled stage cannot start the next stage after eventually returning. It retains its actual evaluation promise in admission accounting until that evaluation settles. Synchronous JavaScript cannot be interrupted; a callback that blocks the event loop delays timeout observation, but an overdue result cannot admit a connection.

Page identity and permission evaluation also have their own deadlines and session/revocation signals. The outer raw-admission deadline does not forcibly stop those nested callbacks or their external I/O. Cancellation of observation is not cancellation of database/network side effects. Honor available signals, set downstream timeouts, and never treat this as a sandbox for untrusted callback code.

Default handler responses are sanitized. Raw routes deliberately configured with exposeErrors: true opt into disclosing handler exception text; do not enable that in production. Existing application/logger hooks may receive original errors and client metadata, so logs require access controls and redaction. The new upgrade pipeline logs only fixed admission failure details, and a throwing logger cannot prevent upgrade rejection or reservation cleanup.

See private rooms, socket contracts, and operating socket services for their complete limits. A successful send means accepted by the local transport, not acknowledged application delivery.