redweb 0.7.7 → 0.9.0

package/client.d.ts

@@ -0,0 +1,42 @@
+// Generated from src/ws/protocol-schema.json by scripts/generate-protocol-types.js.
+export type RedWebProtocolErrorCode =
+    | 'INVALID_MESSAGE'
+    | 'UNKNOWN_HANDLER'
+    | 'HANDLER_FAILED'
+    | 'BINARY_UNSUPPORTED'
+    | 'RATE_LIMITED'
+    | 'QUEUE_FULL'
+    | 'CAPACITY_REACHED'
+    | 'INITIALIZATION_FAILED';
+
+export interface ProtocolMetadata {
+    requestId?: string;
+    sequence?: number;
+}
+
+export interface ProtocolEnvelope<T = unknown> extends ProtocolMetadata {
+    v: string;
+    type: string;
+    payload: T;
+}
+
+export interface ProtocolErrorEnvelope extends ProtocolMetadata {
+    v: string;
+    type: 'error';
+    error: { code: RedWebProtocolErrorCode | string; message: string };
+}
+
+export interface SendableSocket {
+    send(data: string): unknown;
+}
+
+export class ProtocolClient {
+    constructor(socket: SendableSocket, version: string);
+    readonly socket: SendableSocket;
+    readonly version: string;
+    envelope<T>(type: string, payload: T, metadata?: ProtocolMetadata): ProtocolEnvelope<T>;
+    send<T>(type: string, payload: T, metadata?: ProtocolMetadata): void;
+    parse<T = unknown>(input: string | Uint8Array | ArrayBuffer | { data: string | Uint8Array | ArrayBuffer }): ProtocolEnvelope<T> | ProtocolErrorEnvelope;
+}
+
+export const ERROR_CODES: Readonly<Record<RedWebProtocolErrorCode, RedWebProtocolErrorCode>>;

package/client.js

@@ -0,0 +1,55 @@
+const schema = require('./src/ws/protocol-schema.json');
+const { validateEnvelope } = require('./src/ws/protocol-validation');
+
+const ERROR_CODES = Object.freeze(Object.fromEntries(schema.errorCodes.map(code => [code, code])));
+
+function boundedString(value, name, maxLength) {
+    if (typeof value !== 'string' || !value || value.length > maxLength) {
+        throw new TypeError(`${name} must be a non-empty string of at most ${maxLength} characters.`);
+    }
+    return value;
+}
+
+class ProtocolClient {
+    constructor(socket, version) {
+        if (!socket || typeof socket.send !== 'function') throw new TypeError('socket must provide send(data).');
+        this.socket = socket;
+        this.version = boundedString(version, 'version', 64);
+    }
+
+    envelope(type, payload, metadata = {}) {
+        const message = { v: this.version, type: boundedString(type, 'type', 256), payload };
+        if (metadata.requestId !== undefined) {
+            message.requestId = boundedString(metadata.requestId, 'requestId', 256);
+        }
+        if (metadata.sequence !== undefined) {
+            if (!Number.isSafeInteger(metadata.sequence) || metadata.sequence < 0) {
+                throw new TypeError('sequence must be a non-negative safe integer.');
+            }
+            message.sequence = metadata.sequence;
+        }
+        return message;
+    }
+
+    send(type, payload, metadata) {
+        this.socket.send(JSON.stringify(this.envelope(type, payload, metadata)));
+    }
+
+    parse(input) {
+        const raw = input && typeof input === 'object' && 'data' in input ? input.data : input;
+        let serialized;
+        if (typeof raw === 'string') serialized = raw;
+        else if (raw instanceof ArrayBuffer) serialized = new TextDecoder().decode(new Uint8Array(raw));
+        else if (ArrayBuffer.isView(raw)) serialized = new TextDecoder().decode(
+            new Uint8Array(raw.buffer, raw.byteOffset, raw.byteLength)
+        );
+        else serialized = raw.toString();
+        const message = JSON.parse(serialized);
+        if (!validateEnvelope(message, this.version)) {
+            throw new TypeError('Received an invalid Redweb protocol envelope.');
+        }
+        return message;
+    }
+}
+
+module.exports = { ProtocolClient, ERROR_CODES };

package/docs/MULTIPLAYER_OPERATIONS.md

@@ -0,0 +1,50 @@
+# Multiplayer operations
+
+Redweb exposes small composition points and leaves deployment policy to the game. These examples are deliberately infrastructure-neutral.
+
+## Readiness and shutdown
+
+Expose `socketServer.isReady()` from the HTTP stack used by the orchestrator. On termination, call `beginDrain()` first, stop external placement to the node, then call and await `shutdown()`. New upgrades receive `503` after draining begins.
+
+```js
+app.get('/ready', (_request, response) => {
+  response.sendStatus(socketServer.isReady() ? 200 : 503)
+})
+
+process.once('SIGTERM', async () => {
+  socketServer.beginDrain()
+  await socketServer.shutdown()
+})
+```
+
+If `drainHandlers` is enabled, handlers should observe `socket.context.signal` and return promptly. Set the platform termination grace period above the application's maximum cooperative handler time plus `shutdownTimeoutMs`.
+
+## Placement and partitions
+
+The admission `place(principal, request, context)` hook can return another node's `ws`/`wss` URL before upgrade. Keep placement decisions short-lived and retryable. A redirect is not a reservation: the destination must still authenticate, enforce capacity, and reject stale placement.
+
+Treat the distribution adapter as ephemeral fan-out. During broker or network partitions, pause affected matches, continue from one authoritative owner, or reconcile from durable application state. Do not treat adapter delivery or its bounded deduplication window as persistence.
+
+Adapter lifecycle and publish methods receive an optional final `AbortSignal`. Observe it in broker clients that support cancellation. Redweb compensates late startup and subscription completion, but a publish that the broker has already accepted cannot be recalled.
+
+## Capacity signals
+
+Alert on rejected connections, rate-limited messages, full queues, handler failures, active connections, and readiness. Metrics intentionally contain only the route label. Join high-cardinality player, room, and match diagnostics in application logs or traces under the studio's own privacy and retention policy.
+
+Size `maxConnections`, `maxBufferedBytes`, `maxPendingMessages`, room limits, session limits, adapter event limits, and codec byte limits from measured budgets. Run the included verification scripts on the deployment's Node version and instance class before changing those ceilings.
+
+Redweb limits the number and lifetime of session records, but it deliberately does not inspect application session data. Keep that data small, schema-validated, and free of authoritative state that belongs in durable storage.
+
+## Verification
+
+Run `npm test` for unit, real HTTP/WebSocket/WSS integration, fuzz, type-generation, and 100% coverage gates. The additional production gates are:
+
+```bash
+npm run verify:load
+npm run verify:memory
+npm run verify:recovery
+npm run verify:soak
+npm run verify:overhead -- /path/to/redweb-0.8-baseline
+```
+
+The soak defaults to 60 minutes. Shorter durations are useful for CI smoke checks but are not release evidence.

package/docs/PRODUCTION_READINESS.md

@@ -0,0 +1,68 @@
+# Multiplayer production-readiness contract
+
+Redweb remains a small transport foundation. Applications own game rules, authoritative state, matchmaking, databases, and identity providers. Redweb owns bounded connection admission, delivery, grouping, lifecycle, and optional composition points.
+
+## Compatibility invariants
+
+- Every production feature is opt-in.
+- Existing route, handler, and service subclasses require no source changes.
+- The default route, strict routing, IP collision policy, handler dispatch, error hiding, listener ownership, and shutdown behavior remain compatible with 0.8.
+- Disabled multiplayer features create no timers or per-connection queues.
+- No global mutable registry or mandatory infrastructure dependency is permitted.
+- Every timer, listener, queued task, membership, session lease, and adapter subscription has one deterministic cleanup owner.
+- User hooks may be synchronous or asynchronous and may not escape as process-level failures.
+- Cleanup is bounded, idempotent, best-effort, and continues after individual failures. Owned listeners also terminate incomplete HTTP peers at the route deadline; borrowed listeners remain application-owned.
+
+## Delivery claims
+
+WebSocket provides an ordered byte stream while a connection remains healthy. Redweb does not claim exactly-once delivery. Reconnection, distributed adapters, and application retries can introduce loss or duplication; protocol users must use explicitly scoped sequence identifiers when those cases matter.
+
+## Roadmap gates
+
+1. **Bounded transport:** pre-upgrade admission, origin policy, rate limits, slow-consumer enforcement, bounded ordered processing, payload limits, and route-level heartbeat.
+2. **Multiplayer grouping:** route-scoped rooms, atomic membership cleanup, bounded session resumption, fixed-step services, and vendor-neutral metrics.
+3. **Horizontal composition:** draining/readiness, adapter lifecycle, loop prevention, bounded validation, placement hooks, and documented partition behavior.
+4. **Protocol and clients:** version negotiation, stable envelopes and error codes, generated client-facing types, binary replication hooks, and operational examples.
+
+## Release gates
+
+- Existing tests and documented examples run unchanged.
+- New behavior has unit tests and mock-free HTTP/WS/WSS integration tests.
+- Coverage remains 100% for statements, branches, functions, and lines.
+- Disabled-feature throughput regression is at most 3%; p99 latency regression is at most 5% on the same machine and Node version.
+- Heartbeat uses one scheduler per route, never one interval per connection.
+- Every queue, retained session, room, adapter backlog, and deduplication window is finite.
+- Broadcast serializes once and remains O(n) in selected recipients.
+- Slow clients cannot grow framework-owned memory without bound.
+- A 60-minute soak shows no monotonic growth in timers, listeners, rooms, sessions, or queues.
+- Reconnect storms return retained heap to within 10% of the warmed baseline after expiry and forced collection.
+- Readiness becomes false before draining and shutdown completes within its documented bound.
+
+The independent senior-review gate rejects releases that weaken any invariant, hide ambiguous delivery semantics, add mandatory brokers or identity libraries, or substitute coverage percentages for race, load, soak, and failure evidence.
+
+## Horizontal composition contract
+
+- Placement runs before upgrade within the admission timeout. Redirects must use `wss`, contain no credentials or fragment, and may be restricted with `allowedPlacementOrigins`. Plain `ws` placement requires the explicit `allowInsecurePlacement` escape hatch for private development networks.
+- Readiness becomes false before shutdown work begins. New upgrades receive `503`; existing connections stop accepting messages.
+- `drainHandlers` is opt-in. When enabled, every connection context shares the route drain signal and shutdown awaits tracked work. Application handlers remain responsible for observing the signal; non-cooperating promises cannot be forcibly cancelled.
+- Distribution adapters have no framework backlog. Publish and inbound concurrency are finite; publish failure returns `false`; startup, subscription, unsubscription, draining, and close are bounded. Adapter operations receive an optional `AbortSignal`, and late startup/subscription settlement is compensated. Adapters must observe the signal when their external side effects are not otherwise reversible.
+- A failed publish marks a `required` adapter unhealthy, makes the route unready, and causes new upgrades to receive `503`; a later successful publish restores health. Best-effort adapters do not affect route readiness.
+- Event IDs are deduplicated only inside a finite TTL/size window. Source-node events are ignored to prevent reflection loops.
+- Broker partitions and process failure can lose events. Redweb makes no exactly-once or durable-delivery claim; applications own authoritative persistence, reconciliation, tick/sequence semantics, and partition policy.
+
+## Protocol contract
+
+- Negotiation is opt-in and happens before upgrade. Unsupported clients receive `426` plus the finite supported-version list.
+- JSON events use `{ v, type, payload, requestId?, sequence? }`. Error events use `{ v, type: "error", error: { code, message }, requestId? }`.
+- `requestId` correlates a request and response; `sequence` expresses application ordering. Neither implies acknowledgement, durability, or exactly-once delivery.
+- Stable framework codes are generated from `src/ws/protocol-schema.json`; the client declarations and runtime constants share that source.
+- Binary replication is a codec hook, not a codec dependency. Size is checked before decode and after encode, and outbound data uses the normal backpressure ceiling.
+- Protocol-disabled routes retain their 0.8 wire shapes and allocate no protocol context.
+
+## Resource ownership
+
+- `maxPendingUpgrades` bounds authorization work before a socket is accepted.
+- Timed-out admission hooks that ignore cancellation retain their reservation until they actually settle, preventing repeated timeout waves from accumulating unbounded application work.
+- Fixed-step services clamp retained lag with `maxRetainedLagMs`; dropped time is observable rather than replayed forever.
+- Session count, ID length, and lifetime are bounded by Redweb. Session `data` is application-owned, so applications must validate and cap its shape and byte size before storing it.
+- Fully enabled idle routes have a 2 KiB framework-metadata budget per connection. Disabled features retain the legacy path and are compared against 0.8 by the performance gate.

package/docs/VERIFICATION_EVIDENCE.md

@@ -0,0 +1,20 @@
+# 0.9.0 verification evidence
+
+Release-candidate measurements were taken on Windows x64, Node 22.21.0, and an AMD Ryzen 7 7800X3D. Performance numbers are machine-specific; the scripts and thresholds are the durable contract.
+
+## Automated correctness
+
+- 290 unit and mock-free integration/fuzz tests pass on Node 18, 20, and 22.
+- Statements, branches, functions, and lines are each 100% covered.
+- Type declarations compile and generated protocol declarations match their schema.
+
+## Resource and failure gates
+
+- Real-socket load: 32 concurrent clients, 3,200 request/response messages, 6,874 messages/second, 5.87 ms p99, with a paused slow consumer disconnected by the outbound-buffer policy.
+- Reconnect recovery: 200 warm connections followed by 1,200 storm connections; retained heap recovered to 104.33% of warm baseline and connection, room, and session registries returned to zero.
+- Fully enabled idle-route metadata: 1,756.93 bytes per connection across the median of three 500-connection trials, below the 2,048-byte gate.
+- Disabled-feature comparison with Redweb 0.8: throughput improved 1.09% and p99 regressed 2.00% (limits: 3% and 5%), using five alternating 20,000-message trials at concurrency 128.
+- `npm audit` reports zero vulnerabilities after upgrading Express to 4.22.2, `ws` to 8.21.3, and patched transitive dependencies.
+- The corrected 60-minute soak sent 2,099,717 messages across 64 rotating clients and received 2,099,565 responses (99.993%). Steady-state clients, rooms, sessions, in-flight work, queued work, listeners, and Redweb-owned timers showed no sustained growth; late-window heap was 3.24% above the early window, within the 10% gate. Final heap was 100.04% of the warmed baseline; all registries returned to zero; active handles stayed within the one-handle allowance.
+
+All measurements above were rerun on the final release candidate. Shortened soak smoke runs are not counted as release evidence.