@defrex/autobuild-hosted-dispatcher 1.4.2 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -32,14 +32,51 @@ dispatch function installs and loads. The bin has two commands for that:
32
32
  It removes archives left over from other versions.
33
33
  - `ship-deployment [--root DIR] [--dist-dir DIR] [--plugin NAME]...`, run after
34
34
  `next build`, appends the archive and the distribution manifest to the
35
- `/api/dispatch` route's Next.js trace. It then stages each selected provider
36
- plugin into the function bundle. It fails the build, naming the missing
37
- piece, when it cannot ship the archive, the manifest or a selected plugin,
38
- and when the archive's version differs from the installed `@defrex/autobuild`.
35
+ `/api/dispatch` route's Next.js trace. It then stages the deployment's own
36
+ Git (see [Shipped Git](#shipped-git)) and each selected provider plugin into
37
+ the function bundle. It fails the build, naming the missing piece, when it
38
+ cannot ship the archive, the manifest, Git or a selected plugin, and when the
39
+ archive's version differs from the installed `@defrex/autobuild`.
39
40
 
40
41
  The hosted store service's published `ab-hosted-service-build` runs both
41
42
  commands automatically when this package is installed.
42
43
 
44
+ ### Shipped Git
45
+
46
+ Node operations (snapshotting a node's parent, restacking, proving a change is
47
+ present, landing) run `git` on a bare clone inside the dispatch function. The
48
+ Vercel Function runtime has no `git`, so the deployment ships its own:
49
+ `ship-deployment` copies the build host's Git into `<root>/.autobuild-git/`
50
+ and adds it to the `/api/dispatch` bundle, about 55 MB. The tree is
51
+ self-contained: Git, its HTTPS remote helpers, the complete shared-library
52
+ closure including glibc and the dynamic loader, and a CA bundle.
53
+
54
+ - **Platform.** The target is `linux-x64`, and the build host must be one, as
55
+ Vercel's build image is. On any other host `ship-deployment` fails, naming
56
+ both platforms. It also fails when the host lacks `git`, `ldd`, Git's HTTPS
57
+ helper or a CA bundle, or when a library cannot be resolved.
58
+ - **Proof at build time.** Every staged program is checked statically to load
59
+ only from the tree. The build then runs the staged Git with an empty `PATH`,
60
+ clones over HTTP on loopback, and fails if anything loaded from the build
61
+ host. The build log reports the Git and glibc versions, the size Git adds
62
+ and the dispatch function's total.
63
+ - **Runtime contract.** An x86_64 Linux kernel at least as new as the bundled
64
+ glibc supports (recorded in the manifest, 3.2 for current glibc) and a
65
+ writable `/tmp`. Each function instance copies the tree to a fixed
66
+ `/tmp/abg…` path once before its first Git command.
67
+ - **Isolation.** Every kernel Git command of a tick runs the shipped Git with
68
+ its own libraries, no system or global Git config, and HTTPS as the only
69
+ transport, so it never starts a host program. Kernel shell pipelines reach
70
+ it through a `git` launcher on the shell's `PATH` that applies the tree's
71
+ libraries to Git alone, so the shell and other host programs keep the
72
+ host's. The tick log line says
73
+ `kernelGit=shipped:<version>`, or `kernelGit=host-path (<reason>)` when the
74
+ tree could not be used.
75
+
76
+ If Git still cannot run, the dispatcher records one
77
+ `dispatcher.kernel-git-unavailable` repository event, node work waits, and
78
+ `dispatcher.kernel-git-recovered` closes the condition once a clone succeeds.
79
+
43
80
  ### Which provider plugins ship
44
81
 
45
82
  The first of these rules that applies decides:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@defrex/autobuild-hosted-dispatcher",
3
- "version": "1.4.2",
3
+ "version": "1.6.0",
4
4
  "type": "module",
5
5
  "license": "Apache-2.0",
6
6
  "engines": {
package/src/bin.ts CHANGED
@@ -6,6 +6,7 @@ import {
6
6
  writePrebuiltDistributionArchive,
7
7
  } from '@defrex/autobuild/distribution'
8
8
  import { selectDeploymentPlugins } from './deployment-plugins'
9
+ import { defaultStageGitHost, stageGitForDeployment } from './ship-git'
9
10
  import { ensureDistributionArchiveInTrace, findArchive } from './ship-packed-distribution'
10
11
  import { restoresInstallIn, shipProviderPlugins } from './ship-provider-plugin'
11
12
 
@@ -98,8 +99,9 @@ export async function assertArchiveMatchesDistribution(
98
99
  }
99
100
 
100
101
  /** `ship-deployment`: after `next build`, carry the packed archive, the
101
- * distribution manifest, and the selected provider plugins into the
102
- * `/api/dispatch` function bundle. */
102
+ * distribution manifest, a self-contained `linux-x64` Git for kernel node
103
+ * operations, and the selected provider plugins into the `/api/dispatch`
104
+ * function bundle. */
103
105
  export async function runShipDeployment(
104
106
  args: string[],
105
107
  write: (text: string) => void = (text) => console.log(text),
@@ -120,6 +122,12 @@ export async function runShipDeployment(
120
122
  distDir: parsed.distDir,
121
123
  log: write,
122
124
  })
125
+ await stageGitForDeployment({
126
+ root: parsed.root,
127
+ distDir: parsed.distDir,
128
+ host: defaultStageGitHost(env),
129
+ log: write,
130
+ })
123
131
  const selection = await selectDeploymentPlugins(parsed.root, parsed.plugins)
124
132
  write(
125
133
  selection.packages.length === 0
package/src/dispatcher.ts CHANGED
@@ -53,6 +53,7 @@ import {
53
53
  dispatcherOrigin,
54
54
  type HostedStoreEnv,
55
55
  } from '@defrex/autobuild-hosted-store-service'
56
+ import { locateShippedGitOnce, shippedGitExec, type LocateShippedGitResult } from './shipped-git'
56
57
 
57
58
  /** The service environment the dispatcher reads. Secrets are only ever taken
58
59
  * through `parseHostedStoreEnv`'s already-validated fields. */
@@ -236,6 +237,11 @@ export interface HostedDispatcherOptions {
236
237
  /** The kernel entry. Defaults to the real `abDispatch`; integration tests
237
238
  * wrap it with `wire`/`nonStoreWire` fakes and `originConfigTransport`. */
238
239
  dispatch?: (opts: DispatchOpts) => Promise<void>
240
+ /** Find the deployment's shipped Git (`ship-deployment` stages it). Resolved
241
+ * once per invocation; defaults to the per-process memoized locator. When it
242
+ * fails, kernel Git falls back to the host `PATH` and the kernel reports the
243
+ * durable kernel-Git condition if that cannot run either. */
244
+ locateGit?: () => Promise<LocateShippedGitResult>
239
245
  /** Where the kernel's own report lines go. Unset, they are forwarded to
240
246
  * `log`/`logError` prefixed with the repository so a deployment's runtime
241
247
  * logs carry every tick report and warning the kernel prints locally. */
@@ -340,6 +346,7 @@ export function createHostedDispatcher(options: HostedDispatcherOptions = {}): {
340
346
  const dispatch = options.dispatch ?? ((opts: DispatchOpts) => abDispatch(opts))
341
347
  const log = options.log ?? ((line: string) => console.log(line))
342
348
  const logError = options.logError ?? ((line: string) => console.error(line))
349
+ const locateGit = options.locateGit ?? locateShippedGitOnce
343
350
  return {
344
351
  async tick(
345
352
  invocation = invocationId(),
@@ -351,8 +358,20 @@ export function createHostedDispatcher(options: HostedDispatcherOptions = {}): {
351
358
  const now = clock().getTime()
352
359
  const deadlineAt = now + config.budgetSeconds * 1000
353
360
  const sandboxAuth = sandboxAuthSource(env, credentials)
361
+ // Every kernel Git command of the tick runs the shipped Git: the plain
362
+ // exec seam and, in origin mode, the forge's credentialed kernelExec.
363
+ const git = await locateGit().catch(
364
+ (error: unknown): LocateShippedGitResult => ({
365
+ ok: false,
366
+ reason: error instanceof Error ? error.message : String(error),
367
+ }),
368
+ )
369
+ const exec = git.ok ? shippedGitExec(spawnExec, git.git, { PATH: env.PATH }) : spawnExec
370
+ const kernelGit = git.ok
371
+ ? `shipped:${git.git.manifest.gitVersion}`
372
+ : `host-path (${git.reason})`
354
373
  log(
355
- `${LOG_PREFIX} ${invocation}: tick start repositories=${selected.length} budgetSeconds=${config.budgetSeconds} origin=${config.origin} sandboxAuth=${sandboxAuth}`,
374
+ `${LOG_PREFIX} ${invocation}: tick start repositories=${selected.length} budgetSeconds=${config.budgetSeconds} origin=${config.origin} sandboxAuth=${sandboxAuth} kernelGit=${kernelGit}`,
356
375
  )
357
376
  const repositories: HostedDispatcherRepositoryOutcome[] = []
358
377
  const placementFailures = new Set<string>()
@@ -487,7 +506,7 @@ export function createHostedDispatcher(options: HostedDispatcherOptions = {}): {
487
506
  once: true,
488
507
  plain: true,
489
508
  env: childEnv,
490
- exec: spawnExec,
509
+ exec,
491
510
  stdout: (line) => stdout(redact(line).replaceAll(token, '[redacted]')),
492
511
  stderr: (line) => stderr(redact(line).replaceAll(token, '[redacted]')),
493
512
  kernelRunId: runId,
package/src/elf.ts ADDED
@@ -0,0 +1,175 @@
1
+ /**
2
+ * Just enough ELF to stage a self-contained Git: the program interpreter, the
3
+ * dynamic section's library names and search paths, and glibc's ABI note.
4
+ * Only ELF64 little-endian x86_64 objects are accepted — the one platform the
5
+ * hosted dispatcher ships Git for.
6
+ */
7
+
8
+ const PT_LOAD = 1
9
+ const PT_DYNAMIC = 2
10
+ const PT_INTERP = 3
11
+ const PT_NOTE = 4
12
+ const DT_NULL = 0n
13
+ const DT_NEEDED = 1n
14
+ const DT_STRTAB = 5n
15
+ const DT_RPATH = 15n
16
+ const DT_RUNPATH = 29n
17
+ const NT_GNU_ABI_TAG = 1
18
+ export const EM_X86_64 = 62
19
+
20
+ export interface ElfInfo {
21
+ /** Always 64 for an accepted object. */
22
+ class: 64
23
+ machine: number
24
+ /** The `PT_INTERP` segment, when the object names a program loader. */
25
+ interpreter?: { path: string; offset: number; size: number }
26
+ needed: string[]
27
+ rpath: string[]
28
+ runpath: string[]
29
+ /** glibc's `NT_GNU_ABI_TAG`: the oldest Linux kernel the object supports. */
30
+ abiTag?: { os: number; kernel: string }
31
+ }
32
+
33
+ export class ElfError extends Error {}
34
+
35
+ /** Whether `bytes` starts with the ELF magic number. */
36
+ export function isElf(bytes: Uint8Array): boolean {
37
+ return (
38
+ bytes.length >= 4 &&
39
+ bytes[0] === 0x7f &&
40
+ bytes[1] === 0x45 &&
41
+ bytes[2] === 0x4c &&
42
+ bytes[3] === 0x46
43
+ )
44
+ }
45
+
46
+ interface ProgramHeader {
47
+ type: number
48
+ offset: number
49
+ vaddr: bigint
50
+ filesz: number
51
+ align: number
52
+ }
53
+
54
+ function view(bytes: Uint8Array): DataView {
55
+ return new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
56
+ }
57
+
58
+ function headers(bytes: Uint8Array): { machine: number; program: ProgramHeader[] } {
59
+ if (!isElf(bytes)) throw new ElfError('not an ELF object')
60
+ if (bytes.length < 64) throw new ElfError('truncated ELF header')
61
+ if (bytes[4] !== 2) throw new ElfError('not a 64-bit ELF object')
62
+ if (bytes[5] !== 1) throw new ElfError('not a little-endian ELF object')
63
+ const data = view(bytes)
64
+ const machine = data.getUint16(18, true)
65
+ if (machine !== EM_X86_64) throw new ElfError(`ELF machine ${machine} is not x86_64`)
66
+ const phoff = Number(data.getBigUint64(32, true))
67
+ const phentsize = data.getUint16(54, true)
68
+ const phnum = data.getUint16(56, true)
69
+ if (phoff + phentsize * phnum > bytes.length) throw new ElfError('truncated program headers')
70
+ const program: ProgramHeader[] = []
71
+ for (let index = 0; index < phnum; index++) {
72
+ const at = phoff + index * phentsize
73
+ program.push({
74
+ type: data.getUint32(at, true),
75
+ offset: Number(data.getBigUint64(at + 8, true)),
76
+ vaddr: data.getBigUint64(at + 16, true),
77
+ filesz: Number(data.getBigUint64(at + 32, true)),
78
+ align: Number(data.getBigUint64(at + 48, true)),
79
+ })
80
+ }
81
+ return { machine, program }
82
+ }
83
+
84
+ function cString(bytes: Uint8Array, start: number, end = bytes.length): string {
85
+ let stop = start
86
+ while (stop < end && bytes[stop] !== 0) stop++
87
+ return new TextDecoder().decode(bytes.subarray(start, stop))
88
+ }
89
+
90
+ /** File offset of a virtual address, through the load segment mapping it. */
91
+ function fileOffset(program: ProgramHeader[], address: bigint): number {
92
+ for (const segment of program) {
93
+ if (segment.type !== PT_LOAD) continue
94
+ if (address >= segment.vaddr && address < segment.vaddr + BigInt(segment.filesz))
95
+ return segment.offset + Number(address - segment.vaddr)
96
+ }
97
+ throw new ElfError(`address 0x${address.toString(16)} is not mapped by a load segment`)
98
+ }
99
+
100
+ function splitPaths(value: string): string[] {
101
+ return value.split(':').filter((entry) => entry !== '')
102
+ }
103
+
104
+ export function readElf(bytes: Uint8Array): ElfInfo {
105
+ const { machine, program } = headers(bytes)
106
+ const data = view(bytes)
107
+ const info: ElfInfo = { class: 64, machine, needed: [], rpath: [], runpath: [] }
108
+ for (const segment of program) {
109
+ if (segment.type === PT_INTERP) {
110
+ if (segment.offset + segment.filesz > bytes.length)
111
+ throw new ElfError('truncated interpreter segment')
112
+ info.interpreter = {
113
+ path: cString(bytes, segment.offset, segment.offset + segment.filesz),
114
+ offset: segment.offset,
115
+ size: segment.filesz,
116
+ }
117
+ }
118
+ if (segment.type === PT_DYNAMIC) {
119
+ const entries: [bigint, bigint][] = []
120
+ for (let at = segment.offset; at + 16 <= segment.offset + segment.filesz; at += 16) {
121
+ const tag = data.getBigInt64(at, true)
122
+ if (tag === DT_NULL) break
123
+ entries.push([tag, data.getBigUint64(at + 8, true)])
124
+ }
125
+ const strtab = entries.find(([tag]) => tag === DT_STRTAB)?.[1]
126
+ if (strtab === undefined) continue
127
+ const base = fileOffset(program, strtab)
128
+ for (const [tag, value] of entries) {
129
+ const text = () => cString(bytes, base + Number(value))
130
+ if (tag === DT_NEEDED) info.needed.push(text())
131
+ if (tag === DT_RPATH) info.rpath.push(...splitPaths(text()))
132
+ if (tag === DT_RUNPATH) info.runpath.push(...splitPaths(text()))
133
+ }
134
+ }
135
+ if (segment.type === PT_NOTE) {
136
+ const align = segment.align === 8 ? 8 : 4
137
+ const pad = (n: number) => Math.ceil(n / align) * align
138
+ let at = segment.offset
139
+ const end = segment.offset + segment.filesz
140
+ while (at + 12 <= end) {
141
+ const namesz = data.getUint32(at, true)
142
+ const descsz = data.getUint32(at + 4, true)
143
+ const type = data.getUint32(at + 8, true)
144
+ const name = cString(bytes, at + 12, at + 12 + namesz)
145
+ const desc = at + 12 + pad(namesz)
146
+ if (name === 'GNU' && type === NT_GNU_ABI_TAG && descsz >= 16 && desc + 16 <= end) {
147
+ info.abiTag = {
148
+ os: data.getUint32(desc, true),
149
+ kernel: [4, 8, 12].map((offset) => data.getUint32(desc + offset, true)).join('.'),
150
+ }
151
+ }
152
+ at = desc + pad(descsz)
153
+ }
154
+ }
155
+ }
156
+ return info
157
+ }
158
+
159
+ /** Point the object's program loader at `path`, in place. The new path must
160
+ * fit the existing `PT_INTERP` segment with its NUL terminator; the rest of
161
+ * the segment is NUL-padded, which the kernel accepts. Returns whether the
162
+ * object had an interpreter to rewrite (shared libraries have none). */
163
+ export function rewriteInterpreter(bytes: Uint8Array, path: string): boolean {
164
+ const interpreter = readElf(bytes).interpreter
165
+ if (interpreter === undefined) return false
166
+ const encoded = new TextEncoder().encode(path)
167
+ if (encoded.length + 1 > interpreter.size)
168
+ throw new ElfError(
169
+ `interpreter ${JSON.stringify(path)} needs ${encoded.length + 1} bytes but the ` +
170
+ `segment holds ${interpreter.size}`,
171
+ )
172
+ bytes.fill(0, interpreter.offset, interpreter.offset + interpreter.size)
173
+ bytes.set(encoded, interpreter.offset)
174
+ return true
175
+ }
package/src/index.ts CHANGED
@@ -13,3 +13,7 @@ export type {
13
13
  export { ensureDistributionArchiveInTrace } from './ship-packed-distribution'
14
14
  export type { EnsureOptions, EnsureResult } from './ship-packed-distribution'
15
15
  export { dispatcherEndpoint } from './runtime'
16
+ export { stageGitForDeployment } from './ship-git'
17
+ export type { StageGitHost, StagedGit } from './ship-git'
18
+ export { locateShippedGit, shippedGitExec } from './shipped-git'
19
+ export type { ShippedGit, ShippedGitManifest } from './shipped-git'
@@ -0,0 +1,558 @@
1
+ /**
2
+ * Stage a self-contained Git into the hosted dispatcher's `/api/dispatch`
3
+ * function bundle.
4
+ *
5
+ * Origin-mode node work (snapshot, restack, presence, landing) runs `git` on a
6
+ * bare clone, and the Vercel Function runtime has no `git`. This step runs in
7
+ * the deployment's build (a `linux-x64` host with Git, as Vercel's build image
8
+ * is) and copies that Git into `<project>/.autobuild-git/`:
9
+ *
10
+ * - `bin/git`, and `libexec/git-core/` with every non-builtin helper (the
11
+ * HTTPS remote helpers among them) plus plain copies of the git binary for
12
+ * the names Git re-executes (`git`, `git-upload-pack`, `git-receive-pack`,
13
+ * `git-upload-archive`);
14
+ * - `lib/`: the complete shared-library closure, glibc included, and `ld`, the
15
+ * build host's dynamic loader;
16
+ * - `ssl/ca-bundle.crt`, optional `share/git-core/templates/`, and
17
+ * `manifest.json` (see `ShippedGitManifest`).
18
+ *
19
+ * Nothing in the tree depends on the runtime's own libraries: every staged
20
+ * executable's program interpreter is rewritten in place to `<root>/ld`, a
21
+ * fixed `/tmp` path derived from the tree's content that the runtime copies the
22
+ * tree to (`shipped-git.ts`). The build then proves it: a static ELF check of
23
+ * every staged object, and a run of the copied tree with an empty `PATH` that
24
+ * clones over HTTP on loopback with `LD_DEBUG=libs`, failing on any program or
25
+ * library loaded from outside the tree. Every staged file is appended to the
26
+ * dispatch route's `route.js.nft.json`, like the distribution archive.
27
+ */
28
+ import { createHash } from 'node:crypto'
29
+ import { mkdir, mkdtemp, readdir, readFile, realpath, rm, stat, writeFile } from 'node:fs/promises'
30
+ import { tmpdir } from 'node:os'
31
+ import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
32
+ import { ElfError, isElf, readElf, rewriteInterpreter } from './elf'
33
+ import { dispatchTracePath, readTrace } from './ship-packed-distribution'
34
+ import {
35
+ materializeShippedGit,
36
+ SHIPPED_GIT_DIRECTORY,
37
+ SHIPPED_GIT_PLATFORM,
38
+ shippedGitEnv,
39
+ type ShippedGitManifest,
40
+ } from './shipped-git'
41
+
42
+ export interface HostExecResult {
43
+ stdout: string
44
+ stderr: string
45
+ exitCode: number
46
+ }
47
+
48
+ /** The build host, injectable for tests. */
49
+ export interface StageGitHost {
50
+ platform: string
51
+ arch: string
52
+ which(name: string): string | null
53
+ /** Run a command; `env` replaces the environment entirely when given. */
54
+ exec(
55
+ cmd: string[],
56
+ opts?: { cwd?: string; env?: Record<string, string> },
57
+ ): Promise<HostExecResult>
58
+ /** CA bundle locations, first existing wins. */
59
+ caCandidates: string[]
60
+ templateCandidates: string[]
61
+ /** Prefix of the runtime root; the content hash's first 8 hex follow it. */
62
+ materializeBase: string
63
+ /** The dynamic proof; defaults to `proveShippedGit`. */
64
+ prove?: (directory: string, manifest: ShippedGitManifest) => Promise<{ programs: string[] }>
65
+ }
66
+
67
+ async function hostExec(
68
+ cmd: string[],
69
+ opts: { cwd?: string; env?: Record<string, string> } = {},
70
+ ): Promise<HostExecResult> {
71
+ const proc = Bun.spawn(cmd, {
72
+ ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
73
+ env: opts.env ?? (process.env as Record<string, string>),
74
+ stdin: 'ignore',
75
+ stdout: 'pipe',
76
+ stderr: 'pipe',
77
+ })
78
+ const [stdout, stderr, exitCode] = await Promise.all([
79
+ new Response(proc.stdout).text(),
80
+ new Response(proc.stderr).text(),
81
+ proc.exited,
82
+ ])
83
+ return { stdout, stderr, exitCode }
84
+ }
85
+
86
+ export function defaultStageGitHost(
87
+ env: Record<string, string | undefined> = process.env,
88
+ ): StageGitHost {
89
+ return {
90
+ platform: process.platform,
91
+ arch: process.arch,
92
+ which: (name) => Bun.which(name),
93
+ exec: hostExec,
94
+ caCandidates: [
95
+ ...(env.SSL_CERT_FILE ? [env.SSL_CERT_FILE] : []),
96
+ '/etc/pki/tls/certs/ca-bundle.crt',
97
+ '/etc/ssl/certs/ca-certificates.crt',
98
+ '/etc/ssl/cert.pem',
99
+ ],
100
+ templateCandidates: ['/usr/share/git-core/templates'],
101
+ materializeBase: '/tmp/abg',
102
+ }
103
+ }
104
+
105
+ /** Library names glibc `dlopen`s for name resolution without `ldd` listing
106
+ * them; staged when they sit beside the host's `libc.so.6`. */
107
+ const NSS_LIBRARIES = ['libnss_files.so.2', 'libnss_dns.so.2', 'libresolv.so.2']
108
+ /** Names Git executes as the git binary itself. */
109
+ const GIT_COPIES = ['git', 'git-upload-pack', 'git-receive-pack', 'git-upload-archive']
110
+ /** glibc ≥ 2.26 supports Linux 3.2 and newer on x86_64. */
111
+ const GLIBC_KERNEL_FLOOR = '3.2.0'
112
+
113
+ export class StageGitError extends Error {}
114
+
115
+ function fail(message: string): never {
116
+ throw new StageGitError(`cannot stage Git for the hosted dispatcher: ${message}`)
117
+ }
118
+
119
+ async function sha256File(path: string): Promise<string> {
120
+ return createHash('sha256')
121
+ .update(await readFile(path))
122
+ .digest('hex')
123
+ }
124
+
125
+ async function exists(path: string): Promise<boolean> {
126
+ try {
127
+ await stat(path)
128
+ return true
129
+ } catch {
130
+ return false
131
+ }
132
+ }
133
+
134
+ async function filesUnder(directory: string): Promise<string[]> {
135
+ const out: string[] = []
136
+ for (const entry of await readdir(directory, { withFileTypes: true })) {
137
+ const path = join(directory, entry.name)
138
+ const info = await stat(path)
139
+ if (info.isDirectory()) out.push(...(await filesUnder(path)))
140
+ else if (info.isFile()) out.push(path)
141
+ }
142
+ return out
143
+ }
144
+
145
+ export interface LddEntry {
146
+ soname: string
147
+ path: string
148
+ }
149
+
150
+ /** Parse `ldd` output: the resolved libraries, the loader, and anything
151
+ * `not found`. The vDSO is skipped. */
152
+ export function parseLdd(output: string): {
153
+ libraries: LddEntry[]
154
+ loader?: string
155
+ missing: string[]
156
+ } {
157
+ const libraries: LddEntry[] = []
158
+ const missing: string[] = []
159
+ let loader: string | undefined
160
+ for (const raw of output.split('\n')) {
161
+ const line = raw.trim()
162
+ if (line === '' || line.startsWith('linux-vdso') || line.startsWith('linux-gate')) continue
163
+ const arrow = /^(\S+)\s+=>\s+(.*)$/.exec(line)
164
+ if (arrow) {
165
+ const [, soname, rest] = arrow
166
+ if (/^not found/.test(rest!)) missing.push(soname!)
167
+ else {
168
+ const path = /^(\/\S+)/.exec(rest!)?.[1]
169
+ if (path) libraries.push({ soname: soname!, path })
170
+ }
171
+ continue
172
+ }
173
+ const direct = /^(\/\S+)\s+\(0x[0-9a-f]+\)$/.exec(line)
174
+ if (direct && /\/ld-linux[^/]*\.so/.test(direct[1]!)) loader = direct[1]
175
+ }
176
+ return { libraries, ...(loader !== undefined ? { loader } : {}), missing }
177
+ }
178
+
179
+ /** Parse glibc `LD_DEBUG=libs` traces: every program initialized and every
180
+ * object tried or initialized, and those outside `root`. */
181
+ export function parseLdDebug(
182
+ text: string,
183
+ root: string,
184
+ ): { programs: string[]; objects: string[]; foreign: string[] } {
185
+ const programs: string[] = []
186
+ const objects: string[] = []
187
+ for (const line of text.split('\n')) {
188
+ const program = /initialize program: (\S+)/.exec(line)?.[1]
189
+ if (program !== undefined) programs.push(program)
190
+ const object = /(?:calling init|trying file)[:=]\s*(\S+)/.exec(line)?.[1]
191
+ if (object !== undefined) objects.push(object)
192
+ }
193
+ const inside = (path: string) => !isAbsolute(path) || path.startsWith(`${root}/`)
194
+ const foreign = [...new Set([...programs, ...objects].filter((path) => !inside(path)))]
195
+ return { programs, objects, foreign }
196
+ }
197
+
198
+ export interface StagedGit {
199
+ directory: string
200
+ manifest: ShippedGitManifest
201
+ /** Bytes of the staged tree. */
202
+ bytes: number
203
+ trace: string
204
+ /** Total bytes of the dispatch trace's distinct files after the append. */
205
+ traceBytes: number
206
+ appended: number
207
+ }
208
+
209
+ interface PlannedFile {
210
+ relative: string
211
+ source: string
212
+ executable: boolean
213
+ }
214
+
215
+ /** Stage, validate and prove the shipped Git, then append it to the dispatch
216
+ * route's trace. Every failure names the missing or incompatible piece. */
217
+ export async function stageGitForDeployment({
218
+ root,
219
+ distDir = '.next',
220
+ host = defaultStageGitHost(),
221
+ log = (message) => console.log(message),
222
+ }: {
223
+ root: string
224
+ distDir?: string
225
+ host?: StageGitHost
226
+ log?: (message: string) => void
227
+ }): Promise<StagedGit> {
228
+ const platform = `${host.platform}-${host.arch}`
229
+ if (platform !== SHIPPED_GIT_PLATFORM)
230
+ fail(
231
+ `this build host is ${platform}, but the /api/dispatch function runs on ` +
232
+ `${SHIPPED_GIT_PLATFORM} — run ship-deployment on a ${SHIPPED_GIT_PLATFORM} host ` +
233
+ '(Vercel builds stage it automatically)',
234
+ )
235
+ const git = host.which('git')
236
+ if (!git) fail('no `git` on the build host PATH')
237
+ const ldd = host.which('ldd')
238
+ if (!ldd) fail('no `ldd` on the build host PATH (it lists the libraries Git needs)')
239
+ const run = async (cmd: string[]) => {
240
+ const result = await host.exec(cmd)
241
+ if (result.exitCode !== 0)
242
+ fail(`\`${cmd.join(' ')}\` exited ${result.exitCode}: ${result.stderr.trim()}`)
243
+ return result.stdout.trim()
244
+ }
245
+ const gitVersion = (await run([git, '--version'])).replace(/^git version\s+/, '')
246
+ const execPath = await run([git, '--exec-path'])
247
+ const glibcVersion =
248
+ /(\d+\.\d+(?:\.\d+)?)\s*$/.exec((await run([ldd, '--version'])).split('\n')[0] ?? '')?.[1] ??
249
+ 'unknown'
250
+
251
+ // ── Plan the tree ─────────────────────────────────────────────────────────
252
+ const gitBinary = await realpath(git)
253
+ const gitInfo = await stat(gitBinary)
254
+ const gitHash = await sha256File(gitBinary)
255
+ const builtins = new Set([`${gitInfo.dev}:${gitInfo.ino}`])
256
+ try {
257
+ const dashed = await stat(join(execPath, 'git'))
258
+ builtins.add(`${dashed.dev}:${dashed.ino}`)
259
+ } catch {
260
+ // Some layouts keep the git binary only on PATH.
261
+ }
262
+ const planned: PlannedFile[] = [{ relative: 'bin/git', source: gitBinary, executable: true }]
263
+ const helpers = new Set<string>()
264
+ for (const name of (await readdir(execPath)).sort()) {
265
+ if (GIT_COPIES.includes(name)) continue
266
+ const path = join(execPath, name)
267
+ let info: Awaited<ReturnType<typeof stat>>
268
+ try {
269
+ info = await stat(path)
270
+ } catch {
271
+ continue
272
+ }
273
+ if (!info.isFile()) continue
274
+ // A builtin is the git binary under another name: a link, or a copy.
275
+ if (builtins.has(`${info.dev}:${info.ino}`)) continue
276
+ if (info.size === gitInfo.size && (await sha256File(path)) === gitHash) continue
277
+ planned.push({ relative: `libexec/git-core/${name}`, source: path, executable: true })
278
+ helpers.add(name)
279
+ }
280
+ if (!helpers.has('git-remote-https'))
281
+ fail(`no git-remote-https in ${execPath} — install Git's HTTPS transport on the build host`)
282
+ for (const name of GIT_COPIES)
283
+ planned.push({ relative: `libexec/git-core/${name}`, source: gitBinary, executable: true })
284
+
285
+ // Shared-library closure of every ELF executable, glibc and loader included.
286
+ const libraries = new Map<string, string>()
287
+ let loader: string | undefined
288
+ for (const file of planned) {
289
+ const bytes = new Uint8Array(await readFile(file.source))
290
+ if (!isElf(bytes)) continue
291
+ const result = await host.exec([ldd, file.source])
292
+ const parsed = parseLdd(result.stdout)
293
+ if (parsed.missing.length > 0)
294
+ fail(`ldd reports ${parsed.missing.join(', ')} not found for ${file.source}`)
295
+ for (const entry of parsed.libraries)
296
+ if (!libraries.has(entry.soname)) libraries.set(entry.soname, entry.path)
297
+ loader ??= parsed.loader
298
+ }
299
+ if (!loader) fail('ldd reported no dynamic loader for git')
300
+ const libc = libraries.get('libc.so.6')
301
+ if (libc) {
302
+ const libcDirectory = dirname(await realpath(libc))
303
+ for (const name of NSS_LIBRARIES) {
304
+ const candidate = join(libcDirectory, name)
305
+ if (!libraries.has(name) && (await exists(candidate))) libraries.set(name, candidate)
306
+ }
307
+ }
308
+ for (const [soname, path] of [...libraries].sort(([a], [b]) => a.localeCompare(b)))
309
+ planned.push({ relative: `lib/${soname}`, source: await realpath(path), executable: false })
310
+ planned.push({ relative: 'ld', source: await realpath(loader), executable: true })
311
+
312
+ let caBundle: string | undefined
313
+ for (const candidate of host.caCandidates)
314
+ if (await exists(candidate)) {
315
+ caBundle = candidate
316
+ break
317
+ }
318
+ if (!caBundle) fail(`no CA bundle found (looked in ${host.caCandidates.join(', ')})`)
319
+ planned.push({
320
+ relative: 'ssl/ca-bundle.crt',
321
+ source: await realpath(caBundle),
322
+ executable: false,
323
+ })
324
+ let templates: string | undefined
325
+ for (const candidate of host.templateCandidates) {
326
+ if (!(await exists(candidate))) continue
327
+ templates = 'share/git-core/templates'
328
+ for (const file of await filesUnder(candidate))
329
+ planned.push({
330
+ relative: `${templates}/${relative(candidate, file).split(sep).join('/')}`,
331
+ source: await realpath(file),
332
+ executable: false,
333
+ })
334
+ break
335
+ }
336
+
337
+ // ── Fixed runtime root from the tree's content ────────────────────────────
338
+ const digest = createHash('sha256')
339
+ for (const file of [...planned].sort((a, b) => a.relative.localeCompare(b.relative)))
340
+ digest.update(`${file.relative}\0${await sha256File(file.source)}\n`)
341
+ const runtimeRoot = `${host.materializeBase}${digest.digest('hex').slice(0, 8)}`
342
+ const interpreter = `${runtimeRoot}/ld`
343
+
344
+ // ── Write it, rewriting every program interpreter ─────────────────────────
345
+ const directory = join(root, SHIPPED_GIT_DIRECTORY)
346
+ await rm(directory, { recursive: true, force: true })
347
+ let bytes = 0
348
+ for (const file of planned) {
349
+ const content = new Uint8Array(await readFile(file.source))
350
+ if (isElf(content)) {
351
+ try {
352
+ rewriteInterpreter(content, interpreter)
353
+ } catch (error) {
354
+ if (error instanceof ElfError)
355
+ fail(`${file.relative} (from ${file.source}): ${error.message}`)
356
+ throw error
357
+ }
358
+ }
359
+ const target = join(directory, file.relative)
360
+ await mkdir(dirname(target), { recursive: true })
361
+ await writeFile(target, content, { mode: file.executable ? 0o755 : 0o644 })
362
+ bytes += content.length
363
+ }
364
+ const staticCheck = await validateStagedTree(directory, interpreter, basename(loader))
365
+ const manifest: ShippedGitManifest = {
366
+ schema: 1,
367
+ platform: SHIPPED_GIT_PLATFORM,
368
+ gitVersion,
369
+ glibcVersion,
370
+ minimumKernel: staticCheck.minimumKernel ?? GLIBC_KERNEL_FLOOR,
371
+ root: runtimeRoot,
372
+ git: 'bin/git',
373
+ execPath: 'libexec/git-core',
374
+ lib: 'lib',
375
+ caBundle: 'ssl/ca-bundle.crt',
376
+ ...(templates !== undefined ? { templates } : {}),
377
+ files: planned.map((file) => file.relative),
378
+ executables: planned.filter((file) => file.executable).map((file) => file.relative),
379
+ bytes,
380
+ }
381
+ const rawManifest = `${JSON.stringify(manifest, null, 2)}\n`
382
+ await writeFile(join(directory, 'manifest.json'), rawManifest)
383
+ bytes += Buffer.byteLength(rawManifest)
384
+
385
+ const proof = await (host.prove ?? ((dir, m) => proveShippedGit(dir, m, host)))(
386
+ directory,
387
+ manifest,
388
+ )
389
+ log(
390
+ `shipped Git proof: ${proof.programs.map((program) => relative(runtimeRoot, program)).join(', ')} ` +
391
+ `ran from ${runtimeRoot} with nothing loaded from the build host`,
392
+ )
393
+
394
+ // ── Carry it into the dispatch function ───────────────────────────────────
395
+ const trace = dispatchTracePath(root, distDir)
396
+ const files = await readTrace(trace)
397
+ const entries = [...manifest.files, 'manifest.json'].map((file) =>
398
+ relative(dirname(trace), join(directory, file)),
399
+ )
400
+ const added = entries.filter((entry) => !files.includes(entry))
401
+ if (added.length > 0) {
402
+ const parsed = JSON.parse(await readFile(trace, 'utf8'))
403
+ await writeFile(
404
+ trace,
405
+ `${JSON.stringify({ ...parsed, files: [...files, ...added] }, null, 2)}\n`,
406
+ )
407
+ }
408
+ let traceBytes = 0
409
+ for (const entry of new Set([...files, ...added].map((file) => resolve(dirname(trace), file)))) {
410
+ try {
411
+ const info = await stat(entry)
412
+ if (info.isFile()) traceBytes += info.size
413
+ } catch {
414
+ // Next may list optional files it did not emit.
415
+ }
416
+ }
417
+ const megabytes = (value: number) => (value / 1024 / 1024).toFixed(1)
418
+ log(
419
+ `git ${gitVersion} (glibc ${glibcVersion}) for ${SHIPPED_GIT_PLATFORM} staged at ${directory}: ` +
420
+ `${entries.length} files, ${megabytes(bytes)} MB added to ${trace}`,
421
+ )
422
+ log(`dispatch function trace now totals ${megabytes(traceBytes)} MB`)
423
+ return { directory, manifest, bytes, trace, traceBytes, appended: added.length }
424
+ }
425
+
426
+ /** The static half of the target-compatibility gate: every staged ELF is
427
+ * x86_64 ELF64, names `interpreter` as its loader if it names one, finds
428
+ * every needed library in `lib/`, and searches no absolute path outside the
429
+ * tree. Returns the bundled glibc's kernel floor from its ABI note. */
430
+ export async function validateStagedTree(
431
+ directory: string,
432
+ interpreter: string,
433
+ loaderSoname: string,
434
+ ): Promise<{ minimumKernel?: string }> {
435
+ const libraries = new Set(await readdir(join(directory, 'lib')))
436
+ const runtimeRoot = dirname(interpreter)
437
+ let minimumKernel: string | undefined
438
+ for (const path of await filesUnder(directory)) {
439
+ const name = relative(directory, path).split(sep).join('/')
440
+ const bytes = new Uint8Array(await readFile(path))
441
+ if (!isElf(bytes)) continue
442
+ let info: ReturnType<typeof readElf>
443
+ try {
444
+ info = readElf(bytes)
445
+ } catch (error) {
446
+ fail(`${name}: ${error instanceof Error ? error.message : String(error)}`)
447
+ }
448
+ if (info.interpreter !== undefined && info.interpreter.path !== interpreter)
449
+ fail(`${name} still names the program loader ${info.interpreter.path}, not ${interpreter}`)
450
+ for (const needed of info.needed)
451
+ if (!libraries.has(needed) && needed !== loaderSoname)
452
+ fail(`${name} needs ${needed}, which is not in lib/`)
453
+ for (const entry of [...info.rpath, ...info.runpath])
454
+ if (isAbsolute(entry) && !entry.startsWith(`${runtimeRoot}/`))
455
+ fail(`${name} searches ${entry} outside the shipped tree`)
456
+ if (name === 'lib/libc.so.6' && info.abiTag?.os === 0) minimumKernel = info.abiTag.kernel
457
+ }
458
+ return minimumKernel !== undefined ? { minimumKernel } : {}
459
+ }
460
+
461
+ /** The dynamic half: copy the tree to its runtime root exactly as the function
462
+ * does, then with an empty `PATH` and `LD_DEBUG=libs` run Git end to end —
463
+ * `--version`, a bare repository built from builtins, and a dumb-HTTP clone of
464
+ * it from an in-process loopback server through the shipped `git-remote-http`.
465
+ * Fails on any program or library loaded from outside the tree. */
466
+ export async function proveShippedGit(
467
+ directory: string,
468
+ manifest: ShippedGitManifest,
469
+ host: Pick<StageGitHost, 'exec'>,
470
+ ): Promise<{ programs: string[] }> {
471
+ const raw = await readFile(join(directory, 'manifest.json'), 'utf8')
472
+ const root = manifest.root
473
+ const scratch = await mkdtemp(join(tmpdir(), 'ab-git-proof-'))
474
+ let server: ReturnType<typeof Bun.serve> | undefined
475
+ try {
476
+ await materializeShippedGit(directory, manifest, raw)
477
+ await mkdir(join(scratch, 'ld'))
478
+ const env: Record<string, string> = {
479
+ ...shippedGitEnv({ root, manifest }),
480
+ PATH: '/nonexistent',
481
+ GIT_ALLOW_PROTOCOL: 'http:https',
482
+ HOME: scratch,
483
+ LD_DEBUG: 'libs',
484
+ LD_DEBUG_OUTPUT: join(scratch, 'ld', 'trace'),
485
+ }
486
+ const gitPath = join(root, manifest.git)
487
+ const git = async (args: string[], expectSuccess = true) => {
488
+ const result = await host.exec([gitPath, ...args], { cwd: scratch, env })
489
+ if (expectSuccess && result.exitCode !== 0)
490
+ fail(
491
+ `the shipped Git failed \`git ${args.join(' ')}\` (exit ${result.exitCode}): ${result.stderr.trim()}`,
492
+ )
493
+ return result
494
+ }
495
+ await git(['--version'])
496
+ const source = join(scratch, 'src.git')
497
+ await git(['init', '--bare', '--quiet', source])
498
+ const tree = (await git(['-C', source, 'mktree'])).stdout.trim()
499
+ const commit = (
500
+ await git([
501
+ '-C',
502
+ source,
503
+ '-c',
504
+ 'user.name=ab',
505
+ '-c',
506
+ 'user.email=ab@invalid',
507
+ 'commit-tree',
508
+ tree,
509
+ '-m',
510
+ 'shipped Git proof',
511
+ ])
512
+ ).stdout.trim()
513
+ await git(['-C', source, 'update-ref', 'refs/heads/main', commit])
514
+ await git(['-C', source, 'symbolic-ref', 'HEAD', 'refs/heads/main'])
515
+ await git(['-C', source, 'update-server-info'])
516
+ server = Bun.serve({
517
+ hostname: '127.0.0.1',
518
+ port: 0,
519
+ async fetch(request) {
520
+ const path = resolve(scratch, `.${decodeURIComponent(new URL(request.url).pathname)}`)
521
+ if (!path.startsWith(`${scratch}/`)) return new Response('not found', { status: 404 })
522
+ const file = Bun.file(path)
523
+ return (await file.exists())
524
+ ? new Response(file)
525
+ : new Response('not found', { status: 404 })
526
+ },
527
+ })
528
+ const clone = join(scratch, 'out.git')
529
+ await git(['clone', '--bare', '--quiet', `http://127.0.0.1:${server.port}/src.git`, clone])
530
+ const cloned = (await git(['-C', clone, 'rev-parse', 'refs/heads/main'])).stdout.trim()
531
+ if (cloned !== commit)
532
+ fail(`the shipped Git's loopback clone resolved main to ${cloned}, not ${commit}`)
533
+ const helper = await host.exec([join(root, manifest.execPath, 'git-remote-https')], {
534
+ cwd: scratch,
535
+ env,
536
+ })
537
+ if (
538
+ helper.exitCode === 126 ||
539
+ helper.exitCode === 127 ||
540
+ helper.stderr.includes('error while loading shared libraries')
541
+ )
542
+ fail(
543
+ `the shipped git-remote-https cannot run (exit ${helper.exitCode}): ${helper.stderr.trim()}`,
544
+ )
545
+ let traces = ''
546
+ for (const name of await readdir(join(scratch, 'ld')))
547
+ traces += await readFile(join(scratch, 'ld', name), 'utf8')
548
+ const parsed = parseLdDebug(traces, root)
549
+ if (parsed.programs.length === 0) fail('LD_DEBUG recorded no programs for the shipped Git')
550
+ if (parsed.foreign.length > 0)
551
+ fail(`the shipped Git loaded from outside ${root}: ${parsed.foreign.join(', ')}`)
552
+ return { programs: [...new Set(parsed.programs)] }
553
+ } finally {
554
+ await server?.stop(true)
555
+ await rm(scratch, { recursive: true, force: true })
556
+ await rm(root, { recursive: true, force: true })
557
+ }
558
+ }
@@ -62,6 +62,11 @@ const ROUTE_DIRECTORY = join('server', 'app', 'api', 'dispatch')
62
62
  /** The operator HTTP route; retained legacy skill trace entry. */
63
63
  const OPERATOR_ROUTE_DIRECTORY = join('server', 'app', 'operator', '[[...path]]')
64
64
 
65
+ /** The `/api/dispatch` route's Next.js trace file under a project. */
66
+ export function dispatchTracePath(root: string, distDir = '.next'): string {
67
+ return join(root, distDir, ROUTE_DIRECTORY, TRACE_FILE)
68
+ }
69
+
65
70
  /** The single packed archive under `<root>/.autobuild-dist/`. */
66
71
  export async function findArchive(root: string): Promise<string> {
67
72
  const dist = join(root, DIST_DIRECTORY)
@@ -90,7 +95,7 @@ export async function findArchive(root: string): Promise<string> {
90
95
  return join(dist, archives[0]!)
91
96
  }
92
97
 
93
- async function readTrace(path: string): Promise<string[]> {
98
+ export async function readTrace(path: string): Promise<string[]> {
94
99
  let raw: string
95
100
  try {
96
101
  raw = await readFile(path, 'utf8')
@@ -0,0 +1,296 @@
1
+ /**
2
+ * The Git a hosted dispatcher deployment ships (see `ship-git.ts`), found and
3
+ * unpacked at run time. The Vercel Function runtime has no `git`, so every
4
+ * kernel Git command of a dispatch tick is routed to this tree instead of the
5
+ * host `PATH`.
6
+ *
7
+ * The tree carries its own glibc and dynamic loader, and every staged
8
+ * executable's program interpreter is baked to `<root>/ld`, where `root` is a
9
+ * fixed `/tmp` path recorded in the manifest. The bundle directory itself is
10
+ * read-only and lives elsewhere, so the tree is copied to `root` once per
11
+ * function instance before it can run.
12
+ *
13
+ * Kernel shell pipelines (`sh -c '… | git …'`) reach the same Git through a
14
+ * `git` launcher, `<root>/shim/git`, that is put on their `PATH`. The shell and
15
+ * the other host programs it starts keep the host's own libraries; only the
16
+ * launcher applies the tree's environment, to Git alone.
17
+ */
18
+ import { createHash, randomBytes } from 'node:crypto'
19
+ import { chmod, cp, mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises'
20
+ import { release } from 'node:os'
21
+ import { dirname, join } from 'node:path'
22
+ import { distributionRoot } from '@defrex/autobuild/distribution'
23
+ import type { Exec } from '@defrex/autobuild/git-worktree'
24
+
25
+ export const SHIPPED_GIT_DIRECTORY = '.autobuild-git'
26
+ export const SHIPPED_GIT_PLATFORM = 'linux-x64'
27
+ /** The tree directory holding only the `git` launcher for shells. */
28
+ export const SHIPPED_GIT_SHIM_DIRECTORY = 'shim'
29
+ const COMPLETE_MARKER = '.complete'
30
+ /** Tree-confinement keys a caller can never override; the rest of
31
+ * `shippedGitEnv` is a default. */
32
+ const FORCED_KEYS = ['GIT_EXEC_PATH', 'LD_LIBRARY_PATH', 'GIT_TEMPLATE_DIR', 'PATH'] as const
33
+
34
+ /** `.autobuild-git/manifest.json`. Paths other than `root` are relative to the
35
+ * tree. */
36
+ export interface ShippedGitManifest {
37
+ schema: 1
38
+ platform: typeof SHIPPED_GIT_PLATFORM
39
+ gitVersion: string
40
+ glibcVersion: string
41
+ /** Oldest Linux kernel the bundled glibc supports, `major.minor.patch`. */
42
+ minimumKernel: string
43
+ /** Absolute directory the tree must be copied to before it runs; every
44
+ * staged executable's interpreter is `<root>/ld`. */
45
+ root: string
46
+ git: string
47
+ execPath: string
48
+ lib: string
49
+ caBundle: string
50
+ templates?: string
51
+ files: string[]
52
+ executables: string[]
53
+ bytes: number
54
+ }
55
+
56
+ export interface ShippedGit {
57
+ /** The materialized tree (the manifest's `root`). */
58
+ root: string
59
+ manifest: ShippedGitManifest
60
+ }
61
+
62
+ export type LocateShippedGitResult = { ok: true; git: ShippedGit } | { ok: false; reason: string }
63
+
64
+ /** Parse a `major.minor.patch` version prefix (`6.1.0-amzn…` → [6, 1, 0]). */
65
+ function versionParts(value: string): number[] {
66
+ const match = /^(\d+)(?:\.(\d+))?(?:\.(\d+))?/.exec(value)
67
+ if (!match) return []
68
+ return [match[1], match[2], match[3]].map((part) => Number(part ?? 0))
69
+ }
70
+
71
+ export function kernelAtLeast(running: string, minimum: string): boolean {
72
+ const have = versionParts(running)
73
+ const need = versionParts(minimum)
74
+ if (have.length === 0 || need.length === 0) return false
75
+ for (let index = 0; index < 3; index++) {
76
+ if (have[index]! !== need[index]!) return have[index]! > need[index]!
77
+ }
78
+ return true
79
+ }
80
+
81
+ export function parseShippedGitManifest(raw: string): ShippedGitManifest {
82
+ const value = JSON.parse(raw) as Partial<ShippedGitManifest>
83
+ if (value.schema !== 1) throw new Error(`unsupported manifest schema ${String(value.schema)}`)
84
+ for (const key of [
85
+ 'platform',
86
+ 'gitVersion',
87
+ 'glibcVersion',
88
+ 'minimumKernel',
89
+ 'root',
90
+ 'git',
91
+ 'execPath',
92
+ 'lib',
93
+ 'caBundle',
94
+ ] as const)
95
+ if (typeof value[key] !== 'string' || value[key] === '')
96
+ throw new Error(`manifest is missing ${key}`)
97
+ if (!Array.isArray(value.files) || !Array.isArray(value.executables))
98
+ throw new Error('manifest is missing its file lists')
99
+ return value as ShippedGitManifest
100
+ }
101
+
102
+ function manifestHash(raw: string): string {
103
+ return createHash('sha256').update(raw).digest('hex')
104
+ }
105
+
106
+ /** Copy the staged tree at `source` to `manifest.root`, unless a complete
107
+ * copy of the same manifest is already there. Concurrent callers race on a
108
+ * private temporary copy and one `rename`; the loser keeps the winner's tree. */
109
+ export async function materializeShippedGit(
110
+ source: string,
111
+ manifest: ShippedGitManifest,
112
+ raw: string,
113
+ ): Promise<void> {
114
+ const root = manifest.root
115
+ const shim = shippedGitShim({ root, manifest })
116
+ // The launcher is part of the tree's identity, so a tree an older
117
+ // deployment unpacked without it reads as stale and is replaced.
118
+ const hash = manifestHash(`${raw}\0${shim}`)
119
+ const complete = async () => {
120
+ try {
121
+ return (await readFile(join(root, COMPLETE_MARKER), 'utf8')) === hash
122
+ } catch {
123
+ return false
124
+ }
125
+ }
126
+ if (await complete()) return
127
+ const temporary = `${root}.tmp-${process.pid}-${randomBytes(4).toString('hex')}`
128
+ try {
129
+ await mkdir(dirname(root), { recursive: true })
130
+ await rm(temporary, { recursive: true, force: true })
131
+ await cp(source, temporary, { recursive: true, dereference: true })
132
+ for (const file of manifest.executables) await chmod(join(temporary, file), 0o755)
133
+ await mkdir(join(temporary, SHIPPED_GIT_SHIM_DIRECTORY), { recursive: true })
134
+ await writeFile(join(temporary, SHIPPED_GIT_SHIM_DIRECTORY, 'git'), shim, { mode: 0o755 })
135
+ await chmod(join(temporary, SHIPPED_GIT_SHIM_DIRECTORY, 'git'), 0o755)
136
+ await writeFile(join(temporary, COMPLETE_MARKER), hash)
137
+ try {
138
+ await rename(temporary, root)
139
+ } catch (error) {
140
+ // Another instance won the rename. Its tree is good when complete; a
141
+ // stale or partial one (a different deployment's crash) is replaced.
142
+ if (await complete()) return
143
+ const code = (error as NodeJS.ErrnoException).code
144
+ if (code !== 'EEXIST' && code !== 'ENOTEMPTY') throw error
145
+ await rm(root, { recursive: true, force: true })
146
+ await rename(temporary, root)
147
+ }
148
+ } finally {
149
+ await rm(temporary, { recursive: true, force: true })
150
+ }
151
+ }
152
+
153
+ export interface LocateShippedGitOptions {
154
+ /** Directories that may hold `.autobuild-git/`; the first one wins. */
155
+ roots?: readonly string[]
156
+ platform?: string
157
+ arch?: string
158
+ /** The running kernel release (`os.release()`). */
159
+ kernel?: string
160
+ }
161
+
162
+ /** Find the deployment's shipped Git and make it runnable. Each failure names
163
+ * its cause: no manifest, wrong platform, a kernel older than the bundled
164
+ * glibc supports, or a `/tmp` that cannot hold the tree. */
165
+ export async function locateShippedGit(
166
+ options: LocateShippedGitOptions = {},
167
+ ): Promise<LocateShippedGitResult> {
168
+ const roots = [...new Set(options.roots ?? [distributionRoot(), process.cwd()])]
169
+ let found: { directory: string; raw: string } | undefined
170
+ for (const root of roots) {
171
+ const directory = join(root, SHIPPED_GIT_DIRECTORY)
172
+ try {
173
+ found = { directory, raw: await readFile(join(directory, 'manifest.json'), 'utf8') }
174
+ break
175
+ } catch {
176
+ // Try the next root.
177
+ }
178
+ }
179
+ if (!found)
180
+ return {
181
+ ok: false,
182
+ reason: `no ${SHIPPED_GIT_DIRECTORY}/manifest.json under ${roots.join(', ')}`,
183
+ }
184
+ let manifest: ShippedGitManifest
185
+ try {
186
+ manifest = parseShippedGitManifest(found.raw)
187
+ } catch (error) {
188
+ return {
189
+ ok: false,
190
+ reason: `invalid ${found.directory}/manifest.json: ${error instanceof Error ? error.message : String(error)}`,
191
+ }
192
+ }
193
+ const platform = options.platform ?? process.platform
194
+ const arch = options.arch ?? process.arch
195
+ if (`${platform}-${arch}` !== manifest.platform)
196
+ return {
197
+ ok: false,
198
+ reason: `shipped Git targets ${manifest.platform}, but this runtime is ${platform}-${arch}`,
199
+ }
200
+ const kernel = options.kernel ?? release()
201
+ if (!kernelAtLeast(kernel, manifest.minimumKernel))
202
+ return {
203
+ ok: false,
204
+ reason: `shipped Git needs Linux ${manifest.minimumKernel} or newer, but this runtime is ${kernel}`,
205
+ }
206
+ try {
207
+ await materializeShippedGit(found.directory, manifest, found.raw)
208
+ await stat(join(manifest.root, manifest.git))
209
+ } catch (error) {
210
+ return {
211
+ ok: false,
212
+ reason: `could not unpack shipped Git to ${manifest.root} (is /tmp writable?): ${error instanceof Error ? error.message : String(error)}`,
213
+ }
214
+ }
215
+ return { ok: true, git: { root: manifest.root, manifest } }
216
+ }
217
+
218
+ let memo: Promise<LocateShippedGitResult> | undefined
219
+ /** `locateShippedGit` once per process; a failure is retried next time. */
220
+ export function locateShippedGitOnce(): Promise<LocateShippedGitResult> {
221
+ memo ??= locateShippedGit()
222
+ const attempt = memo
223
+ void attempt.then((result) => {
224
+ if (!result.ok && memo === attempt) memo = undefined
225
+ })
226
+ return attempt
227
+ }
228
+
229
+ /** The environment that runs the shipped Git and confines it to its own tree:
230
+ * its libraries, its helpers, its CA bundle, no system or global config, and
231
+ * HTTPS as the only transport, so it never starts a host program (a shell,
232
+ * ssh, a credential helper) under the bundled glibc. */
233
+ export function shippedGitEnv(
234
+ git: ShippedGit,
235
+ inherited: { PATH?: string } = {},
236
+ ): Record<string, string> {
237
+ const { root, manifest } = git
238
+ return {
239
+ GIT_EXEC_PATH: join(root, manifest.execPath),
240
+ LD_LIBRARY_PATH: join(root, manifest.lib),
241
+ GIT_SSL_CAINFO: join(root, manifest.caBundle),
242
+ ...(manifest.templates !== undefined
243
+ ? { GIT_TEMPLATE_DIR: join(root, manifest.templates) }
244
+ : {}),
245
+ GIT_CONFIG_NOSYSTEM: '1',
246
+ GIT_CONFIG_GLOBAL: '/dev/null',
247
+ GIT_ALLOW_PROTOCOL: 'https',
248
+ PATH: [join(root, dirname(manifest.git)), inherited.PATH]
249
+ .filter((entry) => entry !== undefined && entry !== '')
250
+ .join(':'),
251
+ }
252
+ }
253
+
254
+ function shellQuote(value: string): string {
255
+ return `'${value.replaceAll("'", `'\\''`)}'`
256
+ }
257
+
258
+ /** The `<root>/shim/git` launcher: it applies `shippedGitEnv` (without `PATH`)
259
+ * to Git alone and runs the shipped binary. Forced keys are assigned; the
260
+ * others keep a caller's value, as they do for direct `git`. */
261
+ export function shippedGitShim(git: ShippedGit): string {
262
+ const forced = new Set<string>(FORCED_KEYS)
263
+ const lines = ['#!/bin/sh']
264
+ for (const [key, value] of Object.entries(shippedGitEnv(git))) {
265
+ if (key === 'PATH') continue
266
+ lines.push(
267
+ forced.has(key)
268
+ ? `export ${key}=${shellQuote(value)}`
269
+ : `[ -n "\${${key}+set}" ] || ${key}=${shellQuote(value)}; export ${key}`,
270
+ )
271
+ }
272
+ lines.push(`exec ${shellQuote(join(git.root, git.manifest.git))} "$@"`, '')
273
+ return lines.join('\n')
274
+ }
275
+
276
+ /** Route `git` commands to the shipped Git. Everything else (the `gh` probe, a
277
+ * kernel `sh -c` pipeline) runs on the host's own libraries, with the tree's
278
+ * `shim/` first on `PATH` so a `git` it starts is the shipped one. Caller-provided
279
+ * `GIT_SSL_CAINFO` and `GIT_ALLOW_PROTOCOL` win; the library path, exec path and
280
+ * config isolation always come from the tree. `kernelExec`'s `GIT_CONFIG_*`
281
+ * keys pass through. */
282
+ export function shippedGitExec(base: Exec, git: ShippedGit, inherited: { PATH?: string }): Exec {
283
+ const env = shippedGitEnv(git, inherited)
284
+ const shim = join(git.root, SHIPPED_GIT_SHIM_DIRECTORY)
285
+ return (cmd, opts) => {
286
+ if (cmd[0] !== 'git') {
287
+ const path = [shim, opts.env?.PATH ?? inherited.PATH]
288
+ .filter((entry) => entry !== undefined && entry !== '')
289
+ .join(':')
290
+ return base(cmd, { ...opts, env: { ...opts.env, PATH: path } })
291
+ }
292
+ const merged: Record<string, string | undefined> = { ...env, ...opts.env }
293
+ for (const key of FORCED_KEYS) if (env[key] !== undefined) merged[key] = env[key]
294
+ return base([join(git.root, git.manifest.git), ...cmd.slice(1)], { ...opts, env: merged })
295
+ }
296
+ }