Base Class

import { StatefulActor } from "@telnyx/edge-runtime";

export class Account extends StatefulActor {
  async debit(amount: number): Promise<{ ok: boolean; balance: number }> {
    const balance = (await this.ctx.storage.get<number>("balance")) ?? 0;
    if (balance < amount) return { ok: false, balance };
    await this.ctx.storage.put("balance", balance - amount);
    return { ok: true, balance: balance - amount };
  }
}

​

Construction

class MyActor extends StatefulActor<Env> {
  // no constructor needed — this.ctx and this.env are wired by the base
}

​

Dispatch Rules

• Public methods are RPC-callable from a stub — declare them async (every stub call is a Promise on the caller’s side regardless).
• Methods whose names start with _ are internal helpers and are not RPC-exposed — the runtime rejects the call.
• The _ prefix is the only opt-out. TypeScript’s private keyword is erased at runtime and does not stop remote calls; name internal helpers with a leading _.
• fetch(req), alarm(info), webSocket(ws, req), the constructor, and methods defined on StatefulActor itself (not your subclass) are special and not auto-RPC.
• Methods have a wall-clock budget (30s by default). A call that exceeds it fails with ActorMethodTimeoutError — see Errors.

​

alarm(alarmInfo)

async alarm(info: AlarmInfo): Promise<void> {
  // at-least-once delivery — be idempotent
  // info.retryCount is 0 on first delivery; info.isRetry is true on retries
}

​

fetch(req)

async fetch(req: Request): Promise<Response> {
  return new Response("hello from " + this.ctx.id);
}

​

webSocket(ws, req)

import { StatefulActor } from "@telnyx/edge-runtime";
import type { WebSocket } from "ws";

export class Room extends StatefulActor {
  async webSocket(ws: WebSocket, req: Request): Promise<void> {
    const user = req.headers.get("x-user") ?? "anonymous";

    ws.on("message", async (data, isBinary) => {
      if (isBinary) return;
      // messages dispatch one at a time — this read-modify-write never races
      const seq = ((await this.ctx.storage.get<number>("seq")) ?? 0) + 1;
      await this.ctx.storage.put("seq", seq);
      ws.send(JSON.stringify({ echo: String(data), seq, user }));
    });
  }
}

• Called once per accepted connection, with the live socket and the handshake Request. req is the request your function’s front door forwarded: the URL plus application headers, with transport and handshake headers stripped — see WebSockets for the contract. Client-sent app headers pass through too, so trust only headers your front door explicitly set or overwrote — the front door must overwrite or strip anything auth-bearing (like x-user above) before forwarding.
• ws is a Node ws socket (import type { WebSocket } from "ws"): ws.on("message", (data, isBinary) => ...), ws.send(data), ws.close(code, reason). There is no WebSocketPair/accept() shape.
• Register your listeners before webSocket() returns. Frames that arrive before webSocket() returns — including any the client sent immediately after the handshake — are buffered and replayed in order once it returns; nothing drops.
• Socket events share the instance’s single-threaded dispatch. message, close, and error handlers run one at a time, serialized with RPC methods and alarms, each under the method wall-clock budget (30s by default). A message handler that throws or exceeds the budget closes the socket with code 1011.

​

Related

• WebSockets — the full connection contract behind webSocket()
• Actor Context — this.ctx: identity, storage, init
• Actor Storage — this.ctx.storage
• Configuration — the telnyx.toml actor block