main
1// The isolate's write side (docs/rate-limit.md "Write side"): admitted hits accumulate in one open batch; the request
2// that opens it schedules one flush LINGER_MS later from ctx.waitUntil. A flush is one RPC carrying an idempotency key,
3// raced against a per-attempt timer and retried with the same key until acked or FLUSH_DEADLINE_MS have passed.
4// No platform import: the clock, the timer and the RPC are passed in, so the tests drive every path.
5import type { ApplyRequest, ApplyResult, BatchEntry, Fault } from './core.ts';
6import { ATTEMPT_TIMEOUT_MS, FLUSH_DEADLINE_MS, LINGER_MS, MAX_BATCH_KEYS, MAX_INFLIGHT, MAX_KEYS_HELD, RETRY_BACKOFF_MS } from './config.ts';
8export type AttemptOutcome = 'ok' | 'timeout' | 'error';
9export type Attempt = { readonly outcome: AttemptOutcome; readonly ms: number; readonly error: string };
10export type FlushOutcome = 'ok' | 'dropped';
11export type FlushReport = {
12 readonly id: string;
13 readonly keys: number;
14 readonly hits: number;
15 /** Batch open → first attempt. */
16 readonly lingerMs: number;
17 readonly attempts: readonly Attempt[];
18 readonly outcome: FlushOutcome;
19 readonly deadlineHit: boolean;
20 /** The acknowledging attempt was a replay: an earlier attempt had already applied. */
21 readonly replay: boolean;
22 /** First attempt → acked or dropped. */
23 readonly flushMs: number;
24 /** Batch open → flush end: how long the waitUntil kept the isolate alive for this batch. */
25 readonly aliveMs: number;
26 readonly ack: ApplyResult | null;
27 readonly early: boolean;
28 readonly fault: Fault | null;
29};
31export type BatcherDeps = {
32 readonly now: () => number;
33 readonly sleep: (ms: number) => Promise<void>;
34 /** `owner` is the ctx of the request that opened the batch (the RPC goes through its ctx.exports). */
35 readonly send: (req: ApplyRequest, owner: unknown) => Promise<ApplyResult>;
36 /** The isolate's id, minted on first use (no randomness at global scope in Workers). */
37 readonly isolateId: () => string;
38 readonly limits: () => readonly [number, number];
39 /** Called once per batch with its report, inside the flush (so inside the opener's waitUntil). */
40 readonly report: (r: FlushReport) => void;
41 readonly lingerMs: number;
42 readonly attemptTimeoutMs: number;
43 readonly deadlineMs: number;
44 readonly maxKeys: number;
45 readonly maxInflight: number;
46 /** Distinct keys held across the open batch and every flushing batch (MAX_KEYS_HELD). */
47 readonly maxKeysHeld: number;
48};
50export function defaultTuning(): Pick<BatcherDeps, 'lingerMs' | 'attemptTimeoutMs' | 'deadlineMs' | 'maxKeys' | 'maxInflight' | 'maxKeysHeld'> {
51 return { lingerMs: LINGER_MS, attemptTimeoutMs: ATTEMPT_TIMEOUT_MS, deadlineMs: FLUSH_DEADLINE_MS, maxKeys: MAX_BATCH_KEYS, maxInflight: MAX_INFLIGHT, maxKeysHeld: MAX_KEYS_HELD };
52}
54type OpenBatch = {
55 readonly seq: number;
56 readonly openedAt: number;
57 readonly counts: Map<string, number>;
58 hits: number;
59 fault: Fault | null;
60 readonly owner: unknown;
61 closed: boolean;
62 early: boolean;
63 done: Promise<FlushReport>;
64};
66const TIMEOUT: unique symbol = Symbol('timeout');
68function errorText(e: unknown): string {
69 if (e instanceof Error) return `${e.name}: ${e.message}`.slice(0, 120);
70 return String(e).slice(0, 120);
71}
73export class Batcher {
74 readonly #deps: BatcherDeps;
75 #open: OpenBatch | null = null;
76 #seq = 0;
77 #inflight = 0;
78 /** Batches dropped because MAX_INFLIGHT were already flushing. */
79 overflowDrops = 0;
80 /** Hits for a new key dropped because maxKeysHeld keys were already held. */
81 budgetDrops = 0;
82 /** Why the last add/addIsolated returned null. */
83 lastDrop: 'overflow' | 'budget' | null = null;
84 #keysHeld = 0;
86 constructor(deps: BatcherDeps) {
87 this.#deps = deps;
88 }
90 get inflight(): number {
91 return this.#inflight;
92 }
94 /** Distinct keys held now: the open batch plus every batch still flushing (released when its flush ends). */
95 get keysHeld(): number {
96 return this.#keysHeld;
97 }
99 /** The keys and hits waiting in the open batch (tests, and the bound). */
100 pending(): { keys: number; hits: number } {
101 const b = this.#open;
102 return b === null ? { keys: 0, hits: 0 } : { keys: b.counts.size, hits: b.hits };
103 }
105 /**
106 * Count one admitted hit. Returns the promise of the batch it joined, for ctx.waitUntil, or null when the batch was
107 * dropped on overflow (recorded in overflowDrops).
108 */
109 add(key: string, bucket: number, fault: Fault | null, owner: unknown = null): Promise<FlushReport> | null {
110 if (fault !== null) return this.addIsolated(key, bucket, fault, owner);
111 let b = this.#open;
112 const slot = `${key}:${bucket}`;
113 const known = b !== null && b.counts.has(slot);
114 if (!known && this.#keysHeld >= this.#deps.maxKeysHeld) {
115 this.budgetDrops++;
116 this.lastDrop = 'budget';
117 return null;
118 }
119 if (b === null) {
120 if (this.#inflight >= this.#deps.maxInflight) {
121 this.overflowDrops++;
122 this.lastDrop = 'overflow';
123 return null;
124 }
125 b = this.#start(owner);
126 }
127 if (!known) this.#keysHeld++;
128 b.counts.set(slot, (b.counts.get(slot) || 0) + 1);
129 b.hits++;
130 if (b.counts.size >= this.#deps.maxKeys) {
131 b.early = true;
132 this.#close(b);
133 }
134 return b.done;
135 }
137 /**
138 * A fault-injected hit (a load-test request): a batch of its own, flushed at once, never shared. Fault injection then
139 * slows, errors or drops only that request's count; real clients' hits in the same isolate stay in the shared batch
140 * and flush on their own schedule. Same id scheme, same in-flight bound. Null when over maxInflight.
141 */
142 addIsolated(key: string, bucket: number, fault: Fault, owner: unknown = null): Promise<FlushReport> | null {
143 if (this.#keysHeld >= this.#deps.maxKeysHeld) {
144 this.budgetDrops++;
145 this.lastDrop = 'budget';
146 return null;
147 }
148 if (this.#inflight >= this.#deps.maxInflight) {
149 this.overflowDrops++;
150 this.lastDrop = 'overflow';
151 return null;
152 }
153 const b = this.#start(owner, false);
154 this.#keysHeld++;
155 b.counts.set(`${key}:${bucket}`, 1);
156 b.hits = 1;
157 b.fault = fault;
158 this.#close(b);
159 return b.done;
160 }
162 #start(owner: unknown, shared = true): OpenBatch {
163 const deps = this.#deps;
164 this.#inflight++;
165 let release: (r: FlushReport) => void = () => {};
166 const done = new Promise<FlushReport>(resolve => { release = resolve; });
167 const b: OpenBatch = { seq: ++this.#seq, openedAt: deps.now(), counts: new Map(), hits: 0, fault: null, owner, closed: false, early: false, done };
168 // #close starts the flush and resolves `done` when it ends, whichever path closed the batch (linger, size, isolated).
169 this.#pendingRelease.set(b, release);
170 // An isolated batch is closed by its caller at once: it is never the open batch and has no linger.
171 if (!shared) return b;
172 this.#open = b;
173 void deps.sleep(deps.lingerMs).then(() => {
174 if (!b.closed) this.#close(b);
175 });
176 return b;
177 }
179 readonly #pendingRelease = new Map<OpenBatch, (r: FlushReport) => void>();
181 #close(b: OpenBatch): void {
182 b.closed = true;
183 if (this.#open === b) this.#open = null;
184 const release = this.#pendingRelease.get(b);
185 this.#pendingRelease.delete(b);
186 void this.#flush(b).then(r => {
187 this.#inflight--;
188 this.#keysHeld -= b.counts.size;
189 try { this.#deps.report(r); } catch { /* a report hook never fails a flush */ }
190 if (release) release(r);
191 });
192 }
194 async #flush(b: OpenBatch): Promise<FlushReport> {
195 const deps = this.#deps;
196 const entries: BatchEntry[] = [];
197 for (const [slot, n] of b.counts) {
198 const cut = slot.lastIndexOf(':');
199 entries.push([slot.slice(0, cut), Number(slot.slice(cut + 1)), n]);
200 }
201 const id = `${deps.isolateId()}:${b.seq}`;
202 const limits = deps.limits();
203 const started = deps.now();
204 const attempts: Attempt[] = [];
205 let ack: ApplyResult | null = null;
206 let deadlineHit = false;
207 for (let attempt = 1; ; attempt++) {
208 const left = deps.deadlineMs - (deps.now() - started);
209 if (left <= 0) { deadlineHit = true; break; }
210 const t0 = deps.now();
211 const call = deps.send({ id, attempt, limits, entries, fault: b.fault }, b.owner);
212 // The loser of the race keeps running (that is what the key covers). Its rejection must not be unhandled.
213 call.catch(() => {});
214 let outcome: AttemptOutcome;
215 let error = '';
216 try {
217 const won = await Promise.race([call, deps.sleep(Math.min(deps.attemptTimeoutMs, left)).then(() => TIMEOUT)]);
218 if (typeof won === 'symbol') outcome = 'timeout';
219 else { outcome = 'ok'; ack = won; }
220 } catch (e) {
221 outcome = 'error';
222 error = errorText(e);
223 }
224 attempts.push({ outcome, ms: deps.now() - t0, error });
225 if (ack !== null) break;
226 const after = deps.deadlineMs - (deps.now() - started);
227 if (after <= 0) { deadlineHit = true; break; }
228 await deps.sleep(Math.min(RETRY_BACKOFF_MS * 2 ** (attempt - 1), after));
229 }
230 const end = deps.now();
231 return {
232 id,
233 keys: entries.length,
234 hits: b.hits,
235 lingerMs: started - b.openedAt,
236 attempts,
237 outcome: ack === null ? 'dropped' : 'ok',
238 deadlineHit,
239 replay: ack !== null && ack.replay,
240 flushMs: end - started,
241 aliveMs: end - b.openedAt,
242 ack,
243 early: b.early,
244 fault: b.fault,
245 };
246 }
247}
Diagnostics4 git calls · 26 ms
CallStatusSizeTime026 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 B · hit3 ms
git.upload-pack ls-refs http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=3 git.response.bytes=145 git.response.cache=HIT git.response.duration_ms=3 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 1020040 KiB · hit3 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=2 git.response.bytes=41349 git.response.cache=HIT git.response.duration_ms=3 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=526b305930b8ef382f2d7a1f9c0238730a585921 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=41349 git.pkt.payload.max=41254 git.sideband.band1.bytes=41253 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=61 git.pack.bytes=41253 git.pack.ofs_delta=0 git.pack.ref_delta=0 git.pack.chain.max=0 git.pack.trailer=ab60efef4b7243678c75de64a4386986ee885c1c git.pack.full=61Open pack map
fetch2003.2 KiB · hit20 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=20 git.response.bytes=3294 git.response.cache=HIT git.response.duration_ms=20 git.fetch.wants=4f0c38bcd24d70220289b4163e03b856e8254408 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=3294 git.pkt.payload.max=3273 git.sideband.band1.bytes=3272 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
- 526b305930b8ef382f2d7a1f9c0238730a585921
- cf-ray
- a5e338732b9724ce
- Request
- 1dcfb7f6…
- Protocol
- v2 · sha1
- Agent
- gitty/1.0
- Filter
- advertised
- Fetch
- shallow filter sideband-all
- Capabilities
- agent ls-refs fetch object-format