Artifactspublic-v0

ply

main
ply4 git calls26 ms42 KiB3 cachedprotocol v2
202 lines12 KiBRaw
1// v0 receive-pack capability advertisement (GET info/refs). Only needed to check optional capabilities (atomic,
2// push-options) before relying on them; the v2 fetch path never needs it. Parsing the advertisement and checking a
3// push against it are pure; receiveCaps is the one effect.
4import { fail, remoteQuoted, argsError } from './errors.js';
5import type { ErrorOf, PlyError } from './errors.js';
6import { ok, assertNever, getOrElse, mapOption } from './result.js';
7import { decideObjectFormat } from './closed.js';
8import type { Option, Result } from './result.js';
9import { td } from './bytes.js';
10import { pktInit, pktStep, pktFinish } from './pktline.js';
11import { coded, clientSpan, advertise, spanned } from './transport.js';
12import { planPackPush, push, pushPackChecked } from './push.js';
13import type { CheckedCaps, PackPushOptions, PackPushOutcome, PushOptions, PushResult, PushTransport } from './push.js';
14import type { Input } from './absent.js';
15// oxlint-disable-next-line import/max-dependencies -- the advertisement reader joins the frame reader, the v2 parser and push
16import { at, fromNullable, fromNullish, mapGet, withDefaults } from './absent.js';
18// A pkt-line frame as pktStep returns it (payload only on a data frame).
19import type { Frame } from './transport.js';
20import type { Span } from './otel.js';
22type Protocol = ErrorOf<'protocol'>;
23// What reading an advertisement can fail with: the v0 shape is protocol; a v2 answer has no push capabilities to read.
24export type AdvertError = ErrorOf<'protocol' | 'unsupported'>;
25type DataFrame = Extract<Frame, { readonly kind: 'data' }>;
26const frameAt = (frames: readonly Frame[], i: number): Option<Frame> => at(frames, i);
27// The data frame at `i`, if the frame there is one.
28const dataAt = (frames: readonly Frame[], i: number): DataFrame | null => { const f = frameAt(frames, i); return f.tag === 'some' && f.value.kind === 'data' ? f.value : null; };
30// The index of the first frame after a smart-http "# service=<name>" header and its flush, 0 when there is none
31// (remote-curl check_smart_http: the header's metadata lines run to the first flush).
32function serviceHeaderEnd(frames: readonly Frame[]): Result<number, Protocol> {
33 const first = dataAt(frames, 0);
34 if (first === null || !td.decode(first.payload).startsWith('# service=')) return ok(0);
35 const flush = frames.findIndex(f => f.kind !== 'data');
36 const end = frameAt(frames, flush);
37 if (flush < 0 || end.tag === 'none' || end.value.kind !== 'flush') return fail('protocol', 'advertisement: no flush after the service header');
38 return ok(flush + 1);
41// connect.c process_ref/process_shallow parse each oid with the hash the first line's object-format names (sha1 when
42// absent), so a sha256 advertisement is read whole and checkPushCaps names the need, as send-pack does.
43const SHA1_HEX = 40;
44const OID_HEX: ReadonlyMap<string, number> = new Map([['sha1', SHA1_HEX], ['sha256', 64]]);
45const refLine = (n: number): RegExp => new RegExp(`^[0-9a-f]{${n}} [^ ]`, 'u');
46const shallowLine = (n: number): RegExp => new RegExp(`^shallow [0-9a-f]{${n}}$`, 'u');
47const LINE_PREVIEW = 60;
48const FORMAT = 'object-format=';
49// The advertisement's object-format capability, if any.
50const objectFormat = (caps: ReadonlySet<string>): Option<string> => mapOption(fromNullable([...caps].find(c => c.startsWith(FORMAT))), c => c.slice(FORMAT.length));
52// The transport surface receiveCaps reads, beside push's.
53export type CapsTransport = PushTransport;
55// Pure: the advertisement's pkt frames → its capabilities.
56// connect.c get_remote_heads: ref lines up to the first flush, and nothing after it is read. The capabilities ride on
57// the first line (process_capabilities). A delim or response-end is "invalid packet"; the end of the response
58// before the flush (a cut advertisement) is "hung up"; a line that is neither "<oid> <ref>" nor "shallow <oid>" is
59// "protocol error: unexpected". Each used to be read as a complete advertisement.
60// @decoder parseReceiveAdvert prefix=advertisement
61export function parseReceiveAdvert(frames: readonly Frame[]): Result<Set<string>, AdvertError> {
62 const caps = new Set<string>();
63 const end = serviceHeaderEnd(frames);
64 if (!end.ok) return end;
65 const start = end.value;
66 // ply asks for the v0 advertisement here, as git does (http.ts sends no Git-Protocol header for receive-pack). A v2
67 // answer anyway is a different vocabulary, with no report-status or atomic: reading it as an empty set would be
68 // indistinguishable from a server with no capabilities, so it is refused by name.
69 const opening = dataAt(frames, start);
70 if (opening !== null && td.decode(opening.payload).replace(/\n$/u, '') === 'version 2') {
71 return fail('unsupported', 'receive-pack advertisement: the server answered in protocol v2, which has no push capabilities');
72 }
73 let hex = SHA1_HEX;
74 for (let k = start; ; k++) {
75 const next = frameAt(frames, k);
76 if (next.tag === 'none') return fail('protocol', 'receive-pack advertisement: no flush after the refs');
77 const f = next.value;
78 if (f.kind === 'flush') break;
79 if (f.kind !== 'data') return fail('protocol', `receive-pack advertisement: invalid packet (${f.kind})`);
80 const line = td.decode(f.payload).replace(/\n$/u, '');
81 const nul = line.indexOf('\0');
82 const head = nul < 0 ? line : line.slice(0, nul);
83 // Stryker disable next-line EqualityOperator: a first line starting with NUL has no ref, so it is refused below with or without its caps read
84 if (k === start && nul >= 0) {
85 for (const c of line.slice(nul + 1).trim().split(' ')) caps.add(c);
86 // Stryker disable next-line StringLiteral,LogicalOperator: no object-format is a key OID_HEX lacks, which keeps sha1's width either way
87 hex = getOrElse(mapGet(OID_HEX, getOrElse(objectFormat(caps), '')), hex);
88 }
89 if (!refLine(hex).test(head) && !shallowLine(hex).test(head)) return fail('protocol', `receive-pack advertisement: unexpected line ${remoteQuoted(head, LINE_PREVIEW)}`);
90 }
91 return ok(caps);
94// The exchange: the advertisement, read.
95// oxlint-disable-next-line require-await -- async: a synchronous failure (an unusable transport) is a rejection, as it always was
96export async function receiveCaps(t: CapsTransport): Promise<Result<Set<string>, PlyError>> {
97 // oxlint-disable-next-line typescript/promise-function-async -- the exchange's promise, passed through (an async wrapper adds bytes, not behaviour)
98 return coded('protocol', () => spanned(t, 'git.receive-pack advertise', clientSpan(t, { 'git.command': 'advertise', 'git.protocol.version': 0 }), async (span: Span): Promise<Result<Set<string>, PlyError>> => {
99 const buf = await advertise(t, 'git-receive-pack', span);
100 if (!buf.ok) return buf;
101 const stepped = pktStep(pktInit(), buf.value);
102 if (!stepped.ok) return stepped;
103 const { frames, state } = stepped.value;
104 const finished = pktFinish(state);
105 if (!finished.ok) return finished;
106 const caps = parseReceiveAdvert(frames);
107 if (caps.ok) span.set({ 'git.receive.caps': [...caps.value] });
108 return caps;
109 }));
112// What a push asks of the server that send-pack.c send_pack() checks against the advertisement before it sends a byte:
113// the repository's hash ("the receiving end does not support this repository's hash algorithm": ply is sha1-only, and an
114// advertisement without object-format is sha1), `atomic` ("does not support --atomic push") and `push-options` ("does
115// not support push options"). receive-pack ignores an `atomic` or `push-options` capability it did not advertise
116// (builtin/receive-pack.c), so an unchecked atomic push lands ref by ref, and unchecked option lines are read as the
117// pack ("unpacker error"): push takes them only as the CheckedCaps this makes.
118export type PushWantsConfig = { readonly atomic: boolean; readonly pushOptions: readonly string[] };
119export type PushWants = Input<PushWantsConfig>;
120const noWants = (): PushWantsConfig => ({ atomic: false, pushOptions: [] });
121export type CapsProblem =
122 | { readonly tag: 'ok' }
123 | { readonly tag: 'objectFormat'; readonly format: string }
124 | { readonly tag: 'noAtomic' }
125 | { readonly tag: 'noPushOptions' };
126// Pure: ok, or the first unmet need. There is no null.
127export function capsProblem(caps: ReadonlySet<string>, want: PushWants = {}): CapsProblem {
128 const { atomic, pushOptions } = withDefaults(want, noWants());
129 const decision = decideObjectFormat(getOrElse(objectFormat(caps), 'sha1'));
130 switch (decision.tag) {
131 case 'refused': return { tag: 'objectFormat', format: decision.format };
132 case 'ok': {
133 if (atomic && !caps.has('atomic')) return { tag: 'noAtomic' };
134 if (pushOptions.length > 0 && !caps.has('push-options')) return { tag: 'noPushOptions' };
135 return { tag: 'ok' };
136 }
137 }
138 // Stryker disable next-line ConditionalExpression: unreachable, the compiler's exhaustiveness check
139 return assertNever(decision);
141const problemText = (p: Exclude<CapsProblem, { readonly tag: 'ok' }>): string => {
142 switch (p.tag) {
143 case 'objectFormat': return `server repository is object-format ${p.format}`;
144 case 'noAtomic': return 'server does not advertise atomic';
145 case 'noPushOptions': return 'server does not advertise push-options';
146 }
147 // Stryker disable next-line ConditionalExpression: unreachable, the compiler's exhaustiveness check
148 return assertNever(p);
149};
150// Pure: the push's atomic and push options, checked against the advertisement.
151export function checkPushCaps(caps: ReadonlySet<string>, want: PushWants = {}): Result<CheckedCaps, ErrorOf<'unsupported'>> {
152 const problem = capsProblem(caps, want);
153 switch (problem.tag) {
154 case 'objectFormat':
155 case 'noAtomic':
156 case 'noPushOptions':
157 return fail('unsupported', problemText(problem), { caps: [...caps] });
158 case 'ok':
159 // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the one place a CheckedCaps is made: the brand is a type (push.ts)
160 return ok({ atomic: getOrElse(fromNullish(want.atomic), false), pushOptions: getOrElse(fromNullish(want.pushOptions), []) } as CheckedCaps);
161 }
162 // Stryker disable next-line ConditionalExpression: unreachable, the compiler's exhaustiveness check
163 return assertNever(problem);
166// push(), after reading the advertisement when the push needs a capability (atomic, push-options): one extra GET, only then.
167export type CheckedPushOptions = Omit<PushOptions, 'checked'> & PushWants;
168export async function pushWithOptions(t: CapsTransport, options: CheckedPushOptions): Promise<Result<PushResult, PlyError>> {
169 const { atomic: _atomic, pushOptions: _pushOptions, ...opts } = options;
170 const { atomic, pushOptions } = withDefaults(options, noWants());
171 if (!atomic && pushOptions.length === 0) return push(t, opts);
172 const caps = await receiveCaps(t);
173 if (!caps.ok) return caps;
174 const checked = checkPushCaps(caps.value, { atomic, pushOptions });
175 if (!checked.ok) return checked;
176 return push(t, { ...opts, checked: checked.value });
179// pushWithOptions for a pack the caller already has (push.ts PackPushOptions). A request that cannot be sent is refused
180// first: the advertisement GET and the pack are only touched for one that can.
181export type CheckedPackPushOptions = Omit<PackPushOptions, 'checked'> & PushWants;
182// pushPack with whether the push request was sent (push.ts PackPushOutcome): a refusal here or a failed advertisement
183// read is `sent: 'no'`, with nothing sent to receive-pack (the push cannot have landed), and so is push.ts's own
184// refusal or a request whose body was never pulled. transfer.ts reads this, never the error's code.
185export async function pushPackOutcome(t: CapsTransport, options: CheckedPackPushOptions): Promise<PackPushOutcome> {
186 const { atomic: _atomic, pushOptions: _pushOptions, ...opts } = options;
187 const { atomic, pushOptions } = withDefaults(options, noWants());
188 const planned = planPackPush(opts, t.limits);
189 if (!planned.ok) return { sent: 'no', result: planned };
190 if (!atomic && pushOptions.length === 0) return pushPackChecked(t, opts);
191 const caps = await receiveCaps(t);
192 if (!caps.ok) return { sent: 'no', result: caps };
193 const checked = checkPushCaps(caps.value, { atomic, pushOptions });
194 if (!checked.ok) return { sent: 'no', result: checked };
195 return pushPackChecked(t, { ...opts, checked: checked.value });
197export async function pushPack(t: CapsTransport, options: CheckedPackPushOptions): Promise<Result<PushResult, PlyError>> {
198 const shape = argsError('pushPack', [['transport', t, 'object'], ['options', options, 'object']]);
199 if (shape !== null) return shape;
200 const sent = await pushPackOutcome(t, options);
201 return sent.result;
Diagnostics4 git calls · 26 ms
CallStatusSizeTime026 ms
discover200152 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
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=2
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
fetch2004.3 KiB · hit21 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=20
git.response.bytes=4360
git.response.cache=HIT
git.response.duration_ms=21
git.fetch.wants=d5ea093e52d22ede0e2ca83ed1a2061c6a68c1f7
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=4360
git.pkt.payload.max=4339
git.sideband.band1.bytes=4338
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
a5e2c34bbce4aedd
Request
d45086be…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format