GitHubivarvong

ply

main
ply6 git calls151 ms23 KiB4 cachedprotocol v2
122 lines7.5 KiBRaw
1// A random-access byte source: `size` bytes, read as a stream of [offset, offset + length). The one storage interface
2// the pack-over-a-spool code takes (#235, #248), so the same code works over a file, a memory buffer or an object store
3// (an R2 ranged GET). A read past `size`, or a negative or fractional bound, is the source's refusal to make; the stream
4// yields exactly `length` bytes or errors.
5import type { SignalArg } from './absent.js';
6import type { PlyError } from './errors.js';
7import { fail, plyError } from './errors.js';
8import type { Result } from './result.js';
9import { ok } from './result.js';
11// `signal` aborts when the reader no longer wants the range (its consumer cancelled, or the operation's own signal
12// aborted): a source that can abandon a read in flight does. It is optional in the type (SignalArg, absent.ts): an
13// implementer may ignore it (a read of two parameters is a RangeSource), a direct caller may omit it, and a wrapper may
14// pass on the optional signal it was given, so a read that takes it has to work without one. ply always passes one, and
15// never waits for a source that ignores it.
16export type RangeRead = (offset: number, length: number, ...signal: SignalArg) => Promise<Result<ReadableStream<Uint8Array>, PlyError>>;
17export type RangeSource = { readonly size: number; readonly read: RangeRead };
19// The signal that never aborts: the default `signal` of an operation whose caller gave none (resolvePackRange,
20// scanPackIndex, loadTransferPack, packIdentity). Only then is a source that never answers waited for.
21export const UNCANCELLABLE: AbortSignal = new AbortController().signal;
23// One operation's stop, for every await it makes on storage it does not own (opening a range, reading a chunk, asking a
24// stream to cancel, a caller's lookup). The storage may never answer; an operation whose signal aborts settles all the
25// same, with the coded `aborted` outcome, because none of those awaits is made bare: each goes through `race`.
26// race(p, late) p's outcome, or HALTED as soon as the signal aborts, whether or not p ever settles. What p answers
27// after that goes to `late` (a range that opened late is cancelled there); a late rejection goes
28// nowhere, and is handled, so it is never an unhandled rejection.
29// reading(range) the stream being read (null: none): cancelled when the signal aborts, asked and not waited for.
30// release() the operation is over: stop listening to the caller's signal (which may outlive it).
31// Held: one waker per await in flight (removed when it settles), never a reaction per chunk on a long-lived promise.
32// With UNCANCELLABLE nothing can halt, so `race` is the promise's own outcome: no waker, no listener, no extra promise
33// held on the path that takes no signal.
34export const HALTED: unique symbol = Symbol('halted');
35export type Halted = typeof HALTED;
36type Cancellable = { readonly cancel: (reason: unknown) => Promise<unknown> };
37export type Halt = {
38 // given to every source.read: a source that can abandon a read does
39 readonly signal: AbortSignal;
40 readonly halted: () => boolean;
41 readonly race: <T>(p: Promise<T>, late: (v: T) => void) => Promise<T | Halted>;
42 readonly reading: (range: Cancellable | null) => void;
43 readonly release: () => void;
44};
45export const drop = (): void => { /* the operation is halted or already refused: its outcome is decided without this */ };
46// Asks a range to stop, without waiting for the source to say it has. The range is the caller's: a cancel() that throws
47// where it stands, or answers with something that is not a promise, is its own failure to cancel and changes nothing
48// (thrown from here it would leave the abort listener below, past every caller, with its wakers not woken).
49export const cancelRange = (range: Cancellable, reason: unknown): void => {
50 try { Promise.resolve(range.cancel(reason)).catch(drop); } catch { drop(); }
51};
52// A range that opened after the operation stopped waiting for it: cancelled, not left open.
53export const cancelLate = (opened: Result<ReadableStream<Uint8Array>, PlyError>): void => { if (opened.ok) cancelRange(opened.value, null); };
54export const aborted = (what: string): PlyError => plyError('aborted', `${what}: aborted while waiting for the caller's storage`);
55export function haltOn(signal: AbortSignal): Halt {
56 let range: Cancellable | null = null;
57 const wakers = new Set<(halted: Halted) => void>();
58 const onAbort = (): void => {
59 if (range !== null) cancelRange(range, signal.reason);
60 range = null;
61 for (const wake of wakers) wake(HALTED);
62 wakers.clear();
63 };
64 if (signal !== UNCANCELLABLE && !signal.aborted) signal.addEventListener('abort', onAbort, { once: true });
65 return {
66 signal,
67 halted: () => signal.aborted,
68 reading(r) {
69 if (r !== null && signal.aborted) cancelRange(r, signal.reason);
70 else range = r;
71 },
72 // oxlint-disable-next-line typescript/promise-function-async -- an async wrapper is a promise and two hops more per chunk read
73 race<T>(p: Promise<T>, late: (v: T) => void): Promise<T | Halted> {
74 // `p` is typed a promise, but a source written in JavaScript may answer with the value itself, which the bare await
75 // this replaces took. Promise.resolve gives a platform promise back as it is (no promise, no hop added) and makes
76 // one of anything else, so what is returned is always a promise and `then` below is always there.
77 const answer = Promise.resolve(p);
78 if (signal === UNCANCELLABLE) return answer;
79 // One promise per await, settled by whichever comes first: p (one reaction on it) or the abort listener, through
80 // this await's waker (its resolve). No Promise.race and no second promise to lose: a chunk read costs one promise and one hop.
81 return new Promise<T | Halted>((resolve, reject) => {
82 // still waited for (the waker is there to take): p's outcome is the race's. No longer: a value goes to `late`,
83 // and what `late` throws goes nowhere. A rejection is handled here whenever it comes: before the halt the
84 // race carries it, after it nothing does.
85 // oxlint-disable-next-line promise/catch-or-return -- both outcomes are taken here; neither reaction can throw
86 answer.then(v => {
87 const waited = wakers.delete(resolve);
88 resolve(v);
89 if (!waited) { try { late(v); } catch { drop(); } }
90 return null;
91 }, (e: unknown) => {
92 wakers.delete(resolve);
93 // oxlint-disable-next-line typescript/prefer-promise-reject-errors -- p's own rejection, passed on as it came
94 reject(e);
95 return null;
96 });
97 if (signal.aborted) resolve(HALTED);
98 else wakers.add(resolve);
99 });
100 },
101 release() {
102 signal.removeEventListener('abort', onAbort);
103 range = null;
104 wakers.clear();
105 },
106 };
109// A RangeSource over bytes in memory (tests, and a pack small enough to hold): each read is one chunk, a view (no copy).
110export function rangeFromBytes(bytes: Uint8Array): RangeSource {
111 return {
112 size: bytes.length,
113 read: async (offset, length) => {
114 await Promise.resolve();
115 if (!Number.isInteger(offset) || !Number.isInteger(length) || offset < 0 || length < 0 || offset + length > bytes.length) {
116 return fail('bad_request', `range ${offset}+${length} outside ${bytes.length} bytes`);
117 }
118 const view = bytes.subarray(offset, offset + length);
119 return ok(new ReadableStream<Uint8Array>({ start(c) { if (view.length > 0) c.enqueue(view); c.close(); } }));
120 },
121 };
Diagnostics6 git calls · 151 ms
CallStatusSizeTime0151 ms
discover200191 B2 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=1
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 · hit1 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=1
git.response.bytes=11990
git.response.cache=HIT
git.response.duration_ms=1
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 · hit1 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=4347
git.response.cache=HIT
git.response.duration_ms=1
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=10
Open pack map
fetchtree:0200919 B · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=1
git.response.bytes=919
git.response.cache=HIT
git.response.duration_ms=3
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=5323b9266eea5ded637285d1c5320699f12be76e
Open pack map
fetchtree:02002.4 KiB · hit1 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=144
git.response.bytes=2507
git.response.cache=HIT
git.response.duration_ms=1
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=723b6bf1d4d6021fe5eb940c622b9ff00ee4a381
Open pack map
fetch2003.0 KiB144 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=3095
git.response.cache=MISS
git.response.duration_ms=144
git.fetch.wants=b70eed82753a13dffbea604d7ac8d2d2fe02c8d6
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=3095
git.pkt.payload.max=3068
git.sideband.band1.bytes=3068
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
a5e0f847be06332c
Request
0e3defe5…
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