feat(actor): add actors namespace with subscribe/send

[ImriKochWix]

Summary

PR B of 3 for the Actor feature.

• New src/modules/actors.ts: createActorsModule returns a Proxy so base44.actors.GameRoom works dynamically. subscribe(instanceId, cb) fetches a 30s token from the backend, opens a PartySocket to wss://dispatcher/parties/{handlerName}/{instanceId}?token=..., re-fetches token on reconnect. Returns { send, close }.
• New src/modules/actors.types.ts: exported types ActorsModule, ActorClient, ActorSubscription
• src/client.ts: wired actors module with getToken POST to /api/apps/{appId}/actor-token, derives dispatcherWsUrl from serverUrl (https:// → wss://)
• package.json: added partysocket dependency

Depends on

PR A deployed to preview (needs the token endpoint + Dispatcher WS handling live).

🤖 Generated with Claude Code

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/sdk@0.8.40-pr.212.527cb51

Prefer not to change any import paths? Install using npm alias so your code still imports @base44/sdk:

npm i "@base44/sdk@npm:@base44-preview/sdk@0.8.40-pr.212.527cb51"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "@base44/sdk": "npm:@base44-preview/sdk@0.8.40-pr.212.527cb51"
  }
}

• 📦 Preview Package: @base44-preview/sdk@0.8.40-pr.212.527cb51
• 🔗 View this commit on GitHub

---

_{Preview published to npm registry — try new features instantly!}

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[claude]

Claude finished @ImriKochWix's task —— View job

---

PR Review: Actors namespace with subscribe/send

• Read changed files
• Analyze code quality & best practices
• Check for bugs & issues
• Review performance considerations
• Review security concerns
• Assess test coverage

Nice, clean addition overall — the Proxy-based dynamic actor access is elegant, the heartbeat/half-open detection is thoughtful, and the type-registry approach (ActorRegistry / ActorNameRegistry) is a nice DX touch. A few things worth addressing before merge:

---

🔴 Bugs / correctness

1. Duplicate, drifting type definitions in actors.ts
src/modules/actors.ts:123-138 re-declares ActorSubscription and ActorClient locally, while src/modules/actors.types.ts also exports them. The Proxy in actors.ts uses the local copies (which is what makes it compile), but the two definitions have already diverged:

• The doc comment in actors.types.ts:79 shows await base44.actors.MyActor.subscribe(...) and calls it "Open a WebSocket subscription" — implying async — but subscribe is synchronous (returns ActorSubscription, not a Promise). The PR body also describes subscribe returning { send, close }, but the actual return is { id, unsubscribe }. Please reconcile the docs, PR description, and the implementation, and import the shared types from actors.types.ts in actors.ts rather than re-declaring them so they can't drift.

2. crypto.randomUUID() availability — src/modules/actors.ts:39
This relies on a global crypto, which isn't guaranteed in React Native or Node < ~19 (and the SDK explicitly supports RN and older Node via webSocketImpl). Note uuid is already a dependency (used in utils/axios-client.ts). Suggest import { v4 as uuidv4 } from "uuid" for consistency and portability.

3. send() doesn't guard socket state — src/modules/actors.ts:112-117
If called before the socket is OPEN (or during a reconnect), ws.send may throw. Consider checking readyState/buffering, or at least documenting that send can throw if the socket isn't open. Similarly, the public ActorClient.send in types says "Throws if not subscribed," but that only covers the missing-key case — a not-yet-open socket is a separate failure mode.

---

🟠 Design / performance

4. Module-level activeSockets map is global across all clients — src/modules/actors.ts:4
Keying by "ActorName:instanceId" in a module-level Map means two createClient() instances (e.g. user + service role, or multi-tenant SSR) share and can clobber each other's sockets — subscribe closes "existing" sockets that may belong to a different client. Recommend scoping the map inside createActorsModule (per-client) and/or including appId in the key.

5. No cleanup hook wired for actors — src/client.ts:233
userModules.cleanup() disconnects the entities socket and analytics, but open actor sockets aren't closed. Since sockets live in a module-global map with active setInterval heartbeats, an app that forgets to call unsubscribe() will leak sockets and timers. Consider tracking subscriptions per-client and closing them in cleanup().

6. Heartbeat interval is aggressive — src/modules/actors.ts:70-71
PING_MS = 1000 / DEAD_MS = 3000 means a ping every second per subscription. With many concurrent rooms this is a lot of traffic and wakeups (and keeps Durable Objects from hibernating). Worth confirming these are intentional and maybe making them configurable.

---

🟡 Cleanup / minor

7. pstest.mjs looks like a debug scratch file — committed at repo root (+26). It uses a FakeWS to print connect URLs. This should probably be removed or moved into tests/ as a real test.

8. webSocketImpl typed as unknown then cast to any — src/modules/actors.ts:51. Minor, but a narrower type (e.g. a WebSocket-like constructor) would be safer than as any.

9. Anonymous connect — getAuthToken returns token || getAccessToken() (client.ts:231) and the token is only read once at client-creation time via the closure over token. After setToken() is called, subscribe's query() re-reads via getAccessToken() on reconnect, but the initial token const won't reflect the new value. Confirm this is the intended precedence (it likely works since getAccessToken() reads storage, but the stale token closure is a subtle footgun).

---

🧪 Test coverage

There are no unit tests for the actors module, despite this being a non-trivial feature (Proxy dispatch, heartbeat/reconnect, URL derivation, anonymous vs. authed query). The repo has a good tests/unit pattern (see entities-subscribe.test.ts, socket-utils.test.ts). At minimum I'd suggest tests for:

• Proxy returns a client per actor name; subscribe opens a socket with the correct host/party/room/query.
• dispatcherWsUrl derivation in client.ts:89-99 (https→wss, http→ws, trailing-slash strip, appBaseUrl/window/serverUrl precedence) — pstest.mjs already probes this manually; turn it into assertions.
• send throws when there's no active subscription.
• unsubscribe clears the heartbeat and removes the map entry.

---

Overall this is close — the main blockers I'd flag are the duplicated/diverging types (#1), the crypto.randomUUID portability (#2), the global socket map (#4/#5), and removing pstest.mjs (#7). The rest are polish. Nice work! 👍
• feat/realtime-handler

[claude]

Claude finished @ImriKochWix's task —— View job

---

PR Review: Actors namespace (room-handle API)

• Read changed files
• Analyze code quality & best practices
• Check for bugs & issues
• Review performance & security
• Assess test coverage

This is a solid iteration — the API has clearly evolved into a cleaner room-handle design (actors.GameRoom(id).connect() → subscribe/send/close). Nice improvements since the last pass: the duplicated types are gone (actors.ts now imports from actors.types.ts), there's a per-client scope, docs match the sync API, and there's a real test file. A few things still worth addressing before merge.

---

🔴 Bugs / correctness

1. crypto.randomUUID() portability — src/modules/actors.ts:52
Still relies on a global crypto, which isn't guaranteed in React Native or older Node — the very runtimes the webSocketImpl escape hatch exists to support. uuid is already a dependency (src/utils/axios-client.ts:3 uses import { v4 as uuidv4 } from "uuid"). Swap for uuidv4() for consistency and portability.

2. send() can still throw on a not-yet-open socket — src/modules/actors.ts:118-123
connect() returns synchronously but the socket opens asynchronously, so a room.connect().send(...) right away will call ws.send before OPEN. The type doc (actors.types.ts:74) says "buffered by the socket until open" — PartySocket does buffer, but only once its internal socket exists; a send in the same tick as connect() can still throw. Worth confirming PartySocket's buffering covers this, or guarding readyState. At minimum the heartbeat's ws.send is already wrapped in try/catch (:98-102) — send() isn't.

---

🟠 Design / lifecycle

3. No cleanup wiring for actor sockets — src/client.ts:233-238
userModules.cleanup() disconnects the entities socket + analytics, but actor rooms aren't tracked, so their sockets and setInterval heartbeats leak if the app forgets to call room.close(). Since createActorsModule now owns state per-client, consider having it track open rooms and expose a closeAll() that cleanup() calls. (serviceRoleModules.cleanup() at :270 has no actors module, so it's fine there.)

4. Heartbeat is aggressive — src/modules/actors.ts:26-27
PING_MS = 1000 / DEAD_MS = 3000: a ping every second per room. With many concurrent rooms that's a lot of wakeups and keeps Durable Objects from hibernating (cost). Confirm intentional; consider making it configurable or relaxing the interval.

5. close() doesn't reset connId — src/modules/actors.ts:125-133
After close(), this.connId is stale and this.ws = null. A subsequent connect() without options.id mints a new id, but connect() with no args after close silently reuses nothing — fine, but reading .id between close and reconnect returns the old id rather than throwing. Minor; worth a quick check that reconnect semantics are what you intend.

---

🟡 Cleanup / minor

6. pstest.mjs is still a debug scratch file at repo root (+26). It uses a FakeWS to print connect URLs. The real assertions now live in tests/unit/actors.test.ts, so this should be removed (or its URL-derivation checks folded into a test).

7. webSocketImpl typed unknown then as any — src/modules/actors.ts:19,60. A narrower WebSocket-like constructor type would be safer than the as any cast.

8. getAuthToken stale-closure footgun — client.ts:231 () => token || getAccessToken(). Since it re-reads on each query() call and getAccessToken() hits storage, login/logout between reconnects is picked up correctly. But the initial token const won't reflect a later setToken(). Likely fine (storage wins), just noting the subtlety.

---

🧪 Test coverage

Good — tests/unit/actors.test.ts covers the important paths: Proxy dispatch, idempotent connect, throw-before-connect, multi-listener + per-listener unsubscribe, __pong swallowing, send serialization, close teardown, anonymous connect, and per-id independence. Gaps worth adding:

• Heartbeat: with fake timers, assert a __ping is sent every PING_MS and that a stale lastMsg triggers reconnect() after DEAD_MS.
• dispatcherWsUrl derivation in client.ts:89-99 (https→wss, http→ws, trailing-slash strip, appBaseUrl/window/serverUrl precedence) — pstest.mjs probes this manually; turn it into real assertions.
• functionsVersion flows into the query as fv.

---

Blockers I'd flag: crypto.randomUUID portability (#1), missing cleanup wiring (#3), and removing pstest.mjs (#6). The rest is polish. Nice work overall. 👍

View job • feat/realtime-handler