Skip to main content

​
Telnyx Compute: Stateful Actors (Beta) — Documentation Index

Stateful Actors (Beta) documentation within the Compute section of the Telnyx developer docs (https://developers.telnyx.com). Root index: https://developers.telnyx.com/llms.txt · Compute index: https://developers.telnyx.com/development/llms/compute-llms-txt.md · Full content for this subsection: https://developers.telnyx.com/development/llms/compute-stateful-actors-beta-llms-full-txt.md

​
Overview

  • Stateful Actors: A stateful actor is a single-threaded server that owns one entity’s state. The platform runs one instance per name, routes every call for that name to it, runs your methods one at a time, and persist…

​
Get Started

  • Stateful Actors Quick Start: Scaffold an Account Stateful Actor, deploy it, and prove per-account isolation, safe concurrent debits, and persistence.

​
Concepts

  • How It Works: A stateful actor is a single-threaded server with durable, flush-before-ack storage — one per entity. Derive the execution model from first principles, then map it mechanism-by-mechanism to what you’…
  • Execution Model: The four guarantees a stateful actor’s runtime makes: exactly one instance per name, one call at a time, writes durable before the caller sees a result, and only persisted state survives. Each maps t…
  • Lifecycle & Placement: Where a stateful actor instance runs, when it is activated and evicted, and what survives a restart. Instances are placed on first touch, evicted when idle, and restarted on deploy or host failure —…
  • Addressing: Reach a stateful actor instance by name. idFromName is deterministic — the same name always lands on the same instance; newUniqueId mints a fresh one. Both return a stub you call methods on.

​
Reference

  • Overview: The Stateful Actor API surface — the StatefulActor base class, ActorContext, per-instance storage, the actor binding (ActorNamespace / ActorStub), alarms, configuration, and errors.
  • Base Class: The StatefulActor base class — subclass it, declare async methods, and they become RPC-callable from a stub. Holds this.ctx and this.env.
  • Actor Context: The this.ctx object on a StatefulActor — the instance’s identity, per-key storage, single alarm, one-shot init, and its live WebSockets.
  • Actor Storage: Per-key persistent storage for a Stateful Actor, accessed as this.ctx.storage — get/put/delete/list/transaction plus the alarm API. Writes that return successfully are persisted at turn granularity.
  • Actor Namespace: The env.<BINDING> handle your function calls into — idFromName (deterministic) and newUniqueId (random), both returning an ActorStub.
  • Actor Stub: The client handle returned by idFromName / newUniqueId. Calling a method on the stub is an RPC to that one actor instance.
  • Actor Alarms: Schedule deferred work from inside a Stateful Actor method using the single per-actor alarm. At-least-once delivery with automatic redelivery on failure; make your handler idempotent.
  • Configuration: The telnyx.toml [[actors]] block that declares an actor binding — binding (the env property) and type (the class to instantiate per name).
  • Errors: Errors the Stateful Actor runtime can surface — BlockConcurrencyTimeoutError, ActorOutputGateError, ActorMethodTimeoutError, ActorFetchTimeoutError, and CodecError.

​
Guides

  • Project Structure: A Stateful Actor project is one module that exports two things — the actor class and a fetch handler — wired together by an [[actors]] binding in telnyx.toml.
  • Local Development: Run a Stateful Actor project locally with telnyx-edge dev — a full function + actor stack in Docker where env.<BINDING> calls resolve and actor state survives hot reloads.
  • Shared Actors: Reach one Stateful Actor type from multiple functions on the same account by declaring the same type under different bindings — the owner ships the class, the reference ships none.
  • When to Use Stateful Actors: Use a stateful actor when an entity has state that must be mutated coherently across many requests. Use a plain function for stateless work, and a database for cross-entity transactions or bulk queri…
  • Key-Value: Each Stateful Actor has private, durable, per-key storage at this.ctx.storage — get/put/delete/list plus atomic transaction(). Values round-trip through a codec. Reach for it by default; use SQL when…
  • SQL: Each Stateful Actor has a private, durable, embedded SQLite database at this.ctx.storage.sql — synchronous exec() with positional binds, typed rows, a single-pass cursor, and transactionSync() for at…
  • WebSockets: Terminate a live WebSocket on a Stateful Actor: the function authenticates once at the handshake, then inbound messages dispatch one at a time on the owning instance — single-threaded, with durable s…
  • Connection Lifecycle & Limits: How WebSocket connections to a Stateful Actor begin and end: the handshake guarantees, the close-code table, today’s duration budget, a reconnect pattern, and the frame, queue, and handler limits.