// The advertisement space, as code: what ply does with what a server says about itself, and with what ply asks of it. // Four decisions, each a product of axes that are tagged unions (a list of variants with the payload needed to render // them and a `why` citing git's source), each with an exhaustive expected outcome per cell: // // caps discover(): the v2 capability advertisement (GET info/refs?service=git-upload-pack) // refs lsRefs(): the ls-refs response, record by record // push push() through GitHttp/pushWithOptions: what the push asks for × what receive-pack advertises // request fetchPack(): the request arguments ply sends that no other space covers × the server's filter support // // Expected outcome, the one rule: ply proceeds when git proceeds, and gives a typed refusal (`unsupported`, `protocol`, // `remote_error`, `not_git`, `network`) when git refuses or when a feature ply needs is absent. Every cell's expected // value carries both sides: `git` (what git does with the same bytes: `ok` | `refuse`) and `ply` (an outcome tag, with // the parsed value for `ok`); `consistent()` checks the rule over every cell. git sources are v2.50.0: connect.c // (discover_version, process_capabilities_v2, server_supports_v2, server_feature_v2, server_supports_feature, // send_capabilities, get_remote_refs, process_ref_v2), pkt-line.c (packet_read_with_status), remote-curl.c, // serve.c (capabilities[]), upload-pack.c (upload_pack_advertise, process_args), send-pack.c (send_pack), // builtin/receive-pack.c (show_ref, read_head_info), fetch-pack.c (send_fetch_request). import { te, concat } from '../../src/bytes.js'; const pktBytes = payload => { const p = typeof payload === 'string' ? te.encode(payload) : payload; return concat([te.encode((p.length + 4).toString(16).padStart(4, '0')), p]); }; const FLUSH = te.encode('0000'), DELIM = te.encode('0001'); export const AGENT = 'git/2.50.0'; // the five `fetch=` features upload_pack_advertise can write, in its order export const FETCH_FEATURES = ['shallow', 'wait-for-done', 'filter', 'ref-in-want', 'sideband-all']; const subsets = list => list.reduce((acc, x) => acc.concat(acc.map(s => [...s, x])), [[]]).map(s => list.filter(x => s.includes(x))); // payload sizes around git's reader limit (pkt-line.c: payload >= LARGE_PACKET_MAX dies "bad line length") export const PAYLOAD_MAX = 65519; export const product = axes => axes.reduce((cells, a) => cells.flatMap(c => a.variants.map(v => ({ ...c, [a.name]: v }))), [{}]); export const cellId = (axes, c) => axes.map(a => `${a.name}=${c[a.name].tag}${c[a.name].set ? `[${c[a.name].set.join(',')}]` : ''}`).join(' '); // ================================================================== caps ================================================== export const CAPS_AXES = [ { name: 'agent', doc: 'the agent capability', variants: [ { tag: 'present', why: 'serve.c agent_advertise: always written by git' }, { tag: 'absent', why: 'a server that does not say (send_capabilities skips agent= when !server_supports_v2("agent"))' }, { tag: 'empty', why: '`agent=` with an empty value: recorded, never decided on' }, ] }, { name: 'objectFormat', doc: 'object-format, read by send_capabilities with server_feature_v2 (needs `=`)', variants: [ { tag: 'sha1', value: 'sha1', why: 'serve.c object_format_advertise: the repository hash' }, { tag: 'absent', why: 'no line: send_capabilities falls back to sha1' }, { tag: 'sha256', value: 'sha256', why: 'a sha256 repository (git init --object-format=sha256): git proceeds, ply is sha1-only' }, { tag: 'unknown', value: 'sha3', why: 'hash_algo_by_name fails: "unknown object format \'%s\' specified by server"' }, { tag: 'bare', why: '`object-format` with no `=`: server_feature_v2 needs `=`, so it is absent (sha1)' }, { tag: 'empty', value: '', why: '`object-format=`: "unknown object format \'\'"' }, ] }, { name: 'fetch', doc: 'the fetch command and its features', variants: [ { tag: 'absent', why: 'no fetch command: fetch-pack ensure_server_supports_v2("fetch") dies' }, ...subsets(FETCH_FEATURES).map(set => ({ tag: 'features', set, why: 'upload_pack_advertise: shallow and wait-for-done always; filter, ref-in-want, sideband-all by config' })), ] }, { name: 'lsRefs', doc: 'the ls-refs command', variants: [ { tag: 'unborn', why: 'ls_refs_advertise with lsrefs.unborn=advertise (the default)' }, { tag: 'plain', why: 'lsrefs.unborn=ignore' }, { tag: 'absent', why: 'get_remote_refs: ensure_server_supports_v2("ls-refs") dies' }, ] }, { name: 'serverOption', doc: 'server-option', variants: [ { tag: 'present', why: 'serve.c: always advertised' }, { tag: 'absent', why: 'ply never sends server options; recorded only' }, ] }, { name: 'sessionId', doc: 'session-id', variants: [ { tag: 'absent', why: 'transfer.advertiseSID=false (the default)' }, { tag: 'present', value: 'sid-1', why: 'transfer.advertiseSID=true; recorded only' }, ] }, { name: 'malformed', doc: 'one malformation of the advertisement', variants: [ { tag: 'none', why: 'as serve.c writes it' }, { tag: 'noLF', why: 'no line ends in LF: packet_read chomps an LF only when present (PACKET_READ_CHOMP_NEWLINE)' }, { tag: 'unknownCap', why: 'a capability nobody defines: every lookup skips it' }, { tag: 'duplicate', why: 'each capability again with another value, after the first: connect.c takes the first match' }, { tag: 'longMax', why: `a capability line of ${PAYLOAD_MAX} payload bytes: the longest git's reader accepts` }, { tag: 'longOver', why: `a capability line of ${PAYLOAD_MAX + 1} payload bytes: "protocol error: bad line length"` }, { tag: 'noFlush', why: 'the body ends after the last capability: "expected flush after capabilities"' }, { tag: 'delim', why: 'a delim-pkt where the flush belongs: "expected flush after capabilities"' }, { tag: 'trailing', why: 'a data pkt after the flush: remote-curl hands it on as the ls-refs response, "invalid ls-refs response"' }, ] }, ]; // The protocol the server answers with, a tagged union whose only variant with a payload is v2 (it carries CAPS_AXES). export const PROTOCOLS = [ { tag: 'v2', why: 'version 2 then capabilities (serve.c protocol_v2_advertise_capabilities)' }, { tag: 'v0', why: 'a server that ignores Git-Protocol: "# service=" preamble, then v0 ref lines with capabilities after NUL; git proceeds (discover_version), ply needs v2' }, { tag: 'v1', why: '"# service=" preamble, "version 1", then v0 lines: protocol v1, which git reads as v0 (observed: ls-remote proceeds); ply needs v2' }, { tag: 'err', why: 'an ERR pkt first: "remote error: %s"' }, { tag: 'v2service', why: 'git\'s default v2 advertisement after a "# service=git-upload-pack" pkt and its flush (the smart-HTTP v0 preamble some servers keep): remote-curl skips it' }, { tag: 'serviceNoFlush', why: 'the preamble with no flush after it: remote-curl refuses (observed)' }, { tag: 'html', why: 'HTTP 200 with text/html (a login page): remote-curl "not valid: is this a git repository?"; http.js not_git' }, { tag: 'reset', why: 'the connection fails before any response: git "the remote end hung up"; http.js network' }, ]; export const CANONICAL_CAPS = { agent: 'present', objectFormat: 'sha1', fetch: 'shallow,wait-for-done,filter', lsRefs: 'unborn', serverOption: 'present', sessionId: 'absent', malformed: 'none' }; const fetchKey = v => (v.tag === 'absent' ? 'absent' : v.set.join(',')); export const capsDeviations = c => c.protocol.tag !== 'v2' ? 1 : CAPS_AXES.filter(a => (a.name === 'fetch' ? fetchKey(c.fetch) : c[a.name].tag) !== CANONICAL_CAPS[a.name]).length; export function capsCells() { const v2 = product(CAPS_AXES).map(c => ({ protocol: PROTOCOLS[0], ...c })); return [...v2, ...PROTOCOLS.slice(1).map(p => ({ protocol: p }))]; } // the canonical capability axes (git's default advertisement), for the protocol variants that wrap it const canonicalAxes = () => Object.fromEntries(CAPS_AXES.map(a => [a.name, a.name === 'fetch' ? a.variants.find(v => v.set?.join(',') === CANONICAL_CAPS.fetch) : a.variants.find(v => v.tag === CANONICAL_CAPS[a.name])])); const WRAPS_V2 = ['v2service', 'serviceNoFlush']; export const capsCellId = c => (c.protocol.tag === 'v2' ? `v2 ${cellId(CAPS_AXES, c)}` : c.protocol.tag); // The capability lines (no LF), in serve.c's order, before malformation. function capLines(c) { const L = []; if (c.agent.tag === 'present') L.push(`agent=${AGENT}`); else if (c.agent.tag === 'empty') L.push('agent='); if (c.lsRefs.tag === 'unborn') L.push('ls-refs=unborn'); else if (c.lsRefs.tag === 'plain') L.push('ls-refs'); if (c.fetch.tag === 'features') L.push(`fetch=${c.fetch.set.join(' ')}`); if (c.serverOption.tag === 'present') L.push('server-option'); if (c.objectFormat.tag === 'bare') L.push('object-format'); else if ('value' in c.objectFormat) L.push(`object-format=${c.objectFormat.value}`); if (c.sessionId.tag === 'present') L.push(`session-id=${c.sessionId.value}`); return L; } // `duplicate`: each capability again, after all the others, with a value that differs from the first const DUP = c => [ 'agent=dup/1', 'ls-refs' + (c.lsRefs.tag === 'unborn' ? '' : '=unborn'), `fetch=${c.fetch.tag === 'absent' ? FETCH_FEATURES.join(' ') : FETCH_FEATURES.filter(f => !c.fetch.set.includes(f)).join(' ')}`, 'server-option', `object-format=${c.objectFormat.tag === 'sha1' ? 'sha256' : 'sha1'}`, 'session-id=dup', ]; // The effective capabilities: what git (and so ply) reads from the cell, per axis, under `duplicate` first-wins. export function effectiveCaps(c) { const dup = c.malformed.tag === 'duplicate'; const format = c.objectFormat.tag === 'absent' || c.objectFormat.tag === 'bare' ? 'sha1' : c.objectFormat.value; // a DUP after an absent/bare first is sha1 too return { agent: c.agent.tag === 'present' ? AGENT : c.agent.tag === 'empty' ? '' : dup ? 'dup/1' : '', objectFormat: format, fetch: c.fetch.tag === 'features' ? c.fetch.set : dup ? FETCH_FEATURES : null, lsRefs: c.lsRefs.tag !== 'absent' || dup, lsRefsUnborn: c.lsRefs.tag === 'unborn' || (c.lsRefs.tag === 'absent' && dup), serverOption: c.serverOption.tag === 'present' || dup, sessionId: c.sessionId.tag === 'present' ? c.sessionId.value : dup ? 'dup' : '', }; } // fx: the fixture refs { head, main, tag, peeled } (oids; the ls-refs response every caps cell is served with) export function renderCaps(c, fx) { if (c.protocol.tag === 'html') return { status: 200, contentType: 'text/html; charset=utf-8', body: te.encode('
Sign in\n') }; if (c.protocol.tag === 'reset') return { reset: true }; const ct = 'application/x-git-upload-pack-advertisement'; if (c.protocol.tag === 'err') return { status: 200, contentType: ct, body: concat([pktBytes('ERR access denied\n'), FLUSH]) }; if (WRAPS_V2.includes(c.protocol.tag)) { const inner = renderCaps({ ...canonicalAxes(), protocol: PROTOCOLS[0] }, fx); return { ...inner, body: concat([pktBytes('# service=git-upload-pack\n'), ...(c.protocol.tag === 'v2service' ? [FLUSH] : []), inner.body]) }; } if (c.protocol.tag === 'v0' || c.protocol.tag === 'v1') { const v0 = [pktBytes(`${fx.main} HEAD\0multi_ack thin-pack side-band side-band-64k ofs-delta shallow no-progress include-tag symref=HEAD:refs/heads/main object-format=sha1 agent=${AGENT}\n`), pktBytes(`${fx.main} refs/heads/main\n`), FLUSH]; return { status: 200, contentType: ct, body: concat([pktBytes('# service=git-upload-pack\n'), FLUSH, ...(c.protocol.tag === 'v1' ? [pktBytes('version 1\n')] : []), ...v0]) }; } const m = c.malformed.tag; let lines = ['version 2', ...capLines(c)]; if (m === 'unknownCap') lines.push('frobnicate=1'); if (m === 'duplicate') lines.push(...DUP(c)); const eol = m === 'noLF' ? '' : '\n'; const parts = lines.map(l => pktBytes(l + eol)); if (m === 'longMax' || m === 'longOver') parts.push(pktBytes(`x-pad=${'a'.repeat((m === 'longMax' ? PAYLOAD_MAX : PAYLOAD_MAX + 1) - 'x-pad='.length - 1)}\n`)); if (m !== 'noFlush') parts.push(m === 'delim' ? DELIM : FLUSH); if (m === 'trailing') parts.push(pktBytes('trailing\n')); return { status: 200, contentType: ct, body: concat(parts) }; } // git's verdict on the cell. ls-remote: the advertisement, then ls-refs (served with refs in the cell's hash). fetch: // ls-remote plus a fetch of refs/heads/main (fetch-pack needs the `fetch` command; a sha256 cell is not fetched). export function gitCaps(c) { const p = c.protocol.tag; if (p === 'v0' || p === 'v1' || p === 'v2service') return { lsRemote: 'ok', fetch: 'ok' }; if (p !== 'v2') return { lsRemote: 'refuse', fetch: 'refuse' }; const e = effectiveCaps(c); const lsRemote = ['longOver', 'noFlush', 'delim', 'trailing'].includes(c.malformed.tag) || !e.lsRefs || !['sha1', 'sha256'].includes(e.objectFormat) ? 'refuse' : 'ok'; return { lsRemote, fetch: lsRemote === 'refuse' || e.fetch === null ? 'refuse' : 'ok' }; } // ply's discover() on the cell. Order: the pkt framing, the protocol, the advertisement's framing, ls-refs and fetch // present, the object format; ok carries the fields the test compares. export function expectedCaps(c) { const git = gitCaps(c); const p = c.protocol.tag; const out = ply => ({ git, ply }); if (p === 'html') return out({ tag: 'not_git' }); if (p === 'reset') return out({ tag: 'network' }); if (p === 'err') return out({ tag: 'remote_error' }); if (p === 'serviceNoFlush') return out({ tag: 'protocol', why: 'advertisement framing' }); if (p === 'v2service') return expectedCaps({ ...canonicalAxes(), protocol: PROTOCOLS[0] }); if (p !== 'v2') return out({ tag: 'unsupported', why: 'protocol' }); const m = c.malformed.tag; if (m === 'longOver') return out({ tag: 'protocol', why: 'pkt length' }); if (m === 'noFlush' || m === 'delim' || m === 'trailing') return out({ tag: 'protocol', why: 'advertisement framing' }); const e = effectiveCaps(c); if (!e.lsRefs) return out({ tag: 'unsupported', why: 'ls-refs' }); if (e.fetch === null) return out({ tag: 'unsupported', why: 'fetch' }); if (e.objectFormat !== 'sha1') return out({ tag: 'unsupported', why: 'object-format' }); return out({ tag: 'ok', info: { agent: e.agent, objectFormat: 'sha1', fetch: e.fetch, filter: e.fetch.includes('filter'), shallow: e.fetch.includes('shallow'), waitForDone: e.fetch.includes('wait-for-done'), refInWant: e.fetch.includes('ref-in-want'), sidebandAll: e.fetch.includes('sideband-all'), lsRefs: true, lsRefsUnborn: e.lsRefsUnborn, serverOption: e.serverOption, sessionId: e.sessionId } }); } // where ply refuses although git proceeds: only for a need git does not have in that operation (named, never silent) export const PLY_NEEDS = { protocol: 'ply speaks v2 only (every request asserts it)', fetch: 'every ply read fetches', 'object-format': 'ply is sha1-only' }; // ================================================================== refs ================================================== export const REFS_AXES = [ { name: 'record', doc: 'one record of the listing, added to or changed in HEAD (symref), main, a tag (peeled)', variants: [ { tag: 'plain', why: 'the listing as ls_refs writes it: HEAD symref-target, a branch, an annotated tag with peeled' }, { tag: 'unknownAttr', why: 'an attribute ply and git do not know (`frob:1`): process_ref_v2 skips it (#16)' }, { tag: 'unbornHead', why: '"unborn HEAD symref-target:…" in place of HEAD (ls-refs unborn): process_ref_v2 records no ref' }, { tag: 'unbornOther', why: '"unborn