Artifactspublic-v0

ply

main
ply4 git calls440 ms47 KiB2 cachedprotocol v2
374 lines27 KiBRaw
1// The transport contract. A transport is a plain record; the protocol layer (lsrefs, fetch, push, discover, receivecaps)
2// calls exactly two things on it and never looks inside:
3//
4// t.frames(service, body, span, hints) → AsyncIterable of pkt-line frames of one command's response
5// t.advertise(service, span) → Result<Uint8Array>: the service's capability advertisement (pkt-lines)
6//
7// plus the data every caller may read: t.kind ('http'), t.url (credential-free, for spans and messages),
8// t.tracer, t.parent (the span wire spans hang under), t.limits, t.signal, and t.scrub: null, or a function that
9// redacts the transport's credential from any text (server echoes), applied by every span under it (otel.js).
10//
11// `hints` are transport-neutral requests a transport may honor or ignore: { bypassCache: true } asks an HTTP transport
12// with a pack cache in front of it (packcache.js) to go to the origin. Transports record, on the span they are given:
13// git.transport 'http'
14// git.request.bytes body bytes sent
15// git.response.bytes bytes received for this command
16// git.response.first_byte_ms, git.response.duration_ms
17// git.response.cache 'HIT' | 'MISS' | 'BUST' | '' (HTTP with packcache; '' otherwise)
18// server.address, url.full
19// http.response.header.<name> opt-in (createTransport recordResponseHeaders): that response header, lowercased,
20// scrubbed, length-capped. Absent when the response did not send it.
21// http.response.headers.from_cache true when that opt-in exchange was a pack-cache HIT (the header values are the
22// cached response's). Omitted on a live response.
23// and may add transport-specific detail under http.*. Implementation: http.ts (an SSH one was removed 2026-10-31;
24// history on branch archive/ssh).
25import type { Code, ErrorOf, PlyError } from './errors.js';
26import { callbackFailed, describeThrown, fail, plyError } from './errors.js';
27import type { Err, Result } from './result.js';
28import { err, ok } from './result.js';
29import type { CheckedLimits, LimitsInput } from './limits.js';
30import { parseLimits } from './limits.js';
31import type { Span, Tracer } from './otel.js';
32import { KIND, spanOn } from './otel.js';
33import type { Input } from './absent.js';
34import { field, fillIn, fromNullable, mapGet, readKey } from './absent.js';
35import { timeoutLimit } from './deadline.js';
36// the exchange clock (#255), for the HTTP transport
37export { exchangeClock, readAbortable, watchedUpload } from './deadline.js';
38export type { ExchangeClock } from './deadline.js';
39import { isPlyThrown, thrownText } from './boundary.js';
41// One pkt-line frame as pktline.js yields it.
42export type Frame =
43 | { readonly kind: 'data'; readonly payload: Uint8Array }
44 | { readonly kind: 'flush' }
45 | { readonly kind: 'delim' }
46 | { readonly kind: 'end' };
47export type Hints = { readonly bypassCache: boolean };
48export const NO_HINTS: Hints = Object.freeze({ bypassCache: false });
49export type Scrub = (s: string) => string;
50// What a server was found to need, learned at run time and shared by every view of the transport (mutable on purpose).
51// treeFilter: what a filtered fetch is sent as. 'blob:none' for a host that refuses tree:0 (fetch.ts, learned from its
52// 400); 'none' for a host whose upload-pack advertisement has no `filter` on its `fetch=` line (git's own default,
53// uploadpack.allowFilter unset), learned from that advertisement (learnFilter): no filter is sent and the fetch takes
54// the unfiltered pack. blobWants: 'single' for a host that refuses a multi-blob want list (checkout). A caller passes
55// one record to every call on a server; ply fills it (absent.fillIn).
56// The record stays two string enums rather than an ADT with a reason and a time (#136 asked for `refused{reason, at}`):
57// each value already names what was learned (tree:0 = unknown or taken, blob:none = tree:0 refused, none = no filter
58// advertised), the reason and the request that learned it are on that request's span (git.fetch.filter.fallback,
59// .requested, .learned, error.kind), and a time would only serve expiry, which a stale value does not need (see the memo
60// below). Callers persist and compare it as plain JSON; a richer shape would break that for no decision ply makes.
61export type TreeFilter = 'tree:0' | 'blob:none' | 'none';
62export type Quirks = { treeFilter: TreeFilter; blobWants: 'many' | 'single' };
63export const freshQuirks = (): Quirks => ({ treeFilter: 'tree:0', blobWants: 'many' });
64// Whether the remote takes `deepen`: not once an advertisement read for this quirks record listed no `shallow` on its
65// fetch= line (discover, or the read after a refused request: fetch.ts filterUnadvertised). Kept beside the record, not
66// in it, so the public Quirks shape (callers build and persist it as JSON) is unchanged. A record not yet taught is
67// taken to take it (git's upload-pack always lists `shallow`); a server that does not costs one refused request and one
68// advertisement read per record (fetch.ts objectAt). Once a record is taught either way (shallowLearned), an empty
69// response is not a reason to read the advertisement for it again.
70const shallowKnown = new WeakMap<Quirks, boolean>();
71export function learnShallow(t: Transport, advertised: boolean): void { shallowKnown.set(t.quirks, advertised); }
72export const takesShallow = (q: Quirks): boolean => shallowKnown.get(q) !== false;
73export const shallowLearned = (q: Quirks): boolean => shallowKnown.has(q);
74// What an upload-pack advertisement says about `filter`, kept: absent is 'none'; present undoes an earlier 'none' (the
75// host turned it on) and leaves a learned blob:none alone (Artifacts advertises `filter` and refuses tree:0).
76export function learnFilter(t: Transport, advertised: boolean): void {
77 if (!advertised) t.quirks.treeFilter = 'none';
78 else if (t.quirks.treeFilter === 'none') t.quirks.treeFilter = 'tree:0';
80// The default memo (#136): what a remote was found to need, kept per remote for a transport made without a `quirks`
81// record (createTransport, every operation), so a later operation on the same remote does not pay the refusal again
82// (Artifacts' 400 on tree:0 is 100-900 ms; a stock server's empty answer is a request plus an advertisement read).
83// Keyed by origin and path (query, fragment, userinfo and a trailing slash dropped: the credential is never part of the
84// key). Bounded: the least recently used remote is dropped past QUIRKS_MEMO_MAX. Module state, so per process, or per
85// isolate on Workers. A record the caller passes wins (and is filled in place, as before); passing a fresh one (`{}`)
86// opts that call out; forgetQuirks() clears one remote or all of them (a server reconfigured, a test faking several
87// servers at one URL). A stale entry costs bytes, never correctness: blob:none and the unfiltered pack are wider answers
88// to the same question, and a server that stops taking a filter is relearned from its empty answer.
89export const QUIRKS_MEMO_MAX = 256;
90const quirksMemo = new Map<string, Quirks>();
91// The memo key of a parsed remote URL: origin and path, nothing else. The trailing slashes are dropped by walking back
92// from the end, one step per slash dropped: a pattern (`/\/+$/`) restarts at every slash of a run that does not end the
93// path, which is quadratic in a URL the caller's own user may have written.
94const SLASH = 0x2f;
95export const quirksKeyOf = (u: URL): string => {
96 const path = u.pathname;
97 let end = path.length;
98 while (end > 0 && path.codePointAt(end - 1) === SLASH) end -= 1;
99 return `${u.origin}${path.slice(0, end)}`;
100};
101// The same walk for the other pattern of that shape, `/[#;].*$/u` on each line of a stored .git/config (repo-node.ts):
102// where the line's `#` or `;` comment starts, or the line's length when it has none. The pattern cut at the first `#`
103// or `;` with no line end after it (`.` stops at LF, CR, U+2028 and U+2029, and `$` is only the end), and began again
104// at every `#` of a line that ends in CR: quadratic in one CRLF line of a config file. Walking back from the end visits
105// each character once and gives the same cut.
106export const configCommentStart = (line: string): number => {
107 let cut = line.length;
108 for (let i = line.length - 1; i >= 0; i -= 1) {
109 const c = line.charAt(i);
110 if (c === '\n' || c === '\r' || c === '\u2028' || c === '\u2029') break;
111 if (c === '#' || c === ';') cut = i;
112 }
113 return cut;
114};
115// The memo key of a remote URL, or null for a URL that does not parse (createTransport refuses it first).
116export function quirksKey(url: string | URL): string | null {
117 try { return quirksKeyOf(new URL(url)); } catch { return null; }
119// The remembered record for `key`, made (fresh) on first use and marked most recently used.
120export function rememberedQuirks(key: string): Quirks {
121 const hit = mapGet(quirksMemo, key);
122 const q = hit.tag === 'some' ? hit.value : freshQuirks();
123 quirksMemo.delete(key);
124 quirksMemo.set(key, q);
125 for (const oldest of quirksMemo.keys()) {
126 if (quirksMemo.size <= QUIRKS_MEMO_MAX) break;
127 quirksMemo.delete(oldest);
128 }
129 return q;
131// The redirect memo, declared here so forgetQuirks can clear it (described below, with its functions).
132const redirectMemo = new Map<string, Map<string, readonly string[]>>();
133// Forget what was learned about `url` (as quirksKey normalizes it), or about every remote when no url is given: its
134// quirks and its settled redirect (below). Transports already made keep theirs; the next one made for that remote
135// starts fresh.
136export function forgetQuirks(url: string | URL | null = null): void {
137 if (url === null) { quirksMemo.clear(); redirectMemo.clear(); return; }
138 const key = quirksKey(url);
139 // Stryker disable next-line ConditionalExpression: deleting a null key from either map is a no-op, so the guard only states intent
140 if (key !== null) { quirksMemo.delete(key); redirectMemo.delete(key); }
142// The redirect memo (ply-web#117): how a remote's followRedirects 'initial' exchange settled, per remote (the same key as
143// the quirks memo) and per service. The value is the Location of each 3xx that was followed, absolute, without userinfo
144// or fragment, in order; an empty list is "no redirect". A later transport for the same remote replays it with no
145// request: each Location goes through that transport's own allowUrl and the suffix rule again, so a memo never lets a
146// transport go where its own allowUrl would not, and a list longer than its maxRedirects is not used. A memo is a hint:
147// the transport that used one and is then answered with a 3xx drops it and asks the network (http.ts). The same bound
148// and the same per-process (per-isolate) scope as the quirks memo; forgetQuirks clears both.
149export function recalledRedirect(key: string, service: string): readonly string[] | null {
150 const hit = mapGet(redirectMemo, key);
151 if (hit.tag === 'none') return null;
152 redirectMemo.delete(key);
153 redirectMemo.set(key, hit.value);
154 const got = mapGet(hit.value, service);
155 return got.tag === 'some' ? got.value : null;
157export function rememberRedirect(key: string, service: string, locations: readonly string[]): void {
158 const hit = mapGet(redirectMemo, key);
159 const services = hit.tag === 'some' ? hit.value : new Map<string, readonly string[]>();
160 services.set(service, [...locations]);
161 redirectMemo.delete(key);
162 redirectMemo.set(key, services);
163 for (const oldest of redirectMemo.keys()) {
164 if (redirectMemo.size <= QUIRKS_MEMO_MAX) break;
165 redirectMemo.delete(oldest);
166 }
168export function forgetRedirect(key: string, service: string): void {
169 const hit = mapGet(redirectMemo, key);
170 if (hit.tag === 'some') hit.value.delete(service);
172// One probe at a time per record (#136). Until a server has answered a filtered request, two concurrent ones (merge
173// walks both sides at once; two operations on one remembered record) would each pay the refusal or the empty answer.
174// So the first filtered request on a record whose treeFilter is still tree:0 is the probe: a filtered request that
175// arrives while it runs waits for it, then reads the record again (it may now say blob:none or none). An answer that
176// was not a refusal settles the record for what was sent (`filter`: some filter is taken, so a blob:none request needs
177// no probe; `tree:0`: tree:0 itself is taken, nothing does); a failure for another reason (a network error, a missing
178// object) settles nothing and the next request probes. `run` reads the record itself, after any wait.
179export type Probe = 'filter' | 'tree:0';
180const probes = new WeakMap<Quirks, Promise<null>>();
181const settled = new WeakMap<Quirks, Probe>();
182const ignore = (): null => null;
183export async function probing<T extends { readonly ok: boolean }>(q: Quirks, sends: Probe, run: () => Promise<T>): Promise<T> {
184 // read and claimed with no await between them: two callers cannot both see no probe and both start one
185 const pending = fromNullable(probes.get(q));
186 if (pending.tag === 'some') {
187 await pending.value;
188 return probing(q, sends, run);
189 }
190 const known = fromNullable(settled.get(q));
191 if (q.treeFilter !== 'tree:0' || (known.tag === 'some' && (known.value === 'tree:0' || sends === 'filter'))) return run();
192 const running = run();
193 probes.set(q, running.then(ignore, ignore));
194 try {
195 const out = await running;
196 if (out.ok && q.treeFilter === 'tree:0' && (sends === 'tree:0' || known.tag === 'none')) settled.set(q, sends);
197 return out;
198 } finally {
199 probes.delete(q);
200 }
202// Whether a server takes `combine:blob:none+tree:K` for a commit want (#218, pathtrees.ts): learned from its answer, kept
203// per quirks record like `settled` above, so the public Quirks shape (callers build and persist it as JSON) is unchanged.
204// No entry: not known yet. A record the caller keeps (ply-web: one per origin) keeps it for that record's life; the
205// default memo's records keep it per remote. Never re-learned from 'refused': a host that starts taking it is used only
206// once its record is new, as with treeFilter's blob:none.
207export type PathTrees = 'taken' | 'refused';
208const pathTrees = new WeakMap<Quirks, PathTrees>();
209export const pathTreesOf = (q: Quirks): PathTrees | null => { const known = fromNullable(pathTrees.get(q)); return known.tag === 'some' ? known.value : null; };
210export const learnPathTrees = (q: Quirks, value: PathTrees): void => { pathTrees.set(q, value); };
211// The server has answered a tree:0 request on this record (probing settled it): tree:0 itself is taken.
212export const tree0Taken = (q: Quirks): boolean => q.treeFilter === 'tree:0' && settled.get(q) === 'tree:0';
213// Commits and trees harvested from over-wide packs (fetch.js), keyed by oid; `bytes` is their running total.
214export type HeldObject = { readonly type: number; readonly data: Uint8Array };
215export type Harvest = Map<string, HeldObject>;
216// Bytes held: the store is bounded by limits.maxHarvestBytes, so a sum over it is a bounded scan.
217export const harvestBytes = (store: Harvest): number => { let n = 0; for (const o of store.values()) n += o.data.length; return n; };
218// Span attributes as otel.js records them.
219export type Attrs = Record<string, unknown>;
221// A request body: bytes, or a stream of known length (push's streamed pack, packwrite.ts) the transport sends as it is
222// read. `length` is what the stream will yield (the span's git.request.bytes); a stream errors rather than yield more.
223export type StreamBody = { readonly stream: ReadableStream<Uint8Array>; readonly length: number };
224export type RequestBody = Uint8Array | StreamBody;
226export type Transport = {
227 readonly kind: 'http';
228 readonly url: string;
229 readonly tracer: Tracer;
230 readonly parent: Span | null;
231 // parsed once, where the transport was made (createTransport) or handed in (transportFrom)
232 readonly limits: CheckedLimits;
233 readonly signal: AbortSignal | null;
234 readonly quirks: Quirks;
235 readonly objects: Harvest;
236 readonly scrub: Scrub | null;
237 frames: (service: string, body: RequestBody, span: Span, hints: Hints) => AsyncIterable<Frame>;
238 advertise: (service: string, span: Span) => Promise<Result<Uint8Array, PlyError>>;
239};
241// A transport as a caller may hand one in (operations take `transport`): it may lack the learned-quirks record and the
242// harvest store and the credential scrubber, or pass null for them, and its limits are any subset (a plain record).
243// asTransport fills them once, at the edge: a transport that had none had no memory of either, so a private fresh record
244// behaves the same; its limits are parsed (parseLimits), so a bad one is refused before the operation sends anything.
245export type TransportInput = Omit<Transport, 'quirks' | 'objects' | 'scrub' | 'limits'> & { readonly limits: LimitsInput } & Input<{ readonly quirks: Input<Quirks> | null; readonly objects: Harvest | null; readonly scrub: Scrub | null }>;
246export function asTransport(t: TransportInput, limits: CheckedLimits): Transport {
247 const q = readKey(t, 'quirks');
248 const o = readKey(t, 'objects');
249 const sc = readKey(t, 'scrub');
250 const scrub = sc.tag === 'some' ? sc.value : null;
251 const quirks = fillIn(q.tag === 'some' && q.value !== null ? q.value : {}, freshQuirks());
252 const objects = o.tag === 'some' && o.value !== null ? o.value : new Map<string, HeldObject>();
253 if (q.tag === 'some' && q.value === quirks && o.tag === 'some' && o.value === objects && sc.tag === 'some' && t.limits === limits) {
254 // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- every field was present and the limits are the checked record: the record is a Transport
255 return t as Transport;
256 }
257 // A view, like withParent: the caller's methods and state stay the prototype's.
258 // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- Object.create returns any; the view is `t` with the four fields filled
259 return Object.create(t, { quirks: { value: quirks, enumerable: true }, objects: { value: objects, enumerable: true }, scrub: { value: scrub, enumerable: true }, limits: { value: limits, enumerable: true } }) as Transport;
262// A transport handed in is the caller's code. What its frames() or advertise() raises that is not one of ply's typed
263// errors (a transport that wraps ply's own passes those through) is raised instead as the Err that names the method
264// (`what`) and carries the raised value untouched as `cause`: ply writes nothing on the caller's value. The class
265// follows the request: upload-pack and the advertisement only read, so the failure is definite (bad_request: the
266// caller's code); a request for any other service is a push handed to the transport, which may have sent it: ambiguous.
267const READ_SERVICE = 'git-upload-pack';
268// Reading a raised value can itself throw (a revoked Proxy): that one is not a typed error.
269const isTyped = (e: unknown): boolean => { try { return isPlyThrown(e); } catch { return false; } };
270function framesFailed(service: string, e: unknown): PlyError {
271 // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- it carries one of ply's codes: a PlyError's shape
272 if (isTyped(e)) return e as PlyError;
273 if (service === READ_SERVICE) return callbackFailed('transport.frames', e);
274 return plyError('ambiguous', `caller-supplied transport.frames threw after the request was handed to it, outcome unknown: ${describeThrown(e)}`, { what: 'transport.frames', cause: e });
276// A stream reports a failure by rejecting a read (the stream protocol): the named Err is that rejection.
277async function* guardedFrames(inner: Result<AsyncIterable<Frame>, PlyError>, service: string): AsyncGenerator<Frame, void, unknown> {
278 if (!inner.ok) { await Promise.reject(inner.error); return; }
279 try { yield* inner.value; } catch (e) { await Promise.reject(framesFailed(service, e)); }
281// The frames() and advertise() ply made itself (createTransport's, the guards below, operation()'s hand-over view): none
282// of the caller's code runs unguarded in them. A transport whose two methods are these is kept as it is: one ply made,
283// handed back in, is that transport, and an operation inside an operation does not guard a second time.
284const PLY_MADE = new WeakSet<object>();
285export const plyMade = <T extends Transport>(t: T): T => { PLY_MADE.add(t.frames); PLY_MADE.add(t.advertise); return t; };
286// Reading a handed-in transport's methods can itself throw (a getter): then they are not ply's.
287const isPlyMade = (t: Transport): boolean => { try { return PLY_MADE.has(t.frames) && PLY_MADE.has(t.advertise); } catch { return false; } };
288// A view, like withParent: the caller's methods run on the receiver ply called (a further view: `this.parent`).
289// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- Object.create returns any; the view is `given` with its two methods guarded
290const guarded = (given: Transport): Transport => isPlyMade(given) ? given : plyMade(Object.create(given, {
291 frames: { enumerable: true, value: function frames(this: Transport, service: string, body: RequestBody, span: Span, hints: Hints): AsyncIterable<Frame> {
292 // called now, as the caller's own frames() was (it may start its request when called); what it throws when called
293 // is the stream's first read failing
294 let inner: Result<AsyncIterable<Frame>, PlyError>;
295 try { inner = ok(given.frames.call(this, service, body, span, hints)); } catch (e) { inner = err(framesFailed(service, e)); }
296 return guardedFrames(inner, service);
297 } },
298 advertise: { enumerable: true, value: async function advertise(this: Transport, service: string, span: Span): Promise<Result<Uint8Array, PlyError>> {
299 // advertise answers with a Result: what the caller's raises is its Err (a typed error as it is)
300 // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- it carries one of ply's codes: a PlyError's shape
301 try { return await given.advertise.call(this, service, span); } catch (e) { return err(isTyped(e) ? (e as PlyError) : callbackFailed('transport.advertise', e)); }
302 } },
303}) as Transport);
304export function transportFrom(t: TransportInput): Result<Transport, ErrorOf<'bad_request'>> {
305 const limits = parseLimits(t.limits);
306 return limits.ok ? ok(guarded(asTransport(t, limits.value))) : limits;
309// We are not git and do not claim to be: servers that branch on the agent string get the truth.
310export const UA = 'ply/0.2.0';
311export const proto = (msg: string): Err<ErrorOf<'protocol'>> => fail('protocol', msg);
313export const frames = (t: Transport, service: string, body: RequestBody, span: Span, hints: Hints = NO_HINTS): AsyncIterable<Frame> => t.frames(service, body, span, hints);
314// oxlint-disable-next-line typescript/promise-function-async -- a pass-through: the transport's own promise, unwrapped (async adds a wrapper and bytes)
315export const advertise = (t: Transport, service: string, span: Span): Promise<Result<Uint8Array, PlyError>> => t.advertise(service, span);
317// The same transport, with wire spans parented under `parent` (an operation's root). State is shared with the original:
318// the view only shadows `parent`. (A transport's methods must therefore read `parent` from the record they are called on.)
319// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- Object.create returns any; the view is `t` with one field shadowed
320export const withParent = <T extends Transport>(t: T, parent: Span): T => Object.create(t, { parent: { value: parent, enumerable: true } }) as T;
322export type SpanOpts = { readonly parent: Span | null; readonly kind: number; readonly attrs: Attrs; readonly scrub: Scrub | null };
323// Span options for a wire round trip under this transport's parent.
324// It carries the transport's `scrub` (credential redaction, http.js), so even an unparented wire span exports none.
325export const clientSpan = (t: Transport, attrs: Attrs = {}): SpanOpts => ({ parent: t.parent, kind: KIND.CLIENT, attrs, scrub: t.scrub });
327// Set `code` on a raised value. False for a primitive, null or a frozen value (Reflect.set answers false, or a setter
328// throws): that one is wrapped instead.
329const setCode = (e: unknown, code: Code): boolean => {
330 try { return (typeof e === 'object' || typeof e === 'function') && e !== null && Reflect.set(e, 'code', code); } catch { return false; }
331};
332// A raised value as the PlyError it is: a typed error keeps its code; any other value is given `code` (on the value
333// itself when it takes one, else on a wrapper that has it as the cause).
334export function raised(code: Code, e: unknown): PlyError {
335 // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- it carries one of ply's codes (already, or just set): a PlyError's shape
336 if (isPlyThrown(e) || setCode(e, code)) return e as PlyError;
337 return plyError(code, thrownText(e), { cause: e });
339// The stream edge: a transport's frames signal failure through the stream protocol (the iterator rejects), and a
340// transport the caller hands in may raise anything. Caught here, once per exchange, and returned as the Err it is.
341export async function coded<T>(code: Code, fn: () => Promise<Result<T, PlyError>>): Promise<Result<T, PlyError>> {
342 try { return await fn(); } catch (e) { return err(raised(code, e)); }
344// fn(span) under a wire span. An Err is recorded on the span (error status, error.type, the exception event) as the
345// tracer records a raised error; a raised one still is, by the tracer, before coded() catches it.
346// oxlint-disable-next-line typescript/promise-function-async -- the span's promise, passed through (an async wrapper adds bytes, not behaviour)
347export const spanned = <T>(t: Transport, name: string, opts: SpanOpts, fn: (span: Span) => Promise<Result<T, PlyError>>): Promise<Result<T, PlyError>> =>
348 spanOn(t.tracer, name, opts, async (span: Span): Promise<Result<T, PlyError>> => {
349 const r = await fn(span);
350 if (!r.ok) span.error(r.error);
351 return r;
352 });
354// A thrown value's `name` is `want` (an AbortError, a TimeoutError). Any value may be thrown: a primitive has no name.
355const nameIs = (e: unknown, want: string): boolean => { const n = field(e, 'name'); return n.tag === 'some' && n.value === want; };
356// A platform fetch failure → the PlyError it is: aborted or timeout when the signal fired or the error says so, else
357// network. A typed error passes through. `what` names the caller's function that raised it (a supplied fetchImpl), on
358// the network error only. Never throws: a value that cannot be read or described (a revoked Proxy, a null-prototype
359// object) is the network error it would be, carried as the cause.
360export function wrapNet(e: unknown, signal: AbortSignal | null = null, what: string | null = null): PlyError {
361 // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- it carries one of ply's codes: a PlyError's shape
362 if (isTyped(e)) return e as PlyError;
363 const aborted = signal !== null && signal.aborted;
364 try {
365 if (aborted || nameIs(e, 'AbortError') || nameIs(e, 'TimeoutError')) {
366 const timedOut = nameIs(e, 'TimeoutError') || (signal !== null && nameIs(signal.reason, 'TimeoutError'));
367 // the limit that fired (src/deadline.ts), on the thrown value or on the signal's reason
368 const thrown = timeoutLimit(e);
369 const limit = thrown !== null || signal === null ? thrown : timeoutLimit(signal.reason);
370 return plyError(timedOut ? 'timeout' : 'aborted', `request aborted: ${describeThrown(e)}`, { cause: e, ...(timedOut && limit !== null ? { what: limit } : {}) });
371 }
372 } catch { /* the value cannot be read: not an abort */ }
373 return plyError('network', `network: ${describeThrown(e)}`, { cause: e, ...(what === null ? {} : { what }) });
Diagnostics4 git calls · 440 ms
CallStatusSizeTime0440 ms
discover200152 B4 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
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 1020038 KiB · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=433
git.response.bytes=38434
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=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=6
git.pkt.data=4
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=38434
git.pkt.payload.max=38339
git.sideband.band1.bytes=38338
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=63
git.pack.bytes=38338
git.pack.ofs_delta=0
git.pack.ref_delta=8
git.pack.chain.max=8
git.pack.trailer=0bc36ab7adf82d3109177f11f1ea93f1ce071f77
git.pack.full=55
Open pack map
fetch2009.3 KiB433 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=9555
git.response.cache=MISS
git.response.duration_ms=433
git.fetch.wants=bef60ead756334ef203f6feeeae69c4e6a266e81
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=9555
git.pkt.payload.max=9534
git.sideband.band1.bytes=9533
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.git
Ref
refs/heads/main
Commit
19912563f540228593df0c489082e5e2508e21e4
cf-ray
a5e30929bcc015db
Request
ea3df185…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format