main
ply4 git calls29 ms45 KiB3 cachedprotocol v2
218 lines11 KiBRaw
1// RateCounter's logic over a minimal SQL interface (docs/rate-limit.md "Durable Object side"). The Durable Object
2// (src/rate/counter.ts) hands it ctx.storage.sql; the tests hand it node:sqlite. Every method is synchronous: under the
3// Durable Object's input gate, the dedupe check and the writes of one apply() are one atomic transaction.
4import {
5 BUCKET_PACK,
6 BUCKET_PAGE,
7 DEDUPE_RETENTION_MS,
8 KEY_HEX,
9 MAX_BATCH_KEYS,
10 MAX_DOC_ENTRIES,
11 PRUNE_BATCH_ROWS,
12 PRUNE_EVERY_MS,
13 SLOT_MS,
14 WINDOW_MS,
15} from './config.ts';
17export type SqlValue = string | number | null;
18export type SqlRow = Record<string, SqlValue>;
19export type SqlCursorLike = { toArray(): SqlRow[]; readonly rowsWritten: number };
20export type SqlExec = (query: string, ...bindings: SqlValue[]) => SqlCursorLike;
22/** One client's admitted hits in one batch: [key16, bucket, count]. */
23export type BatchEntry = readonly [string, number, number];
24export type FaultKind = 'slow-ack' | 'error';
25export type Fault = { readonly kind: FaultKind; readonly ms: number; readonly attempts: number };
26export type ApplyRequest = {
27 readonly id: string;
28 readonly attempt: number;
29 /** [page limit, pack limit] per window. */
30 readonly limits: readonly [number, number];
31 readonly entries: readonly BatchEntry[];
32 readonly fault: Fault | null;
33};
34export type OverKey = { readonly k: string; readonly b: number; readonly sum: number; readonly limit: number; readonly crossed: number; readonly peak: number };
35export type ApplyResult = {
36 readonly replay: boolean;
37 readonly keys: number;
38 readonly hits: number;
39 readonly newBlocks: number;
40 readonly rowsWritten: number;
41 readonly gen: number;
42 readonly over: readonly OverKey[];
43 /** Rows this apply's prune deleted, per table, and whether a slice came back full (more expired rows waiting). */
44 readonly pruned: { readonly hits: number; readonly batches: number; readonly blocked: number; readonly backlog: boolean };
45};
46/** [key16, bucket, until ms, crossed ms]. */
47export type DocEntry = readonly [string, number, number, number];
48export type BlockedDoc = { readonly v: 1; readonly gen: number; readonly at: number; readonly entries: readonly DocEntry[] };
50const KEY_RE = new RegExp(`^[0-9a-f]{${KEY_HEX}}$`);
51const ID_RE = /^[0-9A-Za-z:_-]{1,96}$/;
52const MAX_COUNT = 1_000_000;
53const MAX_LIMIT = 1_000;
55export class InvalidBatch extends Error {
56 override name = 'InvalidBatch';
59function validLimit(n: unknown): n is number {
60 return typeof n === 'number' && Number.isSafeInteger(n) && n >= 1 && n <= MAX_LIMIT;
63/** Throws InvalidBatch on anything a ply isolate would not send. */
64export function checkApply(req: ApplyRequest): void {
65 if (typeof req.id !== 'string' || !ID_RE.test(req.id)) throw new InvalidBatch('id');
66 if (!Number.isSafeInteger(req.attempt) || req.attempt < 1) throw new InvalidBatch('attempt');
67 if (!Array.isArray(req.limits) || req.limits.length !== 2 || !validLimit(req.limits[0]) || !validLimit(req.limits[1])) throw new InvalidBatch('limits');
68 if (!Array.isArray(req.entries) || req.entries.length > MAX_BATCH_KEYS) throw new InvalidBatch('entries');
69 for (const e of req.entries) {
70 if (!Array.isArray(e) || e.length !== 3) throw new InvalidBatch('entry');
71 const [k, b, n] = e;
72 if (typeof k !== 'string' || !KEY_RE.test(k)) throw new InvalidBatch('key');
73 if (b !== BUCKET_PAGE && b !== BUCKET_PACK) throw new InvalidBatch('bucket');
74 if (!Number.isSafeInteger(n) || n < 1 || n > MAX_COUNT) throw new InvalidBatch('count');
75 }
78/** The first slot that still counts at `now`: a slot counts while its end is within the last WINDOW_MS. */
79export function firstLiveSlot(now: number): number {
80 return Math.floor((now - WINDOW_MS) / SLOT_MS);
83/** When the window sum next drops below `limit`, given live slots ascending. `sum` must be ≥ limit. */
84export function blockedUntil(slots: readonly { slot: number; n: number }[], sum: number, limit: number): number {
85 let remaining = sum;
86 for (const s of slots) {
87 remaining -= s.n;
88 if (remaining < limit) return (s.slot + 1) * SLOT_MS + WINDOW_MS;
89 }
90 const last = slots[slots.length - 1];
91 return last === void 0 ? 0 : (last.slot + 1) * SLOT_MS + WINDOW_MS;
94function num(row: SqlRow | void, col: string): number {
95 if (row === void 0) return 0;
96 const v = row[col];
97 return typeof v === 'number' ? v : Number(v);
100export class CounterCore {
101 readonly #sql: SqlExec;
102 #lastPrune = 0;
103 #pruneBacklog = false;
105 constructor(sql: SqlExec) {
106 this.#sql = sql;
107 sql(`CREATE TABLE IF NOT EXISTS rate_hits (k TEXT NOT NULL, b INTEGER NOT NULL, slot INTEGER NOT NULL, n INTEGER NOT NULL, PRIMARY KEY (k, b, slot))`);
108 sql(`CREATE INDEX IF NOT EXISTS rate_hits_slot ON rate_hits (slot)`);
109 sql(`CREATE TABLE IF NOT EXISTS rate_batches (id TEXT PRIMARY KEY, at INTEGER NOT NULL, hits INTEGER NOT NULL)`);
110 sql(`CREATE INDEX IF NOT EXISTS rate_batches_at ON rate_batches (at)`);
111 sql(`CREATE TABLE IF NOT EXISTS rate_blocked (k TEXT NOT NULL, b INTEGER NOT NULL, until INTEGER NOT NULL, crossed INTEGER NOT NULL, peak INTEGER NOT NULL, PRIMARY KEY (k, b))`);
112 // Serves the document (`WHERE until > ? ORDER BY until DESC LIMIT 4096`, on every revalidation) and the blocked prune
113 // (`until <= ?`) without a scan of every block and a sort.
114 sql(`CREATE INDEX IF NOT EXISTS rate_blocked_until ON rate_blocked (until)`);
115 sql(`CREATE TABLE IF NOT EXISTS rate_meta (name TEXT PRIMARY KEY, v INTEGER NOT NULL)`);
116 }
118 gen(): number {
119 return num(this.#sql(`SELECT v FROM rate_meta WHERE name = 'gen'`).toArray()[0], 'v');
120 }
122 #bumpGen(): number {
123 const next = this.gen() + 1;
124 this.#sql(`INSERT INTO rate_meta (name, v) VALUES ('gen', ?) ON CONFLICT (name) DO UPDATE SET v = excluded.v`, next);
125 return next;
126 }
128 /** Applies a batch once. A replayed id is acknowledged and changes nothing. */
129 apply(req: ApplyRequest, now: number): ApplyResult {
130 checkApply(req);
131 let written = 0;
132 const run = (q: string, ...b: SqlValue[]): SqlRow[] => {
133 const c = this.#sql(q, ...b);
134 const rows = c.toArray();
135 written += c.rowsWritten;
136 return rows;
137 };
138 let hits = 0;
139 for (const e of req.entries) hits += e[2];
140 if (run(`SELECT 1 AS x FROM rate_batches WHERE id = ?`, req.id).length > 0) {
141 return { replay: true, keys: req.entries.length, hits, newBlocks: 0, rowsWritten: written, gen: this.gen(), over: [], pruned: { hits: 0, batches: 0, blocked: 0, backlog: this.#pruneBacklog } };
142 }
143 run(`INSERT INTO rate_batches (id, at, hits) VALUES (?, ?, ?)`, req.id, now, hits);
144 const slot = Math.floor(now / SLOT_MS);
145 const live = firstLiveSlot(now);
146 let newBlocks = 0;
147 let changed = false;
148 const over: OverKey[] = [];
149 for (const [k, b, n] of req.entries) {
150 run(`INSERT INTO rate_hits (k, b, slot, n) VALUES (?, ?, ?, ?) ON CONFLICT (k, b, slot) DO UPDATE SET n = n + excluded.n`, k, b, slot, n);
151 const limit = req.limits[b === BUCKET_PACK ? 1 : 0];
152 const slots = run(`SELECT slot, n FROM rate_hits WHERE k = ? AND b = ? AND slot >= ? ORDER BY slot`, k, b, live).map(r => ({ slot: num(r, 'slot'), n: num(r, 'n') }));
153 let sum = 0;
154 for (const s of slots) sum += s.n;
155 if (sum < limit) continue;
156 const until = blockedUntil(slots, sum, limit);
157 const prior = run(`SELECT until, crossed, peak FROM rate_blocked WHERE k = ? AND b = ?`, k, b)[0];
158 const active = prior !== void 0 && num(prior, 'until') > now;
159 const crossed = active ? num(prior, 'crossed') : now;
160 const peak = active ? Math.max(num(prior, 'peak'), sum) : sum;
161 if (!active) newBlocks++;
162 if (!active || num(prior, 'until') !== until || num(prior, 'peak') !== peak) {
163 run(`INSERT INTO rate_blocked (k, b, until, crossed, peak) VALUES (?, ?, ?, ?, ?) ON CONFLICT (k, b) DO UPDATE SET until = excluded.until, crossed = excluded.crossed, peak = excluded.peak`, k, b, until, crossed, peak);
164 if (!active || num(prior, 'until') !== until) changed = true;
165 }
166 over.push({ k, b, sum, limit, crossed, peak });
167 }
168 const pruned = { hits: 0, batches: 0, blocked: 0, backlog: this.#pruneBacklog };
169 if (this.#pruneBacklog || now - this.#lastPrune >= PRUNE_EVERY_MS) {
170 // Bounded and adaptive: per table at most PRUNE_BATCH_ROWS plus the rows this apply added to it. Under backlog every
171 // apply prunes, and it takes out at least what it put in, so the backlog cannot grow with traffic (1M clients a
172 // minute is ~1M rate_hits rows in, at up to MAX_BATCH_KEYS per apply); an apply's prune never writes more than
173 // its own inserts + 128 rows, so a quiet spell is not followed by a multi-thousand-row apply. A full slice means
174 // more is waiting; the next apply prunes again (#pruneBacklog) instead of waiting PRUNE_EVERY_MS.
175 this.#lastPrune = now;
176 const slice = (table: string, where: string, order: string, bound: number, budget: number): number => {
177 const victims = run(`SELECT rowid AS r FROM ${table} WHERE ${where} ORDER BY ${order} LIMIT ?`, bound, budget);
178 if (victims.length === 0) return 0;
179 run(`DELETE FROM ${table} WHERE rowid IN (SELECT rowid FROM ${table} WHERE ${where} ORDER BY ${order} LIMIT ?)`, bound, budget);
180 return victims.length;
181 };
182 // Each entry adds at most one rate_hits row (its key's current slot).
183 const hitsBudget = PRUNE_BATCH_ROWS + req.entries.length;
184 const batchesBudget = PRUNE_BATCH_ROWS + 1;
185 const blockedBudget = PRUNE_BATCH_ROWS + newBlocks;
186 pruned.hits = slice('rate_hits', 'slot < ?', 'slot', live, hitsBudget);
187 pruned.batches = slice('rate_batches', 'at < ?', 'at', now - DEDUPE_RETENTION_MS, batchesBudget);
188 pruned.blocked = slice('rate_blocked', 'until <= ?', 'until', now, blockedBudget);
189 if (pruned.blocked > 0) changed = true;
190 this.#pruneBacklog = pruned.hits === hitsBudget || pruned.batches === batchesBudget || pruned.blocked === blockedBudget;
191 pruned.backlog = this.#pruneBacklog;
192 }
193 const gen = changed ? this.#bumpGen() : this.gen();
194 return { replay: false, keys: req.entries.length, hits, newBlocks, rowsWritten: written, gen, over, pruned };
195 }
197 /** The read side's one document: every block still in force, newest `until` first. */
198 doc(now: number): BlockedDoc {
199 const rows = this.#sql(`SELECT k, b, until, crossed FROM rate_blocked WHERE until > ? ORDER BY until DESC LIMIT ?`, now, MAX_DOC_ENTRIES).toArray();
200 return { v: 1, gen: this.gen(), at: now, entries: rows.map(r => [String(r['k']), num(r, 'b'), num(r, 'until'), num(r, 'crossed')] as const) };
201 }
203 /** Rows per table, for the stats log. */
204 sizes(): { hits: number; batches: number; blocked: number } {
205 const c = (t: string): number => num(this.#sql(`SELECT COUNT(*) AS c FROM ${t}`).toArray()[0], 'c');
206 return { hits: c('rate_hits'), batches: c('rate_batches'), blocked: c('rate_blocked') };
207 }
209 /** Expired rows still stored (the prune backlog), per table. Index range counts. */
210 backlog(now: number): { hits: number; batches: number; blocked: number } {
211 const c = (q: string, bound: number): number => num(this.#sql(q, bound).toArray()[0], 'c');
212 return {
213 hits: c(`SELECT COUNT(*) AS c FROM rate_hits WHERE slot < ?`, firstLiveSlot(now)),
214 batches: c(`SELECT COUNT(*) AS c FROM rate_batches WHERE at < ?`, now - DEDUPE_RETENTION_MS),
215 blocked: c(`SELECT COUNT(*) AS c FROM rate_blocked WHERE until <= ?`, now),
216 };
217 }
Diagnostics4 git calls · 29 ms
CallStatusSizeTime029 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 · hit2 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=2
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=61
Open pack map
fetch2003.9 KiB · hit24 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=24
git.response.bytes=3975
git.response.cache=HIT
git.response.duration_ms=24
git.fetch.wants=97f49969c5a72691f3fda0c33ad5d4ee6055ff74
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=3975
git.pkt.payload.max=3954
git.sideband.band1.bytes=3953
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
a5e3114d895abdc9
Request
7a1bf4d8…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format