readonly-connections

Readonly Connections

Readonly connections restrict certain WebSocket clients from modifying agent state while still letting them receive state updates and call non-mutating RPC methods.

Overview

When a connection is marked as readonly:

• It receives state updates from the server
• It can call RPC methods that don't modify state
• It cannot call this.setState() — neither via client-side setState() nor via a @callable() method that calls this.setState() internally

import { Agent, type Connection, type ConnectionContext } from "agents";

export class DocAgent extends Agent<Env, DocState> {
  shouldConnectionBeReadonly(connection: Connection, ctx: ConnectionContext) {
    const url = new URL(ctx.request.url);
    return url.searchParams.get("mode") === "view";
  }
}

// Client - view-only mode
const agent = useAgent({
  agent: "DocAgent",
  name: "doc-123",
  query: { mode: "view" },
  onStateUpdateError: (error) => {
    toast.error("You're in view-only mode");
  }
});

Marking connections as readonly

On connect

Override shouldConnectionBeReadonly to evaluate each connection when it first connects. Return true to mark it readonly.

export class MyAgent extends Agent<Env, State> {
  shouldConnectionBeReadonly(
    connection: Connection,
    ctx: ConnectionContext
  ): boolean {
    const url = new URL(ctx.request.url);
    const role = url.searchParams.get("role");
    return role === "viewer" || role === "guest";
  }
}

This hook runs before the initial state is sent to the client, so the connection is readonly from the very first message.

At any time

Use setConnectionReadonly to change a connection's readonly status dynamically:

export class GameAgent extends Agent<Env, GameState> {
  @callable()
  async startSpectating() {
    const { connection } = getCurrentAgent();
    if (connection) {
      this.setConnectionReadonly(connection, true);
    }
  }

  @callable()
  async joinAsPlayer() {
    const { connection } = getCurrentAgent();
    if (connection) {
      this.setConnectionReadonly(connection, false);
    }
  }
}