Actor

Actors provide stateful compute units with persistent storage and unique identity. Each actor instance runs independently with dedicated storage that persists between requests. Actors handle requests serially to maintain data consistency.

Actors support scheduled operations through alarms. You can set alarms to trigger actor execution at specific times. This enables cron-like functionality and delayed processing patterns.

The Actor system provides complete isolation between instances. Each actor maintains its own storage space with a maximum of 10GB total storage, 2MB per key, and 2MB per value.

Creating

Add an actor to your raindrop.manifest file:

application "my-application" {
  actor "demo-actor" {
  }
}

Accessing

Access actors through environment bindings in your service handlers:

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    // Get actor by name-derived ID
    const actorId = env.DEMO_ACTOR.idFromName("user-123");
    const actor = env.DEMO_ACTOR.get(actorId);

    // Make RPC call to actor
    const result = await actor.processRequest(request);
    return new Response(result);
  }
}

Core Concepts

Main Interfaces

• Actor<Env> - Abstract base class for implementing actor logic
• ActorNamespace<T> - Factory for creating and accessing actor instances
• ActorStub<T> - Client for making RPC calls to actor instances
• ActorState - Runtime state interface provided to actor constructors

Core Data Types

ActorId

interface ActorId {
  toString(): string;
  equals(other: ActorId): boolean;
  readonly name?: string;
}

Represents unique actor instance identifier. Compare IDs using equals() method rather than direct comparison.

ActorStorage

interface ActorStorage {
  get<T>(key: string): Promise<T | undefined>;
  get<T>(keys: string[]): Promise<Map<string, T>>;
  put<T>(key: string, value: T): Promise<void>;
  put<T>(entries: Record<string, T>): Promise<void>;
  delete(key: string): Promise<boolean>;
  delete(keys: string[]): Promise<number>;
  list<T>(options?: ListOptions): Promise<Map<string, T>>;
  setAlarm(scheduledTime: number | Date): Promise<void>;
  getAlarm(): Promise<number | null>;
  deleteAlarm(): Promise<void>;
}

Provides persistent key-value storage for actor instances. Supports batch operations for efficient data access.

ActorState

interface ActorState {
  readonly id: ActorId;
  readonly storage: ActorStorage;
  waitUntil(promise: Promise<any>): void;
  blockConcurrencyWhile<T>(callback: () => Promise<T>): Promise<T>;
}

Runtime state interface passed to actor constructors. Provides access to storage and concurrency control methods.

System Limits

• Maximum storage per actor: 10GB
• Maximum key size: 2MB per key
• Maximum value size: 2MB per value
• Request processing: Serial execution (not concurrent)

idFromName

Input

idFromName(name: string): ActorId

Output

ActorId

Creates deterministic actor ID from string name.

// Generate consistent ID for named actor
const userId = env.USER_ACTOR.idFromName("user-456");
const userActor = env.USER_ACTOR.get(userId);

get

Input

get(id: ActorId, options?: ActorGetOptions): ActorStub<T>

Output

ActorStub<T>

Gets or creates actor instance by ID.

// Create actor stub for RPC calls
const actorId = env.CHAT_ACTOR.idFromName("room-789");
const chatActor = env.CHAT_ACTOR.get(actorId, {
  locationHint: 'wnam'
});

jurisdiction

Input

jurisdiction(jurisdiction: ActorJurisdiction): ActorNamespace<T>

Output

ActorNamespace<T>

Gets actor namespace within specific jurisdiction.

// Create EU jurisdiction namespace
const euActors = env.DATA_ACTOR.jurisdiction('eu');
const euActorId = euActors.idFromName("eu-user-123");

get (storage)

Input

get<T>(key: string): Promise<T | undefined>
get<T>(keys: string[]): Promise<Map<string, T>>

Output

Promise<T | undefined>
Promise<Map<string, T>>

Retrieves values from actor storage by key or keys.

// Get single value
const userPrefs = await this.state.storage.get<UserPreferences>("prefs");

// Get multiple values
const data = await this.state.storage.get(["config", "state", "metrics"]);

put (storage)

Input

put<T>(key: string, value: T): Promise<void>
put<T>(entries: Record<string, T>): Promise<void>

Output

Promise<void>

Stores values in actor storage.

// Store single value
await this.state.storage.put("lastActive", Date.now());

// Store multiple values
await this.state.storage.put({
  "sessionId": sessionId,
  "userId": userId,
  "timestamp": Date.now()
});

delete (storage)

Input

delete(key: string): Promise<boolean>
delete(keys: string[]): Promise<number>

Output

Promise<boolean>
Promise<number>

Deletes values from actor storage.

// Delete single key
const deleted = await this.state.storage.delete("tempData");

// Delete multiple keys
const deletedCount = await this.state.storage.delete(["cache1", "cache2"]);

list (storage)

Input

list<T>(options?: {
  start?: string;
  startAfter?: string;
  end?: string;
  prefix?: string;
  reverse?: boolean;
  limit?: number;
}): Promise<Map<string, T>>

Output

Promise<Map<string, T>>

Lists values matching query options.

// List with prefix filter
const sessions = await this.state.storage.list({
  prefix: "session:",
  limit: 10
});

// List in reverse order
const recent = await this.state.storage.list({
  reverse: true,
  limit: 5
});

setAlarm

Input

setAlarm(scheduledTime: number | Date): Promise<void>

Output

Promise<void>

Sets alarm to wake actor at specific time.

// Set alarm for 1 hour from now
const wakeTime = Date.now() + (60 * 60 * 1000);
await this.state.storage.setAlarm(wakeTime);

// Set alarm using Date object
const tomorrow = new Date();
tomorrow.setDate(tomorrow.getDate() + 1);
await this.state.storage.setAlarm(tomorrow);

getAlarm

Input

getAlarm(): Promise<number | null>

Output

Promise<number | null>

Gets current alarm time if set.

// Check if alarm is set
const alarmTime = await this.state.storage.getAlarm();
if (alarmTime) {
  console.log(`Alarm set for ${new Date(alarmTime)}`);
}

deleteAlarm

Input

deleteAlarm(): Promise<void>

Output

Promise<void>

Deletes currently set alarm.

// Cancel scheduled alarm
await this.state.storage.deleteAlarm();

waitUntil

Input

waitUntil(promise: Promise<any>): void

Output

void

Registers promise that must complete before actor exits.

// Register background task
const backgroundTask = this.processDataAsync();
this.state.waitUntil(backgroundTask);

blockConcurrencyWhile

Input

blockConcurrencyWhile<T>(callback: () => Promise<T>): Promise<T>

Output

Promise<T>

Blocks actor concurrency while executing function.

constructor(state: ActorState, env: Env) {
  super(state, env);

  // Initialize from storage without concurrency
  this.state.blockConcurrencyWhile(async () => {
    const config = await this.state.storage.get("config");
    this.initializeFromConfig(config);
  });
}