GitHubivarvong
ply
main
1// The clock of one HTTP exchange (#255): a stall is refused, a long healthy stream is not.
2//
3// firstByteTimeoutMs from the request (or from the end of a streamed upload) to the response headers
4// idleTimeoutMs the longest wait on the network with no progress: no upload piece taken by the platform, no
5// response body chunk in
6// heldTimeoutMs the longest the consumer may hold a chunk (from taking it to asking for the next) (#273)
7// requestTimeoutMs the whole exchange, opt-in (0, the default, is no total cap)
8//
9// 0 turns a timer off. git has no total timeout either (http.lowSpeedLimit is off by default); a caller who needs a
10// wall-clock bound passes requestTimeoutMs or its own signal.
11//
12// The clock is a pure state machine (`transition`, `deadlineOf`); `exchangeClock` only feeds it events and arms what it
13// says. Two rules it cannot break: a state never moves backwards (headers seen means the first byte is satisfied for
14// good, whatever the upload does after), and time is charged only while ply waits on the network: while the consumer
15// holds a chunk, or has not asked for the next one (`held`), neither the first-byte nor the idle limit runs: the held
16// limit does, from the first clock read after the take (the take reads no clock: never early, late by at most one
17// pending timer's interval), so network idle and a stalled
18// consumer are distinct limits with distinct names.
19//
20// One timer. An event moves the mark; the timer is set again only when none is pending or the new deadline is earlier
21// than the pending one, and when it fires it re-arms for what is left: a body chunk costs no setTimeout and no
22// clearTimeout (test/deadline.test.js counts them). While the consumer holds a chunk, a timer that fires re-arms for
23// the hold's start + heldTimeoutMs (or the total cap, if earlier); with both 0 it is not set again until the consumer asks. The timer is the strong owner of the
24// AbortController: AbortSignal.any holds its sources weakly and an AbortSignal.timeout is held only by its own weak
25// timer, so after a GC it never fires and a stalled body hangs forever (Node 20/22; found by the calibration harness).
26// A controller owned by a live timer cannot be collected. Date.now in a Worker advances only across I/O; every mark is
27// taken after the I/O that made it.
28import { field } from './absent.js';
29import { MAX_TIMER_MS } from './limits.js';
30import { assertNever } from './result.js';
32export type TimeoutKey = 'firstByteTimeoutMs' | 'idleTimeoutMs' | 'heldTimeoutMs' | 'requestTimeoutMs';
33// connecting: the request is out (a byte body), no headers yet. uploading: a streamed body is going out.
34// awaiting_first_byte: the upload ended, no headers yet. streaming: headers seen, ply is waiting on the network.
35// held: headers seen, the consumer holds a chunk or has not asked for the next. done: ended, nothing fires.
36export type ClockState = 'connecting' | 'uploading' | 'awaiting_first_byte' | 'streaming' | 'held' | 'done';
37// request_sent: the request went out again (the stale-memo retry). upload_started / upload_bytes / upload_ended: the
38// streamed request body. headers: the response headers arrived. body_chunk: a body chunk arrived from the network.
39// consumer_took: the chunk was handed to the consumer. consumer_asked: the consumer asked for the next. ended: over.
40export type ClockEvent = 'request_sent' | 'upload_started' | 'upload_bytes' | 'upload_ended' | 'headers' | 'body_chunk' | 'consumer_took' | 'consumer_asked' | 'ended';
41// The next state, and whether the event is network progress that restarts the wait (moves the mark).
42type ClockStep = { readonly state: ClockState; readonly restart: boolean };
43export type ExchangeTimeouts = { readonly firstByteMs: number; readonly idleMs: number; readonly heldMs: number; readonly totalMs: number };
44export type ExchangeClock = {
45 readonly signal: AbortSignal;
46 readonly feed: (event: ClockEvent) => void;
47 // the exchange ended: no timer fires after it (feed('ended'))
48 readonly cancel: () => void;
49};
51// Every step there is, made once: the machine runs per body chunk and allocates nothing.
52const steps = (restart: boolean): Readonly<Record<ClockState, ClockStep>> => ({
53 connecting: { state: 'connecting', restart }, uploading: { state: 'uploading', restart }, awaiting_first_byte: { state: 'awaiting_first_byte', restart },
54 streaming: { state: 'streaming', restart }, held: { state: 'held', restart }, done: { state: 'done', restart },
55});
56const STAY = steps(false);
57const GO = steps(true);
58const stay = (state: ClockState): ClockStep => STAY[state];
59const go = (state: ClockState): ClockStep => GO[state];
60// The whole machine. An event a state has no use for leaves it as it is: nothing moves a state backwards.
61export function transition(state: ClockState, event: ClockEvent): ClockStep {
62 if (event === 'ended') return stay('done');
63 switch (state) {
64 case 'done': return stay('done');
65 case 'connecting':
66 if (event === 'request_sent') return go('connecting');
67 if (event === 'upload_started') return go('uploading');
68 return event === 'headers' ? go('streaming') : stay(state);
69 case 'uploading':
70 if (event === 'upload_bytes') return go('uploading');
71 if (event === 'upload_ended') return go('awaiting_first_byte');
72 return event === 'headers' ? go('streaming') : stay(state);
73 case 'awaiting_first_byte': return event === 'headers' ? go('streaming') : stay(state);
74 case 'streaming':
75 // bytes moved either way; an upload that ends here ends nothing the clock waits for
76 if (event === 'upload_bytes' || event === 'body_chunk') return go('streaming');
77 // the take does not read the clock (#273 review: no clock read per chunk added): the hold runs from the first
78 // clock read after the take (exchangeClock's anchor), never from an earlier network mark
79 return event === 'consumer_took' ? stay('held') : stay(state);
80 case 'held':
81 // only the consumer's ask puts ply back on the network, and the wait starts then
82 return event === 'consumer_asked' ? go('streaming') : stay(state);
83 }
84 return assertNever(state);
85}
87// Node's timer has unref (the DOM lib types it as a number); a Worker's has none.
88const unref = (timer: unknown): void => {
89 const f = field(timer, 'unref');
90 if (f.tag === 'some' && typeof f.value === 'function') Reflect.apply(f.value, timer, []);
91};
93const MESSAGES: Readonly<Record<TimeoutKey, (ms: number) => string>> = {
94 firstByteTimeoutMs: ms => `no response within ${ms} ms (limits.firstByteTimeoutMs)`,
95 idleTimeoutMs: ms => `no bytes moved for ${ms} ms (limits.idleTimeoutMs)`,
96 heldTimeoutMs: ms => `the consumer held a chunk for ${ms} ms without asking for the next (limits.heldTimeoutMs)`,
97 requestTimeoutMs: ms => `request exceeded ${ms} ms`,
98};
99// The abort reason: a TimeoutError, as the platform's own, naming the limit that fired (wrapNet reads `limit`).
100export function timeoutReason(key: TimeoutKey, ms: number): DOMException {
101 return Object.assign(new DOMException(MESSAGES[key](ms), 'TimeoutError'), { limit: key });
102}
103// The limit a timeout reason names, or none.
104export function timeoutLimit(reason: unknown): TimeoutKey | null {
105 const f = field(reason, 'limit');
106 return f.tag === 'some' && (f.value === 'firstByteTimeoutMs' || f.value === 'idleTimeoutMs' || f.value === 'heldTimeoutMs' || f.value === 'requestTimeoutMs') ? f.value : null;
107}
109type Due = { readonly at: number; readonly key: TimeoutKey; readonly ms: number };
110const earlier = (a: Due | null, b: Due | null): Due | null => {
111 if (a === null) return b;
112 if (b === null) return a;
113 return a.at <= b.at ? a : b;
114};
115// The deadline to arm in `state`, whose wait began at `mark`, in an exchange that began at `start`; null is none. In
116// `held`, `mark` is when the clock first saw the hold (the first clock read after the take), never the network mark.
117export function deadlineOf(state: ClockState, mark: number, start: number, t: ExchangeTimeouts): Due | null {
118 if (state === 'done') return null;
119 const total: Due | null = t.totalMs > 0 ? { at: start + t.totalMs, key: 'requestTimeoutMs', ms: t.totalMs } : null;
120 if (state === 'held') return earlier(total, t.heldMs > 0 ? { at: mark + t.heldMs, key: 'heldTimeoutMs', ms: t.heldMs } : null);
121 const waiting = state === 'connecting' || state === 'awaiting_first_byte';
122 const ms = waiting ? t.firstByteMs : t.idleMs;
123 const step: Due | null = ms > 0 ? { at: mark + ms, key: waiting ? 'firstByteTimeoutMs' : 'idleTimeoutMs', ms } : null;
124 return earlier(total, step);
125}
127const pastHeaders = (state: ClockState): boolean => state === 'streaming' || state === 'held';
128// Past the headers, whether `state`'s own step deadline (from `mark`) is earlier than a timer pending for `armedFor`.
129const steppedEarlier = (state: ClockState, t: ExchangeTimeouts, mark: number, armedFor: number): boolean => {
130 const ms = state === 'held' ? t.heldMs : t.idleMs;
131 return ms > 0 && armedFor > mark + ms;
132};
134// `onFire` runs once, before the abort, with the limit that fired (the span records it). `now` is the clock (tests).
135export function exchangeClock(t: ExchangeTimeouts, outer: AbortSignal | null, onFire: (key: TimeoutKey, ms: number) => void, now: () => number = Date.now): ExchangeClock {
136 const ac = new AbortController();
137 const start = now();
138 let state: ClockState = 'connecting';
139 let mark = start;
140 // The hold is timed from the first clock read that sees it (a timer firing, or an arm), never from a read of its own:
141 // the take reads no clock. `heldFrom` is that read; `anchored` says the current hold has one.
142 let heldFrom = start;
143 let anchored = true;
144 let timer: ReturnType<typeof setTimeout> | null = null;
145 // when the pending timer fires
146 let armedFor = 0;
147 const due = (): Due | null => deadlineOf(state, state === 'held' ? heldFrom : mark, start, t);
148 // A clock read seeing a hold for the first time starts it there: so a hold is cut no earlier than take + heldMs.
149 const anchor = (at: number): void => { if (state === 'held' && !anchored) { heldFrom = at; anchored = true; } };
150 const clear = (): void => { if (timer !== null) clearTimeout(timer); timer = null; };
151 // A pending timer that fires no later than the deadline is left alone: fire() re-arms for what is left. So is one
152 // pending when there is nothing to wait for (held, no total cap): it finds that out when it fires and is not set again.
153 const arm = (): void => {
154 if (state === 'done') { clear(); return; }
155 // the take is synchronous with this arm when an unanchored hold reaches it from feed: this read is the take's time
156 if (state === 'held' && !anchored) anchor(now());
157 const d = due();
158 if (d === null) return;
159 if (timer !== null && armedFor <= d.at) return;
160 clear();
161 const at = now();
162 const delay = Math.min(MAX_TIMER_MS, Math.max(0, d.at - at));
163 armedFor = at + delay;
164 // oxlint-disable-next-line no-use-before-define -- fire re-arms: the two refer to each other
165 timer = setTimeout(fire, delay);
166 unref(timer);
167 };
168 function fire(): void {
169 timer = null;
170 const at = now();
171 anchor(at);
172 const d = due();
173 if (d === null) return;
174 if (at < d.at) { arm(); return; }
175 state = 'done';
176 onFire(d.key, d.ms);
177 ac.abort(timeoutReason(d.key, d.ms));
178 }
179 const feed = (event: ClockEvent): void => {
180 const from = state;
181 const next = transition(from, event);
182 state = next.state;
183 if (next.restart) mark = now();
184 if (state === 'held' && from !== 'held') anchored = false;
185 // The per-chunk path makes no timer call: a pending timer that fires no later than the new deadline is left alone
186 // and re-arms for what is left when it fires. That covers a restart inside a state (marks only advance) and
187 // a move between streaming and held whose new step deadline (mark + idle, or mark + held) is no earlier than the
188 // pending timer. A move between them that brings the deadline earlier (a timer set for take + held, or the total
189 // cap, and then the ask; or a held limit shorter than the pending idle one) is the one that sets it again.
190 // An unanchored hold keeps a pending timer due by mark + heldMs (mark is before the take): its fire starts the hold.
191 if (timer !== null && (state === from || (pastHeaders(from) && pastHeaders(state) && !steppedEarlier(state, t, mark, armedFor)))) return;
192 arm();
193 };
194 arm();
195 return { signal: outer ? AbortSignal.any([ac.signal, outer]) : ac.signal, feed, cancel: () => { feed('ended'); } };
196}
198// The most bytes handed to the platform at once.
199const UPLOAD_PIECE = 65_536;
200// A streamed request body whose pulls by the platform are the upload's progress marks. A source chunk goes to the
201// platform in views of at most UPLOAD_PIECE (no copy), so one large chunk is many marks, not one. It reads the source
202// only when the platform pulls it (no buffer of its own: highWaterMark 0), and the source is locked only from the first
203// pull, so a request that never reads it leaves it as it was. Its end is the upload's end.
204//
205// What a mark proves, and what it does not. A pull says the platform took another piece into its own buffers, not that
206// the piece reached the server: ply cannot see below fetch. The platform pulls when its buffers have room (on Node,
207// undici's socket queue and the kernel's send buffer), so on a slow link the marks come in bursts a buffer apart, and
208// the last piece is handed over while a buffered tail is still going out. Measured with the real fetch on Node 24 over
209// loopback, 4 MiB to a server reading 64 KiB per 25 ms: 64 pulls in 8 bursts, the longest gap between pulls 473 ms
210// while the server never paused for more than 31 ms, and the last pull 1.7 s before the server's last read. So:
211// - while pieces remain, idleTimeoutMs fires when the platform takes no piece for that long, so that limit must be
212// longer than the link takes to drain one burst of the platform's buffers (not one 64 KiB piece);
213// - once the last piece is handed over the upload has ended for the clock, and firstByteTimeoutMs, which starts
214// there, covers sending the buffered tail as well as the server's answer. A link too slow to drain the tail in
215// that time fails as firstByteTimeoutMs: no response arrived in time, which is all ply can observe by then.
216// Neither measures upload progress below fetch. The bound on a stalled upload as a whole, whatever the platform has
217// buffered, is requestTimeoutMs (off by default) or the caller's signal.
218// test/upload-progress-socket.test.js holds all three on a real socket.
219export function watchedUpload(source: ReadableStream<Uint8Array>, clock: ExchangeClock): ReadableStream<Uint8Array> {
220 let reader: ReadableStreamDefaultReader<Uint8Array> | null = null;
221 let rest: Uint8Array | null = null;
222 return new ReadableStream<Uint8Array>({
223 async pull(c: ReadableStreamDefaultController<Uint8Array>): Promise<void> {
224 let chunk = rest;
225 if (chunk === null) {
226 if (reader === null) reader = source.getReader();
227 const r = await reader.read();
228 if (r.done) { clock.feed('upload_ended'); c.close(); return; }
229 chunk = r.value;
230 }
231 rest = chunk.length > UPLOAD_PIECE ? chunk.subarray(UPLOAD_PIECE) : null;
232 clock.feed('upload_bytes');
233 c.enqueue(rest === null ? chunk : chunk.subarray(0, UPLOAD_PIECE));
234 },
235 cancel: async (reason: unknown): Promise<void> => { rest = null; await (reader === null ? source.cancel(reason) : reader.cancel(reason)); },
236 }, { highWaterMark: 0 });
237}
239// A response body read that the exchange's signal ends, whether or not the platform (or a fetch wrapper, or a double)
240// ties the body to the signal: on abort the read is cancelled and the chunks end, and `cut()` says so; the caller
241// reports the abort (wrapNet of the signal). Leaving early cancels the body, as a for-await over the stream does.
242export type AbortableRead = { readonly chunks: AsyncGenerator<Uint8Array, void, unknown>; readonly cut: () => boolean };
243export function readAbortable(stream: ReadableStream<Uint8Array>, signal: AbortSignal): AbortableRead {
244 let cut = false;
245 async function* chunks(): AsyncGenerator<Uint8Array, void, unknown> {
246 // a fetch double may hand back an async iterable that is not a stream: read it as it is
247 // oxlint-disable-next-line typescript/no-unnecessary-condition -- not every body a double returns has getReader
248 if (typeof stream.getReader !== 'function') { yield* stream; return; }
249 const reader = stream.getReader();
250 const stop = (): void => { reader.cancel(signal.reason).catch(() => { /* the abort is the outcome */ }); };
251 if (signal.aborted) stop(); else signal.addEventListener('abort', stop, { once: true });
252 let finished = false;
253 try {
254 // oxlint-disable no-await-in-loop -- one chunk at a time is the point
255 for (;;) {
256 const r = await reader.read();
257 if (signal.aborted) { cut = true; finished = true; return; }
258 if (r.done) { finished = true; return; }
259 yield r.value;
260 }
261 // oxlint-enable no-await-in-loop
262 } finally {
263 signal.removeEventListener('abort', stop);
264 if (finished) reader.releaseLock(); else await reader.cancel().catch(() => { /* already ended */ });
265 }
266 }
267 return { chunks: chunks(), cut: () => cut };
268}
Diagnostics6 git calls · 38 ms
CallStatusSizeTime038 ms
discover200191 B2 ms
git.upload-pack discover http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=2 git.response.bytes=191 git.server.agent=git/github-9922ec520325-Linux git.server.object_format=sha1 git.server.caps=agent ls-refs fetch server-option object-format git.server.fetch=shallow wait-for-done filter git.protocol.version=2 git.pkt.frames=9 git.pkt.data=7 git.pkt.flush=2 git.pkt.delim=0 git.pkt.bytes=191 git.pkt.payload.max=36
ls-refs20012 KiB · 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=11990 git.response.cache=HIT git.response.duration_ms=3 git.protocol.version=2 git.pkt.frames=152 git.pkt.data=151 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=11990 git.pkt.payload.max=122 git.ls_refs.count=151 git.ls_refs.head=refs/heads/main
fetchtree:0 · deepen 102004.2 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=4347 git.response.cache=HIT git.response.duration_ms=2 git.fetch.filter=tree:0 git.fetch.wants=19912563f540228593df0c489082e5e2508e21e4 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=7 git.pkt.data=5 git.pkt.flush=1 git.pkt.delim=1 git.pkt.bytes=4347 git.pkt.payload.max=4247 git.sideband.band1.bytes=4247 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=10 git.pack.bytes=4247 git.pack.ofs_delta=0 git.pack.ref_delta=0 git.pack.chain.max=0 git.pack.trailer=a6caf8e129bea82c9bae4cbc7c130c9205add400 git.pack.full=10Open pack map
fetchtree:0200919 B · 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=919 git.response.cache=HIT git.response.duration_ms=2 git.fetch.filter=tree:0 git.fetch.wants=800d30ba8923860bfc460ca884b7f9ba22083588 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=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=919 git.pkt.payload.max=892 git.sideband.band1.bytes=892 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=1 git.pack.bytes=892 git.pack.trailer=5323b9266eea5ded637285d1c5320699f12be76eOpen pack map
fetchtree:02002.4 KiB · hit3 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=3 git.response.bytes=2507 git.response.cache=HIT git.response.duration_ms=3 git.fetch.filter=tree:0 git.fetch.wants=8f720d29ff85ce682ffdad9c393b04a3834c3203 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=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=2507 git.pkt.payload.max=2480 git.sideband.band1.bytes=2480 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=1 git.pack.bytes=2480 git.pack.trailer=723b6bf1d4d6021fe5eb940c622b9ff00ee4a381Open pack map
fetch2005.9 KiB · hit28 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=28 git.response.bytes=6022 git.response.cache=HIT git.response.duration_ms=28 git.fetch.wants=3de517da05ddbb5a04b886d5761c228ccefa9362 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=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=6022 git.pkt.payload.max=5995 git.sideband.band1.bytes=5995 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://github.com/ivarvong/ply
- Ref
- refs/heads/main
- Commit
- 19912563f540228593df0c489082e5e2508e21e4
- cf-ray
- a5e2bff4d9ab89da
- Request
- e626a8df…
- Protocol
- v2 · sha1
- Agent
- git/github-9922ec520325-Linux
- Filter
- advertised
- Fetch
- shallow wait-for-done filter
- Capabilities
- agent ls-refs fetch server-option object-format