@cosmicdrift/kumiko-types 0.326.0 → 0.327.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.326.0",
+  "version": "0.327.0",
   "description": "Framework-Type-Definitions für Kumiko — FeatureDefinition, BootCheck-Types und die reinen Engine-Types. Erlaubt Downstream-Konsumenten, gegen die Type-Contracts zu bauen, ohne das ganze Framework-Package zu importieren. Enthaelt keine identitaets-sensitiven Runtime-Werte mehr (Error-Klassen leben seit #1629 in kumiko-framework, Brand-Symbole nutzen Symbol.for) und ist deshalb eine plain dependency, keine peerDependency.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -42,6 +42,10 @@
       "types": "./src/http-route.ts",
       "default": "./src/http-route.ts"
     },
+    "./websocket-route": {
+      "types": "./src/websocket-route.ts",
+      "default": "./src/websocket-route.ts"
+    },
     "./relations": {
       "types": "./src/relations.ts",
       "default": "./src/relations.ts"

package/src/feature.ts

@@ -77,6 +77,7 @@ import type {
 import type { EntityRelations, RelationDefinition } from "./relations";
 import type { ScreenDefinition } from "./screen";
 import type { TreeActionDef, TreeActionsHandle } from "./tree-node";
+import type { WebSocketRouteDefinition } from "./websocket-route";
 import type { WorkspaceDefinition } from "./workspace";
 
 // --- Metrics (declared by features via r.metric()) ---
@@ -371,6 +372,8 @@ export type FeatureDefinition = {
   // den Hono-app (außerhalb /api/*). Pattern symmetrisch zu queryHandlers/
   // writeHandlers — Routes leben mit dem Feature, nicht im Bootstrap.
   readonly httpRoutes: Readonly<Record<string, HttpRouteDefinition>>;
+  // WebSocket routes declared via r.webSocketRoute(), keyed by path.
+  readonly webSocketRoutes: Readonly<Record<string, WebSocketRouteDefinition>>;
   // Store tables declared via r.storeTable() — bypass the event-sourcing
   // system. Keyed by feature-local short name (derived from
   // meta.tableName). The registry attaches featureName on aggregation,
@@ -859,6 +862,12 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   // runProdApp.extraRoutes (declarative list with `entry` tier).
   httpRoute(definition: HttpRouteDefinition): void;
 
+  // Register a WebSocket endpoint under /api/ws/*. Rides the /api/* auth
+  // chain; the framework adds a cookie-session origin check, a per-message
+  // size cap and a heartbeat with session re-validation. Duplicate paths are
+  // rejected per feature here and across features in buildServer.
+  webSocketRoute(definition: WebSocketRouteDefinition): void;
+
   // Declare an "unmanaged" framework-native table that bypasses the
   // event-sourcing system. Reserved for legacy-import, read-only caches,
   // write-only webhook payload buffers, or read-side projections of

package/src/websocket-route.ts

@@ -0,0 +1,68 @@
+// WebSocket route definition — feature-declared WebSocket endpoints under
+// /api/ws/*. Auth (session + origin) runs before the upgrade; `connect`
+// then returns the per-connection handlers or a Response that rejects it.
+
+import type { Context } from "hono";
+import type { SessionUser, WriteResult } from "./handlers";
+
+export const WEBSOCKET_MAX_PAYLOAD_BYTES = 1024 * 1024;
+export const WEBSOCKET_DEFAULT_MAX_MESSAGE_BYTES = 64 * 1024;
+export const WEBSOCKET_ROUTE_PATH_PREFIX = "/api/ws/";
+// Bun closes a socket whose unsent outbound queue exceeds this (slow or stalled reader).
+export const WEBSOCKET_BACKPRESSURE_LIMIT_BYTES = 4 * 1024 * 1024;
+export const WEBSOCKET_DEFAULT_MAX_CONNECTIONS_PER_USER = 5;
+export const WEBSOCKET_MAX_CONNECTIONS_PER_USER_LIMIT = 100;
+
+export type WebSocketMessageData = string | Uint8Array;
+
+export type WebSocketConnection = {
+  readonly send: (data: WebSocketMessageData) => void;
+  readonly close: (code?: number, reason?: string) => void;
+  /**
+   * Aborts when the socket closes. onClose can run while onOpen/onMessage is
+   * still awaiting, so after any await that allocates (e.g. an upstream
+   * session), check `signal.aborted` and release it yourself.
+   */
+  readonly signal: AbortSignal;
+};
+
+export type WebSocketSessionHandlers = {
+  /** May still be awaiting when onClose runs; see `WebSocketConnection.signal`. */
+  readonly onOpen?: (connection: WebSocketConnection) => void | Promise<void>;
+  readonly onMessage?: (
+    data: WebSocketMessageData,
+    connection: WebSocketConnection,
+  ) => void | Promise<void>;
+  /** Runs immediately on close, not queued behind a slow onMessage; pending messages never start after it. */
+  readonly onClose?: (
+    code: number,
+    reason: string,
+    connection: WebSocketConnection,
+  ) => void | Promise<void>;
+};
+
+export type WebSocketRouteConnectDeps = {
+  readonly user: SessionUser;
+  readonly query: (type: string, payload: unknown) => Promise<unknown>;
+  readonly write: (type: string, payload: unknown) => Promise<WriteResult>;
+  /** Resolved via the server's trustedProxyHops-aware resolver, like HttpRouteHandlerDeps.clientIp. */
+  readonly clientIp: string;
+};
+
+export type WebSocketRouteDefinition = {
+  /** Must start with "/api/ws/"; `:param` segments allowed, no "*". */
+  readonly path: string;
+  /** Per-message cap; oversized messages close the socket with 1009. Default 64 KiB, max 1 MiB. */
+  readonly maxMessageBytes?: number;
+  /** Concurrent sockets per user and tenant on this route (per server process). Default 5, max 100; above it the upgrade gets 429. */
+  readonly maxConnectionsPerUser?: number;
+  /**
+   * Runs after auth + origin checks, before the upgrade. Returning a Response rejects the upgrade with it.
+   * Allocate per-connection resources in `onOpen`, not here: if the upgrade then fails, no `onClose` runs.
+   */
+  readonly connect: (
+    // biome-ignore lint/suspicious/noExplicitAny: Hono context generics are invisible at the framework boundary
+    c: Context<any, any>,
+    deps: WebSocketRouteConnectDeps,
+  ) => WebSocketSessionHandlers | Response | Promise<WebSocketSessionHandlers | Response>;
+};