进阶 celld.dev 2026-10-11 10:08:47 · 35 阅读

第11章 Durable Object Facets(子表面)详解

文档:Durable Object Facets

Facet(子表面)是 Durable Object 内部的子对象,拥有独立的 SQLite 数据库。Supervisor(监管者)类通过 Worker Loader 提供的类来启动 Facet,这样生成的或不可信代码就能获得持久化存储,而无需使用 Durable Object 命名空间。请参阅 Cloudflare Durable Object Facets 文档以了解标准 API。

示例

该 Facet 示例通过 Worker Loader 提供的类创建一个 Facet。

index.js
import { DurableObject, WorkerEntrypoint } from "cloudflare:workers";

// Facet 的代码。实际应用会从 bundle、数据库或请求中加载;
// 这里为简化示例,用字符串形式以便包含在一个文件中。
const CODE = `
  import { DurableObject } from "cloudflare:workers";
  export class App extends DurableObject {
    async fetch() {
      const n = this.ctx.storage.kv.get("n") ?? 0;
      this.ctx.storage.kv.put("n", n + 1);
      const greeting = await this.env.GREETER.greet("facet");
      return new Response(String(n) + ":" + greeting);
    }
  }
`;

export class Greeter extends WorkerEntrypoint {
  greet(name) {
    return \`\${this.ctx.props.greeting}, \${name}\`;
  }
}

export class Supervisor extends DurableObject {
  fetch(request) {
    const worker = this.env.LOADER.get("app-v1", () => ({
      compatibilityDate: "2025-01-01",
      mainModule: "app.js",
      modules: { "app.js": CODE },
      env: {
        GREETER: this.ctx.exports.Greeter({
          props: { greeting: "hello" },
        }),
      },
    }));
    const facet = this.ctx.facets.get("app", () => ({
      class: worker.getDurableObjectClass("App"),
    }));
    return facet.fetch(request);
  }
}

export default {
  fetch(request, env) {
    return env.SUPERVISOR.getByName("only").fetch(request);
  },
};
wrangler.jsonc
{
  "name": "facets",
  "main": "index.js",
  "compatibility_date": "2026-01-01",
  "worker_loaders": [{ "binding": "LOADER" }],
  "durable_objects": {
    "bindings": [{ "name": "SUPERVISOR", "class_name": "Supervisor" }]
  },
  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["Supervisor"] }]
}

API

  • ctx.facets.get(name, callback) 返回指定名称 Facet 的存根(stub)。回调返回 { class, id },celld 仅在启动 Facet 时执行该回调。worker.getDurableObjectClass("App")(通过 Worker Loader 绑定)或 ctx.exports.App 提供该类。
  • ctx.exports.App({ props }) 创建带有启动属性的类句柄。
  • ctx.facets.abort(name, reason) 停止 Facet 但保留其数据库。
  • ctx.facets.delete(name) 停止 Facet 并删除其数据库。
  • 存根可以响应 fetch() 及该类的 RPC 方法。

Facet 是其根对象的一部分

Facet 不是一个 cell(单元)。它没有自己的所有权记录或 fencing epoch(栅栏纪元),而是使用根 cell 的这些属性,这在 Durable Objects 页面中有描述。

Facet 运行在根 cell 的所有者节点上。驱逐(eviction)、重置(reset)和迁移(move)会将根对象及其 Facet 视为一组操作,下次调用时启动回调会再次执行。

与 workerd 类似,Facet 的写入提交到 Facet 自身的数据库中,因此根事务的回滚不会撤销其中的 Facet 调用。因此,Facet 及其根对象永远不会原子提交。celld 保留 Facet 的出站效果和 Facet 调用的响应,直到 Facet 流证明该调用的写入完成。该效果还会通过根 cell 的输出门(output gate)。

启动和寻址 Facet

ctx.facets.get(name, callback) 返回存根,celld 仅在 Facet 未运行时执行回调。回调返回一个类和可选的 id。类来自 Worker Loader 绑定上的 worker.getDurableObjectClass("App"),或来自无存储迁移的导出 DurableObject 类的 ctx.exports.App;该 Facet 在其根对象的 isolate(隔离环境)中运行。

加载的类可以继承 DurableObject,也可以是具有 (state, env) 构造函数的普通类。普通类响应 fetch(),其 RPC 方法需要 js_rpc 兼容性标志,如在 workerd 中那样。

id 设置 Facet 中的 ctx.id。DurableObjectId 保留其名称,字符串 ID 保持为字符串,省略 ID 则继承父 ID 及其名称。未迁移的类句柄没有 idFromName(),因此使用 Durable Object 命名空间来创建命名 ID。

ctx.exports.App({ props }) 创建带有启动属性的类句柄。调用会复制属性,因此后续对对象的更改不会到达 ctx.props。属性必须支持结构化克隆。无属性的回环(loopback)类提供一个空对象。

仅名称选择数据库,因此更改 id 仍可访问存储的数据。名称限制为 256 字节。

Facet 可以启动自己的 Facet,总深度限制为 4(包括根对象)。

ctx.facets.abort(name, reason) 停止 Facet 但保留其数据库。在已停止的存根上调用会抛出 reason。

ctx.facets.delete(name) 停止 Facet 并删除其数据库及其下方所有 Facet 的数据库。

外部名称无法到达根对象之外的 Facet,因此外部流量必须经过 Supervisor。如果子对象必须在不同节点上运行,请使用通过 idFromName() 寻址的独立 Durable Object。

Facet 中的 WebSockets

Facet 可以接受 WebSocket:其 fetch() 返回带有 WebSocketPair 客户端端的 101 响应,根对象返回该响应。Facet 可以在服务端调用 accept() 或传递给 ctx.acceptWebSocket()。Facet 也可以通过 new WebSocket(url) 或 Upgrade: websocket fetch 打开 WebSocket。celld 将每个此类套接字的事件传递给 Facet,而非根对象。套接字输出等待 Facet 流并通过根 cell 的输出门。

Facet 套接字不会休眠(hibernate),因为如果没有根对象,celld 无法再次启动 Facet。Facet 接受或打开的套接字会让根 cell 保持常驻,直到关闭。来自其他 Durable Object 的 101 响应的客户端端不会让根 cell 常驻。getWebSockets() 返回该 Facet 的套接字。

ctx.facets.abort() 和 ctx.facets.delete() 以代码 1001 关闭已停止 Facet 的套接字,Facet 不会收到关闭事件。workerd 则直接断开连接,因此其客户端看到 1006。排水(drain)、所有权迁移或代际切换以 1012 关闭 Facet 套接字,输出门失败则以 1011 关闭。

与 Cloudflare 的区别

  • Durable Object 绑定无法提供 Facet 类。具有存储迁移的类也无法提供,因为 ctx.exports 将该类作为命名空间持有。
  • 每个 Facet 有独立的 SQLite 数据库,celld 将其作为根 Durable Object 桶前缀下的独立流进行复制。
  • Facet 无法设置闹钟(alarm)。storage.setAlarm() 在 Facet 内部会抛出异常,因此根对象必须持有调度。
  • Facet 套接字不会休眠。它保持根 cell 常驻直到套接字关闭。
  • Facet 存根不可 await,流水线属性路径(pipelined property path)不可用,因此调用必须指定一个方法。
  • clone() 方法不可用。

Cloudflare 兼容性页面列出了运行时 API 和不支持的服务。

本篇用到的工具

评论 (0)