main
ply4 git calls448 ms46 KiB1 cachedprotocol v2
189 lines12 KiBRaw
1// The ply Worker: the /v1 git API and the public /view repository viewer, served at ply.ivar.workers.dev.
2// `cf build`, `cf dev`, `cf deploy` and `cf workers types` read this file. vite.config.ts holds build settings only.
3import { bindings, defineConfig, exports, triggers, type ConfigContext } from "cf/config";
4import {
5 FLAG_OPERATOR_COMPATIBILITY_DATE,
6 FLAG_OPERATOR_MODE,
7 FLAG_OPERATOR_WORKER,
8 OPERATOR_CONTROL_BINDING,
9 OPERATOR_TOKEN_BINDING,
10} from "./src/flags/operator-names.ts";
11import { FLAGS_MAX_AGE_S, FLAGS_SWR_S } from "./src/flags/ttl.ts";
12import { PUBLIC_NAMESPACE } from "./src/public-namespace.ts";
13import { PROBE_NAMESPACE } from "./src/bench/namespace.ts";
15const MILLISECONDS_PER_SECOND = 1_000;
16const SECONDS_PER_MINUTE = 60;
17// Merge and rebase line merges are CPU-bound. The paid plan's ceiling for one HTTP request is 5 minutes
18// (developers.cloudflare.com/workers/platform/limits, checked 2026-10-23).
19const PAID_PLAN_HTTP_CPU_CEILING_MINUTES = 5;
20const CPU_LIMIT_MS = PAID_PLAN_HTTP_CPU_CEILING_MINUTES * SECONDS_PER_MINUTE * MILLISECONDS_PER_SECOND;
21// Head sampling is a fraction of requests in [0, 1]. Every request is logged and traced.
22const SAMPLE_EVERY_REQUEST = 1;
24const WORKER_NAME = "ply";
26// Live Durable Object namespaces. This replaces the ordered `migrations` list of the old config format.
27// ViewerRateLimit was created by migration tag "v1-viewer-rate" (new_sqlite_classes) as namespace
28// 656fdd50f0d6428393eb2d9250ceee67. Declaring it here as a live SQLite class, with no lifecycle tombstones,
29// keeps that namespace and its data.
30// Never change `storage` on a live class. Retire or rename a class only with a `state` tombstone.
31// RateCounter (2026-11-06) is new and additive: the one counter behind the batched limiter (docs/rate-limit.md).
32const durableObjects = {
33 ViewerRateLimit: exports.durableObject({ storage: "sqlite" }),
34 RateCounter: exports.durableObject({ storage: "sqlite" }),
35 // RefsWatch (2026-11-07) is new and additive: grants and purges the public namespace's long-lived refs cache
36 // (src/refs-watch.ts). Reached through ctx.exports.RefsWatch, never an env binding (same reason as RateCounter).
37 RefsWatch: exports.durableObject({ storage: "sqlite" }),
38 // ProbeBench (2026-11-14) is new and additive: the probe workbench's runs, repositories and admissions
39 // (src/bench/entry.ts). Reached through ctx.exports.ProbeBench, never an env binding (same reason as RateCounter).
40 ProbeBench: exports.durableObject({ storage: "sqlite" }),
41} as const;
43// Workers Caching (never the Cache API / caches.default). The default entrypoint is uncached so it always runs (rate limit,
44// logs, scrub, traces). It sends public upload-pack to GitCache and authenticated inflated blobs to BlobCache over
45// ctx.exports. crossVersionCache keeps immutable content across deploys; CACHE_VERSION (src/cache-version.ts) is in every key.
46// Named entrypoints omit `cache` or set `enabled: true`. `enabled: false` does not compile:
47// the versions API rejects that block on a named entrypoint with error 10375. The default
48// entrypoint is the one place the block is accepted. Caching is off when the block is omitted.
49export type NamedWorkerOptions = { cache?: { enabled: true } };
51export function namedEntrypoint<const T extends NamedWorkerOptions>(options: T): T {
52 return options;
55export const entrypoints = {
56 default: exports.worker({ cache: { enabled: false } }),
57 GitCache: exports.worker(namedEntrypoint({ cache: { enabled: true } })),
58 // CAS graph (src/cas-cache.ts / cas-entries.ts): content-addressed layers via ctx.exports; props.scope partitions.
59 ObjectCache: exports.worker(namedEntrypoint({ cache: { enabled: true } })),
60 TreeCache: exports.worker(namedEntrypoint({ cache: { enabled: true } })),
61 CommitCache: exports.worker(namedEntrypoint({ cache: { enabled: true } })),
62 ResolvePathCache: exports.worker(namedEntrypoint({ cache: { enabled: true } })),
63 // Mutable tip: short TTL + purge-on-write (tags + /vN/ref/ pathPrefixes).
64 RefCache: exports.worker(namedEntrypoint({ cache: { enabled: true } })),
65 // Whole responses pinned to a commit oid (src/pinned.ts): /v1 tree/read/commit and viewer raw files.
66 Pinned: exports.worker(namedEntrypoint({ cache: { enabled: true } })),
67 // The one flag ruleset (src/flags/cache.ts). Caching stays off on the default entrypoint, which always runs.
68 FlagsCache: exports.worker(namedEntrypoint({ cache: { enabled: true } })),
69 // The rate limiter's one blocked-clients document (src/rate/doc.ts): max-age 1, stale-while-revalidate 30.
70 RateCache: exports.worker(namedEntrypoint({ cache: { enabled: true } })),
71 // Caching is off by default. An explicit `enabled: false` on a named entrypoint is rejected by the API with 10375.
72 // RPC writes (src/flags/entry.ts): setRollout and setTargeting are not idempotent GETs.
73 FlagControl: exports.worker({} satisfies NamedWorkerOptions),
74} as const;
76// A binding can only name a class declared live above. src/index.js re-exports it from src/viewer/rate.ts.
77const VIEWER_RATE_CLASS: keyof typeof durableObjects = "ViewerRateLimit";
79const plyWorker = {
80 worker: {
81 // The Worker already exists on the account. Renaming it here creates a second Worker.
82 name: WORKER_NAME,
83 // The date the live Worker already runs on. No nodejs_compat: ply is Web APIs only.
84 compatibilityDate: "2026-10-19",
85 // nodejs_als: only AsyncLocalStorage (node:async_hooks), which src/edge-trace.ts uses to nest ply's spans under
86 // their ply parent in Workers tracing (#67). Declared rather than relying on the runtime allowing the import.
87 compatibilityFlags: ["nodejs_als"],
88 entrypoint: "src/index.js",
89 workersDev: true,
90 previewUrls: false,
91 limits: { cpuMs: CPU_LIMIT_MS },
92 cache: { enabled: false, crossVersionCache: true },
93 // Every minute: bring the public-v0 mirrors (src/mirror.ts MIRRORS) to their GitHub branch. MIRROR_SYNC="off" stops it.
94 triggers: [triggers.scheduled({ schedule: "* * * * *" })],
95 observability: {
96 enabled: true,
97 headSamplingRate: SAMPLE_EVERY_REQUEST,
98 // Remote URLs carry the repo name and path in the query string. Keep them out of the platform's request logs.
99 redactQueryString: true,
100 logs: { enabled: true, invocationLogs: true },
101 traces: { enabled: true, headSamplingRate: SAMPLE_EVERY_REQUEST },
102 },
103 env: {
104 // Bearer token for /v1. A Worker secret, never in this file: set it with
105 // `cf workers secrets update PLY_TOKEN --worker ply --type secret_text` (cf prompts for the value).
106 // cf uploads it as an `inherit` binding with bindings_inherit=strict, so a deploy keeps the stored value
107 // and the API refuses an upload when the Worker has no PLY_TOKEN.
108 PLY_TOKEN: bindings.secret(),
109 // The load-test credential (docs/rate-limit.md "Load-test controls"): unlocks x-ply-rate-client / -mode / -fault and
110 // nothing else. ply-load holds this one, never PLY_TOKEN. Set with
111 // `cf workers secrets update PLY_LOAD_TOKEN --worker ply --type secret_text`; local copy ~/.config/ply/load-token (0600).
112 PLY_LOAD_TOKEN: bindings.secret(),
113 // "on" enables the POST/DELETE endpoints. Anything else answers 501.
114 WRITES: bindings.text("on"),
115 // "off" sends every upstream exchange direct, past GitCache (Workers Caching).
116 PACK_CACHE: bindings.text("on"),
117 // "watched": public-namespace ls-refs answers are cached for minutes and purged by RefsWatch when a ref moves
118 // (src/refs-watch.ts). Anything else keeps every refs answer at max-age 5 + stale-while-revalidate 10.
119 REFS_POLICY: bindings.text("watched"),
120 MIRROR_SYNC: bindings.text("on"),
121 // /view rate limits. One SQLite Durable Object class, defined by this Worker.
122 VIEWER_RATE: bindings.durableObject({ worker: WORKER_NAME, exportName: VIEWER_RATE_CLASS }),
123 // The limiter (docs/rate-limit.md). "memo" (default since 2026-11-07) decides from the isolate's copy of the cached
124 // blocked document and refreshes it in waitUntil (no I/O on the request path); "batched" fetches that document on
125 // every request (25 ms budget); both flush counts in batches to RateCounter. "legacy" calls ViewerRateLimit on every
126 // request. Roll the limiter back alone by setting "batched" (or "legacy") here AND rate.expectMode in
127 // scripts/cd/cd.policy.json, then ship through the pipeline (a `cf` var edit would deploy straight to 100%).
128 // RateCounter is reached through ctx.exports.RateCounter, not a binding: the versions API refuses a binding to a class
129 // that no deploy has provisioned yet (checked 2026-11-06 on the first upload of RateCounter).
130 RATE_MODE: bindings.text("memo"),
131 // The public namespace, served read-only with no token (src/public.ts). The binding is scoped to this one
132 // namespace; the Worker calls only get(<repo>).createToken("read", 3600) and list(). No stored secret.
133 PUBLIC_REPOS: bindings.artifacts({ namespace: PUBLIC_NAMESPACE }),
134 // The probe workbench's namespace (src/bench): ProbeBench creates one repository per run here, revokes every token
135 // it has and deletes it when the run ends. Scoped to the load-and-probe namespace, never the public one.
136 PROBE_REPOS: bindings.artifacts({ namespace: PROBE_NAMESPACE }),
137 // Exchange bodies of workbench runs (runs/<run>/<exchange>.<request|response>, at most 1 MiB each). Create the
138 // bucket before the first deploy that uploads this binding: `cf r2 bucket create ply-bench`.
139 BENCH_BLOBS: bindings.r2({ name: "ply-bench" }),
140 // The running version's id, sent as x-ply-version on every front-door response so a deploy can prove which
141 // version answered a request pinned with Cloudflare-Workers-Version-Overrides (`npm run cd`).
142 VERSION: bindings.versionMetadata(),
143 // R2 is the flag source of truth: one object, flags/config.json, ETag = revision.
144 // The bucket is not created here. It must already exist before a deploy that uploads this binding.
145 // `cf deploy` can provision a missing R2 bucket; create `ply-flags` first so that path is not taken.
146 FLAGS: bindings.r2({ name: "ply-flags" }),
147 FLAGS_MAX_AGE_S: bindings.text(String(FLAGS_MAX_AGE_S)),
148 FLAGS_SWR_S: bindings.text(String(FLAGS_SWR_S)),
149 // ply's own service binding to FlagControl. Nothing outside this Worker can call it.
150 // The operator Worker (`cf deploy --mode flag-operator`) binds the same export and is the
151 // sanctioned write path. Reads of the ruleset go through ctx.exports.FlagsCache.
152 FLAG_CONTROL: bindings.worker({ worker: WORKER_NAME, exportName: "FlagControl" }),
153 },
154 exports: { ...durableObjects, ...entrypoints },
155 },
156};
158// A second Worker, selected only when `--mode` is exactly `flag-operator`.
159// `cf build`, `cf deploy`, and `cf workers types` pass production, development, or undefined, and stay on ply.
160// This Worker has no R2 binding, so a deploy does not provision ply-flags. It does not add a secret to ply.
161function flagOperatorWorker() {
162 return {
163 name: FLAG_OPERATOR_WORKER,
164 compatibilityDate: FLAG_OPERATOR_COMPATIBILITY_DATE,
165 entrypoint: "src/flags/operator-entry.ts",
166 workersDev: true,
167 previewUrls: false,
168 cache: { enabled: false as const },
169 observability: {
170 enabled: true,
171 headSamplingRate: SAMPLE_EVERY_REQUEST,
172 redactQueryString: true,
173 logs: { enabled: true, invocationLogs: true },
174 traces: { enabled: true, headSamplingRate: SAMPLE_EVERY_REQUEST },
175 },
176 env: {
177 // Bearer for this Worker only. Set it with
178 // `cf workers secrets update FLAG_OPERATOR_TOKEN --worker ply-flag-operator --type secret_text`
179 // (cf prompts for the value). ply does not gain this secret.
180 [OPERATOR_TOKEN_BINDING]: bindings.secret(),
181 [OPERATOR_CONTROL_BINDING]: bindings.worker({ worker: WORKER_NAME, exportName: "FlagControl" }),
182 },
183 };
186export default defineConfig((ctx: ConfigContext) => {
187 if (ctx.mode === FLAG_OPERATOR_MODE) return { worker: flagOperatorWorker() };
188 return plyWorker;
189});
Diagnostics4 git calls · 448 ms
CallStatusSizeTime0448 ms
discover200152 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=152
git.server.agent=gitty/1.0
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch object-format
git.server.fetch=shallow filter sideband-all
git.protocol.version=2
git.pkt.frames=8
git.pkt.data=6
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=152
git.pkt.payload.max=34
ls-refs200145 B6 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=6
git.response.bytes=145
git.response.cache=UPDATING
git.response.duration_ms=6
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=145
git.pkt.payload.max=76
git.ls_refs.count=2
git.ls_refs.head=refs/heads/main
fetchblob:none · deepen 1020042 KiB · hit6 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=5
git.response.bytes=42585
git.response.cache=HIT
git.response.duration_ms=6
git.fetch.filter=blob:none
git.fetch.filter.requested=tree:0
git.fetch.filter.fallback=blob:none
git.fetch.filter.learned=false
git.fetch.wants=262b639aa1b258fc1777c3a66ba8f811df3a3da2
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=6
git.pkt.data=4
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=42585
git.pkt.payload.max=42490
git.sideband.band1.bytes=42489
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=61
git.pack.bytes=42489
git.pack.ofs_delta=0
git.pack.ref_delta=0
git.pack.chain.max=0
git.pack.trailer=7dbf576d97429022615f79aa46b440d9da603496
git.pack.full=61
Open pack map
fetch2004.5 KiB436 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=436
git.response.bytes=4561
git.response.cache=MISS
git.response.duration_ms=436
git.fetch.wants=49f648980cfabc8d5ee4baf57054be17082f2b56
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=4561
git.pkt.payload.max=4540
git.sideband.band1.bytes=4539
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/ply-web.git
Ref
refs/heads/main
Commit
262b639aa1b258fc1777c3a66ba8f811df3a3da2
cf-ray
a5e166441ec0b1a9
Request
5dca465e…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format