Artifactspublic-v0

ply

main
ply4 git calls341 ms45 KiB2 cachedprotocol v2
267 lines19 KiBRaw
1// v2 ls-refs: the ref namespace, filtered by prefix. The one request that cannot be cached (it is the freshness source).
2// The listing is read by a step function over frames (lsRefsStep, Result); lsRefs is the exchange, also a Result.
3/* oxlint-disable require-unicode-regexp -- ASCII wire text; `u` costs a byte per literal */
4import type { ErrorOf, PlyError } from './errors.js';
5import type { Span } from './otel.js';
6import type { Frame, Scrub, Transport } from './transport.js';
7import type { Input } from './absent.js';
8import type { Option, Result } from './result.js';
9import { fail, remoteQuoted, remoteText, REMOTE_TEXT_MAX } from './errors.js';
10import { pkts, pktInit, pktStep } from './pktline.js';
11import { decodeBytes } from './bytes.js';
12import { limitExceeded } from './limits.js';
13import { validateWire, type WireField } from './validate.js';
14import { advertise, frames, coded, clientSpan, proto, spanned } from './transport.js';
15import { SHA256_HEX_CHARS, PROTOCOL_V2 } from './format.js';
16import { assertNever, err, ok } from './result.js';
17// oxlint-disable-next-line import/max-dependencies -- the exchange joins the frame reader, the limits and the caller's options
18import { fromNullable, readKey, withDefaults } from './absent.js';
19// oxlint-disable-next-line import/max-dependencies -- and, for an empty answer, the advertisement's reader
20import { parseCapabilitiesV2 } from './caps.js';
21// oxlint-disable-next-line import/max-dependencies -- and the id parser every listed oid goes through
22import { parseOid, type Oid } from './oid.js';
24/* oxlint-disable no-magic-numbers -- error previews and the span's ref sample are diagnostics, not wire-format facts */
25const LINE_PREVIEW = 60;
26const SPAN_REFS = 64;
27/* oxlint-enable no-magic-numbers */
28const ERR = 'ERR ';
29const PEELED = 'peeled', SYMREF_TARGET = 'symref-target';
31// connect.c process_ref_v2 reads an oid with parse_oid_hex_algop, which takes either case (hexval); the oid is kept
32// lowercase, as git stores it in binary and writes it back lowercase. Lowercased, it is parsed (parseOid): only
33// A-F lowercase to hex digits, so the parse accepts exactly the 40 hex digits of either case. An oid upload-pack wrote
34// is lowercase already and parses as it is: no lowercased copy per listed oid (#209).
35function sha1Of(text: string): Result<Oid, ErrorOf<'bad_request'>> {
36 const exact = parseOid(text);
37 // Stryker disable next-line ConditionalExpression: the fast path; a lowercase oid lowercases to itself, so parsing the lowercased copy gives the same result
38 return exact.ok ? exact : parseOid(text.toLowerCase());
40const OID_SHA256 = new RegExp(`^[0-9a-fA-F]{${SHA256_HEX_CHARS}}$`);
41const UNBORN = 'unborn';
43// One ls-refs line, as connect.c process_ref_v2 reads it: split on every space, so a doubled space is an empty field.
44// Returns { oid, name, peeled, symref-target } (null where the line has no such attribute), or null for an `unborn <name> …` line (it is no ref: parseUnbornLine
45// reads it).
46// A listed name: the second field of an ls-refs line, read once by parseLsRefLine (and nothing else grants the brand).
47// What upload-pack writes there is `HEAD` or a name under `refs/` (ls-refs.c: send_possibly_unborn_head, then
48// for_each_namespaced_ref over refs/, each passing check_refname_format in the ref store). Any other field comes only
49// from a server that does not write ls-refs.c's lines: "" from `<oid> ` or a doubled space, `capabilities^{}` (a v0
50// placeholder). git's client (connect.c process_ref_v2) lists each of those as a ref by that name, and so does ply
51// (test/space/advertisement.space.js: emptyName, doubleSpace, capsName). The field is the text between the first space
52// and the next, so it holds no space; it is not a Refname (HEAD is not one, and git's ref store admits names validateRef
53// refuses, such as one past 1024 bytes). A lookup by a caller's name compares it as the string it is.
54declare const listedBrand: unique symbol;
55export type ListedName = string & { readonly [listedBrand]: typeof listedBrand };
56// The brand's check: a field holds no space.
57const isListedName = (field: string): field is ListedName => !field.includes(' ');
58// The name field, which holds no space (it ends at the first space past the oid).
59function listedName(field: string): ListedName {
60 // Stryker disable next-line ConditionalExpression,StringLiteral: the field ends before the first space past the oid, so it holds none; the fallback only gives the guard its other branch
61 return isListedName(field) ? field : listedName('');
63// The end of the field that starts at `from`: the next space, or the end of the line.
64function fieldEnd(line: string, from: number): number {
65 const next = line.indexOf(' ', from);
66 // Stryker disable next-line EqualityOperator: every field starts past the first space, so the next space is never at 0
67 return next < 0 ? line.length : next;
69// One listed ref. Only `peeled` and `symref-target` are kept from the attributes, and only when the line carries them
70// (a key that is present or not: the readers in changes, merge and read test for it).
71export type LsRef = { readonly oid: Oid; readonly name: ListedName; readonly peeled: Oid | null; readonly 'symref-target': string | null };
72// An unborn HEAD: a symref to a branch that has no commit yet (an empty `git init --bare -b main` is
73// `{ name: 'HEAD', target: 'refs/heads/main' }`). Only HEAD is ever reported, as git's client records only HEAD.
74export type LsRefsUnborn = { readonly name: 'HEAD'; readonly target: string };
75// head: the symref target of a born HEAD (null when HEAD is detached, unborn or not listed).
76// unborn: the unborn HEAD, when the server listed one (it does only when the request says `unborn`); null otherwise.
77export type LsRefsResult = { readonly refs: Map<string, LsRef>; readonly head: string | null; readonly unborn: LsRefsUnborn | null };
79const PEELED_KEY = `${PEELED}:`, SYMREF_KEY = `${SYMREF_TARGET}:`;
80// The line is read by index, in place: one slice for the oid, one for the name, one per kept attribute's value, and
81// nothing for the attributes it skips (#209: a large listing paid a split array, and a key and a value per attribute).
82// scrub: the transport's credential scrubber (or null), applied to an ERR line's text before it is cut (errors.ts remoteText).
83// @decoder parseLsRefLine prefix=ls-ref
84export function parseLsRefLine(line: string, scrub: Scrub | null = null): Result<LsRef | null, PlyError> {
85 if (line.startsWith(ERR)) return fail('remote_error', `remote: ${remoteText(line.slice(ERR.length), REMOTE_TEXT_MAX, scrub)}`);
86 const sp = line.indexOf(' ');
87 // Stryker disable next-line EqualityOperator: a leading space still fails the oid check with this same malformed-line error
88 if (sp < 0) return proto(`ls-refs: malformed line ${remoteQuoted(line, LINE_PREVIEW)}`);
89 const oid = line.slice(0, sp);
90 if (oid === UNBORN) return ok(null);
91 // 40 hex digits is a sha1 oid; 64 is a sha256 repository's, refused as such; anything else is malformed.
92 const parsed = sha1Of(oid);
93 if (!parsed.ok) return OID_SHA256.test(oid) ? fail('unsupported', 'unsupported object-format: only sha1 repositories are supported') : proto(`ls-refs: malformed line ${remoteQuoted(line, LINE_PREVIEW)}`);
94 // git takes the second field as the name even when it is empty (`<oid> ` lists a ref named "")
95 const nameEnd = fieldEnd(line, sp + 1);
96 // Only `symref-target:` and `peeled:` are kept, as connect.c process_ref_v2 reads them and skips everything else, so a
97 // server attribute can never stand in for the parsed oid or name. A bad peeled oid is malformed (git: invalid ls-refs response).
98 const rec: { -readonly [K in keyof LsRef]: LsRef[K] } = { oid: parsed.value, name: listedName(line.slice(sp + 1, nameEnd)), [PEELED]: null, [SYMREF_TARGET]: null };
99 // Each attribute is a field after the name. A key is the text before its first colon, so a field starts with
100 // `peeled:` exactly when its key is `peeled` (neither key holds a space or a colon). An empty field (a doubled space)
101 // and a field with no colon match neither key.
102 for (let end = nameEnd; end < line.length;) {
103 const from = end + 1;
104 end = fieldEnd(line, from);
105 if (line.startsWith(PEELED_KEY, from)) {
106 const peeled = sha1Of(line.slice(from + PEELED_KEY.length, end));
107 if (!peeled.ok) return proto(`ls-refs: malformed line ${remoteQuoted(line, LINE_PREVIEW)}`);
108 rec[PEELED] = peeled.value;
109 } else if (line.startsWith(SYMREF_KEY, from)) rec[SYMREF_TARGET] = line.slice(from + SYMREF_KEY.length, end);
110 }
111 return ok(rec);
114// An `unborn <name> …` line (the first field is `unborn`), as connect.c process_ref_v2 reads it: only a line naming HEAD
115// counts, and its first `symref-target:` attribute is the target git records, replacing any earlier one (the last wins).
116// Any other name, or a HEAD line with no target, records nothing: `prev` stands. An empty target is recorded as no
117// unborn HEAD (null): git's clone takes one only when its target is a refs/heads/ name.
118// @decoder parseUnbornLine prefix=ls-unborn
119export function parseUnbornLine(line: string, prev: LsRefsUnborn | null = null): LsRefsUnborn | null {
120 const [first, name, ...attrs] = line.split(' ');
121 if (first !== UNBORN || name !== 'HEAD') return prev;
122 const attr = fromNullable(attrs.find(a => a.startsWith(`${SYMREF_TARGET}:`)));
123 if (attr.tag === 'none') return prev;
124 const target = attr.value.slice(SYMREF_TARGET.length + 1);
125 return target === '' ? null : { name, target };
127export type UnbornReader = typeof parseUnbornLine;
129// The request, in git's order (connect.c get_remote_refs): peel, symrefs, unborn, then the prefixes. `unborn` is sent
130// only to a server whose advertisement lists `ls-refs=unborn` (git: server_supports_feature("ls-refs", "unborn")).
131export type LsRefsBodyConfig = { readonly peel: boolean; readonly symrefs: boolean; readonly unborn: boolean };
132export type LsRefsBodyOptions = Input<LsRefsBodyConfig>;
133// The caller's prefixes, each parsed once into one wire field (`invalid ref prefix: …`, bad_request), or the first
134// that is not one.
135export function refPrefixes(prefixes: readonly string[]): Result<WireField[], ErrorOf<'bad_request'>> {
136 const checked: WireField[] = [];
137 for (const p of prefixes) {
138 const valid = validateWire(p, 'ref prefix');
139 if (!valid.ok) return valid;
140 checked.push(valid.value);
141 }
142 return ok(checked);
144// The command=ls-refs body of parsed prefixes: nothing left to check but the pkt-line length.
145export const lsRefsRequestBody = (prefixes: readonly WireField[], options: LsRefsBodyOptions = {}): Result<Uint8Array<ArrayBuffer>, PlyError> => {
146 const { peel, symrefs, unborn } = withDefaults(options, { peel: true, symrefs: true, unborn: false });
147 return pkts(['command=ls-refs\n', ...[peel && 'peel\n', symrefs && 'symrefs\n', unborn && 'unborn\n'].filter((x): x is string => typeof x === 'string'), ...prefixes.map(p => `ref-prefix ${p}\n`)], { delimAfter: 0 });
148};
149// The caller's prefixes as a command=ls-refs body: parsed once (refPrefixes, as lsRefs parses them), then encoded.
150export function lsRefsBody(prefixes: readonly string[] = [], options: LsRefsBodyOptions = {}): Result<Uint8Array<ArrayBuffer>, PlyError> {
151 const checked = refPrefixes(prefixes);
152 return checked.ok ? lsRefsRequestBody(checked.value, options) : checked;
155// The listing as it is read: `open` until the flush that ends it, then `ended` (any frame after that is refused).
156// It is one object, updated in place, and each step returns it (#209: a copy per line was an allocation per listed
157// ref; `refs` always grew in place, as a copy of the map per line would be quadratic in the ref count). `counted` is the
158// names other than HEAD (HEAD is listed beside the refs, as git ls-remote shows it, and does not consume maxRefs: a
159// repository of exactly maxRefs branches also has a HEAD line; refs/heads/HEAD is a branch and counts).
160export type LsListing = {
161 tag: 'open' | 'ended';
162 readonly refs: Map<string, LsRef>;
163 counted: number;
164 bytes: number;
165 head: string | null;
166 unborn: LsRefsUnborn | null;
167};
168export type LsCaps = { readonly maxBytes: number; readonly maxRefs: number; readonly unborn: Option<UnbornReader | null> };
169export const lsInit = (): LsListing => ({ tag: 'open', refs: new Map(), counted: 0, bytes: 0, head: null, unborn: null });
170// One frame of the listing. gitprotocol-v2 ls-refs: output = *ref flush-pkt. A refusal leaves the listing as it was
171// before the frame (every check comes before the first update) and the caller stops reading: the ref limit refuses the
172// first ref past maxRefs as it arrives, and the byte limit the frame that crosses it, before that frame is decoded.
173export function lsRefsStep(st: LsListing, f: Frame, caps: LsCaps, scrub: Scrub | null = null): Result<LsListing, PlyError> {
174 switch (st.tag) {
175 case 'ended': return proto(`ls-refs: ${f.kind} after the terminating flush-pkt`);
176 case 'open': {
177 if (f.kind === 'flush') { st.tag = 'ended'; return ok(st); }
178 if (f.kind !== 'data') return proto(`ls-refs: unexpected ${f.kind} in ref listing`);
179 const bytes = st.bytes + f.payload.length;
180 if (bytes > caps.maxBytes) return err(limitExceeded('ls-refs bytes', bytes, caps.maxBytes));
181 // A ref name is bytes (check-ref-format allows any byte >= 0x80): decodeBytes keeps them distinct and writable back,
182 // and only the LF comes off, as connect.c's packet reader chomps it. trim() also ate a trailing U+FEFF or U+00A0 (#43).
183 const text = decodeBytes(f.payload);
184 const line = text.endsWith('\n') ? text.slice(0, text.length - 1) : text;
185 const parsed = parseLsRefLine(line, scrub);
186 if (!parsed.ok) return parsed;
187 const rec = parsed.value;
188 if (rec === null) {
189 // A reader the caller passed as null reads nothing (strict-boolean-expressions: the null is the test).
190 // Stryker disable next-line ConditionalExpression: the tag test only narrows the type; a none's value is absent, which the second test reads as no reader
191 if (caps.unborn.tag === 'some' && caps.unborn.value) st.unborn = caps.unborn.value(line, st.unborn); // oxlint-disable-line typescript/strict-boolean-expressions -- see above
192 st.bytes = bytes;
193 return ok(st);
194 }
195 // A name listed twice: git keeps both in its ref list and every lookup (find_ref_by_name) takes the first.
196 if (st.refs.has(rec.name)) { st.bytes = bytes; return ok(st); }
197 const isHead = rec.name === 'HEAD';
198 if (!isHead && st.counted >= caps.maxRefs) return err(limitExceeded('ls-refs lines', st.counted + 1, caps.maxRefs));
199 st.refs.set(rec.name, rec);
200 st.bytes = bytes;
201 if (!isHead) st.counted += 1;
202 // oxlint-disable-next-line typescript/strict-boolean-expressions -- an empty symref-target names no HEAD, as before
203 else if (rec['symref-target']) st.head = rec['symref-target'];
204 return ok(st);
205 }
206 }
207 // Stryker disable next-line ConditionalExpression: unreachable, the compiler's exhaustiveness check
208 return assertNever(st.tag);
210// git dies "expected flush after ref listing" (connect.c) when the flush is missing; a truncated listing must never
211// read as "these are all the refs" (found by the calibration harness).
212export function lsRefsEnd(st: LsListing): Result<LsRefsResult, PlyError> {
213 switch (st.tag) {
214 case 'open': return proto('ls-refs: response ended without the terminating flush-pkt');
215 case 'ended': return ok({ refs: st.refs, head: st.head, unborn: st.unborn });
216 }
217 // Stryker disable next-line ConditionalExpression: unreachable, the compiler's exhaustiveness check
218 return assertNever(st.tag);
221// An ls-refs answer with no frame at all, not even its flush, is what a v0/v1 upload-pack sends a v2 request: it reads
222// `command=ls-refs` as a want line and dies having written nothing. The advertisement (GET info/refs, asked for v2) then
223// says which: a first line other than `version 2` is a server that does not speak protocol v2, refused as discover
224// refuses it (`unsupported`; ply speaks only v2, and asking again cannot help). An advertisement that is v2, or that
225// cannot be read, leaves the empty answer the protocol error it is.
226async function v2Refusal(t: Transport, span: Span, empty: PlyError): Promise<PlyError> {
227 let buf: Result<Uint8Array, PlyError>;
228 // a transport that cannot advertise (an untyped caller's) leaves the empty answer as it is
229 try { buf = await advertise(t, 'git-upload-pack', span); } catch { return empty; }
230 if (!buf.ok) return empty;
231 const framed = pktStep(pktInit(), buf.value);
232 if (!framed.ok) return empty;
233 const caps = parseCapabilitiesV2(framed.value.frames);
234 if (caps.ok || caps.error.code !== 'unsupported') return empty;
235 const refused = fail('unsupported', `ls-refs: the server does not speak protocol v2, which ply requires (an empty answer to command=ls-refs; advertisement: ${caps.error.message})`, { what: 'protocol version' });
236 return refused.error;
239// The ls-refs exchange. `unborn` asks for the unborn HEAD and reads each unborn line (parseUnbornLine): the caller has
240// checked the server advertises it (the public lsRefs in client.ts does, from the advertisement). Passed in, not
241// imported, so a bundle that never asks (edit, read) carries no unborn reader. Without it an unborn line is skipped.
242// oxlint-disable-next-line require-await -- async: a synchronous failure (an unusable transport) is a rejection, as it always was
243export async function lsRefs(t: Transport, prefixes: readonly string[] = [], options: Input<{ readonly unborn: UnbornReader }> = {}): Promise<Result<LsRefsResult, PlyError>> {
244 // each prefix parsed once; the request writes the parsed ones
245 const checked = refPrefixes(prefixes);
246 if (!checked.ok) return checked;
247 // a reader given as null still asks, and reads nothing (as before)
248 const caps: LsCaps = { maxBytes: t.limits.maxLsRefsBytes, maxRefs: t.limits.maxRefs, unborn: readKey(options, 'unborn') };
249 // oxlint-disable-next-line typescript/promise-function-async -- the exchange's promise, passed through (an async wrapper adds bytes, not behaviour)
250 return coded('protocol', () => spanned(t, 'git.upload-pack ls-refs', clientSpan(t, { 'git.command': 'ls-refs', 'git.protocol.version': PROTOCOL_V2, 'git.ls_refs.prefixes': prefixes }), async (span: Span): Promise<Result<LsRefsResult, PlyError>> => {
251 const body = lsRefsRequestBody(checked.value, { unborn: caps.unborn.tag === 'some' });
252 if (!body.ok) return body;
253 let st = lsInit();
254 let seen = 0;
255 for await (const f of frames(t, 'git-upload-pack', body.value, span)) {
256 seen += 1;
257 const next = lsRefsStep(st, f, caps, t.scrub);
258 if (!next.ok) return next;
259 st = next.value;
260 }
261 const listed = lsRefsEnd(st);
262 if (!listed.ok) return seen === 0 ? err(await v2Refusal(t, span, listed.error)) : listed;
263 const { refs, head } = listed.value;
264 span.set({ 'git.ls_refs.count': refs.size, 'git.ls_refs.refs': [...refs.values()].slice(0, SPAN_REFS).map(r => `${r.oid} ${r.name}`), 'git.ls_refs.head': head === null ? '' : head });
265 return listed;
266 }));
Diagnostics4 git calls · 341 ms
CallStatusSizeTime0341 ms
discover200152 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=152
git.server.agent=gitty/1.0
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch object-format
git.server.fetch=shallow filter sideband-all
git.protocol.version=2
git.pkt.frames=8
git.pkt.data=6
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=152
git.pkt.payload.max=34
ls-refs200145 B · hit3 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=145
git.response.cache=HIT
git.response.duration_ms=3
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=145
git.pkt.payload.max=76
git.ls_refs.count=2
git.ls_refs.head=refs/heads/main
fetchblob:none · deepen 1020038 KiB · hit2 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=336
git.response.bytes=38434
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=blob:none
git.fetch.filter.requested=tree:0
git.fetch.filter.fallback=blob:none
git.fetch.filter.learned=false
git.fetch.wants=19912563f540228593df0c489082e5e2508e21e4
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=6
git.pkt.data=4
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=38434
git.pkt.payload.max=38339
git.sideband.band1.bytes=38338
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=63
git.pack.bytes=38338
git.pack.ofs_delta=0
git.pack.ref_delta=8
git.pack.chain.max=8
git.pack.trailer=0bc36ab7adf82d3109177f11f1ea93f1ce071f77
git.pack.full=55
Open pack map
fetch2006.8 KiB336 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=6991
git.response.cache=MISS
git.response.duration_ms=336
git.fetch.wants=1c417f37ace034ae768ea131611d39cae753e6f5
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=6991
git.pkt.payload.max=6970
git.sideband.band1.bytes=6969
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/ply.git
Ref
refs/heads/main
Commit
19912563f540228593df0c489082e5e2508e21e4
cf-ray
a5e2d4e63ee5689d
Request
c4deb795…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format