deepspace 0.6.1 → 0.6.2

package/dist/server.d.ts

@@ -615,7 +615,7 @@ declare function createDeepSpaceAI(env: DeepSpaceAIEnv, provider: Provider, opti
  *   const jwt = c.req.header('Authorization')!.slice(7)
  *   const tools = await composioTools(c.env, { toolkit: 'gmail', authToken: jwt })
  *   const ai = createDeepSpaceAI(c.env, 'anthropic', { authToken: jwt })
- *   const result = streamText({ model: ai('claude-sonnet-4-6'), prompt, tools })
+ *   const result = streamText({ model: ai('claude-sonnet-5'), prompt, tools })
  *
  * Merge with your own tools: `tools: { ...buildTools(executor), ...composio }`.
  */
@@ -1373,6 +1373,8 @@ type ServerMessage = BaseMessage<typeof MSG.QUERY_RESULT, {
  * - Raw SQLite access via this.sql
  * - Broadcast helpers: broadcast(), sendTo()
  * - HTTP fetch handler with WebSocket upgrade detection
+ * - Internal control-plane endpoint: POST /internal/disconnect-sockets
+ *   (force every client to reconnect and resync after out-of-band writes)
  *
  * Subclasses implement lifecycle hooks:
  *   onConnect, onMessage, onBinaryMessage, onDisconnect, onRequest, onAlarm
@@ -1392,6 +1394,21 @@ declare abstract class BaseRoom<E = Record<string, unknown>> {
     protected sql: SqlStorage;
     constructor(state: DurableObjectState, env: unknown);
     fetch(request: Request): Promise<Response>;
+    /**
+     * Handle built-in `/internal/*` control-plane routes shared by every room
+     * type. Returns a `Response` if the request was an internal route, or `null`
+     * to let the caller continue normal dispatch.
+     *
+     * Currently:
+     * - `POST /internal/disconnect-sockets` — close every live WebSocket so
+     *   clients reconnect and resync. Optional JSON body `{ code?, reason? }`
+     *   overrides the defaults (1012 / 'state-refresh'). Responds with
+     *   `{ success: true, closed: <n> }`.
+     *
+     * See the security note on `fetch()`: this path is only reachable via DO
+     * stub fetch from the app worker, never from the public internet.
+     */
+    protected handleInternalRequest(request: Request, url: URL): Promise<Response | null>;
     private handleWebSocketUpgrade;
     webSocketMessage(ws: WebSocket, message: ArrayBuffer | string): Promise<void>;
     webSocketClose(ws: WebSocket, _code: number, _reason: string): Promise<void>;
@@ -1430,6 +1447,33 @@ declare abstract class BaseRoom<E = Record<string, unknown>> {
      * Get all connected WebSockets.
      */
     protected getWebSockets(): WebSocket[];
+    /**
+     * Force every connected client to reconnect and resync by closing all live
+     * WebSockets. Returns the number of sockets closed.
+     *
+     * Use this after an **out-of-band, server-side write** to the room's records
+     * — an admin import route, a migration script, a cron job, or a server
+     * action — that connected clients have no way to learn about. Without it, a
+     * browser tab holding stale in-memory state keeps operating on (and may
+     * autosave over) data that changed underneath it. Closing the socket makes
+     * the client SDK reconnect and pull fresh query results.
+     *
+     * The default close code is 1012 ("service restart") with reason
+     * 'state-refresh'. The DeepSpace client treats *any* close as a reconnect
+     * trigger (it does not special-case clean/1000 closes), so on reconnect it
+     * re-subscribes every active query and receives fresh `QUERY_RESULT`s —
+     * `useQuery` consumers see the new data without re-subscribing.
+     *
+     * Each close is guarded so one already-closing socket can't abort the sweep.
+     *
+     * @param options.code   WebSocket close code (default 1012).
+     * @param options.reason WebSocket close reason (default 'state-refresh').
+     * @returns the number of sockets that were closed.
+     */
+    disconnectAllSockets(options?: {
+        code?: number;
+        reason?: string;
+    }): number;
     /**
      * Get the user attachment for a WebSocket.
      */
@@ -1751,6 +1795,14 @@ declare class RecordRoom<E = Record<string, unknown>> extends BaseRoom<E> {
      * truthy value on the worker to opt in). Off by default.
      */
     private get perfLogEnabled();
+    /**
+     * The HTTP debug API (`/api/debug/*`) runs arbitrary SQL and role changes
+     * with no auth of its own, so it is gated here at the DO's single ingress.
+     * Off unless a deployment opts in with `ALLOW_DEBUG_ROUTES=true`
+     * (`deepspace dev`/`test` set it automatically). Deployments holding shared
+     * data override this to always return false.
+     */
+    protected get debugRoutesEnabled(): boolean;
     constructor(state: DurableObjectState, env: unknown, schemas?: CollectionSchema[], config?: RecordRoomConfig);
     private getPermissionContext;
     fetch(request: Request): Promise<Response>;

package/dist/server.js

@@ -1287,6 +1287,8 @@ var BaseRoom = class {
   // ==========================================================================
   async fetch(request) {
     const url = new URL(request.url);
+    const internal = await this.handleInternalRequest(request, url);
+    if (internal) return internal;
     if (request.headers.get("Upgrade") === "websocket") {
       return this.handleWebSocketUpgrade(request, url);
     }
@@ -1296,6 +1298,36 @@ var BaseRoom = class {
     return new Response("Not Found", { status: 404 });
   }
   // ==========================================================================
+  // Internal Control-Plane Endpoints
+  // ==========================================================================
+  /**
+   * Handle built-in `/internal/*` control-plane routes shared by every room
+   * type. Returns a `Response` if the request was an internal route, or `null`
+   * to let the caller continue normal dispatch.
+   *
+   * Currently:
+   * - `POST /internal/disconnect-sockets` — close every live WebSocket so
+   *   clients reconnect and resync. Optional JSON body `{ code?, reason? }`
+   *   overrides the defaults (1012 / 'state-refresh'). Responds with
+   *   `{ success: true, closed: <n> }`.
+   *
+   * See the security note on `fetch()`: this path is only reachable via DO
+   * stub fetch from the app worker, never from the public internet.
+   */
+  async handleInternalRequest(request, url) {
+    if (request.method === "POST" && url.pathname === "/internal/disconnect-sockets") {
+      let options;
+      try {
+        const text = await request.text();
+        if (text) options = JSON.parse(text);
+      } catch {
+      }
+      const closed = this.disconnectAllSockets(options);
+      return Response.json({ success: true, closed });
+    }
+    return null;
+  }
+  // ==========================================================================
   // WebSocket Connection
   // ==========================================================================
   async handleWebSocketUpgrade(request, url) {
@@ -1382,6 +1414,42 @@ var BaseRoom = class {
   getWebSockets() {
     return this.state.getWebSockets();
   }
+  /**
+   * Force every connected client to reconnect and resync by closing all live
+   * WebSockets. Returns the number of sockets closed.
+   *
+   * Use this after an **out-of-band, server-side write** to the room's records
+   * — an admin import route, a migration script, a cron job, or a server
+   * action — that connected clients have no way to learn about. Without it, a
+   * browser tab holding stale in-memory state keeps operating on (and may
+   * autosave over) data that changed underneath it. Closing the socket makes
+   * the client SDK reconnect and pull fresh query results.
+   *
+   * The default close code is 1012 ("service restart") with reason
+   * 'state-refresh'. The DeepSpace client treats *any* close as a reconnect
+   * trigger (it does not special-case clean/1000 closes), so on reconnect it
+   * re-subscribes every active query and receives fresh `QUERY_RESULT`s —
+   * `useQuery` consumers see the new data without re-subscribing.
+   *
+   * Each close is guarded so one already-closing socket can't abort the sweep.
+   *
+   * @param options.code   WebSocket close code (default 1012).
+   * @param options.reason WebSocket close reason (default 'state-refresh').
+   * @returns the number of sockets that were closed.
+   */
+  disconnectAllSockets(options) {
+    const code = options?.code ?? 1012;
+    const reason = options?.reason ?? "state-refresh";
+    let closed = 0;
+    for (const ws of this.state.getWebSockets()) {
+      try {
+        ws.close(code, reason);
+        closed++;
+      } catch {
+      }
+    }
+    return closed;
+  }
   /**
    * Get the user attachment for a WebSocket.
    */
@@ -3481,6 +3549,16 @@ var RecordRoom = class extends BaseRoom {
   get perfLogEnabled() {
     return !!this.env?.DEEPSPACE_DO_PERF;
   }
+  /**
+   * The HTTP debug API (`/api/debug/*`) runs arbitrary SQL and role changes
+   * with no auth of its own, so it is gated here at the DO's single ingress.
+   * Off unless a deployment opts in with `ALLOW_DEBUG_ROUTES=true`
+   * (`deepspace dev`/`test` set it automatically). Deployments holding shared
+   * data override this to always return false.
+   */
+  get debugRoutesEnabled() {
+    return this.env?.ALLOW_DEBUG_ROUTES === "true";
+  }
   constructor(state, env, schemas = [], config = {}) {
     super(state, env);
     this.schemaRegistry = new SchemaRegistry([
@@ -3516,14 +3594,21 @@ var RecordRoom = class extends BaseRoom {
   // HTTP Entry Point (overrides BaseRoom.fetch)
   // ============================================================================
   async fetch(request) {
+    const url = new URL(request.url);
+    if (url.pathname.startsWith("/internal/")) {
+      const internal = await this.handleInternalRequest(request, url);
+      if (internal) return internal;
+    }
     const fetchStart = Date.now();
     const isColdStart = this.freshConstruct;
     const needsInit = !this.initPromise;
     this.freshConstruct = false;
     await this.ensureInitialized();
     const initMs = Date.now() - fetchStart;
-    const url = new URL(request.url);
     if (url.pathname.startsWith("/api/")) {
+      if (url.pathname.startsWith("/api/debug/") && !this.debugRoutesEnabled) {
+        return new Response("Not Found", { status: 404 });
+      }
       return handleApiRequest(this.createHandlerContext(), request, url);
     }
     if (request.headers.get("Upgrade") === "websocket") {