@jahands/cf-actors

Cloudflare Actors

This project is in active development.

We are building a full-featured framework that makes developing Cloudflare Durable Objects easier by introducing new patterns and out of the box functionality that help developers.

Features

• Request Handler to easily define entrypoints to your Actor, Worker, or Request
• Lifecycle Methods enable you to tap into important lifecycle events
• Persistent Properties that store property values between requests and evictions
• RPC Interface into other Actors with a simple MyActor.get('id') interface
• Managing Instances track, delete, and access all instances that have been created
• Location Placement allow you to control the location of your Actor
• SQL Migrations to apply migrations to the SQLite storage
• Multiple Alarms set any number of alarms by timestamp, delay, or cron
• Retry utilities to retry operations using exponential backoff with jitter strategy, and to detect if Durable Object errors are retryable.

And many more features, check out the Examples for more information.

Getting Started

Step 1: Install the package

npm i @cloudflare/actors

Step 2: Update your Wrangler Configuration

Notice the code class name in your Typescript implementation must match the binding name, class_name and new_sqlite_classes value in the configuration. Verify all of the values match.

{
  "migrations": [
    {
      "new_sqlite_classes": ["MyActor"],
      "tag": "v1"
    }
  ],
  "durable_objects": {
    "bindings": [
      {
        "class_name": "MyActor",
        "name": "MyActor"
      }
    ]
  }
}

Step 3: Create your class implementation:

import { Actor, handler } from "@cloudflare/actors";

export class MyActor extends Actor<Env> {
  async onRequest(request: Request): Promise<Response> {
    return new Response("Hello, World!");
  }
}

export default handler(MyActor);

Step 4: Deploy

npm run deploy

Examples

• Basic Example
• Request Handler
• RPC Interface
• Managing Instances
• Lifecycle Hooks
• Location Placement
• How to use without Actor class

FAQ

Alarms

What is the lifecycle of an Alarm trigger?

When an Actor is awoken by an Alarm trigger, it currently behaves in a slightly different order than if the Actor was already in memory. Below is the sequence of events.

Cold Start:

• [Callback]
• onInit
• onAlarm

Warm Start:

• onAlarm
• [Callback]

For the warm start instance, onInit would have already been called earlier before the alarm trigger.

General

What is an Actor?

An Actor is a Durable Object that is stateful and has access to both compute and storage. You can think of it as a small server instance that is active when being accessed and asleep when not.

How long does a single request keep my Actor alive for?

A single request will keep the Actor alive for ~10 seconds.

Can I keep my Actor alive longer?

Using `setTimeout` in your code can keep it alive for up to ~60 seconds.

Are there other ways to keep my code alive longer?

Yes, you can use alarms to keep the Actor alive longer.

Does every new request reset the time until the Actor is no longer in memory?

Yes.

Location Placement

How do I control the location of my Actor?

You can use location hints to control the location of your Actor.

Where does my Actor live if I do not specify a location hint?

If you do not specify a location hint, your Actor will be placed in the region closest to the user.

Can you change the location or region of your Actor?

No, you cannot change the location or region of your Actor. Once it has been instantiated it will always live in that region. If you want to move your Actor to a different region, you will need to deploy a new version of your code.

With a location hint where will my Actor be placed?

With a location hint, your Actor will be placed in the region you specified. The instance will be spawned somewhere randomly within the location region you provide. For example if you provide the `enam` location hint, the instance will be spawned somewhere randomly within the Eastern North America region.

What happens if the data center where my Actor is located goes down?

If the data center where your Actor is located goes down, your Actor will be moved to another data center.

See FAQ for more answers to common questions.

Contributing

We welcome contributions! Please refer to our Contributing Guidelines for more information.

License

This project is licensed under the MIT License - see the LICENSE file for details.