Actor class that runs in your app’s backend. For the client SDK that connects to a session, see the actors SDK reference.
For actor concepts and terminology, see the actors overview.
Required handlers
TheActor class is abstract. Implement the body of each of the following handlers. The handlers respond to events from clients and timers.
Optional handlers
When your actor needs them, implement these handlers.
When the session ticks, set
tickIntervalMs. If you omit shouldTick(), the session never ticks.
To let app code run a method on a session without connecting to it, list the method in static callable.
Methods to call
The actor class provides built-in functionality. The following are methods that you can use when implementing an actor’s handlers.
Use
this.client to read and write entities.
Class declaration
ImportActor from base44:runtime/actors and export a class that extends Actor as the default export from base44/actors/<actor-name>/entry.ts.
The folder name becomes the actor name in the SDK. For setup details, see create an actor.
Types the messages the actor receives from connected clients. Applies to the
msg parameter of handleMessage().Types the messages the actor sends to connected clients. Applies to
conn.send() and broadcast().Runtime API
Actors import theActor class from the base44:runtime/actors module:
ActorError to refuse a call to a callable method.
Read secrets
Usesecrets.get() to read your app’s environment variables from a handler. The method returns the value as a string, or undefined when the secret isn’t set.
Import secrets from the base44:runtime module:
secrets set.
We recommend calling a backend function for work that needs a secret. The function reads the secret and returns the result, so the actor never receives the secret. For a sample flow, see call a backend function for secret work.
Lifecycle handlers
Base44 calls these handlers in response to client activity in the session. You implement the body for each. Learn more about how actors and clients interact. For a sample flow, see manage client connections.Runs anytime a session activates, such as:
- When the session is first created.
- When a client connects to an idle session.
- When a message arrives on an idle session.
- When a scheduled time arrives.
void or a Promise<void>.Runs when a client connects to the session.
You can send the current session state with
conn.send(), or refuse the connection with conn.reject().
Returns void or a Promise<void>.Runs when a connected client sends a message.
You can validate the message before changing session state or accessing app data.
Returns
void or a Promise<void>.Runs when a client disconnects.
Use this handler to remove any session state associated with the connection ID.
A reconnect that reuses the same ID replaces the old socket without running
handleClose().
Returns void or a Promise<void>.Timer handlers and settings
These handlers and settings control timed work in the session. Base44 calls them when a scheduled time arrives, not in response to client activity. Learn more about scheduled work. For sample flows, see run ticks and schedule wakes.Runs once per interval while
shouldTick() returns true and the session has at least one client.
Returns void or a Promise<void>.Returns a
boolean. Return true to keep the session ticking, or false to stop it. This method is synchronous.Keep this method fast and free of side effects. Base44 calls this method after each connection, message, disconnection, and tick.Schedules one run of
handleWake() at a specified time.
Returns a Promise that settles after Base44 stores the schedule.
The schedule survives an idle period and can start an idle session.
Calling this method again with the same key replaces the scheduled time.Cancels the scheduled wake associated with a key.
Returns a
Promise that settles after Base44 clears the schedule.Connections
These properties and methods are available on theconn object passed to lifecycle handlers that involve a client.
Use these properties and methods to read client identity, send messages, and manage the connection.
For an overview of messaging, see realtime messages.
For a sample flow, see manage client connections.
conn is the backend end of the WebSocket, and Connection in the client is the other end of the same socket. Use conn in the actor class. See the actors SDK reference for the client object.Identifies this connection. Matches the ID the client passed when connecting,
or an ID the SDK generated.
Returns an array of live
conn objects in the session. Use this method in
handleStart() to match restored data with clients that stayed connected
through an idle period.Callable methods
App code can run a method on a session without connecting to it. A page callsbase44.actors.ActorName(sessionId).methodName(args), and server code, such as a backend function, calls base44.asServiceRole.actors.ActorName(sessionId).methodName(args). A workflow step can call a method through the backend function or server route it runs. Use a method for a one-way call into a session: server code pushing an update to the clients in it, or a page that acts on a session without showing it live, such as an admin clearing a board. Connect only when the page shows the session live.
Calling methods needs @base44/sdk 0.8.62 or later. An actor deployed before callable methods were available refuses every call until you deploy it again. For a sample flow, see call a session’s method.
Lists the methods that callers can run. A call to any other method fails
with a
404 error. Handlers and helpers never run this way, even when
listed: names that start with handle, on or _ are ignored.A method you list in
static callable. Runs when app code calls it, even
when no client is connected: an idle session activates first and runs
handleStart(). The method can read and change session state, use storage
and call broadcast(). Returns the caller’s reply, which must be
JSON-serializable. The SDK call resolves to that value.A call takes one argument. To pass several values, wrap them in an
object, such as
methodName({ id, url }), or an array. Any further
arguments are dropped: methodName(a, b) sends only a. The method’s second
parameter is the call context, never a value from the caller.Arguments and replies are JSON. A Date arrives as a string,
undefined is dropped (or becomes null inside an array), and functions,
Map and Set values don’t survive.Calls are rate-limited. Each caller can make 300 calls a minute in each
app, multiplied by your plan’s
rate limit multiplier.
A call over the limit fails with a rate-limit error.Throw
new ActorError(status, message) from a callable method to refuse
the call. The caller’s SDK call rejects with that status. Use a 4xx
status, such as 401 or 403. Any other error thrown from a method reaches
the caller as a 500 error.Storage
Usethis.storage to read and write session data. Unlike class fields, storage survives idle periods. To choose between storage and class fields, see storage. For a sample flow, see persist session data.
Retrieves a value by key. Returns a
Promise that resolves to the stored
value, or undefined when the key doesn’t exist.Saves a value by key. Replaces the value already stored under the key. Returns
a
Promise that settles when the write completes.Removes a value by key. Returns a
Promise that resolves to true when the
key existed, and false otherwise.Removes all saved data for the session. Returns a
Promise that settles when
the store is empty. A later connection starts with the same empty storage as a
new session.Entity access
Usethis.client and this.client.asServiceRole to read and write app entities from inside an actor handler. For a sample flow, see write entity data from a session.
Provides an app client scoped to this session. This client uses anonymous
authentication, so entity access follows the same rules as a logged-out
client, and it reads production data.
Provides elevated access that bypasses row-level security. Validate messages
before you use this client. Make writes safe to repeat, because the session can run a handler
again after an error.
See also
- Actors Overview: Concepts and terminology
- Actors: Sample Flows: Lifecycle, timers, connections, callable methods, storage, entities, and backend functions
actorsSDK reference: Client SDK APIsecrets set: Configure environment variables from the CLI