What is a durable actor?
A durable actor is a tiny server with a SQLite database. It only handles 1 request at a time. Each write is saved to bucket storage before the call returns. After 10s of inactivity, the actor goes dormant. Its saved state stays in storage.What is the lifecycle of a Durable Actor?
Each actor instance has an ID. Its project, class, and ID identify it globally. You can reach the same actor from anywhere. Keep the same ID across reconnects and restarts. Use a new ID for a new conversation or run.How does a call find its actor?
Callget with an ID to get a reference. The first method call routes to that actor. An actor in memory runs the call right away. A dormant actor loads first. A new ID creates a fresh actor with empty state.
How do WebSockets work with durable actors?
Clients connect to the WebSocket gateway, not to the actor. The socket stays open while the actor is dormant. The next message wakes the actor and runs its handler.Why does an actor run one call at a time?
Calls and socket events share one mailbox. The actor runs them in order. A call that awaitsfetch keeps the mailbox closed. This was designed to protect resources in 3P services.
@Interleave opens the mailbox while a method awaits. You really want to run this if a long running task, like triggering an LLM, is in the method. Impact could be catastrophic and throttle everything otherwise.
You can also use this to remove bottlenecks if an actor is getting a lot of requests. Ideally, each actor should have only a few people connected to it.
How do alarms work?
An alarm runs the actor’sonAlarm method at a set time. Each actor has one alarm. It is saved outside the actor, so it fires even while the actor is dormant.