main
1// v2 capability discovery (GET info/refs with Git-Protocol: version=2). The edit path never needs it — v2 is asserted
2// per request — but it is the only place the server says who it is: agent, object-format, and the `fetch=` features
3// (shallow, filter, wait-for-done, ref-in-want...). Run it as a canary so a server-side change shows up as an attr diff.
4// The advertisement is read as git's client reads it (connect.c); the space of advertisements and ply's answer to each
5// is test/space/advertisement.space.js.
6import type { ErrorOf, Extra, PlyError } from './errors.js';
7import type { Span } from './otel.js';
8import type { Transport } from './transport.js';
9import type { Result } from './result.js';
10import { fail } from './errors.js';
11import { assertNever, getOrElse, ok } from './result.js';
12import { fromNullish } from './absent.js';
13import { checkRequiredV2, decideObjectFormat, fetchFeatureFlags } from './closed.js';
14import { pktInit, pktStep, pktFinish, pktAttrs } from './pktline.js';
15import { asTransport, coded, clientSpan, advertise, spanned, learnFilter, learnShallow } from './transport.js';
16import { capLookup, parseCapabilitiesV2 } from './caps.js';
18export { capLookup, parseCapabilitiesV2 } from './caps.js';
19export type { CapLookup, CapsV2Error } from './caps.js';
21// What the server said about itself in its v2 advertisement.
22export type DiscoverInfo = {
23 readonly version: 2; readonly agent: string; readonly objectFormat: string; readonly caps: Map<string, string>;
24 readonly fetch: readonly string[]; readonly filter: boolean; readonly shallow: boolean; readonly waitForDone: boolean; readonly refInWant: boolean; readonly sidebandAll: boolean;
25 readonly lsRefs: boolean; readonly lsRefsUnborn: boolean; readonly serverOption: boolean; readonly bundleUri: boolean; readonly sessionId: string;
26};
28// Every ply read is ls-refs then fetch: a server without either cannot serve ply (git: "server doesn't support '%s'"),
29// and ply reads sha1 repositories only.
30function serverFits(info: DiscoverInfo, has: (key: string) => boolean): Result<DiscoverInfo, ErrorOf<'unsupported'>> {
31 const required = checkRequiredV2(has);
32 switch (required.tag) {
33 // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- an ad-hoc error field (errors.ts Extra); A3 moves it into Detail
34 case 'missing': return fail('unsupported', `server does not advertise ${required.cap}`, { info } as Extra);
35 case 'ok': {
36 const decision = decideObjectFormat(info.objectFormat);
37 switch (decision.tag) {
38 // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- as above
39 case 'refused': return fail('unsupported', `unsupported object-format ${decision.format}`, { info } as Extra);
40 case 'ok': return ok(info);
41 }
42 // Stryker disable next-line ConditionalExpression: unreachable, the compiler's exhaustiveness check
43 return assertNever(decision);
44 }
45 }
46 // Stryker disable next-line ConditionalExpression: unreachable, the compiler's exhaustiveness check
47 return assertNever(required);
48}
50// The exchange: the advertisement, read and held to what ply needs.
51// oxlint-disable-next-line require-await -- async: a synchronous failure (an unusable transport) is a rejection, as it always was
52export async function discover(t: Transport): Promise<Result<DiscoverInfo, PlyError>> {
53 // oxlint-disable-next-line typescript/promise-function-async -- the exchange's promise, passed through (an async wrapper adds bytes, not behaviour)
54 return coded('protocol', () => spanned(t, 'git.upload-pack discover', clientSpan(t, { 'git.command': 'discover', 'git.protocol.version': 2 }), async (span: Span): Promise<Result<DiscoverInfo, PlyError>> => {
55 const buf = await advertise(t, 'git-upload-pack', span);
56 if (!buf.ok) return buf;
57 const stepped = pktStep(pktInit(), buf.value);
58 if (!stepped.ok) return stepped;
59 const { frames, state } = stepped.value;
60 const finished = pktFinish(state);
61 if (!finished.ok) return finished;
62 const parsed = parseCapabilitiesV2(frames, t.scrub);
63 if (!parsed.ok) return parsed;
64 const lines = parsed.value;
65 const { has, value, features } = capLookup(lines);
66 const caps = new Map<string, string>();
67 for (const l of lines) { const eq = l.indexOf('='); const k = eq < 0 ? l : l.slice(0, eq); if (!caps.has(k)) caps.set(k, eq < 0 ? '' : l.slice(eq + 1)); }
68 const fetchFeatures = features('fetch');
69 const fetchFlags = fetchFeatureFlags(fetchFeatures);
70 const info: DiscoverInfo = {
71 version: 2, agent: getOrElse(fromNullish(value('agent')), ''), objectFormat: getOrElse(fromNullish(value('object-format')), 'sha1'), caps,
72 fetch: fetchFeatures, filter: fetchFlags.filter, shallow: fetchFlags.shallow, waitForDone: fetchFlags.waitForDone, refInWant: fetchFlags.refInWant, sidebandAll: fetchFlags.sidebandAll,
73 lsRefs: has('ls-refs'), lsRefsUnborn: features('ls-refs').includes('unborn'), serverOption: has('server-option'), bundleUri: has('bundle-uri'), sessionId: getOrElse(fromNullish(value('session-id')), ''),
74 };
75 // The fetch path reads the same bit when a filtered fetch dies (fetch.ts filterUnadvertised); an advertisement in
76 // hand answers it first. A host that stops (or starts) advertising `filter` is followed either way. A transport handed
77 // in without a quirks record has no memory to keep it in (asTransport gives the view a fresh one).
78 learnFilter(asTransport(t, t.limits), info.filter);
79 // and whether it takes `deepen`: a single-object fetch adds depth 1 only for a server that lists `shallow` (objectAt)
80 learnShallow(asTransport(t, t.limits), info.shallow);
81 span.set({ ...pktAttrs(state), 'git.server.agent': info.agent, 'git.server.object_format': info.objectFormat, 'git.server.caps': [...caps.keys()], 'git.server.fetch': fetchFeatures, 'git.server.filter': info.filter, 'git.server.shallow': info.shallow, 'git.server.wait_for_done': info.waitForDone, 'git.server.ref_in_want': info.refInWant, 'git.server.ls_refs.unborn': info.lsRefsUnborn, 'git.server.server_option': info.serverOption, 'git.server.bundle_uri': info.bundleUri });
82 return serverFits(info, has);
83 }));
84}
Diagnostics4 git calls · 251 ms
CallStatusSizeTime0251 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 · hit6 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=6 git.response.bytes=38434 git.response.cache=HIT git.response.duration_ms=6 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=55Open pack map
fetch2002.3 KiB242 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=242 git.response.bytes=2397 git.response.cache=MISS git.response.duration_ms=242 git.fetch.wants=a8d2e3d3201b295fd7f8b9108551c8bc7ef2df0d 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=2397 git.pkt.payload.max=2376 git.sideband.band1.bytes=2375 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
- a5e2d8e9ccb414c2
- Request
- 8ca79d8a…
- Protocol
- v2 · sha1
- Agent
- gitty/1.0
- Filter
- advertised
- Fetch
- shallow filter sideband-all
- Capabilities
- agent ls-refs fetch object-format