构建 HTTP 远端

HTTP 远端让 Graft 客户端通过你运营的基础设施同步。协议定义仓库发现、不可变对象传输与原子引用更新；宿主服务负责身份、访问控制、租户、限额与存储。

选择接入层

软件包	适用情况
`@eidos.space/graft-remote`	需要与框架无关的 Fetch 协议引擎，并准备自行编写路由适配器。
`@eidos.space/graft-remote-hono`	服务已经使用 Hono。
`@eidos.space/graft-remote-cloudflare`	服务使用 R2 和 SQLite Durable Objects。

挂载 Hono 适配器

pnpm add @eidos.space/graft-remote-hono hono

import { Hono } from "hono";
import {
  GraftProtocolError,
  createGraftRemote,
} from "@eidos.space/graft-remote-hono";

const app = new Hono();

const remote = createGraftRemote({
  async authenticate({ request }) {
    const principal = await authenticateRequest(request);
    if (!principal) {
      throw new GraftProtocolError(401, "unauthorized", "Authentication required");
    }
    return principal;
  },
  async authorize({ action, principal, repository }) {
    if (!(await canAccess(principal, action, repository))) {
      throw new GraftProtocolError(403, "forbidden", "Repository access denied");
    }
  },
  backend({ repository }) {
    return repositories.open(repository.id);
  },
});

app.route("/graft", remote);
export default app;

这个示例在 https://example.com/graft/<namespace>/<repository> 下提供仓库。后端必须为可变引用提供原子 compare-and-swap 与 compare-and-delete，为不可变对象提供 create-only write，并支持 byte-range read 和有界排序列表。

使用 Cloudflare 参考服务起步

仓库在 services/graft-remote-cloudflare 中提供可部署的组合示例。

cd services/graft-remote-cloudflare
pnpm install --frozen-lockfile
cp .dev.vars.example .dev.vars
pnpm types
pnpm dev

部署前，应创建或重命名配置中的 R2 bucket，把 token 保存为 Worker secret，并运行 service README 中列出的检查。

参考服务使用整个 deployment 共享的 bearer token。用于多用户或多租户前，应替换它的 authentication 与 authorization callbacks。

连接客户端

生产环境使用 HTTPS，并通过进程环境传入凭据：

export GRAFT_REMOTE_TOKEN='grt_...'
graft remote add origin 'https://example.com/graft/acme/archive'
graft ls-remote origin
graft push origin main

不要把 token 写进 URL 或 .graft/config.toml。graft+http:// 只用于你控制的本地服务。

构建 HTTP 远端

选择接入层

挂载 Hono 适配器

使用 Cloudflare 参考服务起步

连接客户端

验证契约