// Read one file or one directory listing from a remote, without a clone: ls-refs → the commit (tree:0, deepen 1) → one // tree per path level → the blob, STREAMED (inflate, then the caller). The latest chunk is held until the object // hash and the pack trailer verify; a failure errors the stream without releasing it. Built from the same // primitives as edit.js; carries no push, merge or pack-building code (asserted by test/bundle.test.js). // // readFile(url, { ref, path }, opts) → { ref, commit, blob, mode, size, stream } stream: ReadableStream // listTree(url, { ref, path }, opts) → { ref, commit, tree, entries: [{ name, mode, oid, type }] } // readCommit(url, { ref }, opts) → { ref, oid, tree, parents, author, committer, message, signed } (no trees fetched // unless the server refuses tree:0; then the blob:none fallback applies) // an unborn HEAD, or that branch by name, is { empty: true, ref } — a state, not not_found // walkPath(transport, treeOid, comps, { cache }) → Result<{ tree, entry }, PlyError> one tree per component, from a tree // the caller already has. not_found carries miss (ref, path, directory, submodule, …). // walkCommit(transport, commitOid, comps, { cache, levels }) → Result<{ commit, data, tree, entry }, PlyError> the // commit and the path's trees, the first levels in the commit's own fetch where taken. // // `ref`: null/'HEAD' (the remote's HEAD), a full ref name, a short name resolved the way `git rev-parse` does it for a // remote's refs (refs/, refs/tags/, refs/heads/ — tags win over branches, as in git), or a 40-hex commit oid. // `{ abbrev: 'advertised' }` also accepts a 4–39 character lowercase hex prefix, unique among the tips that one ls-refs // lists (HEAD, branches, tags, and peeled targets). A ref name wins over a prefix, as in git. The default `'off'` // leaves a short hex string as a ref name. That answer is weaker than `git rev-parse`: an interior object is not a // candidate. Annotated tags are peeled. `size` is known before the first content byte (the pack object header carries it), so a // caller can send Content-Length. The stream errors (never ends cleanly) if the content does not hash to the blob's oid // or the server sends a different number of bytes than it declared, and the chunk that would have completed the body // stays held: a consumer that received every byte, or saw `done`, saw the right bytes. // openBlob(transport, oid, { maxBytes, follows }) → Result<{ kind:'stream', size, stream } | { kind:'too_big', size }, PlyError> // readBlob(transport, oid, { maxBytes, follows }) → Result<{ kind:'bytes', data } | { kind:'too_big', size }, PlyError> // `too_big` is decided from the pack object header. The fetch is cancelled and no body byte is delivered. // // Errors are values: every function here returns a Result (docs/STACK.md "Public API policy"). The blob stream errors // as a stream does: its pull, transform and flush raise the PlyError the consumer reads. /* oxlint-disable import/max-dependencies -- an entry composes the protocol from one import per module, so its bundle carries nothing else */ import { fail, isPlyCode, isPlyError, plyError } from './errors.js'; import type { ErrorOf, Miss, PlyError } from './errors.js'; import { assertNever, err, getOrElse, isSome, map, mapOption, none, ok, some } from './result.js'; import type { Err, Option, Result } from './result.js'; import { operation } from './operation.js'; import { lsRefs, parseUnbornLine, type LsRefsResult } from './lsrefs.js'; import { discover } from './discover.js'; import { packStream, objectAt, objectId, spInit, spStep, spFinish, treeEntries } from './fetch.js'; import { parseCommit, parseIdent, parseTree, objectHeader, TYPE, TYPE_NAME } from './objects.js'; import { streamingSha1 } from './sha1.js'; import { bufferSource, concat } from './bytes.js'; import { KIND, spanOn } from './otel.js'; import type { Span } from './otel.js'; import { DEFAULT_LIMITS, limitsOf } from './limits.js'; import type { CheckedLimits, LimitsInput } from './limits.js'; import { validateRef, validatePath } from './validate.js'; import type { SpState, SpStepped } from './fetch.js'; import type { Transport } from './transport.js'; import { raised } from './transport.js'; import type { TreeEntry } from './objects.js'; import { isPlyThrown, thrownCodeOr, thrownText } from './boundary.js'; import { commitById } from './commit.js'; import { commitForWalk } from './pathtrees.js'; import { parseOid, type Oid } from './oid.js'; import type { EntryOptions, TypeNames } from './boundary.js'; import { at, fromNullable, fromNullish, mapGet, readKey, withDefaults } from './absent.js'; import type { Input } from './absent.js'; /* oxlint-disable no-await-in-loop -- a stream is consumed in order: each write waits for the inflate side (back-pressure) */ /* oxlint-disable require-await -- the entry points are async: a refused argument is an Err in a promise, like every other answer */ /* oxlint-disable unicorn/explicit-length-check, require-unicode-regexp, typescript/prefer-includes -- bundle budget: the JS's truthy length checks and non-unicode regexes, byte for byte (no behaviour change); RegExp#test, not includes: a thrown value's message may be no string at run time */ const OID = /^[0-9a-f]{40}$/; // null or the platform's missing value: what a caller's `ref` or `path` left out. const isNothing = (v: unknown): boolean => fromNullish(v).tag === 'none'; // Pure: what to ask ls-refs for, and which answer wins. git's ref_rev_parse_rules minus the remote-tracking forms. // `ref` is the caller's, checked here: anything but null, the missing value or a string is bad_request. export function refCandidates(ref: unknown): Result { if (isNothing(ref) || ref === '' || ref === 'HEAD') return ok(['HEAD']); if (typeof ref !== 'string') return fail('bad_request', 'ref must be a string'); if (OID.test(ref)) return ok([]); const names = ref.startsWith('refs/') ? [ref] : [`refs/${ref}`, `refs/tags/${ref}`, `refs/heads/${ref}`]; const out: string[] = []; for (const name of names) { const valid = validateRef(name); if (!valid.ok) return valid; out.push(valid.value); } return ok(out); } // git ls-tree's object types. export type EntryType = 'tree' | 'commit' | 'blob'; // Pure: git ls-tree's type for a tree entry mode. export const entryType = (mode: string): EntryType => { if (mode === '40000') return 'tree'; return mode === '160000' ? 'commit' : 'blob'; }; // Pure: git ls-tree prints modes as %06o (trees as 040000); the tree object stores them without the leading zero. export const lsMode = (mode: string): string => mode.padStart(6, '0'); // The caller's name and the unborn target name the same branch: HEAD, the full ref, or the short branch name. const sameBranch = (requested: unknown, full: string): boolean => { const name = isNothing(requested) || requested === '' ? 'HEAD' : requested; return typeof name === 'string' && (name === full || name === 'HEAD' || (!name.startsWith('refs/') && full === `refs/heads/${name}`)); }; // Effect: the unborn HEAD's target, or None when the server does not advertise ls-refs=unborn or lists no unborn line // (a deleted branch, a born HEAD). discover runs only on a ref miss; the happy path never asks. async function unbornTarget(t: Transport): Promise, PlyError>> { const info = await discover(t); if (!info.ok) return info; if (!info.value.lsRefsUnborn) return ok(none); const listed = await lsRefs(t, ['HEAD'], { unborn: parseUnbornLine }); if (!listed.ok) return listed; const target = mapOption(fromNullish(listed.value.unborn), u => u.target); return ok(getOrElse(target, '') === '' ? none : target); } // A ref as the caller names it: null or 'HEAD' for the remote's HEAD (as is '' or leaving it out), a name, or a 40-hex oid. export type RefSpec = string | null; export type Resolved = { readonly name: string; readonly commit: Oid }; // How far a short hex string is an object id. `'off'` (the default): it is a ref name. `'advertised'`: after the name // misses, it is a prefix of an advertised tip. export type AbbrevMode = 'advertised' | 'off'; const ABBREV = /^[0-9a-f]{4,39}$/; // Pure, over one ls-refs answer. `unique_among_advertised` is one oid (the ref names are every listing that carried it, // as the oid or as a peeled target). `none`: no advertised oid starts with the prefix. `ambiguous`: more than one oid does. // A bad prefix (not 4..39 lowercase hex) is `bad_request`, not a kind. export type AbbrevResolution = | { readonly kind: 'unique_among_advertised'; readonly oid: Oid; readonly refs: readonly string[] } | { readonly kind: 'none' } | { readonly kind: 'ambiguous'; readonly oids: readonly Oid[] }; export function resolveAbbrev(prefix: string, listed: LsRefsResult): Result { if (!ABBREV.test(prefix)) return fail('bad_request', 'abbreviated oid must be 4..39 lowercase hex', { what: 'ref' }); const byOid = new Map(); for (const rec of listed.refs.values()) { const peeled = fromNullish(rec.peeled); const hits: ReadonlyArray = peeled.tag === 'none' ? [[rec.oid, rec.name]] : [[rec.oid, rec.name], [peeled.value, rec.name]]; for (const [oid, name] of hits) { if (!oid.startsWith(prefix)) continue; const names = mapGet(byOid, oid); if (names.tag === 'none') byOid.set(oid, [name]); else if (!names.value.includes(name)) names.value.push(name); } } const oids = [...byOid.keys()].toSorted(); const oid = at(oids, 0); if (oid.tag === 'none') return ok({ kind: 'none' }); if (oids.length > 1) return ok({ kind: 'ambiguous', oids }); return ok({ kind: 'unique_among_advertised', oid: oid.value, refs: getOrElse(mapGet(byOid, oid.value), []) }); } // The name missed. A unique advertised oid is that commit; more than one is bad_request; none leaves the caller to // report not_found. The prefix already matched ABBREV, so resolveAbbrev's own bad_request does not run. function advertisedCommit(prefix: string, listed: LsRefsResult): Result, PlyError> { const resolved = resolveAbbrev(prefix, listed); if (!resolved.ok) return resolved; const found = resolved.value; switch (found.kind) { case 'unique_among_advertised': return ok(some({ name: found.oid, commit: found.oid })); case 'ambiguous': return fail('bad_request', `abbreviated oid ${prefix} matches ${found.oids.length} advertised objects`, { what: 'ref', got: found.oids }); case 'none': return ok(none); } // Stryker disable next-line ConditionalExpression: unreachable, the compiler's exhaustiveness check return assertNever(found); } // One ls-refs. `hit` is the ref name, a bare oid, or a unique advertised prefix. `miss` is the name not listed and the // prefix not unique. The abbrev refusal lives here so resolveCommit's only fail() is not_found. type Lookup = { readonly kind: 'hit'; readonly resolved: Resolved } | { readonly kind: 'miss'; readonly candidates: readonly string[] }; async function lookupRef(t: Transport, ref: unknown, abbrev: AbbrevMode): Promise> { if (abbrev !== 'off' && abbrev !== 'advertised') return fail('bad_request', 'abbrev must be "advertised" or "off"', { what: 'abbrev' }); // a 40-hex oid is taken as given, parsed once here (refCandidates answers no name for one) const id = parseOid(ref); if (id.ok) return ok({ kind: 'hit', resolved: { name: id.value, commit: id.value } }); const named = refCandidates(ref); if (!named.ok) return named; const cands = named.value; // null: this call is a name. A string: the prefix, and the listing is wide enough to answer it. const prefix = abbrev === 'advertised' && typeof ref === 'string' && ABBREV.test(ref) ? ref : null; const listing = await lsRefs(t, prefix === null ? cands : [...cands, 'HEAD', 'refs/heads/', 'refs/tags/']); if (!listing.ok) return listing; const listed = listing.value; for (const name of cands) { const r = mapGet(listed.refs, name); if (r.tag === 'some') return ok({ kind: 'hit', resolved: { name: name === 'HEAD' ? getOrElse(fromNullish(listed.head), 'HEAD') : name, commit: getOrElse(fromNullish(r.value.peeled), r.value.oid) } }); } if (prefix !== null) { const found = advertisedCommit(prefix, listed); if (!found.ok) return found; if (found.value.tag === 'some') return ok({ kind: 'hit', resolved: found.value.value }); } return ok({ kind: 'miss', candidates: cands }); } export type ResolveConfig = { readonly abbrev: AbbrevMode }; export type ResolveOptions = Input; // Effect: ref → { name, commit } (annotated tags peeled; a bare oid is taken as given and checked by the commit fetch). // `abbrev: 'advertised'` asks once for the name's candidates plus HEAD, branches and tags, tries the name first, then // the prefix. `'off'` is the candidates alone. A miss is not_found, and an unborn HEAD the caller named is head_unborn. export async function resolveCommit(t: Transport, ref: unknown, options: ResolveOptions = {}): Promise> { const { abbrev } = withDefaults(options, { abbrev: 'off' }); const looked = await lookupRef(t, ref, abbrev); if (!looked.ok) return looked; if (looked.value.kind === 'hit') return ok(looked.value.resolved); const { candidates } = looked.value; const head = getOrElse(at(candidates, 0), '') === 'HEAD'; // The unborn question is a second ls-refs, and only after a miss: the advertisement is read then, and `unborn` is // sent only when the server lists ls-refs=unborn. A path miss never reaches here. const unborn = await unbornTarget(t); if (!unborn.ok) return unborn; // refCandidates refused a non-string, and a HEAD miss does not read this. The false arm stays so the type is a string. const asked = typeof ref === 'string' ? ref : ''; const target = unborn.value; let miss: Miss; if (target.tag === 'some' && sameBranch(ref, target.value)) miss = { kind: 'head_unborn', target: target.value }; else if (head) miss = { kind: 'head_absent' }; else miss = { kind: 'ref', ref: asked, candidates }; return fail('not_found', head ? 'remote HEAD is unborn or absent (some hosts point HEAD at a deleted branch); pass ref explicitly' : `ref ${asked} not found`, { miss }); } export { fetchCommit, type FetchedCommit, type CommitMiss } from './commit.js'; // An ident for JSON. `time` is ISO-8601 UTC, `epoch` the raw seconds, `tz` the offset as written (+0530). export type IdentView = { readonly name: string; readonly email: string; readonly time: string | null; readonly epoch: number | null; readonly tz: string }; // Pure: an ident line's view (null for a line parseIdent cannot read). const identView = (line: unknown): IdentView | null => { const p = parseIdent(line); if (!p) return null; const epoch = p.time === null ? null : Number(p.time); const d = epoch === null ? null : new Date(epoch * 1000); return { name: p.name, email: p.email, time: d && !Number.isNaN(d.getTime()) ? d.toISOString().replace('.000Z', 'Z') : null, epoch, tz: p.tz }; }; // The JSON view of a commit object. `signed` is whether it carries a gpgsig/gpgsig-sha256 header (any format: // OpenPGP, SSH, X.509); it says nothing about whether the signature verifies. The message is the raw body, UTF-8. export type CommitView = { readonly tree: string; readonly parents: readonly string[]; readonly author: IdentView | null; readonly committer: IdentView | null; readonly message: string; readonly signed: boolean; }; // Pure: a commit object's view. A malformed commit is parseCommit's (objects.ts) Err. export function commitView(data: Uint8Array, limits: LimitsInput = DEFAULT_LIMITS): Result { const parsed = parseCommit(data, limits); if (!parsed.ok) return parsed; const c: { readonly tree: string; readonly parents: readonly string[]; readonly author: string; readonly committer: string; readonly message: string | null; readonly extra: readonly string[] } = parsed.value; return ok({ tree: c.tree, parents: c.parents, author: identView(c.author), committer: identView(c.committer), message: c.message === null ? '' : c.message, signed: c.extra.some(l => /^gpgsig(-sha256)? /.test(l)) }); } // The options operation() reads pass through (tracer, auth, fetchImpl, limits, transport, …). export type ReadOptions = EntryOptions; // Trees by oid, kept by the caller across reads (immutable: an oid names its bytes). export type TreeCache = Map; export type CommitResult = CommitView & { readonly ref: string; readonly oid: string }; // An unborn HEAD (or that branch by name): git log's "does not have any commits yet". Not a not_found. export type EmptyCommit = { readonly empty: true; readonly ref: string }; // What readCommit, listTree and readFile take as their second argument. `ref: null` is the remote's HEAD. export type RefConfig = { readonly ref: RefSpec }; export type ReadCommitSpec = Input; // An unborn HEAD the caller named is a state (EmptyCommit), not a failure. Every other answer is the resolution's own. const unbornState = (r: Result): Option => { // Only ply's own error is believed: a transport that raises a look-alike object is not the server saying HEAD is unborn. if (r.ok || !isPlyError(r.error) || r.error.code !== 'not_found' || r.error.miss.kind !== 'head_unborn') return none; return some({ empty: true, ref: r.error.miss.target }); }; export async function readCommit(url: string, spec: ReadCommitSpec = {}, opts: ReadOptions = {}): Promise> { const { ref } = withDefaults(spec, { ref: null }); return operation('read_commit', url, { ...opts, attrs: { 'git.read_commit.ref': ref === null ? 'HEAD' : ref } }, async ({ t, outcome }) => { const resolved = await resolveCommit(t, ref); const empty = unbornState(resolved); if (empty.tag === 'some') return outcome('ok', empty.value); if (!resolved.ok) return resolved; const { name, commit } = resolved.value; const fetched = await commitById(t, commit); if (!fetched.ok) return fetched; const viewed = commitView(fetched.value.data, t.limits); if (!viewed.ok) return viewed; const view = viewed.value; return outcome('ok', { ref: name, oid: commit, ...view }, { 'git.read_commit.oid': commit, 'git.read_commit.parents': view.parents.length, 'git.read_commit.signed': view.signed }); }); } // Effect: a tree's entries, from its bytes in the caller's cache (parsed here) or by one tree:0 fetch whose bytes the // cache keeps (the fetch's own check parsed them: treeEntries, #208). async function treeAt(t: Transport, cache: TreeCache, oid: Oid, limits: CheckedLimits): Promise> { const cached = mapGet(cache, oid); if (cached.tag === 'some') return parseTree(cached.value, limits); const fetched = await objectAt(t, oid, { filter: 'tree:0', expectType: TYPE.TREE }); if (!fetched.ok) return fetched; cache.set(oid, fetched.value.data); return treeEntries(fetched.value, limits); } // A failure inside a span: recorded on it (the span's own end follows), and passed on. const spanErr = (span: Span, r: Err): Err => { span.error(r.error); return r; }; export type Walked = { readonly tree: Oid; readonly entry: TreeEntry | null }; export type WalkConfig = { readonly cache: TreeCache }; export type WalkOptions = Input; // Effect: walk `comps` from a tree the caller already has. `tree` is that starting oid; `entry` is the last component // (null when comps is empty). A missing component or a non-directory along the way is not_found with its miss. Each // level is a `git.read.tree` span under the transport's parent, so a readFile/listTree walk stays on that trace. // walkPath from a parsed tree id: readFile, listTree and ply's other walks start here. async function walkFrom(t: Transport, treeOid: Oid, comps: readonly string[], options: WalkOptions = {}): Promise> { const { cache } = withDefaults(options, { cache: new Map() }); let here = treeOid; let entry: TreeEntry | null = null; for (const [depth, name] of comps.entries()) { // oxlint-disable-next-line no-loop-func -- the span runs to completion inside this iteration (awaited) const level = await spanOn(t.tracer, 'git.read.tree', { parent: t.parent, attrs: { 'git.read.tree.depth': depth, 'git.read.tree.oid': here, 'git.read.tree.lookup': name } }, async (span): Promise> => { span.set({ 'git.read.tree.cache_hit': isSome(mapGet(cache, here)) }); const entries = await treeAt(t, cache, here, t.limits); if (!entries.ok) return spanErr(span, entries); const found = fromNullable(entries.value.find(x => x.name === name)); span.set({ 'git.read.tree.entries': entries.value.length, 'git.read.tree.entry.found': found.tag === 'some', 'git.read.tree.entry.mode': getOrElse(mapOption(found, f => f.mode), '') }); if (found.tag === 'none') return spanErr(span, fail('not_found', `path component ${name} not found`, { miss: { kind: 'path', missing: name, existingPath: comps.slice(0, depth).join('/') } })); if (depth < comps.length - 1 && found.value.mode !== '40000') return spanErr(span, fail('not_found', `${name} is not a directory`, { miss: { kind: 'not_directory', path: comps.slice(0, depth + 1).join('/'), mode: found.value.mode } })); return ok(found.value); }); if (!level.ok) return level; entry = level.value; here = entry.oid; } return ok({ tree: treeOid, entry }); } // The caller's tree id is parsed once, before the walk (fetchObject's refusal, as a first fetch of it would give). export async function walkPath(t: Transport, treeOid: string, comps: readonly string[], options: WalkOptions = {}): Promise> { const start = objectId(treeOid); return start.ok ? walkFrom(t, start.value, comps, options) : start; } // A commit-rooted walk: the commit's bytes (as fetched, hash-checked), its root tree, and the walk's last entry. export type CommitWalked = Walked & { readonly commit: Oid; readonly data: Uint8Array }; export type CommitWalkConfig = WalkConfig & { readonly levels: number }; export type CommitWalkOptions = Input; // Effect: walk `comps` from the commit's root tree. `tree` is that root (walkPath's tree is the tree it started from). // `levels` is how many tree levels the caller reads from the root: the path's directories, and the listed directory // itself for listTree. The commit fetch brings the first of them where the server takes it (pathtrees.ts, #218). // `root`, when given, is the operation's span: it carries the commit and its root tree before the walk starts. async function walkFromCommit(t: Transport, commit: Oid, comps: readonly string[], { levels, cache }: CommitWalkConfig, root: Span | null): Promise> { const fetched = await commitForWalk(t, commit, levels); if (!fetched.ok) return fetched; const { data } = fetched.value; const info = parseCommit(data, t.limits); if (!info.ok) return info; if (root !== null) root.set({ 'git.read.commit': commit, 'git.read.tree.root': info.value.tree }); const walked = await walkFrom(t, info.value.tree, comps, { cache }); if (!walked.ok) return walked; return ok({ commit, data, tree: info.value.tree, entry: walked.value.entry }); } // walkCommit(transport, commitOid, comps, { cache, levels }): the commit and its path in as few round trips as the server // allows (#222). A server known to take `combine:blob:none+tree:K` answers the commit and its first min(levels, 2) tree // levels in one fetch (pathtrees.ts); elsewhere it is the commit (tree:0, deepen 1), then one tree per level, as readFile // reads it. Every tree the walk reads lands in `cache`; a tree the commit's fetch brought and the walk did not read (the // listed directory, a sibling) is answered by fetchObject without another request. `levels` defaults to comps.length + 1 // (the path's directories and the listed one); 0 fetches the commit alone. Not a commit (or an oid that is not 40 hex, // or levels that is not a non-negative integer) is that refusal; a missing component is walkPath's not_found. export async function walkCommit(t: Transport, commit: string, comps: readonly string[], options: CommitWalkOptions = {}): Promise> { const id = objectId(commit); if (!id.ok) return id; const config = withDefaults(options, { cache: new Map(), levels: comps.length + 1 }); if (!Number.isSafeInteger(config.levels) || config.levels < 0) return fail('bad_request', `walkCommit: levels must be a non-negative integer, got ${String(config.levels)}`); return walkFromCommit(t, id.value, comps, config, null); } // A path as the entries take it: validated components. With `allowRoot` (a tree path), a missing, null, empty or '/' // path is the root and one trailing '/' is dropped (git: `HEAD:dir/` is the tree). Without it (a file path), a trailing // '/' names a directory and is refused, as git refuses `HEAD:file/` for a blob (#300-8). export const pathComps = (path: unknown, limits: CheckedLimits, { allowRoot }: { readonly allowRoot: boolean }): Result => { if (allowRoot && (isNothing(path) || path === '' || path === '/')) return ok([]); const valid = validatePath(allowRoot && typeof path === 'string' ? path.replace(/\/$/, '') : path, limits); return valid.ok ? ok(valid.value.components) : valid; }; // What listTree and readFile take as their second argument. `path: null` is the root for listTree, and refused by readFile. export type PathConfig = RefConfig & { readonly path: string | null }; export type PathSpec = Input; // The options of listTree and readFile: operation()'s, plus the caller's tree cache. export type TreeReadConfig = { readonly cache: TreeCache; readonly limits: LimitsInput }; export type TreeReadOptions = ReadOptions & Input; // A null or missing limits record is the default, as the nullish read had it, and the record is parsed once, here; the // cache is fresh per call. const treeReadConfig = (options: TreeReadOptions): Result<{ readonly cache: TreeCache; readonly limits: CheckedLimits }, ErrorOf<'bad_request'>> => map(limitsOf(options), limits => ({ cache: getOrElse(readKey(options, 'cache'), new Map()), limits })); export type ListEntry = { readonly name: string; readonly mode: string; readonly oid: string; readonly type: EntryType }; export type ListResult = { readonly ref: string; readonly commit: string; readonly tree: string; readonly entries: readonly ListEntry[] }; // The listed directory: the walk's last entry when it is a tree, the root when the path was. not_found otherwise. function listedDir(walked: Walked, comps: readonly string[]): Result { const { entry } = walked; if (entry === null) return ok(walked.tree); if (entry.mode !== '40000') return fail('not_found', `${comps.join('/')} is not a directory (mode ${entry.mode})`, { miss: { kind: 'not_directory', path: comps.join('/'), mode: entry.mode } }); return ok(entry.oid); } export async function listTree(url: string, spec: PathSpec = {}, options: TreeReadOptions = {}): Promise> { const { ref, path } = withDefaults(spec, { ref: null, path: '' }); const config = treeReadConfig(options); if (!config.ok) return config; const { cache, limits } = config.value; const checked = pathComps(path, limits, { allowRoot: true }); if (!checked.ok) return checked; const comps = checked.value; return operation('ls_tree', url, { ...options, limits, attrs: { 'git.ls_tree.ref': ref === null ? 'HEAD' : ref, 'git.ls_tree.path': comps.join('/'), 'git.ls_tree.path.depth': comps.length } }, async ({ t, root, outcome }) => { const resolved = await resolveCommit(t, ref); if (!resolved.ok) return resolved; const { name, commit } = resolved.value; // the tracer operation() started the root span on (opts.tracer) const walked = await walkFromCommit(t, commit, comps, { levels: comps.length + 1, cache }, root); if (!walked.ok) return walked; const dir = listedDir(walked.value, comps); if (!dir.ok) return dir; const oid = dir.value; const parsed = await treeAt(t, cache, oid, limits); if (!parsed.ok) return parsed; const entries: readonly TreeEntry[] = parsed.value; return outcome('ok', { ref: name, commit, tree: oid, entries: entries.map(e => ({ name: e.name, mode: lsMode(e.mode), oid: e.oid, type: entryType(e.mode) })) }, { 'git.ls_tree.tree': oid, 'git.ls_tree.entries': entries.length }); }); } export type FileResult = { readonly ref: string; readonly commit: string; readonly blob: string; readonly mode: string; readonly size: number; readonly stream: ReadableStream; }; // The file's entry: a symlink's blob is its target (what `git show :` prints); a directory has no blob, and a // gitlink has none in this repository. function fileEntry(entry: TreeEntry, comps: readonly string[]): Result { if (entry.mode === '40000') return fail('not_found', `${comps.join('/')} is a directory`, { miss: { kind: 'is_directory', path: comps.join('/'), tree: entry.oid } }); if (entry.mode === '160000') return fail('not_found', `${comps.join('/')} is a submodule (commit ${entry.oid})`, { miss: { kind: 'submodule', path: comps.join('/'), commit: entry.oid } }); return ok(entry); } // The root span ends when the stream is open (size known); the content's own span, `git.read.blob`, ends when the // stream does, with the bytes delivered and whether the oid verified. It outlives the root, so it is not the root's child // but the root of its own trace, linked both ways (follows_from / followed_by): README "Span lifetimes". export async function readFile(url: string, spec: PathSpec = {}, options: TreeReadOptions = {}): Promise> { const { ref, path } = withDefaults(spec, { ref: null, path: null }); const config = treeReadConfig(options); if (!config.ok) return config; const { cache, limits } = config.value; const checked = pathComps(path, limits, { allowRoot: false }); if (!checked.ok) return checked; const comps = checked.value; return operation('read', url, { ...options, limits, attrs: { 'git.read.ref': ref === null ? 'HEAD' : ref, 'git.read.path': comps.join('/'), 'git.read.path.depth': comps.length } }, async ({ t, root, outcome }) => { const resolved = await resolveCommit(t, ref); if (!resolved.ok) return resolved; const { name, commit } = resolved.value; const walked = await walkFromCommit(t, commit, comps, { levels: comps.length, cache }, root); if (!walked.ok) return walked; // comps is non-empty (validatePath refuses an empty path), so the walk ends at an entry // oxlint-disable-next-line typescript/no-unsafe-type-assertion, typescript/non-nullable-type-assertion-style -- see above (and no `!`: docs/STACK.md) const file = fileEntry(walked.value.entry as TreeEntry, comps); if (!file.ok) return file; const entry = file.value; // oxlint-disable-next-line no-use-before-define -- the JS's order (readFile, then openBlob): a function declaration, hoisted; the bundle's gzip budget const opened = await openBlob(t, entry.oid, { follows: root }); if (!opened.ok) return opened; const { size, stream } = opened.value; return outcome('ok', { ref: name, commit, blob: entry.oid, mode: lsMode(entry.mode), size, stream }, { 'git.read.blob': entry.oid, 'git.read.blob.size': size, 'git.read.blob.mode': entry.mode }); }); } export type BlobStream = { readonly kind: 'stream'; readonly size: number; readonly stream: ReadableStream }; export type BlobTooBig = { readonly kind: 'too_big'; readonly size: number }; export type OpenedBlob = BlobStream | BlobTooBig; // `maxBytes`: the declared size above which the blob is too_big (left out: no cap). `follows`: the span the stream // follows (null: none). export type BlobConfig = { readonly maxBytes: number; readonly follows: Span | null }; export type BlobOpts = Input; // The options without a cap: the answer is always a stream. export type FollowOpts = Input>; export type CappedOpts = Pick & FollowOpts; // The fail-site recorder (test/space/failsite-hook.mjs) installs this only when PLY_FAILSITES is set. A guard, not a // cast: under the hook the value is a function and the property is absent otherwise, so the call is a no-op in a bundle. const FAIL_SITE = Symbol.for('ply.failsite'); // Isolate age: Workers may freeze Date.now() at 0 during module evaluation (prod 8e7f5e26 stamped // ply.isolate_age_ms ≈ epoch). performance.now() starts at 0 with the isolate and advances; the delta // from module init is the age. Stamped on large-read spans (variance diagnosis). const ISOLATE_BORN_PERF = performance.now(); const nowMs = (): number => performance.now(); const isolateAgeMs = (): number => Math.round(nowMs() - ISOLATE_BORN_PERF); const isFailSiteRecorder = (v: unknown): v is (holder: (e: unknown) => unknown) => void => typeof v === 'function'; type BodyState = Extract; // A pull of the pack stream, or a parser step, as a value: what it threw is the failure (failHere classifies it). const nextChunk = async (it: AsyncIterator): Promise, unknown>> => { try { return ok(await it.next()); } catch (e) { return err(e); } }; const stepHeader = (sp: SpState, chunk: Uint8Array): ReturnType => spStep(sp, chunk); // Effect: pull until the object header is read (→ type and size). The zlib bytes after it go to `early`. async function blobHeader(it: AsyncIterator, early: Uint8Array[]): Promise> { let sp: SpState = spInit(); while (sp.phase !== 'body') { const next = await nextChunk(it); if (!next.ok) return next; if (next.value.done === true) return err(plyError('pack_corrupt', 'pack ended before the object header')); const r = stepHeader(sp, next.value.value); if (!r.ok) return r; sp = r.value.state; early.push(...r.value.zlib); } if (sp.type !== TYPE.BLOB) return err(plyError('pack_corrupt', `expected blob, got ${getOrElse(fromNullish((TYPE_NAME as TypeNames)[sp.type]), sp.type)}`)); return ok(sp); } // Effect: one blob on the caller's transport. Reads the pack until the object header (→ size). A declared size above // `maxBytes` is `{ kind: 'too_big' }`: the fetch is cancelled and no body byte is delivered (`git.read.blob.header_only`). // Otherwise the zlib bytes go through DecompressionStream and a verifying transform. The transform releases every chunk // but the latest as it arrives, and releases the latest only after the pack trailer and the object hash verify. A failure // errors the stream with that chunk still held, so the body never completes on unverified bytes. Back-pressure: the pump // awaits each write, so at most one network chunk and one inflate chunk are in flight beyond the chunk being held. // `follows` is the span the stream follows (the read root, or git.checkout.blobs): the consumer reads after it returns. // The tracer is the transport's. Header and cap failures are a Result; a bad `maxBytes` is too. Without `maxBytes` the // result is a stream (a cap is the only way the header refuses the blob). export function openBlob(t: Transport, oid: string, ...opts: [] | [FollowOpts]): Promise>; export function openBlob(t: Transport, oid: string, opts: CappedOpts): Promise>; export function openBlob(t: Transport, oid: string, opts: BlobOpts): Promise>; export async function openBlob(t: Transport, oid: string, opts: BlobOpts = {}): Promise> { // A given maxBytes is checked, null included (a cap the caller passed); only leaving it out is no cap. const cap = readKey(opts, 'maxBytes'); if (cap.tag === 'some' && (!Number.isInteger(cap.value) || cap.value < 0)) return fail('bad_request', 'maxBytes must be an integer >= 0', { what: 'maxBytes' }); const maxBytes = getOrElse(cap, Number.POSITIVE_INFINITY); const { follows } = withDefaults>(opts, { follows: null }); const span = t.tracer.start('git.read.blob', { ...(follows === null ? {} : { follows }), attrs: { 'git.read.blob.oid': oid } }); // Inflated-blob caching lives in ply-web's Workers Cache BlobCache entrypoint (never caches.default). const fetchSpan = t.tracer.start('git.upload-pack fetch', { parent: span, kind: KIND.CLIENT }); // Inflate+verify wall clock (overlaps the upload-pack body). Opened once the object header has passed the size cap. let inflateSpan: { ended: boolean; set(a: Record): { end(): void }; end(): void; error(e: unknown): { end(): void } } | null = null; let hashMs = 0; const endInflate = (attrs: Record = {}): void => { if (inflateSpan === null || inflateSpan.ended) return; inflateSpan.set(attrs).end(); }; const it: AsyncIterator = packStream(t, { wants: [oid] }, fetchSpan)[Symbol.asyncIterator](); // Close the pack stream: the read failed, was cancelled, or the cap ended it. Its own failure then is not the outcome. const close = async (): Promise => { if (typeof it.return === 'function') await it.return().catch(() => { /* the outcome is already decided */ }); }; // the first of failure, cancellation and verified end records the outcome; whatever follows (a cancel aborting the // pump) leaves the ended spans alone const failHere = (e: unknown): unknown => { // A ply error built before this call has a stack that does not name the call, so the fail-site recorder // (installed only under PLY_FAILSITES) would not see it. Absent the hook there is no function to call. const record: unknown = (globalThis as Record)[FAIL_SITE]; if (isFailSiteRecorder(record)) record(failHere); const code = thrownCodeOr(e, null); if (isPlyCode(code)) { if (!span.ended) { fetchSpan.error(e).end(); endInflate({ 'git.blob.inflate.outcome': code }); span.error(e).set({ 'git.read.blob.outcome': code }).end(); } return e; } const wrapped = plyError('pack_corrupt', `blob stream: ${thrownText(e)}`, { cause: e }); if (!span.ended) { fetchSpan.error(wrapped).end(); endInflate({ 'git.blob.inflate.outcome': wrapped.code }); span.error(wrapped).set({ 'git.read.blob.outcome': wrapped.code }).end(); } return wrapped; }; const early: Uint8Array[] = []; const header = await blobHeader(it, early); if (!header.ok) { await close(); return err(raised('pack_corrupt', failHere(header.error))); } let sp: SpState = header.value; const size = header.value.size; span.set({ 'git.read.blob.size': size }); // The cap is the declared size. Bytes already in the packet that completed the header stay unread by the consumer; // the iterator is closed so nothing further is pulled. if (size > maxBytes) { span.set({ 'git.read.blob.header_only': true, 'git.read.blob.outcome': 'too_big' }).end(); fetchSpan.end(); await close(); return ok({ kind: 'too_big', size }); } inflateSpan = t.tracer.start('git.blob.inflate', { parent: span, attrs: { 'git.read.blob.oid': oid, 'git.read.blob.size': size } }); const ds = new DecompressionStream('deflate'); const writer = ds.writable.getWriter(); // a pump failure (network, framing, trailer) aborts the inflate side, which errors the stream the consumer reads. The // verify transform's flush never runs then (its catch is unreachable), so the failure is recorded here. // The abort's reason is the failure: workerd's DecompressionStream errors its readable with a reason of its own (the // message without the code), node's with the one given, so the reader is handed the failure kept here (#144). let aborted: { readonly e: unknown } | null = null; const readFailure = (e: unknown): unknown => { // Stryker disable next-line ConditionalExpression: node's DecompressionStream keeps the abort reason, so only workerd (test/workerd.test.js) tells the two apart if (aborted !== null) return aborted.e; return isPlyThrown(e) ? e : failHere(e); }; const abortWith = async (e: unknown): Promise => { const failed = failHere(e); if (aborted === null) aborted = { e: failed }; await writer.abort(failed).catch(() => { /* already failing */ }); await close(); }; const pump = (async (): Promise => { for (const z of early) await writer.write(bufferSource(z)); for (;;) { const step = await it.next(); // oxlint-disable-next-line typescript/strict-boolean-expressions -- bundle budget: the JS's own truthy test (an iterator's done is true, false or absent) if (step.done) break; const stepped = spStep(sp, step.value); if (!stepped.ok) { await abortWith(stepped.error); return; } const r: SpStepped = stepped.value; sp = r.state; for (const z of r.zlib) await writer.write(bufferSource(z)); } const finished = spFinish(sp); // pack trailer checksum if (!finished.ok) { await abortWith(finished.error); return; } sp = finished.value; fetchSpan.end(); await writer.close(); })(); pump.catch(abortWith); const sha = streamingSha1(); // hash_await_ms: wall time spent awaiting hasher update/hex only. DigestStream hashes in the host while // write() resolves on accept, so this is often ~0 on Workers; the CPU shows up in GET cpu_time_ms overlapping // inflate — not a free hash. Renamed from hash_ms (loop 2026-11-08) so the metric does not claim CPU self-time. // Coalescing into HASH_BUF_BYTES cuts one await per inflate chunk. const HASH_BUF_BYTES = 65_536; const hashBuf = new Uint8Array(HASH_BUF_BYTES); let hashBufLen = 0; const hashFlush = async (): Promise => { if (hashBufLen === 0) return; const h0 = nowMs(); await sha.update(hashBufLen === HASH_BUF_BYTES ? hashBuf : hashBuf.subarray(0, hashBufLen)); hashMs += nowMs() - h0; hashBufLen = 0; }; const hashPush = async (chunk: Uint8Array): Promise => { let off = 0; while (off < chunk.byteLength) { const n = Math.min(HASH_BUF_BYTES - hashBufLen, chunk.byteLength - off); hashBuf.set(chunk.subarray(off, off + n), hashBufLen); hashBufLen += n; off += n; if (hashBufLen === HASH_BUF_BYTES) await hashFlush(); } }; { const h0 = nowMs(); await sha.update(objectHeader('blob', size)); hashMs += nowMs() - h0; } let seen = 0; const inflateStarted = nowMs(); // The latest inflate chunk. An empty chunk is not a chunk: releasing the real tail because a zero-length piece // arrived would finish the body before the hash and the trailer were checked. let held: Uint8Array | null = null; // The stream edge: a transform or flush that throws errors the stream, which is how the consumer is told. const verify = new TransformStream({ async transform(chunk, ctl) { if (chunk.byteLength === 0) return; seen += chunk.length; if (seen > size) throw failHere(plyError('pack_corrupt', `server streamed more than the ${size} bytes it declared`)); await hashPush(chunk); if (held) ctl.enqueue(held); held = chunk; }, async flush(ctl) { try { await pump; } catch (e) { throw failHere(e); } if (seen !== size) throw failHere(plyError('pack_corrupt', `inflated ${seen} != declared ${size}`)); await hashFlush(); const h1 = nowMs(); const got = await sha.hex(); hashMs += nowMs() - h1; if (got !== oid) throw failHere(plyError('pack_corrupt', `blob content hashes to ${got}, not ${oid}`)); if (held) ctl.enqueue(held); held = null; const inflateMs = Math.max(0, nowMs() - inflateStarted); const bytesPerSec = inflateMs > 0 ? Math.round(seen / (inflateMs / 1000)) : 0; endInflate({ 'git.blob.inflate.outcome': 'ok', 'git.read.blob.hash_await_ms': Math.round(hashMs * 1000) / 1000, 'git.blob.inflate.bytes_per_sec': bytesPerSec, 'ply.isolate_age_ms': isolateAgeMs(), }); span.set({ 'git.read.blob.bytes': seen, 'git.read.blob.verified': true, 'git.read.blob.hasher': sha.kind, 'git.read.blob.hash_await_ms': Math.round(hashMs * 1000) / 1000, 'git.blob.inflate.bytes_per_sec': bytesPerSec, 'ply.isolate_age_ms': isolateAgeMs(), 'git.read.blob.outcome': 'ok', }).end(); }, }); // DecompressionStream's own refusals (trailing junk after the deflate end, a bad block) are platform errors with no ply // code; the consumer sees them as pack_corrupt like every other refusal on this path (I1: a code from the fixed set). // The consumer's cancel() is an outcome of its own ('cancelled', not an error): without the cancel hook a cancel after the // pump has written its last chunk would leave both spans open forever, and one before it would read as pack_corrupt. const inner = ds.readable.pipeThrough(verify).getReader(); const stream = new ReadableStream({ async pull(c) { let r: ReadableStreamReadResult; try { r = await inner.read(); } catch (e) { throw readFailure(e); } if (r.done) c.close(); else c.enqueue(r.value); }, async cancel(reason) { if (!span.ended) { fetchSpan.end(); endInflate({ 'git.blob.inflate.outcome': 'cancelled' }); span.set({ 'git.read.blob.bytes': seen, 'git.read.blob.hash_await_ms': Math.round(hashMs * 1000) / 1000, 'git.read.blob.outcome': 'cancelled' }).end(); } await inner.cancel(reason).catch(() => { /* cancelling: the outcome is recorded */ }); await close(); }, }, { highWaterMark: 0 }); return ok({ kind: 'stream', size, stream }); } export type BlobData = { readonly kind: 'bytes'; readonly data: Uint8Array }; // Effect: openBlob, then the whole verified stream. A stream that errors is that error; `too_big` is not read. export function readBlob(t: Transport, oid: string, ...opts: [] | [FollowOpts]): Promise>; export function readBlob(t: Transport, oid: string, opts: CappedOpts): Promise>; export function readBlob(t: Transport, oid: string, opts: BlobOpts): Promise>; export async function readBlob(t: Transport, oid: string, opts: BlobOpts = {}): Promise> { // The general overload: a caller's options may or may not carry a cap. const open: (t: Transport, oid: string, opts: BlobOpts) => Promise> = openBlob; const opened = await open(t, oid, opts); if (!opened.ok) return opened; switch (opened.value.kind) { case 'too_big': return ok(opened.value); case 'stream': { const parts: Uint8Array[] = []; try { for await (const chunk of opened.value.stream) parts.push(chunk); } // the stream's error, as the consumer of readFile's stream sees it; a value that is not ply's is coded here catch (e) { return err(raised('pack_corrupt', e)); } return ok({ kind: 'bytes', data: concat(parts) }); } } // Stryker disable next-line ConditionalExpression: unreachable, the compiler's exhaustiveness check return assertNever(opened.value); }