// v0 receive-pack capability advertisement (GET info/refs). Only needed to check optional capabilities (atomic, // push-options) before relying on them; the v2 fetch path never needs it. Parsing the advertisement and checking a // push against it are pure; receiveCaps is the one effect. import { fail, remoteQuoted, argsError } from './errors.js'; import type { ErrorOf, PlyError } from './errors.js'; import { ok, assertNever, getOrElse, mapOption } from './result.js'; import { decideObjectFormat } from './closed.js'; import type { Option, Result } from './result.js'; import { td } from './bytes.js'; import { pktInit, pktStep, pktFinish } from './pktline.js'; import { coded, clientSpan, advertise, spanned } from './transport.js'; import { planPackPush, push, pushPackChecked } from './push.js'; import type { CheckedCaps, PackPushOptions, PackPushOutcome, PushOptions, PushResult, PushTransport } from './push.js'; import type { Input } from './absent.js'; // oxlint-disable-next-line import/max-dependencies -- the advertisement reader joins the frame reader, the v2 parser and push import { at, fromNullable, fromNullish, mapGet, withDefaults } from './absent.js'; // A pkt-line frame as pktStep returns it (payload only on a data frame). import type { Frame } from './transport.js'; import type { Span } from './otel.js'; type Protocol = ErrorOf<'protocol'>; // What reading an advertisement can fail with: the v0 shape is protocol; a v2 answer has no push capabilities to read. export type AdvertError = ErrorOf<'protocol' | 'unsupported'>; type DataFrame = Extract; const frameAt = (frames: readonly Frame[], i: number): Option => at(frames, i); // The data frame at `i`, if the frame there is one. const dataAt = (frames: readonly Frame[], i: number): DataFrame | null => { const f = frameAt(frames, i); return f.tag === 'some' && f.value.kind === 'data' ? f.value : null; }; // The index of the first frame after a smart-http "# service=" header and its flush, 0 when there is none // (remote-curl check_smart_http: the header's metadata lines run to the first flush). function serviceHeaderEnd(frames: readonly Frame[]): Result { const first = dataAt(frames, 0); if (first === null || !td.decode(first.payload).startsWith('# service=')) return ok(0); const flush = frames.findIndex(f => f.kind !== 'data'); const end = frameAt(frames, flush); if (flush < 0 || end.tag === 'none' || end.value.kind !== 'flush') return fail('protocol', 'advertisement: no flush after the service header'); return ok(flush + 1); } // connect.c process_ref/process_shallow parse each oid with the hash the first line's object-format names (sha1 when // absent), so a sha256 advertisement is read whole and checkPushCaps names the need, as send-pack does. const SHA1_HEX = 40; const OID_HEX: ReadonlyMap = new Map([['sha1', SHA1_HEX], ['sha256', 64]]); const refLine = (n: number): RegExp => new RegExp(`^[0-9a-f]{${n}} [^ ]`, 'u'); const shallowLine = (n: number): RegExp => new RegExp(`^shallow [0-9a-f]{${n}}$`, 'u'); const LINE_PREVIEW = 60; const FORMAT = 'object-format='; // The advertisement's object-format capability, if any. const objectFormat = (caps: ReadonlySet): Option => mapOption(fromNullable([...caps].find(c => c.startsWith(FORMAT))), c => c.slice(FORMAT.length)); // The transport surface receiveCaps reads, beside push's. export type CapsTransport = PushTransport; // Pure: the advertisement's pkt frames → its capabilities. // connect.c get_remote_heads: ref lines up to the first flush, and nothing after it is read. The capabilities ride on // the first line (process_capabilities). A delim or response-end is "invalid packet"; the end of the response // before the flush (a cut advertisement) is "hung up"; a line that is neither " " nor "shallow " is // "protocol error: unexpected". Each used to be read as a complete advertisement. // @decoder parseReceiveAdvert prefix=advertisement export function parseReceiveAdvert(frames: readonly Frame[]): Result, AdvertError> { const caps = new Set(); const end = serviceHeaderEnd(frames); if (!end.ok) return end; const start = end.value; // ply asks for the v0 advertisement here, as git does (http.ts sends no Git-Protocol header for receive-pack). A v2 // answer anyway is a different vocabulary, with no report-status or atomic: reading it as an empty set would be // indistinguishable from a server with no capabilities, so it is refused by name. const opening = dataAt(frames, start); if (opening !== null && td.decode(opening.payload).replace(/\n$/u, '') === 'version 2') { return fail('unsupported', 'receive-pack advertisement: the server answered in protocol v2, which has no push capabilities'); } let hex = SHA1_HEX; for (let k = start; ; k++) { const next = frameAt(frames, k); if (next.tag === 'none') return fail('protocol', 'receive-pack advertisement: no flush after the refs'); const f = next.value; if (f.kind === 'flush') break; if (f.kind !== 'data') return fail('protocol', `receive-pack advertisement: invalid packet (${f.kind})`); const line = td.decode(f.payload).replace(/\n$/u, ''); const nul = line.indexOf('\0'); const head = nul < 0 ? line : line.slice(0, nul); // 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 if (k === start && nul >= 0) { for (const c of line.slice(nul + 1).trim().split(' ')) caps.add(c); // Stryker disable next-line StringLiteral,LogicalOperator: no object-format is a key OID_HEX lacks, which keeps sha1's width either way hex = getOrElse(mapGet(OID_HEX, getOrElse(objectFormat(caps), '')), hex); } if (!refLine(hex).test(head) && !shallowLine(hex).test(head)) return fail('protocol', `receive-pack advertisement: unexpected line ${remoteQuoted(head, LINE_PREVIEW)}`); } return ok(caps); } // The exchange: the advertisement, read. // oxlint-disable-next-line require-await -- async: a synchronous failure (an unusable transport) is a rejection, as it always was export async function receiveCaps(t: CapsTransport): Promise, PlyError>> { // oxlint-disable-next-line typescript/promise-function-async -- the exchange's promise, passed through (an async wrapper adds bytes, not behaviour) return coded('protocol', () => spanned(t, 'git.receive-pack advertise', clientSpan(t, { 'git.command': 'advertise', 'git.protocol.version': 0 }), async (span: Span): Promise, PlyError>> => { const buf = await advertise(t, 'git-receive-pack', span); if (!buf.ok) return buf; const stepped = pktStep(pktInit(), buf.value); if (!stepped.ok) return stepped; const { frames, state } = stepped.value; const finished = pktFinish(state); if (!finished.ok) return finished; const caps = parseReceiveAdvert(frames); if (caps.ok) span.set({ 'git.receive.caps': [...caps.value] }); return caps; })); } // What a push asks of the server that send-pack.c send_pack() checks against the advertisement before it sends a byte: // the repository's hash ("the receiving end does not support this repository's hash algorithm": ply is sha1-only, and an // advertisement without object-format is sha1), `atomic` ("does not support --atomic push") and `push-options` ("does // not support push options"). receive-pack ignores an `atomic` or `push-options` capability it did not advertise // (builtin/receive-pack.c), so an unchecked atomic push lands ref by ref, and unchecked option lines are read as the // pack ("unpacker error"): push takes them only as the CheckedCaps this makes. export type PushWantsConfig = { readonly atomic: boolean; readonly pushOptions: readonly string[] }; export type PushWants = Input; const noWants = (): PushWantsConfig => ({ atomic: false, pushOptions: [] }); export type CapsProblem = | { readonly tag: 'ok' } | { readonly tag: 'objectFormat'; readonly format: string } | { readonly tag: 'noAtomic' } | { readonly tag: 'noPushOptions' }; // Pure: ok, or the first unmet need. There is no null. export function capsProblem(caps: ReadonlySet, want: PushWants = {}): CapsProblem { const { atomic, pushOptions } = withDefaults(want, noWants()); const decision = decideObjectFormat(getOrElse(objectFormat(caps), 'sha1')); switch (decision.tag) { case 'refused': return { tag: 'objectFormat', format: decision.format }; case 'ok': { if (atomic && !caps.has('atomic')) return { tag: 'noAtomic' }; if (pushOptions.length > 0 && !caps.has('push-options')) return { tag: 'noPushOptions' }; return { tag: 'ok' }; } } // Stryker disable next-line ConditionalExpression: unreachable, the compiler's exhaustiveness check return assertNever(decision); } const problemText = (p: Exclude): string => { switch (p.tag) { case 'objectFormat': return `server repository is object-format ${p.format}`; case 'noAtomic': return 'server does not advertise atomic'; case 'noPushOptions': return 'server does not advertise push-options'; } // Stryker disable next-line ConditionalExpression: unreachable, the compiler's exhaustiveness check return assertNever(p); }; // Pure: the push's atomic and push options, checked against the advertisement. export function checkPushCaps(caps: ReadonlySet, want: PushWants = {}): Result> { const problem = capsProblem(caps, want); switch (problem.tag) { case 'objectFormat': case 'noAtomic': case 'noPushOptions': return fail('unsupported', problemText(problem), { caps: [...caps] }); case 'ok': // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the one place a CheckedCaps is made: the brand is a type (push.ts) return ok({ atomic: getOrElse(fromNullish(want.atomic), false), pushOptions: getOrElse(fromNullish(want.pushOptions), []) } as CheckedCaps); } // Stryker disable next-line ConditionalExpression: unreachable, the compiler's exhaustiveness check return assertNever(problem); } // push(), after reading the advertisement when the push needs a capability (atomic, push-options): one extra GET, only then. export type CheckedPushOptions = Omit & PushWants; export async function pushWithOptions(t: CapsTransport, options: CheckedPushOptions): Promise> { const { atomic: _atomic, pushOptions: _pushOptions, ...opts } = options; const { atomic, pushOptions } = withDefaults(options, noWants()); if (!atomic && pushOptions.length === 0) return push(t, opts); const caps = await receiveCaps(t); if (!caps.ok) return caps; const checked = checkPushCaps(caps.value, { atomic, pushOptions }); if (!checked.ok) return checked; return push(t, { ...opts, checked: checked.value }); } // pushWithOptions for a pack the caller already has (push.ts PackPushOptions). A request that cannot be sent is refused // first: the advertisement GET and the pack are only touched for one that can. export type CheckedPackPushOptions = Omit & PushWants; // pushPack with whether the push request was sent (push.ts PackPushOutcome): a refusal here or a failed advertisement // read is `sent: 'no'`, with nothing sent to receive-pack (the push cannot have landed), and so is push.ts's own // refusal or a request whose body was never pulled. transfer.ts reads this, never the error's code. export async function pushPackOutcome(t: CapsTransport, options: CheckedPackPushOptions): Promise { const { atomic: _atomic, pushOptions: _pushOptions, ...opts } = options; const { atomic, pushOptions } = withDefaults(options, noWants()); const planned = planPackPush(opts, t.limits); if (!planned.ok) return { sent: 'no', result: planned }; if (!atomic && pushOptions.length === 0) return pushPackChecked(t, opts); const caps = await receiveCaps(t); if (!caps.ok) return { sent: 'no', result: caps }; const checked = checkPushCaps(caps.value, { atomic, pushOptions }); if (!checked.ok) return { sent: 'no', result: checked }; return pushPackChecked(t, { ...opts, checked: checked.value }); } export async function pushPack(t: CapsTransport, options: CheckedPackPushOptions): Promise> { const shape = argsError('pushPack', [['transport', t, 'object'], ['options', options, 'object']]); if (shape !== null) return shape; const sent = await pushPackOutcome(t, options); return sent.result; }