Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Actor Namespace

WorkerdActorNamespace is the Worker-side handle for a Cloudflare Durable Object actor.

The namespace is separate from the actor runtime. It binds a Cloudflare Durable Object namespace, validates upgrade requests, and exposes handles for upgrading clients or calling internal methods between Durable Object instances.

import { WorkerdActorNamespace } from "liminal/workerd"
 
import { TicTacToeActor } from "./TicTacToeActor.ts"
 
export class TicTacToeNamespace extends WorkerdActorNamespace.Service<TicTacToeNamespace>()("TicTacToeNamespace", {
  binding: "TICTACTOE",
  actor: TicTacToeActor,
  internal: {},
}) {}

Fields

  • binding: the Cloudflare Durable Object binding name
  • actor: the Liminal actor definition
  • internal: methods callable through namespace handles from other Durable Object instances or Worker code

Bind an actor instance

Use Namespace.bind(name) to get a handle for one Durable Object instance.

const game = TicTacToeNamespace.bind(gameId)
 
yield * game.upgrade({ player: "X" })
yield * game.call("SomeInternalMethod", { value: 1 })

upgrade(...) forwards the current request into the Durable Object as a WebSocket upgrade. call(...) invokes one of the namespace's internal methods through Durable Object RPC.

Provide the namespace

Use TicTacToeNamespace.layer in the Worker runtime. The binding name comes from the namespace definition.

const WorkerLive = TicTacToeNamespace.layer

Define the runtime

The Durable Object class itself comes from WorkerdActorRuntime.make(...).

import { Effect, Layer } from "effect"
import { WorkerdActorRuntime } from "liminal/workerd"
 
import Move from "./handleMove.ts"
import hydrate from "./hydrate.ts"
import { KvLive } from "./KvLive.ts"
import { TicTacToeNamespace } from "./TicTacToeNamespace.ts"
 
export class TicTacToeRuntime extends WorkerdActorRuntime.make({
  namespace: TicTacToeNamespace,
  prelude: KvLive,
  hydrate,
  onDisconnect: Effect.void,
  external: { Move },
  internal: {},
  layer: Layer.empty,
  hibernation: "5 seconds",
}) {}

Runtime fields:

  • namespace: the namespace definition this Durable Object implements
  • prelude: long-lived runtime dependencies for the Durable Object instance
  • hydrate: returns initial client state during audition
  • external: handlers for client-callable methods from Client.external
  • internal: handlers for namespace-callable methods from Namespace.internal
  • layer: short-lived, invocation-scoped dependencies derived from actor context
  • onDisconnect: cleanup or notifications for closed sockets
  • hibernation: optional hibernatable WebSocket timeout (Duration.Input)

Read Prelude vs Layer for the dependency model.