import { PassThrough, Readable } from 'node:stream' import { Client } from 'ssh2' import { classifyNgReason, classifySshStderr, WireError } from './errors' import { encodePktLine, flushPkt, lineToString, PktLineReader } from './pkt-line' import { type Advertisement, parseAdvertisement } from './refs' const AGENT = 'synchub.to' const STDERR_CAP = 16 * 1024 /** * Whole-session budget. receive-pack blocks indefinitely waiting for commands, * so without this a knot that accepts the connection but stalls mid-protocol * would hang a worker until its job lease expires. On expiry we SIGKILL the * child; the in-flight read sees the stream end and throws, surfacing as a * transient failure the queue retries. */ const SESSION_TIMEOUT_MS = 120_000 export interface RefUpdate { ref: string /** Current value on the knot, or the zero SHA to create. The compare-and-swap. */ old: string /** New value, or the zero SHA to delete. */ next: string } /** * A process exposing `git-receive-pack`'s stdio. The default factory runs an * in-process `ssh2` channel to the knot; tests inject a factory that spawns the * binary against a local bare repo, so the stdio protocol is identical either * way. */ export interface ReceivePackProcess { stdin: NodeJS.WritableStream stdout: AsyncIterable /** Last bytes of stderr, for diagnostics (we don't request side-band). */ stderr(): string kill(): void /** Resolves with the exit code once the process ends. */ done: Promise } export type ReceivePackFactory = () => ReceivePackProcess export interface SshTarget { host: string port?: number repoPath: string /** Decrypted OpenSSH-format private key for this install. */ privateKey: string } /** * Default transport: open an in-process `ssh2` connection to the knot and run * its `git-receive-pack`. No `ssh` binary (the Vercel runtime has none); the * key stays in memory. * * Host keys: tangled knots are addressed by hostname over TLS-fronted DNS, and * v1 has no pinned host keys, so `hostVerifier` accepts any (TOFU-equivalent to * the previous `StrictHostKeyChecking=accept-new`). Pin once the canonical knot * keys are known. */ export function ssh2ReceivePackFactory(target: SshTarget): ReceivePackFactory { return () => { // The knot resolves repos by the leading-slash path, single-quoted. const remoteCmd = `git-receive-pack '${target.repoPath}'` const client = new Client() const stdin = new PassThrough() const stdout = new PassThrough() let stderrBuf = Buffer.alloc(0) let connError: Error | null = null let killed = false const appendStderr = (chunk: Buffer) => { stderrBuf = Buffer.concat([stderrBuf, chunk]).subarray(-STDERR_CAP) } const done = new Promise(resolve => { let settled = false const settle = (code: number | null) => { if (settled) return settled = true resolve(code) } client.on('ready', () => { client.exec(remoteCmd, (err, channel) => { if (err) { connError = err stdout.end() client.end() settle(null) return } stdin.pipe(channel) channel.pipe(stdout) channel.stderr.on('data', appendStderr) // A channel-level error (peer reset, transport dying mid-stream) would // otherwise be lost: the write side is a PassThrough whose 'error' we // swallow, and a half-sent pack reaches the knot as a corrupt stream // it reports back as an `unpack` failure. Fold it into the stderr band // so push() can tell a truncated push apart from a clean one. channel.on('error', (err: Error) => { if (!killed) connError = err }) channel.on('exit', code => settle(typeof code === 'number' ? code : null)) channel.on('close', () => { client.end(); stdout.end() }) }) }) // A connection / auth failure surfaces here. Capturing it (rather than // leaving 'error' unhandled, which crashes the process) folds the message // into the stderr band so open() reports a WireError the job handler // catches. Ending stdout unblocks the advertisement read. client.on('error', err => { if (!killed) connError = err stdout.end() settle(null) }) // Always-fires backstop: `client.end()` (from kill(), a channel close, or // an exec error) emits 'close', so `done` resolves even if the channel // already exited and won't emit another event. client.on('close', () => { stdout.end() settle(null) }) }) // stdin EPIPE-style errors once the channel goes away are expected. stdin.on('error', () => {}) client.connect({ host: target.host, port: target.port ?? 22, username: 'git', privateKey: target.privateKey, readyTimeout: 8_000, // The channel sits idle while we fetch the thin pack from GitHub (we need // the knot's advertised tips as haves before we can ask for the delta). // Keepalives stop the knot or an intermediary from dropping that idle // channel out from under us, which otherwise surfaces as a truncated pack // (`unpack` failure) once we resume streaming. keepaliveInterval: 5_000, keepaliveCountMax: 6, hostVerifier: () => true, }) return { stdin, stdout, stderr: () => { const captured = stderrBuf.toString('utf8') if (connError) return `${captured}${captured ? '\n' : ''}ssh error: ${connError.message}`.trim() return captured }, kill: () => { killed = true client.end() stdout.end() }, done, } } } /** * An open receive-pack session. Read `tips` after construction to learn the * knot's current refs (needed as haves and as the compare-and-swap base), * then call `push` once with the commands and packfile. */ export class ReceivePackSession { readonly tips: Map readonly capabilities: Set private readonly watchdog: NodeJS.Timeout private constructor( private readonly proc: ReceivePackProcess, private readonly reader: PktLineReader, adv: Advertisement, watchdog: NodeJS.Timeout, ) { this.tips = adv.refs this.capabilities = adv.capabilities this.watchdog = watchdog } /** Open the session and read the advertisement. */ static async open(factory: ReceivePackFactory, timeoutMs = SESSION_TIMEOUT_MS): Promise { const proc = factory() const watchdog = setTimeout(() => proc.kill(), timeoutMs) try { const reader = new PktLineReader(proc.stdout) const advLines = await reader.readUntilFlush() if (advLines === null) { const err = classifySshStderr(proc.stderr()) throw err ?? new WireError(`receive-pack: no advertisement (stderr: ${proc.stderr().trim() || 'empty'})`) } const adv = parseAdvertisement(advLines) assertCapabilities(adv) return new ReceivePackSession(proc, reader, adv, watchdog) } catch (err) { clearTimeout(watchdog) proc.kill() await proc.done.catch(() => null) throw err } } /** * Send the ref update commands plus (for non-deletions) the packfile, then * read and validate report-status. The packfile is streamed straight from * `packStream` into stdin; nothing is buffered. Pass `null` for pure * deletions. */ async push(updates: RefUpdate[], packStream: AsyncIterable | null): Promise { if (updates.length === 0) throw new WireError('receive-pack: no updates') try { await writeAll(this.proc.stdin, buildCommandList(updates)) if (packStream) await pipePack(this.proc.stdin, packStream) else this.proc.stdin.end() const report = await this.reader.readUntilFlush() // If the transport died while we were streaming the pack, the knot saw a // truncated stream and reports it as an `unpack` failure (e.g. "pack // signature mismatch"). That reads like a terminal protocol error but is // really a transient network fault, and a naive retry replays the same // broken pipe. Check the channel/exit state first and surface it as a // plain transient WireError so the queue retries with a fresh session. const exitCode = await this.proc.done.catch(() => null) const transport = classifySshStderr(this.proc.stderr()) if (transport) throw transport if (exitCode !== null && exitCode !== 0) { throw new WireError(`receive-pack exited ${exitCode} (stderr: ${this.proc.stderr().trim() || 'empty'})`) } parseReportStatus(report ?? [], updates, this.proc.stderr()) } finally { clearTimeout(this.watchdog) this.proc.kill() await this.proc.done.catch(() => null) } } /** Close the session without pushing (advertisement-only use). */ async close(): Promise { clearTimeout(this.watchdog) this.proc.stdin.end() this.proc.kill() await this.proc.done.catch(() => null) } } function assertCapabilities(adv: Advertisement): void { if (!adv.capabilities.has('report-status')) { throw new WireError('knot receive-pack does not advertise report-status') } } function buildCommandList(updates: RefUpdate[]): Buffer { const parts: Buffer[] = [] updates.forEach((u, i) => { const caps = i === 0 ? `\0report-status agent=${AGENT}/1` : '' parts.push(encodePktLine(`${u.old} ${u.next} ${u.ref}${caps}\n`)) }) parts.push(flushPkt) return Buffer.concat(parts) } function parseReportStatus(lines: Buffer[], updates: RefUpdate[], stderr: string): void { if (lines.length === 0) { const err = classifySshStderr(stderr) throw err ?? new WireError(`receive-pack: empty report-status (stderr: ${stderr.trim() || 'empty'})`) } const unpack = lineToString(lines[0]!) if (unpack !== 'unpack ok') { throw new WireError(`receive-pack: ${unpack}`) } for (const raw of lines.slice(1)) { const line = lineToString(raw) if (line.startsWith('ng ')) { // `ng ` const rest = line.slice(3) const sp = rest.indexOf(' ') const reason = sp === -1 ? rest : rest.slice(sp + 1) throw classifyNgReason(reason) } } } async function writeAll(stream: NodeJS.WritableStream, data: Buffer): Promise { await new Promise((resolve, reject) => { stream.write(data, err => (err ? reject(err) : resolve())) }) } async function pipePack(stdin: NodeJS.WritableStream, packStream: AsyncIterable): Promise { const src = Readable.from(packStream) await new Promise((resolve, reject) => { let settled = false const done = (err?: Error) => { if (settled) return settled = true if (err) reject(err) else resolve() } // A `close` before `finish` means the write side went away before the pack // was fully flushed (the knot's channel reset mid-stream). Resolving there // would hand a truncated pack to report-status parsing; reject so push() // treats it as the transient transport failure it is. src.on('error', done) stdin.on('error', done) stdin.on('finish', () => done()) stdin.on('close', () => done(new WireError('receive-pack: stdin closed before pack finished streaming'))) src.pipe(stdin, { end: true }) }) }