GitHubivarvong
ply
main
1// The error taxonomy: a closed set of codes, each with the caller's retry policy. `satisfies` makes the table
2// exhaustive both ways: a code without a policy, or a policy for an unknown code, does not compile.
3// Descriptions live in errors-doc.ts (documentation, kept out of the runtime bundle).
4//
5// retry: 'yes' — safe to retry as-is (nothing was changed on the server, or the change is idempotent)
6// 'fresh' — retry from a fresh read (a compare-and-swap lost; the parent must be re-resolved)
7// 'no' — retrying the same request cannot succeed
8// 'read' — do not retry blindly: the server MAY have applied the change; read the ref back first
9import type { ObjectTypeName } from './format.js';
10import type { Err } from './result.js';
11import { err, getOrElse } from './result.js';
12import type { Input } from './absent.js';
13import { field } from './absent.js';
15export type Retry = 'yes' | 'fresh' | 'no' | 'read';
17// The closed set of codes. A type costs nothing at run time; the names ship once, as RETRY's keys. The annotation
18// makes the table exhaustive both ways: a code without a policy, or a policy for an unknown code, does not compile.
19export type Code =
20 | 'bad_request' | 'unsupported' | 'network' | 'timeout' | 'aborted' | 'http' | 'auth' | 'not_found' | 'rate_limited'
21 | 'upstream_5xx' | 'not_git' | 'protocol' | 'pack_corrupt' | 'remote_error'
22 | 'limit_exceeded' | 'match_count' | 'lfs_pointer' | 'cas_conflict' | 'push_rejected' | 'push_partial'
23 | 'merge_conflict' | 'not_fast_forward' | 'not_linear' | 'unrelated_histories' | 'ambiguous' | 'internal';
25export const RETRY: Readonly<Record<Code, Retry>> = Object.freeze({
26 bad_request: 'no', unsupported: 'no', network: 'yes', timeout: 'yes', aborted: 'no', http: 'no', auth: 'no',
27 not_found: 'no', rate_limited: 'yes', upstream_5xx: 'yes', not_git: 'no', protocol: 'yes',
28 pack_corrupt: 'yes', remote_error: 'no', limit_exceeded: 'no', match_count: 'no',
29 lfs_pointer: 'no', cas_conflict: 'fresh', push_rejected: 'no', push_partial: 'no', merge_conflict: 'no',
30 not_fast_forward: 'no', not_linear: 'no', unrelated_histories: 'no', ambiguous: 'read', internal: 'no',
31});
32// Object.keys widens to string[]; the keys of RETRY are exactly Code (its annotation says so).
33// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- see above
34export const CODES: readonly Code[] = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.keys(RETRY) as Code[]);
36// Per-code payload: the fields a code always carries. A code not listed carries only code + message (+ Extra).
37// Adding detail to a code is one line here, and every constructor and match site is re-checked. These are the
38// fields today's call sites attach unconditionally (grep `fail('<code>'`); a converting module tightens its codes.
39// Why a commit id is not a commit the remote will serve (#112, nested under Miss). `absent`: upload-pack said the oid
40// is not its ref. `not_commit`: the object arrived and it is a tree, blob, or tag.
41export type CommitMiss =
42 | { readonly kind: 'absent'; readonly oid: string }
43 | { readonly kind: 'not_commit'; readonly oid: string; readonly type: Exclude<ObjectTypeName, 'commit'> };
45// Why a not_found missed (#115). Callers switch on `kind`. A corrupt pack stays pack_corrupt and carries none of these.
46export type Miss =
47 | { readonly kind: 'ref'; readonly ref: string; readonly candidates: readonly string[] }
48 | { readonly kind: 'head_unborn'; readonly target: string }
49 | { readonly kind: 'head_absent' }
50 | { readonly kind: 'path'; readonly missing: string; readonly existingPath: string }
51 | { readonly kind: 'not_directory'; readonly path: string; readonly mode: string }
52 | { readonly kind: 'is_directory'; readonly path: string; readonly tree: string }
53 | { readonly kind: 'submodule'; readonly path: string; readonly commit: string }
54 | { readonly kind: 'commit'; readonly miss: CommitMiss }
55 | { readonly kind: 'repository' };
57export type Detail = {
58 readonly http: { readonly status: number };
59 // read/resolve, and a 404: which thing was absent. Required, so a not_found cannot be told apart by its message.
60 readonly not_found: { readonly miss: Miss };
61 readonly limit_exceeded: { readonly what: string; readonly got: number; readonly max: number };
62 readonly cas_conflict: { readonly expected: string | null; readonly actual: string | null };
63 readonly match_count: { readonly matches: number };
64 readonly merge_conflict: { readonly conflicts: readonly string[] };
65 // push.ts: the refs that moved, and the refused ones with git's reason
66 readonly push_partial: { readonly landed: readonly string[]; readonly rejected: ReadonlyArray<{ readonly ref: string; readonly reason: string }> };
67};
68// `unknown` is the identity of `&`: a code without a payload adds nothing to its member.
69type DetailOf<C extends Code> = C extends keyof Detail ? Detail[C] : unknown;
71// Context any error may carry: what was checked, the offending path, the underlying cause (a platform error, or
72// another PlyError for `ambiguous`), and the code an `ambiguous` replaced. The fields are total here; Extra, the bag a
73// constructor takes, is Input<ExtraFields> (a caller attaches the ones it has). Unconverted modules attach more ad-hoc
74// fields to thrown errors; they are not part of the typed surface until their module converts.
75export type ExtraFields = {
76 readonly what: string;
77 readonly path: string;
78 readonly got: unknown;
79 readonly max: number;
80 readonly cause: unknown;
81 readonly original: unknown;
82 // objects.ts: git fsck's message id on a refused commit, tag or duplicate header; the name a tree carries twice
83 readonly msgId: string;
84 readonly entry: string;
85 // edit.ts: the span attributes of a failed tree lookup (lookupEntry)
86 readonly attrs: Readonly<Record<string, unknown>>;
87 // push.ts: the receive-pack report as classified (null when it was not git's) and band 2 (hook stderr) as received
88 readonly report: { readonly tag: string; readonly refs: ReadonlyArray<{ readonly ref: string; readonly ok: boolean; readonly reason: string }> } | null;
89 readonly hookOutput: string;
90 // receivecaps.ts: the capabilities the server advertised, beside an `unsupported` push
91 readonly caps: readonly string[];
92 // A machine-readable sub-reason a caller switches on instead of matching the message (#76). Closed: a new reason is
93 // a member here. 'short_read': a bounded read ran past the buffer (bytes.ts take), so more bytes may complete it.
94 // 'not_our_ref': upload-pack's ERR or band 3 said the wanted oid is not its ref (v2Step). Any other remote_error has none.
95 // 'empty_response': a fetch response with no section in it, not even its flush (v2End): what git's upload-pack sends
96 // when it dies on an argument it did not advertise (fetch.ts filterAdvertised).
97 readonly reason: Reason;
98};
99// The error context bag: one of the two places Input is allowed (docs/STACK.md, Absence). Any subset of the fields.
100export type Extra = Input<ExtraFields>;
101export type Reason = 'short_read' | 'not_our_ref' | 'empty_response';
103// A PlyError is a value: returned in an Err, matched on `code`, never thrown by converted code. At run time it is an
104// Error instance carrying its fields (a stack for whoever logs it, and the exact shape today's thrown errors have, so
105// the migration boundary below is the identity). Its type is the discriminated union; nothing reads it as a class.
106export type PlyError = {
107 readonly [C in Code]: Error & { readonly code: C; readonly message: string } & Extra & DetailOf<C>;
108}[Code];
109export type ErrorOf<C extends Code> = Extract<PlyError, { readonly code: C }>;
111// Payload fields required by the code are required here; a code without a payload takes Extra or nothing.
112type Payload<C extends Code> = unknown extends DetailOf<C> ? [] | [extra: Extra] : [detail: DetailOf<C> & Extra];
114// `in`, as before: RETRY's keys are the codes (inherited names such as 'toString' also pass, as they always have).
115export const isPlyCode = (code: unknown): code is Code => typeof code === 'string' && code in RETRY;
116// A PlyError is the Error plyError builds. A thrown number, a string, or an Error with no code is not one.
117export const isPlyError = (e: unknown): e is PlyError => e instanceof Error && 'code' in e && isPlyCode(e.code);
118// Accepts a thrown value too (the public API throws until the Result cut-over; see docs/STACK.md). Any value is read
119// loosely, through absent.ts `field`: a primitive, null, or an object without a code has none, and that is 'no'.
120export const retryPolicy = (e: unknown): Retry => {
121 const code = field(e, 'code');
122 return code.tag === 'some' && isPlyCode(code.value) ? RETRY[code.value] : 'no';
123};
124export const isRetryable = (e: unknown): boolean => retryPolicy(e) === 'yes';
126// The one constructor. The typed signature is the error value for `code` with exactly its payload; `fail` wraps it in
127// an Err. A JS caller reaches the untyped signature; the code check is for that caller (an unknown code is a bug).
128// An overload, not a cast: the implementation returns Error & { code }, which each member of the union refines.
129export function plyError<C extends Code>(code: C, message: string, ...detail: Payload<C>): ErrorOf<C>;
130export function plyError(code: string, message: string, ...extra: [] | [object]): Thrown {
131 if (!isPlyCode(code)) throw new Error(`internal: unknown error code ${code}`);
132 // No bag spreads nothing; a JS caller's missing bag spreads nothing too, as it did.
133 return Object.assign(new Error(message), { code, ...extra[0] });
134}
135export const fail = <C extends Code>(code: C, message: string, ...detail: Payload<C>): Err<ErrorOf<C>> =>
136 err(plyError(code, message, ...detail));
138// plyError's untyped signature: an Error carrying one of ply's codes.
139export type Thrown = Error & { readonly code: Code };
141// After a push body is on the wire, any failure to obtain a trustworthy report means the ref MAY have moved.
142// That includes our own limits: a report too large to read says nothing about whether the ref moved.
143export const ambiguousAfterPush = (e: unknown, message = 'push outcome unknown'): unknown => {
144 const code = field(e, 'code');
145 if (code.tag === 'some' && code.value === 'ambiguous') return e;
146 // A thrown value of any type renders as String() renders it. `original` is the code it replaced; none, no key.
147 return plyError('ambiguous', `${message}: ${String(getOrElse(field(e, 'message'), e))}`, { cause: e, ...(code.tag === 'some' ? { original: code.value } : {}) });
148};
150// What a thrown value says, for a message: its `message` when it has one, else the value as String() renders it.
151// Never throws. Reading a caller's value can itself throw (a `message` getter that throws, a revoked Proxy, an object
152// with no string form such as a null-prototype one): the description then says only that; the value is the `cause`.
153export function describeThrown(e: unknown): string {
154 try { return String(getOrElse(field(e, 'message'), e)); } catch { return 'a value with no string form'; }
155}
157// A caller-supplied callback that is part of an operation (a signer, a pushDir filter, a transport) threw or rejected
158// before any push request was handed to a transport: a definite failure. The Err names the callback (`what`) and
159// carries what it threw (`cause`). bad_request (retry 'no'): the failure is in the caller's code; the caller reads `cause`.
160export const callbackFailed = (what: string, e: unknown): ErrorOf<'bad_request'> =>
161 plyError('bad_request', `caller-supplied ${what} threw: ${describeThrown(e)}`, { what, cause: e });
163// Rewrite every string an error carries through `scrub`, in place: message, stack, own fields, nested plain objects,
164// prototype-less maps (merge reasons, report options) and arrays (a push report, hook output) and the cause chain.
165// Anything else (a Span on `e.span`, bytes) is left alone. A prototype of null marks a map keyed by names the server
166// or repo chose. Mutation is the contract: the caller rethrows what this returns (`e` itself unless e is a string).
167// No scrubber (null, the default) leaves `e` as it is.
168export function scrubError(e: unknown, scrub: ((s: string) => string) | null = null): unknown {
169 if (!scrub) return e;
170 const seen = new Set<object>();
171 const walk = (v: unknown): unknown => {
172 if (typeof v === 'string') return scrub(v);
173 if (v === null || typeof v !== 'object' || seen.has(v)) return v;
174 const isErr = v instanceof Error;
175 const proto: unknown = Object.getPrototypeOf(v);
176 if (!isErr && !Array.isArray(v) && proto !== Object.prototype && proto !== null) return v;
177 seen.add(v);
178 const keys = new Set(Object.keys(v));
179 if (isErr) for (const k of ['message', 'stack', 'cause']) if (k in v) keys.add(k);
180 // A plain object or an Error, so its fields are a record. A read-only field stays as it is.
181 // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- see above
182 const rec = v as Record<string, unknown>;
183 for (const k of keys) {
184 try { rec[k] = walk(rec[k]); } catch { /* read-only */ }
185 }
186 return v;
187 };
188 return walk(e);
189}
191// Remote-written text on its way into an error message or a span attribute. The sites that pass it through one of
192// these two are listed in SAFETY.md I43 and counted by test/remote-text.test.js: ERR lines, band 3, the HTTP error body
193// and content-type, refused protocol lines, v2End's section names, the too-large push reason and the
194// git.push.band2.tail attribute. Not every field does: I43 also lists the ones that still carry remote text as received
195// (hookOutput, git.push.remote.messages, git.push.ng.reason, fetch progress, the lines / rejected detail fields, an ng
196// reason quoted in a push message). A server chooses these bytes, and whoever prints the error to a terminal or a log
197// must not be driven by them. The text is cut to `max` UTF-16 units (after the scrub, where a site passes one), so the
198// result is bounded whatever the line's size; then every control (Cc: C0, DEL, C1), format
199// character (Cf: bidi overrides, zero-width and tag characters), line or paragraph separator and lone surrogate (a cut
200// pair, or ill-formed input) is written as \uXXXX (\u{XXXXX} above the BMP). Invalid UTF-8 has already decoded to U+FFFD, which
201// is printable and kept.
202// remoteText — running text (an ERR message, hook output, an error page): tab and newline stay, as in git's own
203// reports (usage.c vreportf masks every other control).
204// remoteQuoted — one line shown in quotes: JSON's quoting (so `"`, `\`, tab and newline are escaped too), then the
205// characters JSON leaves raw (DEL, C1, format characters, U+2028/9).
206export const REMOTE_TEXT_MAX = 1024;
207const HEX = 16;
208const UNIT_DIGITS = 4;
209const UNPRINTABLE = /[\p{Cc}\p{Cf}\p{Cs}\p{Zl}\p{Zp}]/gu;
210// one match is one code point: a BMP character is \uXXXX (as JSON writes it), an astral one \u{XXXXX}
211const escaped = (c: string): string => { const hex = Number(c.codePointAt(0)).toString(HEX); return c.length === 1 ? `\\u${hex.padStart(UNIT_DIGITS, '0')}` : `\\u{${hex}}`; };
212// `scrub` (a transport's credential scrubber, or null) runs BEFORE the cut, on the whole text: a cut that falls inside
213// an echoed credential would leave a remainder too short for the scrubber to recognise afterwards. Where it is passed
214// the text is one pkt-line payload (at most 65516 bytes), so the scrub is bounded too.
215export const remoteText = (text: string, max: number = REMOTE_TEXT_MAX, scrub: ((s: string) => string) | null = null): string =>
216 (typeof scrub === 'function' ? scrub(text) : text).slice(0, max).replaceAll(UNPRINTABLE, c => (c === '\n' || c === '\t' ? c : escaped(c)));
217export const remoteQuoted = (text: string, max: number = REMOTE_TEXT_MAX): string => JSON.stringify(text.slice(0, max)).replaceAll(UNPRINTABLE, escaped);
219// The shape check of a public entry point's arguments (#296): a caller passing null, a number or an array where an
220// object is documented gets bad_request naming the argument, never a TypeError from the first property read.
221// An optional options argument is defaulted (`= {}`) in the signature, so undefined never reaches the check; 'bytes'
222// is a Uint8Array.
223export type ArgKind = 'object' | 'array' | 'bytes';
224const ARG_NOUN: Readonly<Record<ArgKind, string>> = { object: 'an object', array: 'an array', bytes: 'a Uint8Array' };
225const argFits = (value: unknown, kind: ArgKind): boolean => {
226 if (kind === 'array') return Array.isArray(value);
227 if (kind === 'bytes') return value instanceof Uint8Array;
228 return typeof value === 'object' && value !== null && !Array.isArray(value);
229};
230export function argsError(entry: string, args: ReadonlyArray<readonly [string, unknown, ArgKind]>): Err<ErrorOf<'bad_request'>> | null {
231 for (const [what, value, kind] of args) if (!argFits(value, kind)) return fail('bad_request', `${entry}: ${what} must be ${ARG_NOUN[kind]}`, { what });
232 return null;
233}
Diagnostics6 git calls · 93 ms
CallStatusSizeTime093 ms
discover200191 B3 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=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 KiB3 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=UPDATING 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=3 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 · 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=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=5323b9266eea5ded637285d1c5320699f12be76eOpen pack map
fetchtree:02002.4 KiB · hit2 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=83 git.response.bytes=2507 git.response.cache=HIT git.response.duration_ms=2 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
fetch2006.5 KiB83 ms
git.upload-pack fetch http.response.status_code=200 git.response.bytes=6650 git.response.cache=MISS git.response.duration_ms=83 git.fetch.wants=d2fa2a98c1eb9cf23d3e3044ea10613b0052f664 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=6650 git.pkt.payload.max=6623 git.sideband.band1.bytes=6623 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
- a5e19e46bee73cd0
- Request
- d1fc62da…
- 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