GitHubivarvong

ply

main
ply6 git calls104 ms43 KiB4 cachedprotocol v2
1131 lines77 KiBRaw
1// v2 fetch: request body (pure), response state machine (pure step), the streamed band-1 pack, and fetchObject — one
2// object by oid through the single-object pack parser, hash-verified. The multi-object fetch (the pack read through
3// the scan as it arrives, then delta-resolved) lives in fetchpack.js.
4// The step functions, the checks and fetchObject return Result. packStream is a stream: it fails through the stream
5// protocol (its iterator rejects with the PlyError), and the exchanges that drain it catch that once (coded).
6/* oxlint-disable require-unicode-regexp -- ASCII wire text; `u` costs a byte per literal and changes what /i matches (U+017F, U+212A) */
7import type { ErrorOf, Extra, PlyError } from './errors.js';
8import type { CheckedLimits } from './limits.js';
9import type { Span } from './otel.js';
10import type { Input } from './absent.js';
11import type { Option, Result } from './result.js';
12import type { Attrs, Frame, Scrub, Transport } from './transport.js';
13import { fail, scrubError, remoteQuoted, remoteText, REMOTE_TEXT_MAX } from './errors.js';
14import { pkts, pktInit, pktStep, pktFinish, pktAttrs } from './pktline.js';
15import { td, concat, take, decodeChunk } from './bytes.js';
16import { Sha1, toHex } from './sha1.js';
17import { TYPE, TYPE_NAME, hashObject, assertFetched, nonCommitType, parseTree } from './objects.js';
18import type { ObjType, ObjectError, TreeEntry } from './objects.js';
19// oxlint-disable-next-line import/max-dependencies -- the fetch path's parsers each live in their own module (pack, inflate, objects, sha1, cache)
20import { corruptCacheHit } from './cachestatus.js';
21import { assertNever, err, getOrElse, mapOption, none, ok } from './result.js';
22import type { InflateError, InflateStats, InflateStream } from './inflatestream.js';
23import { inflateInit, inflateFeed, inflatePull, inflateEnd, inflateUnread, declaredBound, zlibWrap } from './inflatestream.js';
24import { resolvePack, resolvePackCollect, packCaps, packCollectOpen, packCollectFeed, packCollectEnd, readObjHeader, readUint32BE } from './packresolve.js';
25import type { PackCollector, ParsedPack, ScannedHeader } from './packresolve.js';
26import type { HeaderError, ObjSize } from './packstream.js';
27import { NO_SIZE_CAP } from './packstream.js';
28import { atOr, fromNullish, mapGet, withDefaults } from './absent.js';
29import { PACK_SIGNATURE, PACK_VERSION, PACK_HEADER_BYTES, PACK_TRAILER_BYTES, UINT32_BYTES, SIDEBAND_PACK, SIDEBAND_PROGRESS, SIDEBAND_ERROR, SIDEBAND_CHANNEL_BYTES, OID_HEX_CHARS, PROTOCOL_V2, zlibBound } from './format.js';
30import { DEFAULT_LIMITS, limitExceeded } from './limits.js';
31import { validateWire } from './validate.js';
32import type { WireField } from './validate.js';
33import { parseOid, type Oid } from './oid.js';
34import { frames, advertise, coded, clientSpan, proto, harvestBytes, learnFilter, learnShallow, takesShallow, shallowLearned, probing, spanned } from './transport.js';
35import { capLookup, parseCapabilitiesV2 } from './caps.js';
36import { thrownCodeIs, thrownReasonIs, thrownCode, thrownMessage } from './boundary.js';
38/* oxlint-disable no-magic-numbers -- span tails are diagnostics, not wire-format facts */
39const PROGRESS_KEEP = 512;
40const PROGRESS_ATTR = 200;
41const OID_PREVIEW = 48;
42/* oxlint-enable no-magic-numbers */
44// TYPE_NAME read by a type id that is a number on the wire, as String() renders the lookup (objects.js keys it by the
45// ids it knows; an id it does not know renders as the platform's missing value did).
46const typeText = (type: number): string => String(Reflect.get(TYPE_NAME, type));
47// A git object as the pack parser and resolver hand it over (and as the harvest holds it).
48export type PackObject = { readonly type: number; readonly data: Uint8Array };
50// ---- request body (pure) ----
51type BadRequest = ErrorOf<'bad_request'>;
52const UNIT: Result<null, never> = ok(null);
53// A count on the wire: a non-negative safe integer (a NaN or a fraction is refused, never written).
54const countField = (value: number, what: string): Result<number, BadRequest> => {
55 if (!Number.isSafeInteger(value) || value < 0) return fail('bad_request', `invalid ${what}: must be a non-negative safe integer`, { what });
56 return ok(value);
57};
58// done is true, false or left out (the default, true). Anything else is refused: a null, 0 or '' from a JavaScript
59// caller used to leave `done` off the request while the answer was judged as the answer to a done request.
60const doneField = (value: unknown): Result<boolean, BadRequest> =>
61 typeof value === 'boolean' ? ok(value) : fail('bad_request', 'invalid done: must be true, false or left out', { what: 'done' });
62// deepen-since is a unix timestamp on the wire (a number from callers, or a digit string). Either way it is one token.
63const sinceField = (value: number | string, what: string): Result<number | WireField, BadRequest> =>
64 typeof value === 'number' ? countField(value, what) : validateWire(value, what);
65// Every value of a list argument as one wire field, or the first that is not.
66function wireList(values: readonly string[], what: string): Result<WireField[], BadRequest> {
67 const out: WireField[] = [];
68 for (const v of values) {
69 const valid = validateWire(v, what);
70 if (!valid.ok) return valid;
71 out.push(valid.value);
72 }
73 return ok(out);
76// A want, a have and a shallow are object ids. upload-pack.c reads each with get_oid_hex and dies otherwise: parse_want
77// "expected to get oid, not 'want …'" (a ref name, an abbreviation, an empty want: ref-in-want is its own `want-ref`
78// line, which ply does not send), process_haves "expected SHA1 object, got '…'", process_shallow "invalid shallow line".
79// get_oid_hex reads either case (hexval), so an upper-case id is the same object to git: it is lowercased, as ls-refs
80// lowercases a listed oid, and parsed once. git reads only the first OID_HEX_CHARS characters and ignores the rest of the
81// line; ply refuses text after the id instead of sending it (test/want-oracle.test.js). A NUL, CR or LF is the wire
82// refusal it always was.
83type OidArg = 'want' | 'have' | 'shallow';
84function oidList(values: readonly string[], what: OidArg): Result<Oid[], BadRequest> {
85 const out: Oid[] = [];
86 for (const v of values) {
87 const field = validateWire(v, what);
88 if (!field.ok) return field;
89 const id = parseOid(field.value.toLowerCase());
90 if (!id.ok) return fail('bad_request', `invalid ${what}: must be an object id (${OID_HEX_CHARS} hex digits)`, { what });
91 out.push(id.value);
92 }
93 return ok(out);
96// The arguments of one v2 fetch command. An empty filter, a zero deepen and a zero deepen-since are absent.
97export type FetchConfig = {
98 readonly haves: readonly string[];
99 readonly filter: string;
100 readonly deepen: number;
101 readonly deepenSince: number | string;
102 readonly deepenNot: readonly string[];
103 readonly deepenRelative: boolean;
104 readonly thinPack: boolean;
105 readonly ofsDelta: boolean;
106 readonly includeTag: boolean;
107 readonly noProgress: boolean;
108 readonly done: boolean;
109 readonly shallows: readonly string[];
110 readonly bypassCache: boolean;
111};
112export type FetchOpts = { readonly wants: readonly string[] } & Input<FetchConfig>;
113const fetchDefaults = (): FetchConfig => ({
114 haves: [], filter: '', deepen: 0, deepenSince: 0, deepenNot: [], deepenRelative: false, thinPack: false, ofsDelta: true,
115 includeTag: false, noProgress: true, done: true, shallows: [], bypassCache: false,
116});
118// A fetch command parsed once (fetchRequest): every want, have and shallow an object id, every other token one wire field
119// and every count a checked integer, so encoding it (fetchRequestBody) checks nothing. No filter is null, and no deepen or
120// deepen-since is 0.
121export type FetchRequest = {
122 readonly wants: readonly Oid[];
123 readonly haves: readonly Oid[];
124 readonly shallows: readonly Oid[];
125 readonly deepenNot: readonly WireField[];
126 readonly filter: WireField | null;
127 readonly deepen: number;
128 readonly deepenSince: number | WireField;
129 readonly deepenRelative: boolean;
130 readonly thinPack: boolean;
131 readonly ofsDelta: boolean;
132 readonly includeTag: boolean;
133 readonly noProgress: boolean;
134 readonly done: boolean;
135};
137// The caller's options, checked in this order: wants, haves, shallows, deepen-nots, the filter, deepen, deepen-since,
138// done. The parsed `done` is the only one read afterwards: it decides the request's `done` line (fetchRequestBody) and
139// how the answer is judged (packStream, v2End).
140// An empty filter, a zero (or NaN) deepen and a falsy deepen-since are left out, as they always have been.
141// oxlint-disable-next-line complexity -- one check per fetch argument
142export function fetchRequest(opts: FetchOpts): Result<FetchRequest, BadRequest> {
143 const { haves, filter, deepen, deepenSince, deepenNot, deepenRelative, thinPack, ofsDelta, includeTag, noProgress, done, shallows } = withDefaults(opts, fetchDefaults());
144 const w = oidList(opts.wants, 'want');
145 if (!w.ok) return w;
146 const h = oidList(haves, 'have');
147 if (!h.ok) return h;
148 const sh = oidList(shallows, 'shallow');
149 if (!sh.ok) return sh;
150 const dn = wireList(deepenNot, 'deepen-not');
151 if (!dn.ok) return dn;
152 let f: WireField | null = null;
153 if (filter) { const c = validateWire(filter, 'filter'); if (!c.ok) return c; f = c.value; }
154 let d = 0;
155 if (deepen) { const c = countField(deepen, 'deepen'); if (!c.ok) return c; d = c.value; }
156 let since: number | WireField = 0;
157 // oxlint-disable-next-line typescript/strict-boolean-expressions -- 0, '' and NaN mean no deepen-since, as they always have
158 if (deepenSince) { const c = sinceField(deepenSince, 'deepen-since'); if (!c.ok) return c; since = c.value; }
159 const sentDone = doneField(done);
160 if (!sentDone.ok) return sentDone;
161 return ok({ wants: w.value, haves: h.value, shallows: sh.value, deepenNot: dn.value, filter: f, deepen: d, deepenSince: since, deepenRelative, thinPack, ofsDelta, includeTag, noProgress, done: sentDone.value });
164// The command=fetch body of a parsed request.
165// oxlint-disable-next-line complexity -- one optional line per fetch argument
166export function fetchRequestBody(req: FetchRequest): Result<Uint8Array<ArrayBuffer>, BadRequest> {
167 const args = [
168 ...req.wants.map(w => `want ${w}\n`),
169 ...req.haves.map(h => `have ${h}\n`),
170 ...req.shallows.map(s => `shallow ${s}\n`),
171 ...(req.filter === null ? [] : [`filter ${req.filter}\n`]),
172 ...(req.deepen ? [`deepen ${req.deepen}\n`] : []),
173 // oxlint-disable-next-line typescript/strict-boolean-expressions -- 0 is no deepen-since; a parsed string is never empty
174 ...(req.deepenSince ? [`deepen-since ${req.deepenSince}\n`] : []),
175 ...req.deepenNot.map(r => `deepen-not ${r}\n`),
176 ...(req.deepenRelative ? ['deepen-relative\n'] : []),
177 ...(req.thinPack ? ['thin-pack\n'] : []),
178 ...(req.ofsDelta ? ['ofs-delta\n'] : []),
179 ...(req.includeTag ? ['include-tag\n'] : []),
180 ...(req.noProgress ? ['no-progress\n'] : []),
181 ...(req.done ? ['done\n'] : []),
182 ];
183 return pkts(['command=fetch\n', ...args], { delimAfter: 0 });
186// The caller's options as a command=fetch body: parsed once, then encoded.
187export function fetchBody(opts: FetchOpts): Result<Uint8Array<ArrayBuffer>, BadRequest> {
188 const req = fetchRequest(opts);
189 return req.ok ? fetchRequestBody(req.value) : req;
192// ---- v2 fetch response state machine (pure step over frames) ----
193// One sideband frame: the band byte and its payload.
194export type Sideband = { readonly band: number; readonly body: Uint8Array };
195// @decoder parseSideband prefix=sideband
196export function parseSideband(payload: Uint8Array): Result<Sideband, ErrorOf<'protocol'>> {
197 // an empty payload (0004) has no band byte: git's demultiplex_sideband "missing sideband designator"
198 // take returns exactly SIDEBAND_CHANNEL_BYTES bytes or the short read, so the fallback never applies
199 const head = take(payload, 0, SIDEBAND_CHANNEL_BYTES, 'protocol');
200 if (!head.ok) return head;
201 const band: number = atOr(head.value, 0, 0);
202 const body = payload.subarray(SIDEBAND_CHANNEL_BYTES);
203 return ok({ band, body });
206// The response's two phases: section lines up to `packfile`, then sideband frames. `section` is the open section
207// (null between a delim and the next header); its line count is `sectionLines` (shallow-info) or `otherLines` (a
208// section ply does not read). `done` is the flush that ends the response, in either phase.
209export type V2Phase = 'sections' | 'pack';
210export type V2State = {
211 readonly limits: CheckedLimits;
212 readonly phase: V2Phase;
213 readonly section: string | null;
214 readonly sections: readonly string[];
215 readonly shallow: readonly string[];
216 readonly unshallow: readonly string[];
217 readonly acks: readonly string[];
218 readonly ready: boolean;
219 readonly band1: number;
220 readonly band2: number;
221 readonly band3: number;
222 readonly band2Frames: number;
223 readonly progress: string;
224 readonly progressCarry: Uint8Array;
225 readonly error: null;
226 readonly done: boolean;
227 readonly packFrames: number;
228 readonly sectionLines: number;
229 readonly otherLines: number;
230};
231export type V2Step = { readonly state: V2State; readonly pack: Uint8Array | null };
233// upload-pack's own words for an oid it will not send. v2 prefixes `upload-pack: `; v0 and v1 do not. A trailing oid
234// is separated by a space, so `not our refresh` is a different error. Recognised once, here (#112): callers switch
235// on `reason` instead of the message (#76). Any other text carries no reason (an empty extra adds no field).
236const NOT_OUR_REF = 'not our ref';
237const UPLOAD_PACK_NOT_OUR_REF = 'upload-pack: not our ref';
238function notOurRefReason(text: string): Extra {
239 const bare = text === NOT_OUR_REF || text.startsWith(`${NOT_OUR_REF} `);
240 const prefixed = text === UPLOAD_PACK_NOT_OUR_REF || text.startsWith(`${UPLOAD_PACK_NOT_OUR_REF} `);
241 if (bare || prefixed) return { reason: 'not_our_ref' };
242 return {};
245// The sideband counters a demultiplexer keeps (V2State carries them): bytes and frames per band, and the progress tail.
246export type SidebandCounters = {
247 readonly band1: number;
248 readonly band2: number;
249 readonly band2Frames: number;
250 readonly packFrames: number;
251 readonly progress: string;
252 readonly progressCarry: Uint8Array;
253};
254// What one frame was: pack bytes (a view into the frame's payload, which pktStep copied out of the chunk), or progress.
255export type SidebandPiece = { readonly kind: 'pack'; readonly body: Uint8Array } | { readonly kind: 'progress'; readonly text: string };
256export type Sidebanded<S> = { readonly state: S; readonly piece: SidebandPiece };
257export type SidebandError = ErrorOf<'protocol'> | ErrorOf<'limit_exceeded'> | ErrorOf<'remote_error'>;
258// One packfile-section frame, demultiplexed (git's demultiplex_sideband): band 1 is pack bytes and band 2 progress, each
259// held to maxPack before the frame is handed on; band 3 is the remote's error, its text the message. Peak is the frame.
260// scrub: the transport's credential scrubber (or null), applied to band 3's text before it is cut (errors.ts remoteText).
261// @decoder sidebandStep prefix=sideband
262export function sidebandStep<S extends SidebandCounters>(st: S, frame: Frame, maxPack: number, scrub: Scrub | null = null): Result<Sidebanded<S>, SidebandError> {
263 // A delim or response-end inside the packfile section ends git's sideband demultiplexer (demultiplex_sideband:
264 // SIDEBAND_FLUSH), so git reads a pack cut there; neither is a frame upload-pack writes in it. Refused, not skipped.
265 if (frame.kind !== 'data') return proto(`v2: ${frame.kind} inside the packfile section`);
266 const sb = parseSideband(frame.payload);
267 if (!sb.ok) return sb;
268 const band = sb.value;
269 if (band.band === SIDEBAND_PACK) {
270 const band1 = st.band1 + band.body.length;
271 if (band1 > maxPack) return err(limitExceeded('pack bytes', band1, maxPack));
272 return ok({ state: { ...st, band1, packFrames: st.packFrames + 1 }, piece: { kind: 'pack', body: band.body } });
273 }
274 if (band.band === SIDEBAND_PROGRESS) {
275 const band2 = st.band2 + band.body.length;
276 if (band2 > maxPack) return err(limitExceeded('progress bytes', band2, maxPack));
277 // decodeChunk: a character cut by a frame boundary is held for the next frame instead of decoding as two U+FFFD
278 const d = decodeChunk(st.progressCarry, band.body);
279 return ok({ state: { ...st, band2, band2Frames: st.band2Frames + 1, progress: (st.progress + d.text).slice(-PROGRESS_KEEP), progressCarry: d.carry }, piece: { kind: 'progress', text: d.text } });
280 }
281 if (band.band === SIDEBAND_ERROR) {
282 const text = td.decode(band.body).trim();
283 return fail('remote_error', `remote: ${remoteText(text, REMOTE_TEXT_MAX, scrub)}`, notOurRefReason(text));
284 }
285 return proto(`v2: bad sideband ${band.band}`);
288// A commit want whose object is a tree, blob, or tag is not_found, before pack_corrupt is built. Any other mismatch
289// (a blob want, a delta, an unknown type id) stays the caller's pack_corrupt.
290function refuseNonCommit(expectType: number | null, type: number, oid: string): Result<null, ErrorOf<'not_found'>> {
291 if (expectType !== TYPE.COMMIT) return UNIT;
292 const found = nonCommitType(type);
293 switch (found.tag) {
294 case 'commit':
295 case 'delta':
296 case 'invalid':
297 return UNIT;
298 case 'notCommit':
299 return fail('not_found', `${oid} is not a commit`, { miss: { kind: 'commit', miss: { kind: 'not_commit', oid, type: found.name } } });
300 }
301 // Stryker disable next-line ConditionalExpression: unreachable, the compiler's exhaustiveness check
302 return assertNever(found);
305// characters of a refused acknowledgment line quoted in the error (remoteQuoted: cut first, then every control and format character escaped)
306const ACK_LINE_SHOWN = 60;
307// v2End's "no packfile section" names the answer's sections. A section header is a line the server wrote: each name
308// goes through remoteText cut to SECTION_SHOWN units, and at most SECTIONS_SHOWN of them are named.
309const SECTIONS_SHOWN = 8;
310const SECTION_SHOWN = 60;
311// limits: a checked record (parseLimits; DEFAULT_LIMITS when none is given): v2Step reads its caps on every frame.
312export const v2Init = (limits: CheckedLimits = DEFAULT_LIMITS): V2State => Object.freeze({ limits,
313 phase: 'sections', section: null, sections: [], shallow: [], unshallow: [], acks: [], ready: false,
314 band1: 0, band2: 0, band3: 0, band2Frames: 0, progress: '', progressCarry: new Uint8Array(0), error: null, done: false, packFrames: 0,
315 sectionLines: 0, otherLines: 0,
316});
317const stepped = (state: V2State, pack: Uint8Array | null = null): Result<V2Step, never> => ok({ state, pack });
318// scrub: the transport's credential scrubber (or null), applied to an ERR line's or band 3's text before it is cut.
319// @decoder v2Step prefix=v2
320// oxlint-disable-next-line complexity -- a step function is one transition table
321export function v2Step(st: V2State, frame: Frame, scrub: Scrub | null = null): Result<V2Step, PlyError> {
322 // Every section line, including ones this client does not interpret, counts against the same cap. The state's limits
323 // are checked (v2Init takes a CheckedLimits): a missing maxSectionLines used to make `n >= <missing>` false.
324 const maxLines = st.limits.maxSectionLines;
325 // The one place every consumer of a fetch response passes: band 1 (the pack) and band 2 (progress) are each held to
326 // maxPackBytes here, before the frame is yielded, so fetchSingle, fetchWide, fetchPackOnce, the streamed blob (edit,
327 // read, checkout) and any new consumer are bounded without a check of their own. Before, only the buffered consumers
328 // counted, and a streamed blob body was accepted until the request timer (~5 GiB at the default 60 s).
329 const maxPack = st.limits.maxPackBytes;
330 if (st.done) return proto('v2: frame after flush');
331 if (frame.kind === 'flush') return stepped({ ...st, done: true });
332 switch (st.phase) {
333 case 'pack': {
334 const sb = sidebandStep(st, frame, maxPack, scrub);
335 if (!sb.ok) return sb;
336 // Stryker disable next-line ConditionalExpression: a progress piece has no body field, and stepped's default parameter makes the missing value the same null
337 return stepped(sb.value.state, sb.value.piece.kind === 'pack' ? sb.value.piece.body : null);
338 }
339 case 'sections': {
340 // A response-end outside the packfile section is skipped.
341 if (frame.kind === 'end') return stepped(st);
342 if (frame.kind === 'delim') return stepped({ ...st, section: null });
343 const line = td.decode(frame.payload).replace(/\n$/, '');
344 if (line.startsWith('ERR ')) {
345 const text = line.slice('ERR '.length);
346 return fail('remote_error', `remote: ${remoteText(text, REMOTE_TEXT_MAX, scrub)}`, notOurRefReason(text));
347 }
348 if (st.section === null) {
349 if (st.sections.length >= maxLines) return err(limitExceeded('section headers', st.sections.length + 1, maxLines));
350 const next: { -readonly [K in keyof V2State]: V2State[K] } = { ...st, section: line, sections: [...st.sections, line] };
351 if (line === 'packfile') next.phase = 'pack';
352 return stepped(next);
353 }
354 if (st.section === 'shallow-info') {
355 if (st.sectionLines >= maxLines) return err(limitExceeded('shallow-info lines', st.sectionLines + 1, maxLines));
356 const s = { ...st, sectionLines: st.sectionLines + 1 };
357 // the server may repeat a shallow line when a commit is wanted both directly and through a tag; keep them unique
358 if (line.startsWith('shallow ')) return stepped({ ...s, shallow: s.shallow.includes(line.slice('shallow '.length)) ? s.shallow : [...s.shallow, line.slice('shallow '.length)] });
359 if (line.startsWith('unshallow ')) return stepped({ ...s, unshallow: s.unshallow.includes(line.slice('unshallow '.length)) ? s.unshallow : [...s.unshallow, line.slice('unshallow '.length)] });
360 return stepped(s);
361 }
362 if (st.section === 'acknowledgments') {
363 if (st.acks.length >= maxLines) return err(limitExceeded('acknowledgment lines', st.acks.length + 1, maxLines));
364 if (line === 'ready') return stepped({ ...st, ready: true });
365 // git reads NAK, ACK <oid> and ready, and dies on anything else ("unexpected acknowledgment line")
366 if (line !== 'NAK' && !line.startsWith('ACK ')) return proto(`v2: unexpected acknowledgment line ${remoteQuoted(line, ACK_LINE_SHOWN)}`);
367 return stepped({ ...st, acks: [...st.acks, line] });
368 }
369 if (st.otherLines >= maxLines) return err(limitExceeded('section lines', st.otherLines + 1, maxLines));
370 return stepped({ ...st, otherLines: st.otherLines + 1 });
371 }
372 }
373 // Stryker disable next-line ConditionalExpression: unreachable, the compiler's exhaustiveness check
374 return assertNever(st.phase);
376// The response is over: it ended with its flush, and it is the answer the request asked for. git is the judge of its
377// shape. `done` is whether the request carried `done` (the parsed request's, fetchRequest): after it git's fetch-pack
378// reads the packfile section next and dies on an acknowledgments section ("expected 'packfile', received
379// 'acknowledgments'"), so one is refused here whether or not a pack follows it, and an answer with no pack is never ok.
380// Without `done` a round may end on its acknowledgments, unless the server said `ready`: the packfile follows that in
381// the same response (git: "expected packfile to be sent after 'ready'").
382// A response with no section at all, not even its flush, carries reason 'empty_response': the answer git's upload-pack
383// gives when it dies on an argument (fetch.ts filterUnadvertised reads it).
384export function v2End(st: V2State, done: boolean): Result<V2State, ErrorOf<'protocol'>> {
385 if (!st.done) return fail('protocol', 'v2: response ended without flush', st.sections.length === 0 ? { reason: 'empty_response' } : {});
386 const acks = st.sections.includes('acknowledgments');
387 if (st.phase === 'pack') return done && acks ? proto('v2: expected packfile, received acknowledgments') : ok(st);
388 if (done || !acks) return proto(`v2: no packfile section (sections: ${st.sections.slice(0, SECTIONS_SHOWN).map(s => remoteText(s, SECTION_SHOWN)).join(',') || 'none'})`);
389 if (st.ready) return proto('v2: the server said ready and sent no packfile section');
390 return ok(st);
392export const v2Attrs = (st: V2State): Attrs => ({
393 'git.fetch.sections': st.sections.join(','), 'git.fetch.shallow': st.shallow, 'git.fetch.unshallow': st.unshallow,
394 'git.fetch.acks': st.acks, 'git.fetch.ready': st.ready,
395 'git.sideband.band1.bytes': st.band1, 'git.sideband.band2.bytes': st.band2, 'git.sideband.band2.frames': st.band2Frames,
396 'git.sideband.band3.bytes': st.band3, 'git.sideband.pack.frames': st.packFrames, 'git.sideband.progress.tail': st.progress.slice(-PROGRESS_ATTR),
397});
398// The request's arguments as the caller gave them: a left-out or null argument reads as its default.
399export const fetchAttrs = (opts: FetchOpts): Attrs => ({
400 'git.command': 'fetch', 'git.protocol.version': PROTOCOL_V2, 'git.fetch.wants': opts.wants, 'git.fetch.wants.count': opts.wants.length,
401 'git.fetch.haves.count': getOrElse(fromNullish(opts.haves), []).length, 'git.fetch.filter': getOrElse(fromNullish(opts.filter), ''), 'git.fetch.deepen': getOrElse(fromNullish(opts.deepen), 0),
402 'git.fetch.deepen_since': getOrElse<number | string>(fromNullish(opts.deepenSince), 0), 'git.fetch.deepen_not': getOrElse(fromNullish(opts.deepenNot), []), 'git.fetch.shallows.count': getOrElse(fromNullish(opts.shallows), []).length, 'git.fetch.done': opts.done !== false,
403 'git.fetch.thin_pack': Boolean(opts.thinPack), 'git.fetch.ofs_delta': opts.ofsDelta !== false, 'git.fetch.no_progress': opts.noProgress !== false,
404});
406// Band-1 pack bytes as they arrive; the v2 state is the generator's return value.
407export type PackFetch = AsyncGenerator<Uint8Array, V2State, unknown>;
408// The response read frame by frame: band-1 bytes yielded as they arrive, the v2 state or the first Err returned. A
409// caller's own span (GitHttp.packStream) may not carry t.scrub: band-3/ERR text is redacted here too, and so is
410// whatever the transport's stream raised (it is re-raised, scrubbed).
411// The request is parsed once here: its `done` is the line that is sent and the one the answer is judged against (v2End).
412async function* v2Frames(t: Transport, opts: FetchOpts, span: Span): AsyncGenerator<Uint8Array, Result<V2State, PlyError>, unknown> {
413 const req = fetchRequest(opts);
414 if (!req.ok) return req;
415 const body = fetchRequestBody(req.value);
416 if (!body.ok) return body;
417 // the exchange (no request yet: the frames are pulled below), then the limits it runs under
418 const exchange = frames(t, 'git-upload-pack', body.value, span, { bypassCache: Boolean(opts.bypassCache) });
419 let st = v2Init(t.limits);
420 try { for await (const f of exchange) {
421 const r = v2Step(st, f, t.scrub);
422 if (!r.ok) { scrubError(r.error, t.scrub); return r; }
423 st = r.value.state;
424 if (r.value.pack) yield r.value.pack;
425 } } catch (e) { throw scrubError(e, t.scrub); }
426 return v2End(st, req.value.done);
428// Stream band-1 pack bytes. Consumer drives it; the v2 state is the generator's return value. A stream: a failure is
429// raised through it (the iterator rejects with the PlyError).
430export async function* packStream(t: Transport, opts: FetchOpts, span: Span): PackFetch {
431 span.set(fetchAttrs(opts));
432 const end = yield* v2Frames(t, opts, span);
433 if (!end.ok) throw end.error;
434 span.set(v2Attrs(end.value));
435 return end.value;
438// ---- single-object pack stream parser (pure step) ----
439// Emits the zlib bytes of the single object, withholding the trailing 20-byte trailer, verifying it at finish.
440// A bounded read that ran past the buffer (`reason: 'short_read'`, bytes.ts). spStep waits for more bytes on this reason,
441// never on the message (#76). A finished header readObjHeader refuses (a varint past 64 bits) is that error, returned.
442export const isShortRead = (e: unknown): boolean => thrownCodeIs(e, 'pack_corrupt') && thrownReasonIs(e, 'short_read');
444// The single-object parser's state: the pack header and the object header (`header`), then the zlib body with the
445// trailer withheld (`body`); `trailer` is null until spFinish has checked it, then the trailer it checked.
446type SpCommon = { readonly head: Uint8Array; readonly lag: Uint8Array; readonly sha: Sha1; readonly bytes: number; readonly zlibBytes: number; readonly trailer: string | null; readonly maxObject: number };
447export type SpHeader = SpCommon & { readonly phase: 'header'; readonly type: number; readonly size: number };
448export type SpBody = SpCommon & { readonly phase: 'body'; readonly type: ObjType; readonly size: ObjSize; readonly headerBytes: number };
449export type SpState = SpHeader | SpBody;
450export type SpFinished = SpBody & { readonly trailer: string };
451export type SpStepped = { readonly state: SpState; readonly zlib: Uint8Array[] };
452type Corrupt = ErrorOf<'pack_corrupt'>;
453type SpError = HeaderError;
455// `maxObject`: the cap on the object's declared size, refused where its header is read (limit_exceeded, `pack object
456// size`). A streamed blob (edit, read) has none: its reader bounds it.
457export const spInit = (maxObject: number = NO_SIZE_CAP): SpState => Object.freeze({ head: new Uint8Array(0), phase: 'header', type: 0, size: 0, lag: new Uint8Array(0), sha: new Sha1(), bytes: 0, zlibBytes: 0, trailer: null, maxObject });
458const hasSignature = (head: Uint8Array): boolean => head.subarray(0, PACK_SIGNATURE.length).every((b, i) => b === PACK_SIGNATURE[i]);
459// The header phase, given every byte so far (`head`): still waiting (null), or the body state and the bytes after the
460// object header. Past the length check the header fields are views into `head`, not bounded reads: they cannot be short.
461function spHeader(s: SpHeader, head: Uint8Array): Result<{ readonly body: SpBody; readonly rest: Uint8Array } | null, SpError> {
462 // need the pack header plus the first object-header byte; a short read means the chunk has not arrived.
463 if (head.length < PACK_HEADER_BYTES + 1) return ok(null);
464 if (!hasSignature(head)) return fail('pack_corrupt', 'pack: bad signature');
465 const version = readUint32BE(head, PACK_SIGNATURE.length);
466 if (!version.ok) return version;
467 if (version.value !== PACK_VERSION) return fail('pack_corrupt', 'pack: bad version');
468 const counted = readUint32BE(head, PACK_SIGNATURE.length + UINT32_BYTES);
469 if (!counted.ok) return counted;
470 const count = counted.value;
471 if (count !== 1) return fail('pack_corrupt', `pack: expected 1 object, got ${count}`);
472 const header = readObjHeader(head, PACK_HEADER_BYTES, PACK_HEADER_BYTES, s.maxObject);
473 if (!header.ok) return isShortRead(header.error) ? ok(null) : header;
474 if (header.value.type === TYPE.OFS_DELTA || header.value.type === TYPE.REF_DELTA) return fail('pack_corrupt', 'pack: single-object pack is a delta');
475 const p: number = header.value.next;
476 s.sha.update(head.subarray(0, p));
477 return ok({ body: { ...s, phase: 'body', type: header.value.type, size: header.value.size, head: new Uint8Array(0), headerBytes: p }, rest: head.subarray(p) });
479// Where a chunk lands: still in the header (the state waits for more), or body bytes after the object header.
480type SpEntry = { readonly tag: 'wait'; readonly state: SpHeader } | { readonly tag: 'body'; readonly state: SpBody; readonly data: Uint8Array };
481function spEnter(st: SpState, chunk: Uint8Array): Result<SpEntry, SpError> {
482 switch (st.phase) {
483 case 'header': {
484 // The header phase is bounded here, for every caller: readObjHeader refuses an object header past 10 bytes
485 // (VARINT_MAX_SHIFT), so `head` never holds more than PACK_HEADER_BYTES + 9 bytes between chunks and the 22nd
486 // byte of a pack whose object header never ends is `pack_corrupt` (#13: endless 0x80 used to grow `head` without bound).
487 const head = concat([st.head, chunk]);
488 const opened = spHeader(st, head);
489 if (!opened.ok) return opened;
490 if (opened.value === null) return ok({ tag: 'wait', state: { ...st, head } });
491 return ok({ tag: 'body', state: opened.value.body, data: opened.value.rest });
492 }
493 case 'body':
494 return ok({ tag: 'body', state: st, data: chunk });
495 }
496 // Stryker disable next-line ConditionalExpression: unreachable, the compiler's exhaustiveness check
497 return assertNever(st);
499// @decoder spStep prefix=sp-header
500export function spStep(st: SpState, chunk: Uint8Array): Result<SpStepped, SpError> {
501 const entered = spEnter({ ...st, bytes: st.bytes + chunk.length }, chunk);
502 if (!entered.ok) return entered;
503 const entry = entered.value;
504 if (entry.tag === 'wait') return ok({ state: entry.state, zlib: [] });
505 const { state: s, data } = entry;
506 // body: pass through with the trailer withheld
507 // Stryker disable next-line ConditionalExpression,EqualityOperator: equivalent: concat([empty lag, data]) is a copy of data, byte for byte
508 const all = s.lag.length > 0 ? concat([s.lag, data]) : data;
509 const emitLen = Math.max(0, all.length - PACK_TRAILER_BYTES);
510 const emit = all.subarray(0, emitLen);
511 const lag = all.slice(emitLen);
512 // The zlib bytes of an object declared `size` may not run past zlibBound(size) (format.js). The declared-size check on
513 // inflated bytes cannot see a stream that inflates to nothing (non-final empty stored blocks, 5 bytes in, 0 out), which
514 // used to be accepted until the request timer; this refuses it on the chunk that crosses the bound, so a 10-byte blob
515 // costs at most 26 zlib bytes plus the rest of that chunk, whatever maxPackBytes is. The message carries no count: the
516 // same bytes in any chunking give the same error (I10).
517 const zlibBytes = s.zlibBytes + emitLen;
518 const bound = zlibBound(s.size);
519 // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- an ad-hoc error field (`size`); Extra has got and max
520 if (zlibBytes > bound) return fail('pack_corrupt', `pack: zlib stream longer than its declared size allows (${s.size}-byte object, ${bound}-byte bound)`, { got: zlibBytes, max: bound, size: s.size } as Extra);
521 // Stryker disable next-line ConditionalExpression: hashing an empty emit leaves the trailer digest unchanged
522 if (emitLen) s.sha.update(emit);
523 return ok({ state: { ...s, lag, zlibBytes }, zlib: emitLen ? [emit] : [] });
525export function spFinish(st: SpState): Result<SpFinished, Corrupt> {
526 if (st.phase !== 'body') return fail('pack_corrupt', 'pack: truncated before object header');
527 if (st.lag.length !== PACK_TRAILER_BYTES) return fail('pack_corrupt', 'pack: missing trailer');
528 const got = st.sha.hex(), want = toHex(st.lag);
529 if (want !== got) return fail('pack_corrupt', `pack: trailer ${want} != ${got}`);
530 return ok({ ...st, trailer: want });
532const trailerOf = (st: SpState): string => (st.trailer === null ? '' : st.trailer);
533export const spAttrs = (st: SpState, prefix = 'git.pack'): Attrs => ({ [`${prefix}.objects`]: 1, [`${prefix}.bytes`]: st.bytes, [`${prefix}.trailer`]: trailerOf(st), [`${prefix}.compressed.bytes`]: st.zlibBytes, [`${prefix}.type.${typeText(st.type)}`]: 1 });
535// One object by oid (a tree or a commit, under a filter that keeps the pack to that object), fully in memory but bounded
536// by limits.maxObjectSize, inflated with our inflate and hash-verified against the oid. A verification failure after a
537// cache HIT is retried once past the cache (packcache.js). Returns { type, data, oid, size, bust }.
538//
539// The blob:none fallback. Some servers advertise `fetch=filter` but honour only `blob:none` (Cloudflare Artifacts:
540// HTTP 400 "Unsupported Git fetch filter; only blob:none is supported.", observed 2026-10-23). Detected by that answer,
541// never by host name: the transport's `quirks.treeFilter` becomes 'blob:none' and this and every later tree:0 fetch on
542// it asks for blob:none instead. That pack is wider — a commit want (deepen 1) brings every tree of the commit, a tree
543// want its whole subtree — so it is parsed and delta-resolved (packresolve.js), the wanted object is taken by its
544// computed hash, and the other commits and trees are harvested into `t.objects` (bounded by limits.maxHarvestBytes):
545// the next tree:0 fetch of any of them is answered locally. Spans: `git.fetch.filter.fallback`, `git.fetch.wide.*`.
546// The phrases a server uses when it refuses a fetch filter. Cloudflare Artifacts (observed 2026-10-23) is HTTP 400
547// plus the first one; git's upload-pack says "filter '<spec>' not supported" (upload-pack.c). One predicate, shared:
548// ply-web used to keep a copy of it next to the cache. The text is remote, so it is read in linear time. A single
549// `filter .* not` restarts its run at every "filter " (quadratic, ply#274); here each "filter " takes the rest of its
550// line once, the global exec resumes after it, and one fixed-phrase test (a bounded number of steps at each start)
551// reads that rest. The first "filter " on a line takes the longest rest, so a later one on the same line could find
552// nothing it did not. Same flags as before (/i, no /u): the same case fold.
553const FILTER_PHRASE = /only blob:none is supported|unsupported (git )?fetch filter/i;
554const FILTER_REST = /filter ([^\n\r\u2028\u2029]*)/gi;
555const FILTER_NOT = / not (supported|allowed)/i;
556const isFilterPhrase = (text: string): boolean => {
557 if (FILTER_PHRASE.test(text)) return true;
558 FILTER_REST.lastIndex = 0; // shared /g: every call starts at the beginning, whatever an earlier return left
559 for (let m = FILTER_REST.exec(text); m !== null; m = FILTER_REST.exec(text)) if (FILTER_NOT.test(atOr(m, 1, ''))) return true;
560 return false;
561};
562// oxlint-disable-next-line no-magic-numbers -- RFC 9110 Bad Request: Artifacts' refusal, and the only status this predicate accepts
563const FILTER_REFUSAL_STATUS = 400;
564// A raw upload-pack answer (the HTTP status and the body, or the text an error quoted from it). Status is part of the
565// answer: a 500 that happens to contain the phrase is not a filter refusal.
566export const isFilterRefusal = (status: number, text: string): boolean => status === FILTER_REFUSAL_STATUS && isFilterPhrase(text);
567// A thrown value is not a PlyError until it is: message may be no string, and `status` is only on an http error.
568export const isFilterRejection = (e: unknown): boolean => {
569 const code = getOrElse(thrownCode(e), null);
570 const text = String(getOrElse(thrownMessage(e), ''));
571 // remote_error and protocol have no HTTP status. The phrase in the message is the refusal, so the same predicate
572 // sees it as the 400 it is when the server says it over HTTP.
573 if (code === 'remote_error' || code === 'protocol') return isFilterRefusal(FILTER_REFUSAL_STATUS, text);
574 if (code !== 'http') return false;
575 if (e === null || typeof e !== 'object' || !Object.hasOwn(e, 'status')) return false;
576 const status: unknown = Reflect.get(e, 'status');
577 return typeof status === 'number' && isFilterRefusal(status, text);
578};
580// The no-filter fallback. git's upload-pack takes a `filter` argument only with uploadpack.allowFilter set, which is not
581// git's default: a stock `git http-backend` does not list `filter` on its `fetch=` line, and on a request that sends one
582// it dies without a word (upload-pack.c process_args: "unexpected line"), no ERR, no flush, an empty body. That answer
583// to a filtered request (v2End's reason 'empty_response'), and only that one, sends ply to the advertisement, the one
584// place the server says what `fetch` takes (GET info/refs, read as discover reads it). No `filter` there: the transport's
585// quirks.treeFilter becomes 'none' (learnFilter), true is returned, and the caller asks again without a filter, taking
586// the wider pack (a commit want with deepen 1 is its whole snapshot, a tree want its whole subtree; held to every pack
587// limit like any other). `filter` advertised, or an advertisement that cannot be read: false, and the empty response
588// stays the protocol error it is. An advertisement already in hand (discover) sets the quirk before any filtered fetch.
589// Spans: this one is `git.upload-pack discover` with git.server.fetch/filter; the fetch that follows carries
590// `git.fetch.filter.fallback: 'none'`.
591export const isEmptyResponse = (e: unknown): boolean => thrownCodeIs(e, 'protocol') && thrownReasonIs(e, 'empty_response');
592// The other ways a server refuses an argument it does not take: an ERR pkt-line (remote_error) or HTTP 400 (Artifacts'
593// answer to a filter it does not take). 401, 403, 404, 429 and 5xx are other codes and never match. objectAt reads the
594// advertisement on one of these only for a `deepen` it added itself, once per quirks record.
595const isArgumentRefusal = (e: PlyError): boolean => e.code === 'remote_error' || (e.code === 'http' && e.status === FILTER_REFUSAL_STATUS);
596// `refusal`: the answers that send this call to the advertisement. Every caller but objectAt's depth takes the default.
597export async function filterUnadvertised(t: Transport, e: PlyError, refusal: (e: PlyError) => boolean = isEmptyResponse): Promise<boolean> {
598 if (!refusal(e)) return false;
599 const attrs = { 'git.command': 'discover', 'git.protocol.version': PROTOCOL_V2 };
600 // oxlint-disable-next-line typescript/promise-function-async -- the exchange's promise, passed through
601 const read = await coded('protocol', () => spanned(t, 'git.upload-pack discover', clientSpan(t, attrs), async (span: Span): Promise<Result<{ readonly filter: boolean; readonly shallow: boolean }, PlyError>> => {
602 const buf = await advertise(t, 'git-upload-pack', span);
603 if (!buf.ok) return buf;
604 const framed = pktStep(pktInit(), buf.value);
605 if (!framed.ok) return framed;
606 const finished = pktFinish(framed.value.state);
607 if (!finished.ok) return finished;
608 const lines = parseCapabilitiesV2(framed.value.frames, t.scrub);
609 if (!lines.ok) return lines;
610 const features = capLookup(lines.value).features('fetch');
611 const filter = features.includes('filter');
612 const shallow = features.includes('shallow');
613 span.set({ ...pktAttrs(finished.value), 'git.server.fetch': features, 'git.server.filter': filter, 'git.server.shallow': shallow });
614 return ok({ filter, shallow });
615 }));
616 if (!read.ok) return false;
617 learnFilter(t, read.value.filter);
618 // the same line says whether the server takes `deepen`: objectAt asks again without the depth it added
619 learnShallow(t, read.value.shallow);
620 return !read.value.filter;
623// Check a wide (blob:none) pack's commits, trees and tags before any of it is returned or harvested (#18, #46).
624// `wanted(oid, o)` names what a tree:0 server would have sent — what the caller asked for. Those pass assertFetched
625// under the caller's limits exactly as a single-object fetch would, and any failure is the fetch's. The rest are extras
626// only the widening brought, and the two ways one can fail are treated differently:
627// - limit_exceeded (say a sibling directory with more than maxTreeEntries entries): the extra is dropped from the
628// pack, so it is neither returned nor harvested, and counted. A limit is the caller's bound on what it will parse for
629// what it reads; an honest repository can hold a tree past it that the caller never reads, and a tree:0 server would
630// never have sent it. Failing on it made the answer depend on the server's filter support (#46: one 2,135-entry
631// directory failed every read of curl on Artifacts). Dropping it is safe: the caller never sees it, and a later
632// want of it is a fetch of its own that applies the limits to it as the wanted object. Whether its bytes past the
633// limit are well formed is unobservable, since checking them would mean parsing past the limit.
634// - pack_corrupt (malformed; git fsck would refuse it): the fetch fails, as #18 decided. This server sent bytes no
635// honest git server holds, hash-verified or not, so nothing from this response is trusted, including its other
636// objects; pack_corrupt is retryable (and a cached response is refetched once past the cache).
637// maxPackBytes, maxPackObjects and maxInflatedTotal have already bounded the whole pack. Returns the skipped extras,
638// or the first failure that is not one (nothing is dropped then).
639export type Skipped = { readonly oid: string; readonly what: unknown; readonly bytes: number };
640export function checkWide(objects: Map<string, PackObject>, wanted: (oid: string, o: PackObject) => boolean, limits: CheckedLimits): Result<Skipped[], PlyError> {
641 const skipped: Skipped[] = [];
642 for (const [oid, o] of objects) {
643 if (o.type !== TYPE.COMMIT && o.type !== TYPE.TREE && o.type !== TYPE.TAG) continue;
644 const checked = assertFetched(typeText(o.type), o.data, limits);
645 if (checked.ok) continue;
646 if (checked.error.code !== 'limit_exceeded' || wanted(oid, o)) return checked;
647 // a limit_exceeded error carries `what` (limits.ts)
648 skipped.push({ oid, what: checked.error.what, bytes: o.data.length });
649 }
650 for (const s of skipped) objects.delete(s.oid);
651 return ok(skipped);
653export const skippedAttrs = (skipped: readonly Skipped[]): Attrs => ({ 'git.fetch.wide.skipped': skipped.length, 'git.fetch.wide.skipped_reason': [...new Set(skipped.map(s => s.what))].join(',') });
655// Keep commits and trees from a wide pack for later tree:0 wants. Every entry's key is its computed hash (resolvePack);
656// every caller has run checkWide over the pack first (what is left passed assertFetched under the transport's limits),
657// since fetchObject serves the harvest without another look.
658export function harvest(t: Transport, objects: ReadonlyMap<string, PackObject>, skip: string | null = null): Result<{ readonly kept: number; readonly bytes: number }, PlyError> {
659 const store = t.objects;
660 const cap = t.limits.maxHarvestBytes;
661 let bytes = 0, held = harvestBytes(store), kept = 0;
662 for (const [oid, o] of objects) {
663 if (oid === skip || store.has(oid) || (o.type !== TYPE.COMMIT && o.type !== TYPE.TREE)) continue;
664 if (held + o.data.length > cap) break;
665 store.set(oid, { type: o.type, data: o.data }); held += o.data.length; kept++; bytes += o.data.length;
666 }
667 return ok({ kept, bytes });
670// A failed fetch's error carries the cache status of the response it came from (fetchPack and the retry read it back).
671export function stampCacheStatus(e: unknown, span: Span): void {
672 if (e === null || typeof e !== 'object') return;
673 Reflect.set(e, 'cacheStatus', getOrElse(fromNullish(span.attrs['git.response.cache']), ''));
676// One upload-pack fetch under its span. What the stream raised is caught (coded: an uncoded value is pack_corrupt), and
677// a failure is stamped with the response's cache status for the retry rule (corruptCacheHit).
678export async function fetchExchange<T>(t: Transport, attrs: Attrs, fn: (span: Span) => Promise<Result<T, PlyError>>): Promise<Result<T, PlyError>> {
679 const held: { span: Span | null } = { span: null };
680 // oxlint-disable-next-line typescript/promise-function-async -- the exchange's promise, passed through (an async wrapper adds bytes, not behaviour)
681 const r = await coded('pack_corrupt', () => spanned(t, 'git.upload-pack fetch', clientSpan(t, attrs), (span: Span): Promise<Result<T, PlyError>> => { held.span = span; return fn(span); }));
682 if (!r.ok && held.span !== null) stampCacheStatus(r.error, held.span);
683 return r;
685// A verification failure after a cache HIT is retried once past the cache (packcache.ts); a corrupt live response is not.
686async function onceMore<T>(once: (bust: boolean) => Promise<Result<T, PlyError>>): Promise<Result<T, PlyError>> {
687 const first = await once(false);
688 if (first.ok || !corruptCacheHit(first.error)) return first;
689 return once(true);
692// One object wanted by oid. `expectType` (a TYPE id) is checked against what arrives; null takes any type.
693// `deepen`: the depth sent with the want. Left out (or null) it is 1 for a want that may be a commit (expectType null,
694// commit or tag) on a server that takes `deepen`, so one object costs one object of pack whatever the history behind it:
695// with no depth a commit want is answered with every commit reachable from it. A number is sent as given: n for the
696// commit and n - 1 generations of ancestors, 0 for no `deepen` line (the whole history). A want the caller names a tree
697// or a blob gets none: no history is reachable from one.
698export type ObjectWantConfig = { readonly filter: string; readonly deepen: number | null; readonly expectType: number | null };
699export type ObjectWant = { readonly oid: string } & Input<ObjectWantConfig>;
700const objectWantDefaults = (): ObjectWantConfig => ({ filter: 'tree:0', deepen: null, expectType: null });
701// The entries of a fetched tree as its check (assertFetched) parsed them, and the entry cap they were parsed under: the
702// only limit parseTree reads (#208).
703export type CheckedTree = { readonly entries: TreeEntry[]; readonly maxTreeEntries: number };
704// `tree`: a tree fetched by its own want carries the parse that checked it; a harvested or wide answer, and any other
705// type, none.
706type FetchedBase = { readonly type: number; readonly data: Uint8Array; readonly oid: Oid; readonly size: number; readonly bust: boolean; readonly tree: Option<CheckedTree> };
707// A fetched object; `harvested` when the transport's harvest answered it, `wide` when a blob:none pack did.
708export type FetchedObject = FetchedBase | (FetchedBase & { readonly harvested: true }) | (FetchedBase & { readonly wide: true });
709// A fetched tree's entries, parsed once (#208): the check's parse when the reader's entry cap is the one it was made
710// under (parseTree is a pure function of the bytes and that cap, so it is the parse the reader would make), else the
711// reader's own parse under its limits. The fetch hands its object to one reader, so the array is that reader's.
712export function treeEntries(fetched: FetchedObject, limits: CheckedLimits): Result<TreeEntry[], ObjectError> {
713 const { tree } = fetched;
714 if (tree.tag === 'some' && tree.value.maxTreeEntries === limits.maxTreeEntries) return ok(tree.value.entries);
715 return parseTree(fetched.data, limits);
718type Single = { readonly oid: Oid; readonly filter: string; readonly deepen: number; readonly expectType: number | null };
719// The object count in a pack header, or null when the header is not a version-2 pack (the single-object parser then
720// reports its own error). A commit want may be a tag plus the commit it peels to: more than one object, and still the
721// wanted object's type.
722function declaredPackCount(pack: Uint8Array): number | null {
723 if (pack.length < PACK_HEADER_BYTES) return null;
724 if (!hasSignature(pack)) return null;
725 const version = readUint32BE(pack, PACK_SIGNATURE.length);
726 if (!version.ok || version.value !== PACK_VERSION) return null;
727 const count = readUint32BE(pack, PACK_SIGNATURE.length + UINT32_BYTES);
728 return count.ok ? count.value : null;
730// A multi-object answer to a commit want: the wanted object, once its type is a commit. A tree, blob, or tag is
731// not_found from refuseNonCommit. Null means the single-object parser should refuse the pack (it does not hold the want).
732function commitFromPack(t: Transport, oid: Oid, parsed: ParsedPack, span: Span, bust: boolean): Result<FetchedObject | null, PlyError> {
733 // Stryker disable next-line ArrowFunction: null and a bare return both mean the base is not in the pack
734 const resolved = resolvePack(parsed, () => null, t.limits);
735 if (!resolved.ok) return resolved;
736 const objects: Map<string, PackObject> = resolved.value.objects;
737 const found = mapGet(objects, oid);
738 if (found.tag === 'none') return ok(null);
739 const want = found.value;
740 span.set({ 'git.pack.objects': parsed.stats.count, 'git.object.oid': oid, 'git.object.type': typeText(want.type) });
741 const refused = refuseNonCommit(TYPE.COMMIT, want.type, oid);
742 if (!refused.ok) return refused;
743 // a resolved object is commit, tree, blob or tag, and refuseNonCommit answered the other three
744 // Stryker disable next-line ConditionalExpression,BlockStatement: see above
745 if (want.type !== TYPE.COMMIT) return ok(null);
746 const checked = assertFetched('commit', want.data, t.limits);
747 if (!checked.ok) return checked;
748 return ok({ type: want.type, data: want.data, oid, size: want.data.length, bust, tree: none });
750// A pack read through the collector as its chunks arrive (#172): the bytes are dropped once fed, so what is held is the
751// objects the collector keeps. A refusal is held, the rest of the response read and dropped, and then returned: the
752// response's own refusals (packStream raises them) come first, as when the whole pack was read before it was parsed.
753export type WirePack = { readonly state: V2State; readonly pack: Result<ParsedPack, PlyError> };
754export async function collectWire(it: PackFetch, c: PackCollector): Promise<WirePack> {
755 let held: Result<null, PlyError> = UNIT;
756 for (;;) {
757 // oxlint-disable-next-line no-await-in-loop -- the generator is drained in order; its return value is the v2 state
758 const n = await it.next();
759 if (n.done === true) return { state: n.value, pack: held.ok ? packCollectEnd(c) : held };
760 // Stryker disable next-line ConditionalExpression: a refused scan answers every later feed with the same refusal
761 if (held.ok) held = packCollectFeed(c, n.value);
762 }
764// Where a commit want's bytes go: the first bytes are held until the pack header says how many objects there are (one:
765// the single-object parser, `feed`; more: a tag and the commit it peels to, collected).
766type CommitRoute =
767 | { readonly tag: 'head'; readonly head: Uint8Array }
768 | { readonly tag: 'single' }
769 | { readonly tag: 'multi'; readonly c: PackCollector; readonly head: Uint8Array };
770// A commit want's answer, read as it arrives (#172). Ok(null): the single-object parser has the pack (the caller checks
771// its trailer and object); otherwise the commit, or the refusal, held until the response was read to its end.
772async function commitWire(t: Transport, wire: PackFetch, feed: (chunk: Uint8Array) => Result<null, PlyError>, want: { readonly oid: Oid; readonly span: Span; readonly bust: boolean }): Promise<Result<FetchedObject | null, PlyError>> {
773 // one record the closures below move along (a `let` the compiler would narrow to its first value)
774 const at: { route: CommitRoute } = { route: { tag: 'head', head: new Uint8Array(0) } };
775 // the header and the first object-header byte: enough for the single-object parser to refuse a count it does not take
776 const enough = PACK_HEADER_BYTES + 1;
777 const open = (bytes: Uint8Array): Result<null, PlyError> => {
778 const count = declaredPackCount(bytes);
779 if (count === null || count === 1) { at.route = { tag: 'single' }; return feed(bytes); }
780 const caps = packCaps({ limits: t.limits });
781 if (!caps.ok) return caps;
782 const c = packCollectOpen(caps.value, true);
783 // the caps passed packCaps, so the scan opens (packScanOpen)
784 // Stryker disable next-line ConditionalExpression,BlockStatement: see above
785 if (!c.ok) return c;
786 at.route = { tag: 'multi', c: c.value, head: bytes.subarray(0, enough) };
787 return packCollectFeed(c.value, bytes);
788 };
789 const step = (chunk: Uint8Array): Result<null, PlyError> => {
790 switch (at.route.tag) {
791 case 'single': return feed(chunk);
792 case 'multi': return packCollectFeed(at.route.c, chunk);
793 case 'head': {
794 const head = concat([at.route.head, chunk]);
795 // Stryker disable next-line ConditionalExpression,EqualityOperator: deciding on more bytes reads the same pack (the header is its first 12)
796 if (head.length < enough) { at.route = { tag: 'head', head }; return UNIT; }
797 return open(head);
798 }
799 }
800 // Stryker disable next-line ConditionalExpression,BlockStatement,CallExpression: unreachable, the compiler's exhaustiveness check
801 return assertNever(at.route);
802 };
803 let held: Result<null, PlyError> = UNIT;
804 for await (const chunk of wire) if (held.ok) held = step(chunk);
805 if (!held.ok) return held;
806 // a response shorter than `enough`: decided on what came
807 if (at.route.tag === 'head') {
808 const opened = open(at.route.head);
809 if (!opened.ok) return opened;
810 }
811 const route = at.route;
812 if (route.tag !== 'multi') return ok(null);
813 const parsed = packCollectEnd(route.c);
814 if (!parsed.ok) return parsed;
815 const found = commitFromPack(t, want.oid, parsed.value, want.span, want.bust);
816 if (!found.ok || found.value !== null) return found;
817 // the pack does not hold the commit: the single-object parser's refusal of its count
818 const fed = feed(route.head);
819 return fed.ok ? ok(null) : fed;
821// The single object's member, inflated as its zlib bytes arrive (issue #172): the object is written into one
822// Uint8Array of its declared size and the zlib bytes are dropped as they are read, so the peak is the object plus the
823// inflate window, one chunk and one frame (streambound.ts), not the member as well. A refusal is held, not returned, until
824// the pack has been read to its trailer: spStep's and spFinish's refusals come first, as they did when the member was
825// inflated whole after spFinish.
826type Member =
827 | { readonly tag: 'header' }
828 | { readonly tag: 'open'; readonly stream: InflateStream; readonly out: Uint8Array<ArrayBuffer>; readonly at: number }
829 | { readonly tag: 'done'; readonly out: Uint8Array<ArrayBuffer>; readonly consumed: number; readonly stats: InflateStats; readonly after: number }
830 | { readonly tag: 'failed'; readonly error: InflateError };
831const MEMBER_HEADER: Member = { tag: 'header' };
832// Pull until the member wants more input, or ends, or is refused.
833function memberDrain(m: Member, end: boolean): Member {
834 if (m.tag !== 'open') return m;
835 let at = m.at;
836 for (;;) {
837 const r = end ? inflateEnd(m.stream) : inflatePull(m.stream);
838 if (!r.ok) return { tag: 'failed', error: r.error };
839 const piece = r.value;
840 switch (piece.kind) {
841 case 'need': return { ...m, at };
842 // a declared bound: the stream never yields past the declared size, which is out's length
843 case 'chunk': m.out.set(piece.bytes, at); at += piece.bytes.length; continue;
844 case 'end': return { tag: 'done', out: m.out, consumed: piece.consumed, stats: piece.stats, after: inflateUnread(m.stream).length };
845 }
846 // Stryker disable next-line ConditionalExpression,BlockStatement,CallExpression: unreachable, the compiler's exhaustiveness check
847 return assertNever(piece);
848 }
850function memberTake(m: Member, z: Uint8Array): Member {
851 switch (m.tag) {
852 case 'open': inflateFeed(m.stream, z); return memberDrain(m, false);
853 case 'done': return { ...m, after: m.after + z.length };
854 // memberFeed opens a member before it hands it bytes, so 'header' does not reach here; a failed member drops them
855 // Stryker disable next-line StringLiteral: 'header' is unreachable here, see above
856 case 'header':
857 case 'failed': return m;
858 }
859 // Stryker disable next-line ConditionalExpression,BlockStatement,CallExpression: unreachable, the compiler's exhaustiveness check
860 return assertNever(m);
862// The zlib bytes spStep passed on. The member opens once the object header is read (spStep held its size to maxObject,
863// spInit's cap); bytes after the member's end are counted, not kept.
864function memberFeed(m: Member, sp: SpState, zlib: readonly Uint8Array[], maxObject: number): Member {
865 let cur = m;
866 if (cur.tag === 'header') {
867 if (sp.phase !== 'body') return cur;
868 const opened = inflateInit({ bound: declaredBound(sp.size, maxObject), wrap: zlibWrap(true) });
869 // the size is within maxObject (spStep), which parseLimits checked: the record always opens
870 // Stryker disable next-line all: see above
871 if (!opened.ok) return { tag: 'failed', error: opened.error };
872 cur = { tag: 'open', stream: opened.value, out: new Uint8Array(sp.size), at: 0 };
873 }
874 for (const z of zlib) cur = memberTake(cur, z);
875 return cur;
877type Inflated = { readonly out: Uint8Array<ArrayBuffer>; readonly stats: InflateStats };
878// The member once the pack has been read: its object, or the refusal it held. A member that ended before its zlib
879// bytes did is the trailing-bytes refusal.
880function memberFinish(m: Member): Result<Inflated, PlyError> {
881 const last = memberDrain(m, true);
882 switch (last.tag) {
883 // spFinish passed (so the object header was read, its size within maxObject): the member opened. inflateEnd
884 // ends a member or refuses it, so it is not still open.
885 // Stryker disable next-line all: unreachable, see above
886 case 'header': return fail('internal', 'member never opened');
887 // Stryker disable next-line all: unreachable, see above
888 case 'open': return fail('internal', 'member open after inflateEnd');
889 case 'failed': return err(last.error);
890 case 'done':
891 if (last.after !== 0) return fail('pack_corrupt', `pack: ${last.after} trailing bytes after object`);
892 return ok({ out: last.out, stats: last.stats });
893 }
894 // Stryker disable next-line ConditionalExpression,BlockStatement,CallExpression: unreachable, the compiler's exhaustiveness check
895 return assertNever(last);
897// The single object, inflated: hashed against the want, its type checked.
898type Received = { readonly sp: SpFinished; readonly member: Member; readonly want: Single; readonly span: Span; readonly bust: boolean };
899function singleObject(t: Transport, { sp, member, want, span, bust }: Received): Result<FetchedObject, PlyError> {
900 const { oid, expectType } = want;
901 const inflated = memberFinish(member);
902 if (!inflated.ok) return inflated;
903 const { out, stats } = inflated.value;
904 const got = hashObject(typeText(sp.type), out);
905 span.set({ ...spAttrs(sp), 'git.pack.inflated.bytes': out.length, 'git.pack.inflate.blocks': stats.blocks, 'git.pack.inflate.stored': stats.stored, 'git.pack.inflate.fixed': stats.fixed, 'git.pack.inflate.dynamic': stats.dynamic, 'git.object.oid': got, 'git.object.type': typeText(sp.type) });
906 if (got !== oid) return fail('pack_corrupt', `object ${got} served for want ${oid}`);
907 const checked = assertFetched(typeText(sp.type), out, t.limits);
908 if (!checked.ok) return checked;
909 const refused = refuseNonCommit(expectType, sp.type, oid);
910 if (!refused.ok) return refused;
911 if (expectType !== null && sp.type !== expectType) return fail('pack_corrupt', `expected ${typeText(expectType)}, got ${typeText(sp.type)}`);
912 const tree = mapOption(checked.value, (entries): CheckedTree => ({ entries, maxTreeEntries: t.limits.maxTreeEntries }));
913 return ok({ type: sp.type, data: out, oid, size: out.length, bust, tree });
915// oxlint-disable-next-line typescript/promise-function-async -- onceMore's promise, passed through
916function fetchSingle(t: Transport, want: Single): Promise<Result<FetchedObject, PlyError>> {
917 const { oid, filter, deepen, expectType } = want;
918 // The span is where the transport says whether the response came from a cache (fetchExchange, onceMore).
919 // oxlint-disable-next-line typescript/promise-function-async -- the exchange's promise, passed through
920 const once = (bust: boolean): Promise<Result<FetchedObject, PlyError>> => fetchExchange(t, { 'git.pack.cache.bust': bust }, async (span: Span): Promise<Result<FetchedObject, PlyError>> => {
921 const maxObject = t.limits.maxObjectSize;
922 // Pack bytes are held to maxPackBytes by v2Step (inside packStream) before a chunk reaches here; the zlib bytes are
923 // bounded by spStep at zlibBound(sp.size) and inflated as they arrive (memberFeed), sp.size by maxObjectSize where
924 // the header is read (readObjHeader, through spStep).
925 let sp = spInit(maxObject); let member = MEMBER_HEADER;
926 const feed = (chunk: Uint8Array): Result<null, PlyError> => {
927 const r = spStep(sp, chunk);
928 if (!r.ok) return r;
929 sp = r.value.state;
930 member = memberFeed(member, sp, r.value.zlib, maxObject);
931 return UNIT;
932 };
933 const wire = packStream(t, { wants: [oid], filter, deepen, bypassCache: bust }, span);
934 // A commit id may arrive as the tag object plus the commit it peels to (commitWire). Other wants stream, and stop at
935 // the header whose size is past maxObject (spStep refuses it) before the rest of the pack is read.
936 if (expectType === TYPE.COMMIT) {
937 const found = await commitWire(t, wire, feed, { oid, span, bust });
938 if (!found.ok) return found;
939 if (found.value !== null) return ok(found.value);
940 } else {
941 for await (const chunk of wire) {
942 const fed = feed(chunk);
943 if (!fed.ok) return fed;
944 }
945 }
946 const finished = spFinish(sp);
947 if (!finished.ok) return finished;
948 return singleObject(t, { sp: finished.value, member, want, span, bust });
949 });
950 return onceMore(once);
953// The wide form of a filtered single-object fetch (see fetchObject): blob:none for a host that refuses tree:0, no filter
954// ('') for one that does not take `filter` at all. Bounded by limits.maxPackBytes (v2Step) and the pack parser's limits.
955export type WideFilter = 'blob:none' | '';
956// The filter a wide fetch sent, as spans and messages name it.
957export const packName = (filter: string): string => (filter === '' ? 'unfiltered' : filter);
958export const fallbackName = (filter: WideFilter): string => (filter === '' ? 'none' : filter);
959// A wide fetch: the want, and the filter sent (a fallback's WideFilter, or a path walk's combine filter, #218).
960type Wide = { readonly oid: Oid; readonly deepen: number; readonly expectType: number | null; readonly filter: string };
961// What a wide fetch left out as it read the pack: full blobs (a commit or tree want is neither, and a harvest keeps
962// commits and trees) and the deltas on them, by offset, with their declared bytes.
963type Dropped = { readonly offsets: Set<number>; bytes: number };
964// The objects a wide pack keeps (#172): all of them, unless the want cannot be a blob. Then a full blob is dropped as its
965// header arrives, and so is an OFS_DELTA on a dropped object (its base, and so its result, is a blob). A REF_DELTA is
966// kept; one whose base was dropped stays unresolved (wideObject).
967function wideKeep(want: Wide, dropped: Dropped): (h: ScannedHeader) => boolean {
968 const dropBlobs = want.expectType === TYPE.COMMIT || want.expectType === TYPE.TREE;
969 return (h: ScannedHeader): boolean => {
970 // a header typed blob is a full object (a delta's type is OFS_DELTA or REF_DELTA); only an OFS base has an offset
971 // Stryker disable next-line ConditionalExpression,LogicalOperator: a base that is not OFS has no offset, which no dropped offset equals
972 const blob = h.type === TYPE.BLOB || (h.base.tag === 'ofs' && dropped.offsets.has(h.base.offset));
973 if (!dropBlobs || !blob) return true;
974 dropped.offsets.add(h.offset);
975 dropped.bytes += h.size;
976 return false;
977 };
979// The pack resolved: with nothing dropped, every base must be in the pack (resolvePack); with blobs dropped, what waits
980// on a base outside it is counted, not refused.
981function wideResolve(t: Transport, parsed: ParsedPack, dropped: Dropped): Result<{ readonly objects: Map<string, PackObject>; readonly unresolved: number }, PlyError> {
982 if (dropped.offsets.size === 0) {
983 // Stryker disable next-line ArrowFunction: null and a bare return both mean the base is not in the pack
984 const r = resolvePack(parsed, () => null, t.limits);
985 return r.ok ? ok({ objects: r.value.objects, unresolved: 0 }) : r;
986 }
987 // Stryker disable next-line ArrowFunction: null and a bare return both mean the base is not in the pack
988 const r = resolvePackCollect(parsed, () => null, t.limits);
989 return r.ok ? ok({ objects: r.value.objects, unresolved: r.value.unresolved.length }) : r;
991// The wanted object out of the wide pack, its extras checked (checkWide) and harvested. When blobs were dropped, a delta
992// the resolver cannot resolve waits on a dropped base (a REF_DELTA on a blob, or on a delta of one) and is counted with
993// them: this fetch asked for no thin pack, so a base outside the pack is a blob it left out.
994type WideRead = { readonly parsed: ParsedPack; readonly dropped: Dropped };
995function wideObject(t: Transport, { parsed, dropped }: WideRead, want: Wide, span: Span, bust: boolean): Result<FetchedObject, PlyError> {
996 const { oid, expectType } = want;
997 const maxObject = t.limits.maxObjectSize;
998 const resolved = wideResolve(t, parsed, dropped);
999 if (!resolved.ok) return resolved;
1000 const { objects, unresolved } = resolved.value;
1001 const checked = checkWide(objects, k => k === oid, t.limits);
1002 if (!checked.ok) return checked;
1003 const skipped = checked.value;
1004 const found = mapGet(objects, oid);
1005 const left = dropped.offsets.size + unresolved;
1006 if (found.tag === 'none') return fail('pack_corrupt', `object ${oid} not in the ${packName(want.filter)} pack (${objects.size + left} objects)`);
1007 const wanted = found.value;
1008 if (wanted.data.length > maxObject) return err(limitExceeded('object size', wanted.data.length, maxObject));
1009 const refused = refuseNonCommit(expectType, wanted.type, oid);
1010 if (!refused.ok) return refused;
1011 if (expectType !== null && wanted.type !== expectType) return fail('pack_corrupt', `expected ${typeText(expectType)}, got ${typeText(wanted.type)}`);
1012 let blobs = left, extraBytes = skipped.reduce((n, x) => n + x.bytes, dropped.bytes); for (const [k, o] of objects) { if (k !== oid) extraBytes += o.data.length; if (o.type === TYPE.BLOB) blobs++; }
1013 const harvested = harvest(t, objects, oid);
1014 if (!harvested.ok) return harvested;
1015 const h = harvested.value;
1016 const all = objects.size + skipped.length + left;
1017 span.set({ 'git.pack.objects': parsed.stats.count, 'git.pack.bytes': parsed.bytes, 'git.object.oid': oid, 'git.object.type': typeText(wanted.type), 'git.fetch.wide.objects': all, 'git.fetch.wide.extra_objects': all - 1, 'git.fetch.wide.extra_bytes': extraBytes, 'git.fetch.wide.blobs': blobs, 'git.fetch.wide.harvested': h.kept, 'git.fetch.wide.harvested_bytes': h.bytes, ...skippedAttrs(skipped) });
1018 return ok({ type: wanted.type, data: wanted.data, oid, size: wanted.data.length, bust, tree: none, wide: true });
1020// The wide pack read and its wanted object taken (wideObject), under one fetch span carrying `attrs`.
1021// oxlint-disable-next-line typescript/promise-function-async -- onceMore's promise, passed through
1022function wideFetch(t: Transport, want: Wide, attrs: Attrs): Promise<Result<FetchedObject, PlyError>> {
1023 const { oid, deepen, filter } = want;
1024 // oxlint-disable-next-line typescript/promise-function-async -- the exchange's promise, passed through
1025 const once = (bust: boolean): Promise<Result<FetchedObject, PlyError>> => fetchExchange(t, { 'git.pack.cache.bust': bust, ...attrs }, async (span: Span): Promise<Result<FetchedObject, PlyError>> => {
1026 const caps = packCaps({ limits: t.limits });
1027 if (!caps.ok) return caps;
1028 // the pack is read through the scan as it arrives: its bytes and every zlib member are dropped once inflated, and
1029 // what is held is the objects wideKeep keeps (#172)
1030 const dropped: Dropped = { offsets: new Set(), bytes: 0 };
1031 const c = packCollectOpen(caps.value, true, wideKeep(want, dropped));
1032 // the caps passed packCaps, so the scan opens (packScanOpen)
1033 // Stryker disable next-line ConditionalExpression,BlockStatement: see above
1034 if (!c.ok) return c;
1035 const read = await collectWire(packStream(t, { wants: [oid], filter, deepen, bypassCache: bust }, span), c.value);
1036 if (!read.pack.ok) return read.pack;
1037 return wideObject(t, { parsed: read.pack.value, dropped }, want, span, bust);
1038 });
1039 return onceMore(once);
1041// The fallback (fetchObject): what was asked (tree:0, or the filter the caller gave), what was sent, and whether this
1042// request is the one that learned the refusal.
1043type Fallback = { readonly oid: Oid; readonly deepen: number; readonly expectType: number | null; readonly learned: boolean; readonly filter: WideFilter; readonly requested: string };
1044// oxlint-disable-next-line typescript/promise-function-async -- wideFetch's promise, passed through
1045const fetchWide = (t: Transport, { learned, requested, ...want }: Fallback): Promise<Result<FetchedObject, PlyError>> =>
1046 wideFetch(t, want, { 'git.fetch.filter.fallback': fallbackName(want.filter), 'git.fetch.filter.requested': requested, 'git.fetch.filter.learned': learned });
1047// A commit and the trees `filter` brings with it (deepen 1), read as a wide pack is: every object keyed by its computed
1048// hash, each commit and tree held to the caller's limits (checkWide, the commit the wanted object: an extra over a limit
1049// is dropped, a malformed one fails the fetch), the trees harvested into the transport's store for the walk's tree:0
1050// reads (objectAt answers them locally). A path walk's first levels in one round trip (pathtrees.ts, #218).
1051// oxlint-disable-next-line typescript/promise-function-async -- wideFetch's promise, passed through
1052export const commitWithTrees = (t: Transport, oid: Oid, filter: string): Promise<Result<FetchedObject, PlyError>> =>
1053 wideFetch(t, { oid, deepen: 1, expectType: TYPE.COMMIT, filter }, { 'git.fetch.path_trees': filter });
1055// The caller's oid, parsed once: a JS caller may pass anything, so it is read as String() renders it (a missing one
1056// renders as no id) and quoted the same way. Not 40 lowercase hex is `fetchObject: oid must be 40-hex` (bad_request, no
1057// `what`, as always).
1058export function objectId(oid: unknown): Result<Oid, BadRequest> {
1059 const text = String(oid);
1060 const id = parseOid(text);
1061 return id.ok ? id : fail('bad_request', `fetchObject: oid must be 40-hex, got ${JSON.stringify(text.slice(0, OID_PREVIEW))}`);
1063// fetchObject of a parsed id: ply's own callers, which hold an Oid, start here.
1064// oxlint-disable-next-line typescript/promise-function-async -- probing's promise (or the harvest's answer), passed through
1065export function objectAt(t: Transport, oid: Oid, options: Input<ObjectWantConfig> = {}): Promise<Result<FetchedObject, PlyError>> {
1066 const { filter, deepen: asked, expectType } = withDefaults(options, objectWantDefaults());
1067 // The depth to send (ObjectWantConfig): the caller's, else 1 when the want may be a commit and the server is not known
1068 // to lack `shallow`. Read at each send: the advertisement may be read between two of them.
1069 const mayBeCommit = expectType !== TYPE.TREE && expectType !== TYPE.BLOB;
1070 const depth = (): number => {
1071 if (asked !== null) return asked;
1072 return mayBeCommit && takesShallow(t.quirks) ? 1 : 0;
1073 };
1074 // run(depth). When it fails carrying a depth this call added, an empty response, an ERR line or HTTP 400 (the shapes a
1075 // server refuses an argument in) sends ply to the advertisement (as for a refused filter: filterUnadvertised learns
1076 // `shallow` from the same line), and a server that lists no `shallow` is asked once more with no `deepen`, as before
1077 // the default: the answer is then the history, held to the pack limits. `shallow` listed: the first error stands.
1078 const ask = async (run: (deepen: number) => Promise<Result<FetchedObject, PlyError>>): Promise<Result<FetchedObject, PlyError>> => {
1079 const sent = depth();
1080 const first = await run(sent);
1081 // once per quirks record: an advertisement already read for it has said whether `shallow` is listed
1082 if (first.ok || asked !== null || sent === 0 || shallowLearned(t.quirks)) return first;
1083 await filterUnadvertised(t, first.error, e => isEmptyResponse(e) || isArgumentRefusal(e));
1084 return depth() === sent ? first : run(depth());
1085 };
1086 // a depth this call added: the caller gave none and one was sent
1087 const added = (sent: number): boolean => asked === null && sent !== 0;
1088 const narrow = filter === 'tree:0';
1089 const held = narrow ? mapGet(t.objects, oid) : none;
1090 if (held.tag === 'some' && (expectType === null || held.value.type === expectType)) return Promise.resolve(ok({ type: held.value.type, data: held.value.data, oid, size: held.value.data.length, bust: false, tree: none, harvested: true }));
1091 // oxlint-disable-next-line typescript/promise-function-async -- ask's promise, passed through
1092 const wide = (sent: WideFilter, learned: boolean): Promise<Result<FetchedObject, PlyError>> => ask(deepen => fetchWide(t, { oid, deepen, expectType, learned, filter: sent, requested: filter }));
1093 // oxlint-disable-next-line typescript/promise-function-async -- fetchSingle's promise, passed through
1094 if (filter === '') return ask(deepen => fetchSingle(t, { oid, filter, deepen, expectType }));
1095 // one probe at a time per quirks record (transport.ts probing): the checks below read it after any wait
1096 return probing(t.quirks, narrow ? 'tree:0' : 'filter', async (): Promise<Result<FetchedObject, PlyError>> => {
1097 const harvested = narrow ? mapGet(t.objects, oid) : none;
1098 if (harvested.tag === 'some' && (expectType === null || harvested.value.type === expectType)) return ok({ type: harvested.value.type, data: harvested.value.data, oid, size: harvested.value.data.length, bust: false, tree: none, harvested: true });
1099 if (t.quirks.treeFilter === 'none') return wide('', false);
1100 if (narrow && t.quirks.treeFilter === 'blob:none') return wide('blob:none', false);
1101 const sent = depth();
1102 const single = await fetchSingle(t, { oid, filter, deepen: sent, expectType });
1103 if (single.ok) return single;
1104 if (narrow && isFilterRejection(single.error)) {
1105 t.quirks.treeFilter = 'blob:none';
1106 return wide('blob:none', true);
1108 if (await filterUnadvertised(t, single.error)) return wide('', true);
1109 // an ERR line or HTTP 400 that answered a depth this call added: the advertisement is read for `shallow` (see `ask`;
1110 // not read above, where an unlisted `filter` would change the request main sends)
1111 const unlisted = added(sent) && !shallowLearned(t.quirks) && (await filterUnadvertised(t, single.error, isArgumentRefusal));
1112 // the advertisement was just read: a depth this call added that the server does not take is dropped (see `ask`).
1113 // The request without it is main's, and its answer is handled as main handles it: no `filter` listed is the
1114 // unfiltered pack, a refused tree:0 is blob:none, an empty response is the advertisement's to explain.
1115 if (depth() === sent) return single;
1116 if (unlisted) return wide('', true);
1117 const again = await fetchSingle(t, { oid, filter, deepen: depth(), expectType });
1118 if (again.ok) return again;
1119 if (narrow && isFilterRejection(again.error)) {
1120 t.quirks.treeFilter = 'blob:none';
1121 return wide('blob:none', true);
1123 return (await filterUnadvertised(t, again.error)) ? wide('', true) : again;
1124 });
1126// One object by oid: a bad oid, a fetch failure, a verification failure are the Err.
1127// oxlint-disable-next-line typescript/promise-function-async -- objectAt's promise, passed through
1128export function fetchObject(t: Transport, want: ObjectWant): Promise<Result<FetchedObject, PlyError>> {
1129 const id = objectId(want.oid);
1130 return id.ok ? objectAt(t, id.value, want) : Promise.resolve(id);
Diagnostics6 git calls · 104 ms
CallStatusSizeTime0104 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=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 · 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 · 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=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=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=5323b9266eea5ded637285d1c5320699f12be76e
Open 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=94
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=723b6bf1d4d6021fe5eb940c622b9ff00ee4a381
Open pack map
fetch20023 KiB95 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=23709
git.response.cache=MISS
git.response.duration_ms=95
git.fetch.wants=dcc66552ee4477c6bfb14db91f8f817998e52df3
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=6
git.pkt.data=5
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=23709
git.pkt.payload.max=15461
git.sideband.band1.bytes=23672
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
a5e0f844e875332c
Request
d073f567…
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