Artifactspublic-v0

ply

main
ply4 git calls236 ms51 KiB2 cachedprotocol v2
625 lines40 KiBRaw
1// O(1)-memory single-file edit: ls-refs → commit (tree:0, deepen 1) → one tree per level →
2// streamed blob replace (never materialized) → thin push with REF_DELTAs.
3// Shape: pure decisions between thin effects. Every decision (validateSpec, decideHead, lookupEntry, buildCommitObjects,
4// memFromScan, summarize) is a function of its arguments; the effects (lsRefs, fetchObject, packStream, push) are free
5// functions over a transport record, imported individually so a bundle of this file carries nothing else.
6// Decisions and the public entries (editFile, validateSpec, lookupEntry) return Result; inside the operation each step's
7// Err is the operation's, which operation() records on its span.
8/* oxlint-disable import/max-dependencies -- an entry composes the protocol from one import per module, so its bundle carries nothing else */
9import { fail, isPlyError } from './errors.js';
10import type { ErrorOf, Extra, Miss, PlyError } from './errors.js';
11import { operation, verifyRef } from './operation.js';
12import { lsRefs } from './lsrefs.js';
13import { packStream, objectAt, spInit, spStep, spFinish, treeEntries } from './fetch.js';
14import { push, ZERO_OID } from './push.js';
15import { spliceDelta } from './pack.js';
16import { parseCommit, parseTree, objectHeader, TYPE } from './objects.js';
17import { streamingSha1 } from './sha1.js';
18import { te, bufferSource, concat, indexOfBytes, bytesOf } from './bytes.js';
19import { KIND, cpuNow, cpuSince, spanOn } from './otel.js';
20import type { Attrs, Span, StartOptions, Tracer } from './otel.js';
21import { limitsOf, parseLimits } from './limits.js';
22import type { CheckedLimits, LimitsInput } from './limits.js';
23import { validateIdent, validateRef, validatePushRef, validatePath, validateMessage } from './validate.js';
24import type { IdentInput, ValidatedIdent } from './validate.js';
25import { parseCommitId, parseOid, type Oid } from './oid.js';
26import { signCommit } from './sign.js';
27import type { FetchedObject as Fetched, SpState } from './fetch.js';
28import type { PackObject } from './push.js';
29import type { Signer } from './sign.js';
30import type { Transport } from './transport.js';
31import type { TreeEntry } from './objects.js';
32import { isPlyThrown, thrownText } from './boundary.js';
33import type { EntryOptions } from './boundary.js';
34import type { Input } from './absent.js';
35import { atOr, field, fromNullish, mapGet, withDefaults } from './absent.js';
36import { err, getOrElse, map, mapOption, ok } from './result.js';
37import type { Err, Result } from './result.js';
38import { DEFAULT_REF } from './refname.js';
39import type { Refname } from './refname.js';
40import { buildCommitObjects, withCommitData } from './commit-build.js';
41import { expectedCreate } from './editexpect.js';
42import type { Author, Level as BuiltLevel, NewTree as BuiltNewTree } from './commit-build.js';
44/* oxlint-disable no-await-in-loop -- a stream is consumed in order: each write waits for the inflate side (back-pressure) */
45/* oxlint-disable unicorn/explicit-length-check, require-unicode-regexp -- bundle budget: the JS's truthy length checks and non-unicode regexes, byte for byte (no behaviour change) */
47export { spInit, spStep, spFinish }; // the single-object pack parser lives in fetch.js; re-exported for callers of old paths
48export { buildCommitObjects, withCommitData } from './commit-build.js';
50// A caller's identity, before validateIdent. `time` overrides the spec's `time` for this person; omitted uses the spec's.
51export type { Author };
52// A validated identity (validate.js validateIdent): frozen, branded, the only input ident() accepts.
53export type Ident = ValidatedIdent;
55// ---- streaming find/replace scanner (pure step) ----
56// Emits transformed bytes; counts matches and records the first MATCH_OFFSETS_KEPT offsets. Carry ≤ |find|-1 bytes.
57// The contract is exactly one match, so offsets past the first few decide nothing: `count` is the outcome, `matches`
58// is evidence for the span. Keeping every offset (a fresh array per hit) made a one-byte find over a 128 KiB run of that
59// byte O(matches²): 400 s (#13). Now each hit costs O(1).
60export const MATCH_OFFSETS_KEPT = 16;
61export type ScanState = {
62 readonly find: Uint8Array;
63 readonly replace: Uint8Array;
64 readonly carry: Uint8Array;
65 readonly base: number;
66 readonly matches: readonly number[];
67 readonly count: number;
68 readonly emitted: number;
69 readonly chunks: number;
70 readonly maxChunk: number;
71};
72export type ScanOut = { readonly emit: Uint8Array[]; readonly state: ScanState };
73export const scanInit = ({ find, replace }: { readonly find: Uint8Array; readonly replace: Uint8Array }): ScanState => Object.freeze({ find, replace, carry: new Uint8Array(0), base: 0, matches: [], count: 0, emitted: 0, chunks: 0, maxChunk: 0 });
74export function scanStep(st: ScanState, chunk: Uint8Array): ScanOut {
75 const data = st.carry.length ? concat([st.carry, chunk]) : chunk;
76 const emit: Uint8Array[] = [];
77 const matches = [...st.matches];
78 let count = st.count;
79 let emitted = st.emitted;
80 let p = 0;
81 for (;;) {
82 const i = indexOfBytes(data, st.find, p);
83 if (i < 0) break;
84 emit.push(data.subarray(p, i)); emitted += i - p;
85 emit.push(st.replace); emitted += st.replace.length;
86 if (matches.length < MATCH_OFFSETS_KEPT) matches.push(st.base + i);
87 count += 1;
88 p = i + st.find.length;
89 }
90 const keep = Math.min(st.find.length - 1, data.length - p);
91 const flushTo = data.length - keep;
92 if (flushTo > p) { emit.push(data.subarray(p, flushTo)); emitted += flushTo - p; }
93 return {
94 emit: emit.filter(e => e.length),
95 state: { ...st, carry: data.slice(flushTo), base: st.base + flushTo, matches, count, emitted, chunks: st.chunks + 1, maxChunk: Math.max(st.maxChunk, chunk.length) },
96 };
98export function scanFinish(st: ScanState): ScanOut {
99 const emit = st.carry.length ? [st.carry] : [];
100 return { emit, state: { ...st, carry: new Uint8Array(0), emitted: st.emitted + st.carry.length } };
102export const scanAttrs = (st: ScanState): Attrs => ({
103 'git.edit.blob.scan.chunks': st.chunks, 'git.edit.blob.scan.chunk.max': st.maxChunk, 'git.edit.blob.scan.matches': st.count,
104 'git.edit.blob.scan.match_offsets': st.matches, 'git.edit.blob.scan.emitted': st.emitted,
105});
107// ---- the pipeline ----
109// What the caller names. `ref` defaults to DEFAULT_REF; `base` (a ref or a 40-hex commit id) to `ref`; `committer` (null
110// or left out) is the author; `time` to now (an author's own time wins). `ref` and `path` are plain strings: validateSpec
111// checks them (validatePushRef, validatePath) and the plan carries the branded ref.
112export type EditSpecConfig = { readonly ref: string; readonly base: string | null; readonly committer: Author | null; readonly time: number | null };
113export type EditSpec = Input<EditSpecConfig> & {
114 readonly path: string;
115 readonly find: string | Uint8Array;
116 readonly replace: string | Uint8Array;
117 readonly author: Author;
118 readonly message: string;
119};
120const specDefaults = (): { -readonly [K in keyof EditSpecConfig]: EditSpecConfig[K] } => ({ ref: DEFAULT_REF, base: null, committer: null, time: null });
121// The commit an edit is built on, parsed once: a ref whose tip it is, or a commit id.
122export type EditBase = { readonly kind: 'ref'; readonly ref: Refname } | { readonly kind: 'commit'; readonly oid: Oid };
123// The base as spans and messages name it.
124export const baseName = (b: EditBase): string => (b.kind === 'ref' ? b.ref : b.oid);
125// An EditSpec parsed once (validateSpec): every attempt of editFile runs on this plan, and nothing in the pipeline
126// checks a spec field again.
127export type EditPlan = {
128 readonly ref: Refname;
129 readonly base: EditBase;
130 readonly create: boolean;
131 readonly path: string;
132 readonly comps: readonly string[];
133 readonly find: Uint8Array;
134 readonly replace: Uint8Array;
135 readonly author: Ident;
136 readonly committer: Ident;
137 readonly message: string;
138 readonly time: number;
139 readonly head: Oid | null;
140};
141const HEX40 = /^[0-9a-fA-F]{40}$/u;
142// Pure: everything the caller controls, checked before any I/O. None of these strings can be escaped once inside git.
143// `base`: the ref whose head the commit is built on (default: `ref` itself), or a 40-hex commit id. With a ref base ≠ ref
144// the push *creates* `ref` (old oid = zeros). A commit id is that parent; the ref is created only when it is absent,
145// and when it exists the id must be its tip (refuseRebase). The zero id is not a commit (parseCommitId, before any I/O).
146function resolvedBase(base: string): Result<EditBase, PlyError> {
147 if (!HEX40.test(base)) {
148 const ref = validateRef(base);
149 return ref.ok ? ok({ kind: 'ref', ref: ref.value }) : ref;
150 }
151 const id = parseCommitId(base);
152 return id.ok ? ok({ kind: 'commit', oid: id.value }) : id;
154// The caller's head hint: none, or a 40-hex oid (as String() renders a JS caller's value), parsed once.
155function headHint(head: string | null): Result<Oid | null, PlyError> {
156 if (head === null) return ok(null);
157 // oxlint-disable-next-line typescript/no-unnecessary-type-conversion -- a JS caller's head may be any value; String() as before
158 const id = parseOid(String(head));
159 return id.ok ? id : fail('bad_request', 'head must be a 40-hex oid');
161// One person as validateIdent takes it: the time given, and the zone only when one is (UTC otherwise).
162const identInput = (who: Author, time: number): IdentInput => {
163 const tz = fromNullish(who.tz);
164 return tz.tag === 'some' ? { name: who.name, email: who.email, time, tz: tz.value } : { name: who.name, email: who.email, time };
165};
166export function validateSpec(spec: EditSpec, limits: LimitsInput, head: string | null = null): Result<EditPlan, PlyError> {
167 const checkedLimits = parseLimits(limits);
168 if (!checkedLimits.ok) return checkedLimits;
169 const given = withDefaults(spec, specDefaults());
170 // a null ref is the default too, as the JS read it
171 const givenRef = getOrElse(fromNullish(given.ref), DEFAULT_REF);
172 const baseIn: string = given.base === null ? givenRef : given.base;
173 const author = spec.author;
174 const message = spec.message;
175 const atAuthorTime = fromNullish(author.time);
176 const stamp = atAuthorTime.tag === 'some' ? atAuthorTime.value : getOrElse(fromNullish(given.time), Math.floor(Date.now() / 1000));
177 const pushRef = validatePushRef(givenRef, false);
178 if (!pushRef.ok) return pushRef;
179 // oxlint-disable-next-line typescript/no-unnecessary-type-conversion -- a JS caller's base may be any value; String() as before
180 const parsed = resolvedBase(String(baseIn));
181 if (!parsed.ok) return parsed;
182 const resolved = parsed.value;
183 const person = validateIdent(identInput(author, stamp));
184 if (!person.ok) return person;
185 const committer = fromNullish(given.committer);
186 const written = committer.tag === 'none' ? person : validateIdent(identInput(committer.value, getOrElse(fromNullish(committer.value.time), stamp)));
187 if (!written.ok) return written;
188 const checkedMessage = validateMessage(message);
189 if (!checkedMessage.ok) return checkedMessage;
190 const comps = map(validatePath(spec.path, checkedLimits.value), p => p.components);
191 if (!comps.ok) return comps;
192 const find: unknown = bytesOf(spec.find), replace: unknown = bytesOf(spec.replace);
193 if (!(find instanceof Uint8Array) || !(replace instanceof Uint8Array)) return fail('bad_request', 'find/replace must be string or Uint8Array');
194 if (!find.length) return fail('bad_request', 'find must be non-empty');
195 const hint = headHint(head);
196 if (!hint.ok) return hint;
197 // oxlint-disable-next-line typescript/no-unnecessary-type-conversion -- a JS caller's ref and path may be any value; String() as before
198 return ok(Object.freeze({ ref: pushRef.value, base: resolved, create: resolved.kind === 'ref' && resolved.ref !== String(givenRef), path: String(spec.path), comps: comps.value, find, replace, author: person.value, committer: written.value, message, time: person.value.time, head: hint.value }));
201// The ref exists and the caller named a commit that is not its tip. Committing there would move the ref off its
202// history. A new ref is how that commit is published. Not inside editOnce: that function's fail sites belong to the
203// merged `edges` space.
204export function refuseRebase(ref: string, base: string, tip: string): Err<ErrorOf<'bad_request'>> {
205 return fail('bad_request', `base ${base} is not the tip of ${ref} (${tip}); omit base to commit on the tip, or name a new ref to start from that commit`, { what: 'rebase' });
208// Pure: which oid is the parent, and what the hint turned out to be. ls-refs always wins; the hint only decides
209// whether the speculative commit fetch was useful ('used') or wasted ('stale').
210export type HintOutcome = 'used' | 'stale';
211export type HeadDecision<R> = { readonly oldCommit: R; readonly hint: HintOutcome | null };
212export function decideHead<R extends string | null>({ hint, resolved }: { readonly hint: string | null; readonly resolved: R }): HeadDecision<R> {
213 if (hint === null) return { oldCommit: resolved, hint: null };
214 return { oldCommit: resolved, hint: hint === resolved ? 'used' : 'stale' };
216// Pure: `strictHead` makes the hint a precondition. A stale hint is a cas_conflict before anything is pushed.
217export function strictParent(strictHead: boolean, decided: HeadDecision<string | null>, base: string, head: string | null): Result<null, ErrorOf<'cas_conflict'>> {
218 if (!strictHead || decided.hint !== 'stale') return ok(null);
219 return fail('cas_conflict', `${base} is at ${getOrElse(fromNullish(decided.oldCommit), 'nothing')}, not the expected head ${String(head)}`, { expected: head, actual: decided.oldCommit });
221// Pure: `strictHead` without a `head` has nothing to hold the ref to.
222export function needsHead(strictHead: boolean, head: string | null): Result<null, ErrorOf<'bad_request'>> {
223 return strictHead && head === null ? fail('bad_request', 'strictHead needs head') : ok(null);
226// Pure: one path component against one tree's entries.
227export type Found = { readonly entry: TreeEntry; readonly attrs: Attrs };
228// The lookup on entries already parsed (a fetched tree's, #208); `bytes` is the tree's size, for the span
229function findEntry(entries: readonly TreeEntry[], bytes: number, name: string, last: boolean): Result<Found, PlyError> {
230 const found = fromNullish(entries.find(e => e.name === name));
231 const attrs = { 'git.edit.tree.bytes': bytes, 'git.edit.tree.entries': entries.length, 'git.edit.tree.entry.found': found.tag === 'some', 'git.edit.tree.entry.mode': getOrElse(mapOption(found, e => e.mode), ''), 'git.edit.tree.entry.oid': getOrElse(mapOption(found, (e): string => e.oid), ''), 'git.edit.tree.entry.oid_offset': getOrElse(mapOption(found, e => e.oidOffset), -1) };
232 if (found.tag === 'none') return fail('not_found', `path component ${name} not found`, { attrs, miss: { kind: 'path', missing: name, existingPath: '' } });
233 const entry = found.value;
234 if (!last && entry.mode !== '40000') return fail('not_found', `${name} is not a directory`, { attrs, miss: { kind: 'not_directory', path: name, mode: entry.mode } });
235 if (last && !(entry.mode === '100644' || entry.mode === '100755')) {
236 let miss: Miss;
237 if (entry.mode === '40000') miss = { kind: 'is_directory', path: name, tree: entry.oid };
238 else if (entry.mode === '160000') miss = { kind: 'submodule', path: name, commit: entry.oid };
239 else miss = { kind: 'not_directory', path: name, mode: entry.mode };
240 return fail('not_found', `${name} is not a regular file (mode ${entry.mode})`, { attrs, miss });
241 }
242 return ok({ entry, attrs });
244export function lookupEntry(data: Uint8Array, name: string, last: boolean, limits: LimitsInput): Result<Found, PlyError> {
245 const parsed = parseTree(data, limits);
246 return parsed.ok ? findEntry(parsed.value, data.length, name, last) : parsed;
249export type Level = BuiltLevel;
250// The blob side of an edit, as streamBlobEdit returns it.
251export type BlobEdit = {
252 readonly oldOid: Oid;
253 readonly newOid: Oid;
254 readonly delta: Uint8Array;
255 readonly baseLen: number;
256 readonly newLen: number;
257 readonly matchOffset: number;
258 readonly scan: ScanState;
259 readonly inflated: number;
260};
261export type NewTree = BuiltNewTree;
262export type Built = {
263 readonly trees: readonly NewTree[];
264 readonly newTree: Oid;
265 readonly commitData: Uint8Array;
266 readonly newCommit: Oid;
267 readonly objects: readonly PackObject[];
268};
269// buildCommitObjects and withCommitData now live in commit/build.ts
271// Pure: memory accounting for the whole edit, from what was actually held: each metadata object (whole, bounded by
272// limits.maxObjectSize) and the streamed blob's chunks (DecompressionStream's; counted from the scanner's state).
273type Held = Pick<ScanState, 'chunks' | 'maxChunk'>;
274export const memFromScan = (scan: Held, inflated: number): Attrs => ({ 'mem.alloc.inflate_chunk.bytes': inflated, 'mem.alloc.inflate_chunk.count': scan.chunks, 'mem.alloc.inflate_chunk.max_single': scan.maxChunk });
275export const memAttrs = ({ objects, scan, inflated }: { readonly objects: readonly number[]; readonly scan: Held; readonly inflated: number }): Attrs => ({
276 'mem.alloc.bytes': objects.reduce((n, o) => n + o, 0) + inflated, 'mem.alloc.count': objects.length + scan.chunks, 'mem.alloc.max_single': Math.max(0, ...objects, scan.maxChunk),
277 'mem.alloc.object.bytes': objects.reduce((n, o) => n + o, 0), 'mem.alloc.object.count': objects.length, ...memFromScan(scan, inflated),
278});
280export type EditResult = {
281 readonly noop: boolean;
282 readonly oldCommit: Oid;
283 readonly newCommit: Oid;
284 readonly oldTree: Oid;
285 readonly newTree: Oid;
286 readonly oldBlob: Oid;
287 readonly newBlob: Oid;
288 readonly matchOffset: number;
289 readonly baseLen: number;
290 readonly newLen: number;
291 readonly pushBytes: number;
292 readonly trees: ReadonlyArray<{ readonly old: string; readonly new: string }>;
293 readonly hint: HintOutcome | null;
294 readonly attempt: number;
295};
296// Pure: the result record. `next` is the commit that was pushed; a no-op has none.
297type Pushed = { readonly newCommit: Oid; readonly newTree: Oid; readonly trees: readonly NewTree[]; readonly pushBytes: number };
298const summarize = ({ oldCommit, commit, blob, hint, attempt }: {
299 readonly oldCommit: Oid;
300 readonly commit: { readonly tree: Oid };
301 readonly blob: BlobEdit;
302 readonly hint: HintOutcome | null;
303 readonly attempt: number;
304}, next: Pushed | null): EditResult => {
305 const { newCommit, newTree, trees, pushBytes }: Pushed = next === null ? { newCommit: oldCommit, newTree: commit.tree, trees: [], pushBytes: 0 } : next;
306 return { noop: next === null, oldCommit, newCommit, oldTree: commit.tree, newTree, oldBlob: blob.oldOid, newBlob: blob.newOid, matchOffset: blob.matchOffset, baseLen: blob.baseLen, newLen: blob.newLen, pushBytes, trees: trees.map(t => ({ old: t.baseOid, new: t.newOid })), hint, attempt };
307};
309// The options operation() reads pass through (tracer, auth, fetchImpl, limits, transport, …); these are the edit's own.
310// `cache` null: a fresh tree cache per attempt. `signer` null: the commit is not signed.
311export type EditConfig = {
312 readonly head: string | null;
313 readonly strictHead: boolean;
314 readonly cache: Map<string, Uint8Array> | null;
315 readonly verify: boolean;
316 readonly allowLfsPointer: boolean;
317 readonly signer: Signer | null;
318 readonly retry: boolean;
319};
320export type EditOptions = EntryOptions & Input<EditConfig>;
321const editDefaults = (): { -readonly [K in keyof EditConfig]: EditConfig[K] } => ({ head: null, strictHead: false, cache: null, verify: false, allowLfsPointer: false, signer: null, retry: true });
322// `create`: what commitChanges already read about `ref`, which every push of this edit asserts (editexpect.ts):
323// true, the ref is absent (zero old oid); false, it is at the parent; null, this attempt's own reads decide.
324type Attempt = { readonly head: Oid | null; readonly attempt: number; readonly linkTo: Span | null; readonly hintWas: HintOutcome | null; readonly create: boolean | null };
326// A packcache fetch reports its counters (attrs()); any other fetch has none.
327const fetchCounters = (opts: EntryOptions): Attrs => {
328 const fetchImpl = fromNullish(opts.fetchImpl);
329 if (fetchImpl.tag === 'none') return {};
330 const counters = fromNullish(fetchImpl.value.attrs);
331 return counters.tag === 'some' ? counters.value() : {};
332};
334// A span whose body answers with a Result: an Err is recorded on the span as a thrown error would be (status, error.type,
335// the exception event), and returned. What the body throws (another module's refusal) still ends the span as an error.
336// oxlint-disable-next-line typescript/promise-function-async -- the span's promise, returned as is
337export function inSpan<T>(tracer: Tracer, name: string, opts: StartOptions, body: (span: Span) => Promise<Result<T, PlyError>>): Promise<Result<T, PlyError>> {
338 return spanOn(tracer, name, opts, async span => {
339 const r = await body(span);
340 if (!r.ok) span.error(r.error);
341 return r;
342 });
345// What a failed attempt carries out (operation() sets the root span; the attempt loop sets attempt and hint), read back
346// for the retry: the span to link to and the hint as it turned out.
347const isSpan = (v: unknown): v is Span => typeof v === 'object' && v !== null && 'spanId' in v && 'traceId' in v;
348const isHint = (v: unknown): v is HintOutcome => v === 'used' || v === 'stale';
349export const retryLink = (e: unknown): { readonly linkTo: Span | null; readonly hintWas: HintOutcome | null } => {
350 const span = field(e, 'span');
351 const hint = field(e, 'hint');
352 return { linkTo: span.tag === 'some' && isSpan(span.value) ? span.value : null, hintWas: hint.tag === 'some' && isHint(hint.value) ? hint.value : null };
353};
354// An attempt's error leaves with its attempt number and how the hint turned out (an object only: a primitive has no fields).
355export const tagAttempt = (e: unknown, attempt: number, hint: HintOutcome | null): void => {
356 if (typeof e === 'object' && e !== null) Object.assign(e, { attempt, hint });
357};
359// Effect: stream one blob through inflate → scan → sha, never holding it. Returns the new blob's identity and delta.
360// A Git LFS pointer is what the repository stores for an LFS-tracked file; the real content lives in the LFS store.
361// Editing the pointer as if it were the file corrupts the pointer (and git-lfs then refuses the whole checkout). The
362// pointer announces itself in its first bytes, which we are streaming anyway, so the guard costs nothing.
363type Hasher = ReturnType<typeof streamingSha1>;
364const LFS_MAGIC = te.encode('version https://git-lfs.github.com/spec/v1');
365export const isLfsPointerPrefix = (bytes: Uint8Array): boolean => { const n = Math.min(bytes.length, LFS_MAGIC.length); for (let i = 0; i < n; i++) if (bytes[i] !== LFS_MAGIC[i]) return false; return n === LFS_MAGIC.length; };
366const ignore
367 = (): void => { /* the read side's error is the one reported */ };
369type BlobWant = {
370 readonly t: Transport;
371 readonly tracer: Tracer;
372 readonly root: Span;
373 readonly blobOid: Oid;
374 readonly find: Uint8Array;
375 readonly replace: Uint8Array;
376 readonly allowLfsPointer: boolean;
377};
378// oxlint-disable-next-line typescript/promise-function-async -- the span's promise, returned as is
379function streamBlobEdit({ t, tracer, root, blobOid, find, replace, allowLfsPointer }: BlobWant): Promise<Result<BlobEdit, PlyError>> {
380 return inSpan(tracer, 'git.edit.blob', { parent: root, attrs: { 'git.edit.blob.oid': blobOid } }, async span => {
381 const fetchSpan = tracer.start('git.upload-pack fetch', { parent: span, kind: KIND.CLIENT });
382 let sp: SpState = spInit();
383 let scan = scanInit({ find, replace });
384 // -1 until the declared size is known and checked (begin)
385 let newLen = -1;
386 let inflated = 0;
387 let cpuMs = 0;
388 const ds = new DecompressionStream('deflate');
389 const writer = ds.writable.getWriter();
390 // The pump's failure reaches the inflate side through the stream protocol: aborting the writer errors ds.readable,
391 // which inflate() reads, so the pump itself never rejects.
392 const abortWith = async (e: unknown): Promise<void> => { fetchSpan.error(e).end(); await writer.abort(e).catch(ignore); };
393 const pump = (async (): Promise<void> => {
394 try {
395 for await (const chunk of packStream(t, { wants: [blobOid] }, fetchSpan)) {
396 const r = spStep(sp, chunk);
397 if (!r.ok) { await abortWith(r.error); return; }
398 sp = r.value.state;
399 for (const z of r.value.zlib) await writer.write(bufferSource(z));
400 }
401 const finished = spFinish(sp);
402 if (!finished.ok) { await abortWith(finished.error); return; }
403 sp = finished.value;
404 await writer.close();
405 fetchSpan.end();
406 } catch (e) { await abortWith(e); }
407 })();
408 const partial = (): Span => span.set({ 'git.edit.blob.base_len': sp.size, 'git.edit.blob.new_len': newLen, 'git.edit.blob.inflated': inflated, 'git.edit.blob.zlib.bytes': sp.zlibBytes, 'git.edit.blob.pack.bytes': sp.bytes, 'git.edit.blob.pack.trailer': getOrElse(fromNullish(sp.trailer), ''), 'git.edit.blob.cpu_ms': cpuMs, ...scanAttrs(scan) });
409 // the hasher, once the declared size is known and checked: it has hashed the object header
410 const begin = async (): Promise<Result<Hasher, PlyError>> => {
411 if (sp.type !== TYPE.BLOB) return fail('pack_corrupt', `expected blob, got type ${sp.type}`);
412 if (sp.size < find.length) return fail('match_count', `blob (${sp.size} bytes) is shorter than find (${find.length} bytes): expected exactly one match, found 0`, { matches: 0 });
413 newLen = sp.size - find.length + replace.length; // exactly-one-match contract
414 const h = streamingSha1(); span.set({ 'git.edit.blob.hasher': h.kind });
415 await h.update(objectHeader('blob', newLen));
416 return ok(h);
417 };
418 // The inflate side: every chunk scanned and hashed. The hasher once the first chunk arrived (none for an empty blob).
419 const inflate = async (): Promise<Result<Hasher | null, PlyError>> => {
420 let sha: Hasher | null = null;
421 for await (const chunk of ds.readable) {
422 // before begin(): a stream that inflates past its declared size is the server's lie (pack_corrupt), even when the
423 // declared size is shorter than find (an empty blob followed by a byte used to be reported as match_count)
424 inflated += chunk.length;
425 if (inflated > sp.size) return fail('pack_corrupt', `server streamed more than the ${sp.size} bytes it declared`);
426 if (sha === null) {
427 // Unreachable: zlib is written only after phase is body, and a header-phase size is 0, so any positive
428 // chunk has already failed the declared-size check. DecompressionStream emits no empty chunk.
429 if (sp.phase !== 'body') return fail('pack_corrupt', 'inflated bytes before header');
430 const lfs = isLfsPointerPrefix(chunk); span.set({ 'git.edit.blob.lfs_pointer': lfs });
431 // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the pointer's size rides as an ad-hoc field (errors.ts Extra), as fetch.ts's size does
432 if (lfs && !allowLfsPointer) return fail('lfs_pointer', `${blobOid} is a Git LFS pointer (${sp.size} bytes); the file's content is in the LFS store, not in git. Pass allowLfsPointer to edit the pointer itself.`, { size: sp.size } as Extra);
433 const began = await begin();
434 if (!began.ok) return began;
435 sha = began.value;
436 }
437 const c0 = cpuNow();
438 const r = scanStep(scan, chunk); scan = r.state;
439 for (const p of r.emit) await sha.update(p);
440 const dc = cpuSince(c0); if (dc !== null) cpuMs += dc;
441 }
442 await pump;
443 return ok(sha);
444 };
445 let inflatedTo: Result<Hasher | null, PlyError>;
446 try { inflatedTo = await inflate(); } catch (e) {
447 await pump.catch(ignore);
448 partial();
449 if (isPlyError(e)) return err(e);
450 if (!isPlyThrown(e)) return fail('pack_corrupt', `blob stream: ${thrownText(e)}`, { cause: e });
451 // a coded value that is not an Error: the caller's own, passed on as thrown
452 throw e;
453 }
454 if (!inflatedTo.ok) { await pump.catch(ignore); partial(); return inflatedTo; }
455 let sha: Hasher;
456 if (inflatedTo.value === null) { // empty blob
457 const began = await begin();
458 if (!began.ok) { partial(); return began; }
459 sha = began.value;
460 } else sha = inflatedTo.value;
461 const fin = scanFinish(scan); scan = fin.state; for (const p of fin.emit) await sha.update(p);
462 partial();
463 if (inflated !== sp.size) return fail('pack_corrupt', `inflated ${inflated} != header size ${sp.size}`);
464 if (scan.count !== 1) return fail('match_count', `expected exactly one match, found ${scan.count}`, { matches: scan.count });
465 if (scan.emitted !== newLen) return fail('internal', `emitted ${scan.emitted} != ${newLen}`);
466 const newOid = await sha.hex();
467 // exactly one match (checked above), so matches[0] is its offset
468 const matchOffset = atOr(scan.matches, 0, 0);
469 const { delta, ops } = spliceDelta({ baseLen: sp.size, off: matchOffset, oldLen: find.length, insert: replace });
470 span.set({ 'git.edit.blob.new': newOid, 'git.edit.blob.match_offset': matchOffset, 'git.edit.blob.delta.bytes': delta.length, 'git.edit.blob.delta.copy_ops': ops.copy, 'git.edit.blob.delta.insert_ops': ops.insert });
471 return ok({ oldOid: blobOid, newOid, delta, baseLen: sp.size, newLen, matchOffset, scan, inflated });
472 });
475// oxlint-disable-next-line require-await -- async, as before: the spec's refusal is an Err the promise resolves with
476async function editOnce(url: string, s: EditPlan, options: EditOptions & { readonly limits: CheckedLimits }, cfg: EditConfig, { head, attempt, linkTo, hintWas, create }: Attempt): Promise<Result<EditResult, PlyError>> {
477 const { verify, allowLfsPointer, signer, strictHead } = cfg;
478 const cache = cfg.cache === null ? new Map<string, Uint8Array>() : cfg.cache;
479 const { limits } = options;
480 const base = baseName(s.base);
481 const held: number[] = []; // sizes of metadata objects held whole, for memAttrs
482 let streamed: { readonly scan: Held; readonly inflated: number } = { scan: { chunks: 0, maxChunk: 0 }, inflated: 0 };
483 let hint = hintWas;
484 let creating = create === null ? s.create : create;
485 const attrs = { 'git.edit.ref': s.ref, 'git.edit.base': base, 'git.edit.create': s.create, 'git.edit.path': s.path, 'git.edit.path.depth': s.comps.length, 'git.edit.find.bytes': s.find.length, 'git.edit.replace.bytes': s.replace.length, 'git.edit.head.hint': head === null ? '' : head, 'git.edit.attempt': attempt };
486 // on every exit: how the hint turned out, what was held in memory, and the pack cache's counters if the fetch has them
487 const onFinish = (): Attrs => ({ 'git.edit.head.outcome': hint === null ? '' : hint, ...memAttrs({ objects: held, ...streamed }), ...fetchCounters(options) });
488 return operation('edit', url, { ...options, attrs, onFinish, link: linkTo === null ? null : { span: linkTo, kind: 'retry_of' } }, async ({ t, root, outcome }) => {
489 // the tracer operation() started the root span on (opts.tracer)
490 const tracer = root.tracer;
491 const getObject = async (oid: Oid, expectType: number, deepen: number): Promise<Result<Fetched, PlyError>> => { const o = await objectAt(t, oid, { filter: 'tree:0', deepen, expectType }); if (o.ok) held.push(o.value.size); return o; };
492 // An attempt's Err leaves with its attempt number and how the hint turned out: retryLink reads them for the retry.
493 // oxlint-disable-next-line complexity -- the edit is one sequence of protocol steps
494 const done = await (async (): Promise<Result<EditResult, PlyError>> => {
495 // 1+2. parent commit: ls-refs, overlapped with a speculative fetch of the hinted commit when there is a hint.
496 // A ref base keeps the original chain. A 40-hex base is that commit; the ref is listed, and a tip that is some
497 // other commit is refuseRebase (the ref is not moved off its tip). A missing ref is not_found with miss.kind 'ref'.
498 const resolve = async (): Promise<Result<Oid, PlyError>> => {
499 const b = s.base;
500 if (b.kind === 'commit') {
501 const listed = await lsRefs(t, [s.ref]); if (!listed.ok) return listed;
502 const tip = mapOption(mapGet(listed.value.refs, s.ref), r => r.oid);
503 if (tip.tag === 'some' && tip.value !== b.oid) return refuseRebase(s.ref, b.oid, tip.value);
504 if (create === null) creating = tip.tag === 'none';
505 return ok(b.oid);
506 }
507 const listed = await lsRefs(t, [b.ref]); if (!listed.ok) return listed;
508 const found = mapGet(listed.value.refs, b.ref);
509 if (found.tag === 'none') return fail('not_found', `ref ${b.ref} not found`, { miss: { kind: 'ref', ref: b.ref, candidates: [b.ref] } });
510 // another ref as the base is the commit it names: an annotated tag is peeled, as `git checkout -b <ref> <tag>` does
511 return ok(s.create ? getOrElse(fromNullish(found.value.peeled), found.value.oid) : found.value.oid);
512 };
513 // oxlint-disable-next-line typescript/strict-boolean-expressions -- bundle budget: the JS's own truthy test, byte for byte (head is null or a checked oid)
514 const [resolvedTo, speculative] = await Promise.all([resolve(), head ? getObject(head, TYPE.COMMIT, 1) : null]);
515 if (!resolvedTo.ok) return resolvedTo;
516 const resolved = resolvedTo.value;
517 root.set({ 'git.edit.create': creating });
518 const decided = decideHead({ hint: head, resolved });
519 hint = hintWas === null ? decided.hint : hintWas;
520 const { oldCommit } = decided;
521 const strict = strictParent(strictHead, decided, base, head);
522 if (!strict.ok) return strict;
523 if (speculative !== null && !speculative.ok) root.set({ 'git.edit.head.speculative_error': speculative.error.code });
524 const commitGot = decided.hint === 'used' && speculative !== null && speculative.ok ? speculative : await getObject(oldCommit, TYPE.COMMIT, 1);
525 if (!commitGot.ok) return commitGot;
526 const parsed = parseCommit(commitGot.value.data, limits);
527 if (!parsed.ok) return parsed;
528 const commit: { readonly tree: Oid; readonly parents: readonly Oid[] } = parsed.value;
529 root.set({ 'git.edit.commit.old': oldCommit, 'git.edit.tree.root': commit.tree, 'git.edit.commit.old.parents': commit.parents.length });
531 // 3. trees, one per level. Effect: fetch on cache miss; decision: lookupEntry.
532 const levels: Level[] = [];
533 let cacheHits = 0;
534 let treeOid = commit.tree;
535 for (const [depth, name] of s.comps.entries()) {
536 const last = depth === s.comps.length - 1;
537 // oxlint-disable-next-line no-loop-func -- the span runs to completion inside this iteration (awaited)
538 const lvl = await inSpan(tracer, 'git.edit.tree', { parent: root, attrs: { 'git.edit.tree.depth': depth, 'git.edit.tree.oid': treeOid, 'git.edit.tree.lookup': name } }, async span => {
539 const cached = mapGet(cache, treeOid);
540 let data: Uint8Array;
541 // a fetched tree's entries are the ones its check parsed (treeEntries, #208); a cached tree's are parsed here
542 let entries: Result<TreeEntry[], PlyError>;
543 if (cached.tag === 'some') { data = cached.value; cacheHits++; entries = parseTree(data, limits); } else { const got = await getObject(treeOid, TYPE.TREE, 0); if (!got.ok) return got; data = got.value.data; cache.set(treeOid, data); entries = treeEntries(got.value, limits); }
544 span.set({ 'git.edit.tree.cache_hit': cached.tag === 'some' });
545 const found = entries.ok ? findEntry(entries.value, data.length, name, last) : entries;
546 if (!found.ok) {
547 const seen = fromNullish(found.error.attrs);
548 if (seen.tag === 'some') span.set(seen.value);
549 return found;
550 }
551 span.set(found.value.attrs);
552 return ok({ treeOid, data, entry: found.value.entry });
553 });
554 if (!lvl.ok) return lvl;
555 const level = lvl.value;
556 levels.push(level);
557 treeOid = level.entry.oid;
558 }
559 const blobOid = treeOid;
560 root.set({ 'git.edit.blob.old': blobOid, 'git.edit.tree.cache_hits': cacheHits, 'git.edit.tree.fetches': s.comps.length - cacheHits });
562 // 4. streamed blob replace. Effect: one pack stream; decisions: spStep/scanStep (pure), the exactly-one-match contract.
563 const edited = await streamBlobEdit({ t, tracer, root, blobOid, find: s.find, replace: s.replace, allowLfsPointer });
564 if (!edited.ok) return edited;
565 const blob = edited.value;
566 streamed = { scan: blob.scan, inflated: blob.inflated };
568 // identical content → no commit; a no-op edit must not create an empty commit
569 if (blob.newOid === blobOid) return outcome('noop', summarize({ oldCommit, commit, blob, hint, attempt }, null), { 'git.edit.blob.new': blob.newOid });
571 // 5+6. new trees + commit (pure), then push (effect).
572 const objects = buildCommitObjects({ levels, blob, oldCommit, author: s.author, committer: s.committer, time: s.time, message: s.message });
573 if (!objects.ok) return objects;
574 let built = objects.value;
575 if (signer !== null) {
576 const signed = await signCommit(built.commitData, signer);
577 if (!signed.ok) return signed;
578 built = withCommitData(built, signed.value); root.set({ 'git.edit.commit.signed': signer.kind, 'git.edit.commit.signer': getOrElse(fromNullish(signer.publicKeyLine), '') });
579 }
580 for (const tr of built.trees) cache.set(tr.newOid, tr.newData);
581 root.set({ 'git.edit.tree.new': built.newTree, 'git.edit.commit.new': built.newCommit, 'git.edit.commit.bytes': built.commitData.length });
582 const pushed = await push(t, { ref: s.ref, oldOid: creating ? ZERO_OID : oldCommit, newOid: built.newCommit, objects: built.objects });
583 if (!pushed.ok) return pushed;
584 // report-status is the only receipt git offers, and a middlebox can forge it. verify: re-read the ref (one ~100 B
585 // roundtrip) and require it to be our commit; a mismatch is 'ambiguous' (the push was acknowledged but not observed).
586 if (verify) { const seen = await verifyRef(t, root, 'git.edit', s.ref, built.newCommit); if (!seen.ok) return seen; }
587 const { packBytes } = pushed.value;
588 return outcome('ok', summarize({ oldCommit, commit, blob, hint, attempt }, { newCommit: built.newCommit, newTree: built.newTree, trees: built.trees, pushBytes: packBytes }), { 'git.edit.push.bytes': packBytes, 'git.edit.push.ratio': packBytes / Math.max(1, blob.newLen) });
589 })();
590 if (!done.ok) tagAttempt(done.error, attempt, hint);
591 return done;
592 });
595// `head`: an oid the caller believes `ref` points at (e.g. its last newCommit). ls-refs and the hinted commit fetch run
596// concurrently; a stale hint is corrected before anything is pushed (same wall time as skipping ls-refs, one more
597// request, no wasted push). A cas_conflict on attempt 0 (replica lag: ls-refs and receive-pack disagreed) is redone
598// once; the retry's root span links to the first attempt's.
599// `strictHead: true` turns the hint into a precondition: if `ref` is not at `head`, the edit is a `cas_conflict` before
600// anything is pushed, and it is not retried (the caller asked for exactly that parent).
601// `retry: false` is the caller's own race handling (commitChanges): attempt 0's cas_conflict is not redone here.
602// An Err carries the attempt's tag (attempt, hint, the root span).
603// commitChanges has already read `ref` and decided its compare-and-swap; it says so through editexpect.ts, which no
604// package entry exports, so a consumer's editFile always decides by its own reads (`create` null). `create` true: the
605// ref was absent, so the push asserts the zero old oid whatever this edit's own ls-refs sees later (a ref another
606// writer made in between is a cas_conflict, never a commit on top of it). false: the ref existed, and the push
607// asserts the parent.
608export async function editFile(url: string, spec: EditSpec, options: EditOptions = {}): Promise<Result<EditResult, PlyError>> {
609 const create = expectedCreate(options);
610 const cfg = withDefaults(options, editDefaults());
611 const needs = needsHead(cfg.strictHead, cfg.head);
612 if (!needs.ok) return needs;
613 // the limits and the spec are parsed once: both attempts run on this plan (the retry asks with no head hint)
614 const limits = limitsOf(options);
615 if (!limits.ok) return limits;
616 const planned = validateSpec(spec, limits.value, cfg.head);
617 if (!planned.ok) return planned;
618 const plan = planned.value;
619 const checked = { ...options, limits: limits.value };
620 const first = await editOnce(url, plan, checked, cfg, { head: plan.head, attempt: 0, linkTo: null, hintWas: null, create });
621 // only attempt 0's cas_conflict is redone, once: the retry's Err is the answer
622 // Only ply's own error is a lost race: a look-alike object a transport raises is returned as it is, not retried.
623 if (first.ok || !cfg.retry || !isPlyError(first.error) || first.error.code !== 'cas_conflict' || cfg.strictHead) return first;
624 return editOnce(url, plan, checked, cfg, { head: null, attempt: 1, create, ...retryLink(first.error) });
Diagnostics4 git calls · 236 ms
CallStatusSizeTime0236 ms
discover200152 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=152
git.server.agent=gitty/1.0
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch object-format
git.server.fetch=shallow filter sideband-all
git.protocol.version=2
git.pkt.frames=8
git.pkt.data=6
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=152
git.pkt.payload.max=34
ls-refs200145 B · hit3 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=145
git.response.cache=HIT
git.response.duration_ms=3
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=145
git.pkt.payload.max=76
git.ls_refs.count=2
git.ls_refs.head=refs/heads/main
fetchblob:none · deepen 1020038 KiB · hit2 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=38434
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=blob:none
git.fetch.filter.requested=tree:0
git.fetch.filter.fallback=blob:none
git.fetch.filter.learned=false
git.fetch.wants=19912563f540228593df0c489082e5e2508e21e4
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=6
git.pkt.data=4
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=38434
git.pkt.payload.max=38339
git.sideband.band1.bytes=38338
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=63
git.pack.bytes=38338
git.pack.ofs_delta=0
git.pack.ref_delta=8
git.pack.chain.max=8
git.pack.trailer=0bc36ab7adf82d3109177f11f1ea93f1ce071f77
git.pack.full=55
Open pack map
fetch20013 KiB231 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=231
git.response.bytes=13199
git.response.cache=MISS
git.response.duration_ms=231
git.fetch.wants=ea9b2097d18342a9ad6e831843b49602708a7eeb
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=13199
git.pkt.payload.max=13178
git.sideband.band1.bytes=13177
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/ply.git
Ref
refs/heads/main
Commit
19912563f540228593df0c489082e5e2508e21e4
cf-ray
a5e24ca87c6b0ecd
Request
42c64f41…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format