[0froq]

Fixes #689

Description

Let rooms declare named actions that other server code can call through getRoom() from void/ws/server.

An auth hook can pass a session ID to an action that closes matching connections inside the room. The filtering stays in the Durable Object rather than crossing the boundary as a callback. Action arguments and return values retain their declared types.

getRoom() uses the same room addressing as client connections, including route params and custom keys. Actions run over Durable Object RPC, not through an HTTP endpoint or client message. Internal helpers use JavaScript private methods so they are not exposed through RPC.

The server-only entry point stays separate from void/ws. Existing rooms without actions and defineWebSocket routes retain their behavior. The guide includes a session-revocation example using server-authenticated session IDs.

Current boundaries:

• Authorization belongs in the calling server code. Action context has no request or user.
• Arguments must be structured-cloneable.
• Broadcast messages are schema-validated at runtime but are not statically typed inside actions yet.
• Room hooks should use ctx.room directly instead of awaiting an RPC action on their own room.
• then is reserved by the actions proxy to prevent accidental Promise assimilation.

Test

• 309 focused unit and integration tests pass, including existing WebSocket and routing regressions.
• Miniflare tests exercise the generated Worker, action dispatch, connection filtering, storage, broadcasts, cron and queue callers, and client/HTTP isolation.
• Regression tests verify that internal helpers cannot be called over RPC and that awaiting the actions proxy does not dispatch an action. Both fail against the pre-fix implementation.
• A temporary project checks getRoom() against actual generated route declarations, including invalid calls. The test uses the package's built declarations.
• Package typecheck, lint and formatting checks pass.

The full suite has not passed locally. Earlier runs encountered missing Playwright browsers, an older Node version and missing generated configs; those failures were not compared against the base commit. Live Cloudflare deployment and the development server have not been verified.

[0froq]

👁️‍🗨️ Review this pull request with grouped, summarized diffs at:
👉 https://pulls.review/gh/voidzero-dev/void/780?from=0froq

raw result

💭 analyzed by openai-compatible/opencode-go/deepseek-v4.1-flash
🕰️ 2026-11-12 05:54 UTC
🔗 head cf28f78
🤖 automated by pulls.review

{
  "headSha": "cf28f78bea495b60f2f309471487036d9038dde6",
  "result": {
    "overallSummary": "Adds server-side room actions: `defineRoom({ actions })` declares typed handlers, and `getRoom()` from the new `void/ws/server` entry point calls them over Durable Object RPC on the same instance a client's `connect()` reaches. Codegen exposes the declared action types per room route and registers route metadata for server addressing; tests cover dispatch, isolation from client messages/HTTP, cron and queue callers, and type-level contracts.\n\nReview the RPC surface first: the WebSocket Durable Object now extends `DurableObject` (RPC enabled), so the confinement of internal helpers to `#`-private methods and the `then` guard on the actions proxy are what keep actions server-only.",
    "groups": [
      {
        "key": "room-actions-runtime",
        "label": "Room actions types & getRoom",
        "summary": "New public surface: `RoomActionContext`/`RoomActions` and the `defineRoom()` overloads that preserve each action's annotated parameter and return types, plus the `getRoom()` handle in the new `void/ws/server` module (pattern canonicalization lookup, param validation, instance id, action proxy).",
        "category": "api",
        "filePaths": [
          "packages/void/src/runtime/ws.ts",
          "packages/void/src/runtime/ws-room.ts"
        ],
        "fileNotes": [
          {
            "path": "packages/void/src/runtime/ws-room.ts",
            "text": "The actions proxy returns `undefined` for `then` so `await room.actions` cannot dispatch an action; instance addressing reuses `buildWebSocketInstanceId()` and the route's `key` so `getRoom()` lands on the same Durable Object `connect()` uses."
          },
          {
            "path": "packages/void/src/runtime/ws.ts",
            "text": "`Array<never>` in `RoomActions` is what makes unannotated action parameters resolve to `never` while keeping declared parameter lists intact; the two `defineRoom()` overloads keep the no-actions form unchanged."
          }
        ]
      },
      {
        "key": "room-action-dispatch",
        "label": "Durable Object action dispatch",
        "summary": "Server side of the feature: the generated WebSocket Durable Object extends `DurableObject` from `cloudflare:workers` so RPC exists, exposes only `__voidRoomAction` for actions, and keeps every internal helper `#`-private. Also adds the `globalThis`-backed route registry that `getRoom()` reads.",
        "category": "core",
        "filePaths": [
          "packages/void/src/runtime/ws-server.ts"
        ],
        "critical": true,
        "fileNotes": [
          {
            "path": "packages/void/src/runtime/ws-server.ts",
            "text": "This is the security boundary: extending `DurableObject` puts every public method on the RPC surface, hence the `#`-private renames. Dispatch uses `Object.hasOwn` so prototype names like `constructor` are rejected as unknown actions.",
            "critical": true
          }
        ]
      },
      {
        "key": "codegen-routing",
        "label": "Route codegen & registration",
        "summary": "Codegen emits `actions` in `WebSocketRouteMap` for room routes only (union across colliding route files), and the compiled route table carries `mode` and calls `__registerWebSocketRoutes` after `key` is attached so server and client addressing agree.",
        "category": "core",
        "filePaths": [
          "packages/void/src/codegen/route-types.ts",
          "packages/void/src/router/compile.ts"
        ],
        "fileNotes": [
          {
            "path": "packages/void/src/router/compile.ts",
            "text": "Registration order matters: the `__registerWebSocketRoutes` call is emitted after the `key` assignment loop, otherwise `getRoom()` would compute a different instance id than the client path."
          }
        ]
      },
      {
        "key": "tests",
        "label": "Tests",
        "summary": "Unit tests for `getRoom()` addressing/validation and in-DO dispatch, a Miniflare integration test that exercises the generated Worker end to end, and typecheck tests against both hand-written and generated route declarations. Existing WebSocket unit tests are adjusted for the new `DurableObject` base class.",
        "category": "tests",
        "filePaths": [
          "packages/void/test/unit/ws-room-actions.test.ts",
          "packages/void/test/unit/ws-room.typecheck.ts",
          "packages/void/test/unit/compile.test.ts",
          "packages/void/test/unit/route-types.test.ts",
          "packages/void/test/unit/resource-name-runtime.test.ts",
          "packages/void/test/unit/ws-server-close.test.ts",
          "packages/void/test/integration/websocket-room-actions.test.ts",
          "packages/void/test/integration/room-action-types-typecheck.test.ts"
        ],
        "fileNotes": [
          {
            "path": "packages/void/test/integration/room-action-types-typecheck.test.ts",
            "text": "The second case deletes the generated `actions` line and asserts the same check file now fails, proving the positive assertions are live rather than trivially passing."
          },
          {
            "path": "packages/void/test/integration/websocket-room-actions.test.ts",
            "text": "Covers the claims in the PR description directly: helper methods must fail with \"does not implement the method\", awaiting the proxy must not dispatch, and a forged client message or HTTP request must not reach an action."
          }
        ]
      },
      {
        "key": "packaging",
        "label": "Package entry & build",
        "summary": "Registers the new `void/ws/server` subpath export (pointing at `ws-room`) and adds `ws-room.ts` as a built runtime entry.",
        "category": "build",
        "filePaths": [
          "packages/void/package.json",
          "packages/void/vite.config.ts"
        ]
      },
      {
        "key": "docs",
        "label": "Docs",
        "summary": "Documents the action workflow with a session-revocation example, the boundaries (no `ctx.request`/`ctx.user`, structured-cloneable args, no self-calls from room hooks), the new entry point in the API table, and the internal invariant for maintainers.",
        "category": "docs",
        "filePaths": [
          "docs/guide/websockets.md",
          "docs/reference/api.md",
          "packages/void/AGENTS.md"
        ],
        "fileNotes": [
          {
            "path": "docs/guide/websockets.md",
            "text": "The guide's security advice (derive the session id from `getSession()`/server state, never from client input) is the part that makes the revoke example safe; worth checking it stays accurate if the API changes."
          }
        ]
      }
    ],
    "schemaVersion": 1,
    "source": "llm",
    "generatedAt": "2026-11-12T05:54:46.262Z",
    "model": "openai-compatible/opencode-go/deepseek-v4.1-flash",
    "locale": "en"
  }
}