main
1// A whole tree as one commit: the caller names every file (a build output, a generated site, a deploy artifact) and
2// the commit's tree is exactly that set. Where editFile changes one path of the parent's tree, pushTree replaces it.
3//
4// ls-refs (‖ the hinted commit) → the parent commit (tree:0, deepen 1) → the parent's trees, only where the new tree
5// differs (tree:0 per directory; on a host that refuses tree:0 the first fetch is blob:none and carries them all) →
6// one thin pack: the commit, the new trees (REF_DELTA against the tree they replace when that is smaller), and only the
7// blobs no fetched parent tree names → receive-pack, old oid = the parent (or zeros for a new ref) as the CAS.
8//
9// Workers-safe (Web APIs only). The directory walk is Node's and lives in tree-node.js.
10//
11// Shape: pure decisions between thin effects, as edit.js. fileEntries, buildTree, selectObjects are functions of their
12// arguments; the effects (lsRefs, fetchObject, push, verifyRef) are free functions over a transport record.
13/* oxlint-disable import/max-dependencies -- an entry composes the protocol from one import per module, so its bundle carries nothing else */
14/* 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) */
15// Decisions and the public functions (fileEntries, buildTree, validateTreeSpec, pushTree) return Result.
16import { fail, isPlyError } from './errors.js';
17import type { ErrorOf, PlyError } from './errors.js';
18import { operation, verifyRef } from './operation.js';
19import { lsRefs } from './lsrefs.js';
20import { objectAt, treeEntries } from './fetch.js';
21import { push, ZERO_OID } from './push.js';
22import { parseRefname } from './refname.js';
23import type { Refname } from './refname.js';
24import { makeDelta } from './packresolve.js';
25import { parseCommit, parseTree, encodeEntries, encodeCommitOf, hashObject, ident, TYPE } from './objects.js';
26import { bytesOf } from './bytes.js';
27import { DEFAULT_LIMITS, LIMIT_OBJECT_OVERHEAD, limitExceeded, limitsOf, parseLimits } from './limits.js';
28import type { CheckedLimits, LimitsInput } from './limits.js';
29import { validateIdent, validateRef, validatePushRef, validatePath, validateMessage } from './validate.js';
30import { decideHead, inSpan, needsHead, retryLink, strictParent, tagAttempt } from './edit.js';
31import type { Author, EditConfig, EditOptions, HintOutcome, Ident } from './edit.js';
32import { signCommit } from './sign.js';
33import { MODE_BLOB, MODE_LINK, MODE_TREE, MODE_COMMIT, BLOB_MODES, DELTA_SIZE_MIN } from './format.js';
34import type { Span } from './otel.js';
35import type { FetchedObject as Fetched } from './fetch.js';
36import type { PackObject, PushResult as Pushed } from './push.js';
37import type { Transport } from './transport.js';
38import type { EntryOf, Mode, TreeEntry } from './objects.js';
39import { parseOid, type Oid } from './oid.js';
40import type { Input } from './absent.js';
41import { fromNullable, fromNullish, mapGet, withDefaults } from './absent.js';
42import { err, getOrElse, map, mapOption, matchOption, ok } from './result.js';
43import type { Result } from './result.js';
45const BLOB_MODE_SET: ReadonlySet<unknown> = new Set(BLOB_MODES);
46// A file's mode, parsed: one of the three blob modes.
47const isBlobMode = (mode: unknown): mode is (typeof BLOB_MODES)[number] => BLOB_MODE_SET.has(mode);
49// The caller's files, in either shape (below): a record or Map of path → content, or an iterable of file specs.
50export type FileSpec = { readonly path: string } & Input<{ readonly mode: string; readonly data: string | Uint8Array; readonly oid: string }>;
51export type FileContent = string | Uint8Array | Omit<FileSpec, 'path'>;
52export type TreeFiles = Readonly<Record<string, FileContent>> | ReadonlyMap<string, FileContent> | Iterable<FileSpec>;
53// One checked file: its path (and components), mode, oid, and bytes. A gitlink has no bytes (and no `data` key).
54// Mode and oid are parsed once, here (fileEntries): buildTree encodes them as they are.
55type EntryBase = { readonly path: string; readonly comps: readonly string[]; readonly mode: Mode; readonly oid: Oid };
56export type BlobFileEntry = EntryBase & { readonly data: Uint8Array };
57export type FileEntry = EntryBase | BlobFileEntry;
58const isBlobEntry = (e: FileEntry): e is BlobFileEntry => 'data' in e;
59type TreeError = ErrorOf<'bad_request' | 'limit_exceeded'>;
61// One caller entry, read as given: an entry that is not an object (null, a string) has no fields, and validatePath
62// refuses its missing path.
63const specOf = (f: unknown): Input<FileSpec> => {
64 // the caller's object: each field is checked below
65 return typeof f === 'object' && f !== null ? f : {};
67};
69// Pure: the caller's files as one list of { path, comps, mode, data?, oid }. Two input shapes:
70// { 'path': content } or a Map content: string | Uint8Array (100644) | { data, mode } | { mode: '160000', oid }
71// iterable of { path, mode?, data?, oid? }
72// Modes are git's tree modes: 100644 file, 100755 executable, 120000 symlink (data = the link target, as git stores
73// it), 160000 gitlink (oid = the submodule commit; no data — the server does not need that commit). Every path goes
74// through validatePath (no `.git`, `..`, empty component); each blob is bounded by maxObjectSize, the count by
75// maxPackObjects, and the running total by maxPushBytes, before anything is hashed. The total is each blob's bytes plus
76// LIMIT_OBJECT_OVERHEAD per entry (a gitlink too): a file's entry, its tree entry and its pack entry cost that much heap
77// whatever its size, so 100 000 tiny files are refused here instead of exhausting a Worker (#142). got is the running
78// total, including the entry that crossed the cap; exactly the cap is allowed.
79// oxlint-disable-next-line complexity -- one check per field, in the order git would refuse them
80export function fileEntries(files: unknown, limits: LimitsInput = DEFAULT_LIMITS): Result<FileEntry[], PlyError> {
81 if (files === null || typeof files !== 'object') return fail('bad_request', 'files must be an object or an iterable of { path, mode, data }', { what: 'files' });
82 const checked = parseLimits(limits);
83 if (!checked.ok) return checked;
84 const { maxPackObjects: maxFiles, maxObjectSize: maxObject, maxPushBytes: maxPush } = checked.value;
85 let pushBytes = 0;
86 const charge = (bytes: number): Result<null, PlyError> => {
87 const next = pushBytes + bytes + LIMIT_OBJECT_OVERHEAD;
88 if (next > maxPush) return err(limitExceeded('push bytes', next, maxPush));
89 pushBytes = next;
90 return ok(null);
91 };
92 // the caller's values: each is checked below (validatePath refuses a missing entry or path)
93 /* oxlint-disable typescript/no-unsafe-type-assertion -- see above */
94 // oxlint-disable-next-line no-nested-ternary -- bundle budget: the JS's expression, byte for byte
95 const pairs = files instanceof Map ? [...(files as Map<unknown, unknown>)] : Symbol.iterator in files ? null : Object.entries(files);
96 // oxlint-disable-next-line oxc/no-map-spread -- a fresh object per value: a spread defines `path`, where Object.assign would run a `__proto__` setter
97 const list = (pairs ? pairs.map(([path, v]) => (typeof v === 'string' || v instanceof Uint8Array ? { path, data: v } : { ...(v as object), path })) : files) as Iterable<unknown>;
98 /* oxlint-enable typescript/no-unsafe-type-assertion */
99 const out: FileEntry[] = [];
100 for (const f of list) {
101 if (out.length >= maxFiles) return err(limitExceeded('files', out.length + 1, maxFiles));
102 const spec = specOf(f);
103 const comps = map(validatePath(spec.path, checked.value), p => p.components);
104 if (!comps.ok) return comps;
105 const path = comps.value.join('/');
106 // a mode left out is a file's; any other value (null included) is the caller's, and checked
107 const mode: unknown = getOrElse<unknown>(fromNullable(spec.mode), MODE_BLOB);
108 if (mode === MODE_COMMIT) {
109 // a missing oid is no id either
110 const oid = parseOid(spec.oid);
111 if (!oid.ok || fromNullable(spec.data).tag === 'some') return fail('bad_request', `${path}: a gitlink (160000) takes a 40-hex oid and no data`, { what: 'gitlink', path });
112 const charged = charge(0);
113 if (!charged.ok) return charged;
114 out.push({ path, comps: comps.value, mode, oid: oid.value });
115 continue;
116 }
117 if (!isBlobMode(mode)) return fail('bad_request', `${path}: mode ${JSON.stringify(mode)} is not 100644, 100755, 120000 or 160000`, { what: 'mode', path });
118 const raw: unknown = spec.data;
119 if (typeof raw !== 'string' && !(raw instanceof Uint8Array)) return fail('bad_request', `${path}: data must be a string or Uint8Array`, { what: 'data', path });
120 const data = bytesOf(raw);
121 if (data.length > maxObject) return err(limitExceeded('object size', data.length, maxObject));
122 // a symlink target is a path: git cannot check out an empty one, and a NUL ends it on every platform
123 if (mode === MODE_LINK && (data.length === 0 || data.includes(0))) return fail('bad_request', `${path}: a symlink target must be non-empty and contain no NUL`, { what: 'symlink', path });
124 const charged = charge(data.length);
125 if (!charged.ok) return charged;
126 out.push({ path, comps: comps.value, mode, data, oid: hashObject('blob', data) });
127 }
128 return ok(out);
129}
131// A directory entry of a built tree; the built trees by directory ('' is the root) and the blobs by oid.
132export type DirEntry = EntryOf;
133export type BuiltDir = { readonly oid: Oid; readonly data: Uint8Array; readonly entries: readonly DirEntry[] };
134export type BuiltTree = { readonly root: Oid; readonly trees: ReadonlyMap<string, BuiltDir>; readonly blobs: ReadonlyMap<string, Uint8Array> };
135// Pure: the trees of `entries`, bottom up. Returns { root, trees: Map(dir → { oid, data, entries }), blobs: Map(oid →
136// data) }; '' is the root directory. A path given twice, or used as both a file and a directory, is the caller's
137// error (git would reject the tree as duplicateEntries); each directory is bounded by maxTreeEntries. No files at all is
138// git's empty tree (4b825dc6…), a valid root.
139export function buildTree(entries: readonly FileEntry[], limits: LimitsInput = DEFAULT_LIMITS): Result<BuiltTree, TreeError> {
140 const checked = parseLimits(limits);
141 if (!checked.ok) return checked;
142 const maxEntries = checked.value.maxTreeEntries;
143 // null: a subdirectory (its entries are under its own key)
144 const dirs = new Map<string, Map<string, DirEntry | null>>([['', new Map()]]);
145 const blobs = new Map<string, Uint8Array>();
146 // every directory looked up below was added to `dirs` (or `trees`) before: the root, or by the step that named it
147 /* oxlint-disable typescript/no-unsafe-type-assertion, typescript/non-nullable-type-assertion-style -- see above (and no `!`: docs/STACK.md) */
148 for (const e of entries) {
149 let dir = '';
150 for (const name of e.comps.slice(0, -1)) {
151 const sub = dir ? `${dir}/${name}` : name;
152 const here = dirs.get(dir) as Map<string, DirEntry | null>;
153 if (here.has(name) && here.get(name) !== null) return fail('bad_request', `${sub} is both a file and a directory`, { what: 'path', path: e.path });
154 if (!here.has(name)) { here.set(name, null); dirs.set(sub, new Map()); }
155 dir = sub;
156 }
157 const here = dirs.get(dir) as Map<string, DirEntry | null>, name = e.comps.at(-1) as string;
158 if (here.has(name)) return fail('bad_request', here.get(name) === null ? `${e.path} is both a file and a directory` : `${e.path} is given twice`, { what: 'path', path: e.path });
159 if (here.size >= maxEntries) return err(limitExceeded('tree entries', here.size + 1, maxEntries));
160 here.set(name, { mode: e.mode, name, oid: e.oid });
161 if (isBlobEntry(e)) blobs.set(e.oid, e.data);
162 }
163 // deepest first, so every subtree's oid exists before its parent is encoded
164 const trees = new Map<string, BuiltDir>();
165 // oxlint-disable-next-line unicorn/consistent-function-scoping -- bundle budget: where the JS had it
166 const depth = (dir: string): number => (dir === '' ? 0 : dir.split('/').length);
167 for (const dir of [...dirs.keys()].toSorted((a, b) => depth(b) - depth(a))) {
168 const list = [...(dirs.get(dir) as Map<string, DirEntry | null>)].map(([name, e]): DirEntry => (e === null ? { mode: MODE_TREE, name, oid: (trees.get(dir ? `${dir}/${name}` : name) as BuiltDir).oid } : e));
169 const encoded = encodeEntries(list);
170 if (!encoded.ok) return encoded;
171 const data = encoded.value;
172 trees.set(dir, { oid: hashObject('tree', data), data, entries: list });
173 }
174 return ok({ root: (trees.get('') as BuiltDir).oid, trees, blobs });
175 /* oxlint-enable typescript/no-unsafe-type-assertion, typescript/non-nullable-type-assertion-style */
176}
178// What the server is known to hold: `have` (oids), `old` (dir → the parent's tree there, a delta base).
179export type Known = { readonly have: ReadonlySet<string>; readonly old: ReadonlyMap<string, { readonly oid: string; readonly data: Uint8Array }> };
180export type Selected = { readonly trees: PackObject[]; readonly blobs: PackObject[]; readonly deltas: number };
181// Pure: what the pack must carry, given what the server is known to have. `have`: every oid named by a parent tree we
182// fetched (the server holds the parent commit's whole closure, so each of those objects is there); `old`: dir → the
183// parent's tree bytes at that path, a REF_DELTA base. A tree the server has is skipped with everything under it; a
184// blob or tree reached twice is sent once (receive-pack refuses a pack with an object twice). Gitlinks send nothing.
185export function selectObjects(built: BuiltTree, { have = new Set(), old = new Map() }: Input<Known> = {}): Selected {
186 const sent = new Set<string>();
187 const trees: PackObject[] = [];
188 const blobs: PackObject[] = [];
189 // every dir walked is a key of built.trees (the root, or a tree entry of one), and every blob entry's oid a key of built.blobs
190 /* oxlint-disable typescript/no-unsafe-type-assertion, typescript/non-nullable-type-assertion-style -- see above (and no `!`: docs/STACK.md) */
191 const walk = (dir: string): void => {
192 const t = built.trees.get(dir) as BuiltDir;
193 if (have.has(t.oid) || sent.has(t.oid)) return;
194 sent.add(t.oid);
195 // git's patch_delta rejects a delta under DELTA_SIZE_MIN; a delta no smaller than the tree is not worth the base lookup
196 const thin = mapOption(mapGet(old, dir), base => ({ base: base.oid, delta: makeDelta(base.data, t.data).delta }));
197 trees.push(thin.tag === 'some' && thin.value.delta.length >= DELTA_SIZE_MIN && thin.value.delta.length < t.data.length ? { type: TYPE.TREE, data: thin.value.delta, base: { tag: 'ref', oid: thin.value.base } } : { type: TYPE.TREE, data: t.data });
198 for (const e of t.entries) {
199 if (e.mode === MODE_TREE) walk(dir ? `${dir}/${e.name}` : e.name);
200 else if (BLOB_MODE_SET.has(e.mode) && !have.has(e.oid) && !sent.has(e.oid)) { sent.add(e.oid); blobs.push({ type: TYPE.BLOB, data: built.blobs.get(e.oid) as Uint8Array }); }
201 }
202 };
203 /* oxlint-enable typescript/no-unsafe-type-assertion, typescript/non-nullable-type-assertion-style */
204 walk('');
205 // oxlint-disable-next-line typescript/strict-boolean-expressions -- bundle budget: a truthy test (a tree here has a ref base or none at all)
206 return { trees, blobs, deltas: trees.filter(t => t.base).length };
207}
209// What the caller names besides the files: `ref` (default refs/heads/main), `base` (default `ref`), `time` (default now).
210export type TreeSpecConfig = { readonly ref: string; readonly base: string; readonly time: number };
211export type TreeSpec = Input<TreeSpecConfig> & { readonly files: TreeFiles; readonly author: Author; readonly message: string };
212export type TreePlan = {
213 readonly ref: Refname;
214 readonly base: string;
215 readonly create: boolean;
216 readonly built: BuiltTree;
217 readonly files: number;
218 readonly author: Ident;
219 readonly message: string;
220 readonly head: Oid | null;
221};
222// The author as validateIdent reads it: a missing author has no fields (and is refused there); a zone left out is UTC,
223// any other value is the caller's and checked.
224const authorInput = (author: Author | null, time: number): Parameters<typeof validateIdent>[0] =>
225 matchOption(fromNullish(author), {
226 none: () => ({ time }),
227 some: a => matchOption(fromNullable(a.tz), { none: () => ({ name: a.name, email: a.email, time }), some: tz => ({ name: a.name, email: a.email, time, tz }) }),
228 });
229// Pure: every caller-controlled field, checked before any I/O. `base` as in editFile: the ref whose head is the
230// parent (default `ref`); base ≠ ref creates `ref` (zero old oid). base = ref and the ref absent: the first commit of a
231// new ref, no parent, zero old oid — a deploy's first push.
232export function validateTreeSpec(spec: TreeSpec, limits: LimitsInput, head: string | null = null): Result<TreePlan, PlyError> {
233 const { ref, time } = withDefaults(spec, { ref: 'refs/heads/main', time: Math.floor(Date.now() / 1000) });
234 const { files, author, message } = spec;
235 const pushRef = validatePushRef(ref, false);
236 if (!pushRef.ok) return pushRef;
237 // a base left out is `ref`; any other value (null included) is the caller's, and checked
238 const baseRef = validateRef(getOrElse<unknown>(fromNullable(spec.base), ref));
239 if (!baseRef.ok) return baseRef;
240 const base = baseRef.value;
242 const person = validateIdent(authorInput(author, time));
243 if (!person.ok) return person;
244 const checkedMessage = validateMessage(message);
245 if (!checkedMessage.ok) return checkedMessage;
246 // the head hint, parsed once (as String() renders a JS caller's value)
247 // oxlint-disable-next-line typescript/no-unnecessary-type-conversion -- see above
248 const hint = head === null ? ok(null) : parseOid(String(head));
249 if (!hint.ok) return fail('bad_request', 'head must be a 40-hex oid');
250 // maxPushBytes is charged per entry as fileEntries reads them, before buildTree retains the blobs
251 const checked = parseLimits(limits);
252 if (!checked.ok) return checked;
253 const entries = fileEntries(files, checked.value);
254 if (!entries.ok) return entries;
255 const built = buildTree(entries.value, checked.value);
256 if (!built.ok) return built;
257 // validatePushRef passed, so the ref is a refname
258 const branded = parseRefname(ref);
259 if (!branded.ok) return branded;
260 return ok(Object.freeze({ ref: branded.value, base, create: base !== ref, built: built.value, files: entries.value.length, author: person.value, message, head: hint.value }));
261}
263export type PushTreeResult = {
264 readonly noop: boolean;
265 readonly ref: string;
266 readonly oldCommit: string | null;
267 readonly newCommit: string | null;
268 readonly oldTree: string | null;
269 readonly newTree: string;
270 readonly hint: HintOutcome | null;
271 readonly attempt: number;
272 readonly pushBytes: number;
273 readonly treesRead: number;
274 readonly objects: { readonly files: number; readonly trees: number; readonly sent: number; readonly sentTrees: number; readonly sentBlobs: number; readonly treeDeltas: number };
275};
276// Pure: the result record. `sent` is what was pushed; a no-op has nothing.
277type Sent = { readonly newCommit: string; readonly sel: Selected; readonly pushed: Pushed; readonly treesRead: number };
278const summarize = ({ s, parent, oldTree, hint, attempt }: {
279 readonly s: TreePlan;
280 readonly parent: string | null;
281 readonly oldTree: string | null;
282 readonly hint: HintOutcome | null;
283 readonly attempt: number;
284}, sent: Sent | null): PushTreeResult => {
285 const files = s.files, trees = s.built.trees.size;
286 if (sent === null) {
287 return { noop: true, ref: s.ref, oldCommit: parent, newCommit: parent, oldTree, newTree: s.built.root, hint, attempt, pushBytes: 0, treesRead: 0, objects: { files, trees, sent: 0, sentTrees: 0, sentBlobs: 0, treeDeltas: 0 } };
288 }
289 const { newCommit, sel, pushed, treesRead } = sent;
290 return {
291 noop: false, ref: s.ref, oldCommit: parent, newCommit, oldTree, newTree: s.built.root, hint, attempt, pushBytes: pushed.packBytes, treesRead,
292 objects: { files, trees, sent: pushed.entries.length, sentTrees: sel.trees.length, sentBlobs: sel.blobs.length, treeDeltas: sel.deltas },
293 };
294};
296type Read = Known & { read: number; hits: number };
297// Effect: the parent's trees wherever the new tree differs, recursing only into directories present on both sides with
298// different oids. Every oid those trees name joins `have`. On a host that refuses tree:0 the first fetch is a blob:none
299// pack that brings every tree of the subtree (fetch.js harvests them), so the rest are answered without a round trip.
300async function parentTrees(t: Transport, cache: Map<string, Uint8Array>, built: BuiltTree, oldTree: Oid | null, limits: CheckedLimits): Promise<Result<Read, PlyError>> {
301 const have = new Set<string>(), old = new Map<string, { readonly oid: string; readonly data: Uint8Array }>();
302 const k = { have, old, read: 0, hits: 0 };
303 if (oldTree === null) return ok(k);
304 have.add(oldTree);
305 // a tree's bytes and entries: from the cache (parsed here), or fetched (the fetch's check parsed it: treeEntries, #208)
306 const read = async (oid: Oid): Promise<Result<{ readonly data: Uint8Array; readonly entries: TreeEntry[] }, PlyError>> => {
307 const cached = mapGet(cache, oid);
308 if (cached.tag === 'some') { k.hits++; return map(parseTree(cached.value, limits), entries => ({ data: cached.value, entries })); }
309 const got = await objectAt(t, oid, { expectType: TYPE.TREE });
310 if (!got.ok) return got;
311 cache.set(oid, got.value.data); k.read++;
312 return map(treeEntries(got.value, limits), entries => ({ data: got.value.data, entries }));
313 };
314 const visit = async (dir: string, oid: Oid): Promise<Result<null, PlyError>> => {
315 const parsed = await read(oid);
316 if (!parsed.ok) return parsed;
317 const { data, entries } = parsed.value;
318 old.set(dir, { oid, data });
319 const before = new Map<string, TreeEntry>(entries.map((e: TreeEntry) => [e.name, e]));
320 for (const e of before.values()) have.add(e.oid);
321 const next: Array<Promise<Result<null, PlyError>>> = [];
322 // dir is a key of built.trees: the root, or a tree entry of a directory visited before it
323 // oxlint-disable-next-line typescript/no-unsafe-type-assertion, typescript/non-nullable-type-assertion-style -- see above (and no `!`: docs/STACK.md)
324 for (const e of (built.trees.get(dir) as BuiltDir).entries) {
325 const was = mapGet(before, e.name);
326 if (e.mode === MODE_TREE && was.tag === 'some' && was.value.mode === MODE_TREE && was.value.oid !== e.oid) next.push(visit(dir ? `${dir}/${e.name}` : e.name, was.value.oid));
327 }
328 for (const r of await Promise.all(next)) if (!r.ok) return r;
329 return ok(null);
330 };
331 if (oldTree !== built.root) {
332 const visited = await visit('', oldTree);
333 if (!visited.ok) return visited;
334 }
335 return ok(k);
336}
338// Pure: an absent base is a new ref only when base = ref; a base ≠ ref must exist.
339function baseFound(s: TreePlan, resolved: string | null): Result<null, ErrorOf<'not_found'>> {
340 if (resolved === null && s.create) return fail('not_found', `ref ${s.base} not found`, { miss: { kind: 'ref', ref: s.base, candidates: [s.base] } });
341 return ok(null);
342}
344type Attempt = { readonly head: Oid | null; readonly attempt: number; readonly linkTo: Span | null; readonly hintWas: HintOutcome | null };
345// editFile's options without allowLfsPointer (and retry, which pushTree does not read: a cas_conflict is redone once).
346export type PushTreeOptions = Omit<EditOptions, 'allowLfsPointer'>;
347type TreeConfig = Omit<EditConfig, 'allowLfsPointer' | 'retry'>;
348const treeDefaults = (): { -readonly [K in keyof TreeConfig]: TreeConfig[K] } => ({ head: null, strictHead: false, cache: null, verify: false, signer: null });
350// oxlint-disable-next-line require-await -- async, as before
351async function pushTreeOnce(url: string, s: TreePlan, options: PushTreeOptions & { readonly limits: CheckedLimits }, cfg: TreeConfig, { head, attempt, linkTo, hintWas }: Attempt): Promise<Result<PushTreeResult, PlyError>> {
352 const { verify, signer, strictHead } = cfg;
353 const cache = cfg.cache === null ? new Map<string, Uint8Array>() : cfg.cache;
354 const { limits } = options;
355 let hint = hintWas;
356 const attrs = { 'git.push_tree.ref': s.ref, 'git.push_tree.base': s.base, 'git.push_tree.create': s.create, 'git.push_tree.files': s.files, 'git.push_tree.trees': s.built.trees.size, 'git.push_tree.tree.new': s.built.root, 'git.push_tree.head.hint': head === null ? '' : head, 'git.push_tree.attempt': attempt };
357 // oxlint-disable-next-line complexity -- the push is one sequence of protocol steps
358 return operation('push_tree', url, { ...options, attrs, onFinish: () => ({ 'git.push_tree.head.outcome': hint === null ? '' : hint }), link: linkTo === null ? null : { span: linkTo, kind: 'retry_of' } }, async ({ t, root, outcome }) => {
359 // oxlint-disable-next-line promise-function-async -- fetchObject's promise, returned as is
360 const commitOf = (oid: Oid): Promise<Result<Fetched, PlyError>> => objectAt(t, oid, { expectType: TYPE.COMMIT, deepen: 1 });
361 // An attempt's Err leaves with its attempt number and how the hint turned out: retryLink reads them for the retry.
362 // oxlint-disable-next-line complexity -- the push is one sequence of protocol steps
363 const done = await (async (): Promise<Result<PushTreeResult, PlyError>> => {
364 // 1. the parent: ls-refs, overlapped with the hinted commit. An absent base is a new ref only when base = ref.
365 // 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)
366 const [resolvedR, speculative] = await Promise.all([lsRefs(t, [s.base]).then(r => map(r, ({ refs }) => getOrElse<Oid | null>(mapOption(mapGet(refs, s.base), x => x.oid), null))), head ? commitOf(head) : null]);
367 if (!resolvedR.ok) return resolvedR;
368 const resolved = resolvedR.value;
369 const found = baseFound(s, resolved);
370 if (!found.ok) return found;
371 const decided = decideHead({ hint: head, resolved });
372 hint = hintWas === null ? decided.hint : hintWas;
373 const parent = decided.oldCommit;
374 const strict = strictParent(strictHead, decided, s.base, head);
375 if (!strict.ok) return strict;
376 if (speculative !== null && !speculative.ok) root.set({ 'git.push_tree.head.speculative_error': speculative.error.code });
377 let oldTree: Oid | null = null;
378 if (parent !== null) {
379 const commitGot = decided.hint === 'used' && speculative !== null && speculative.ok ? speculative : await commitOf(parent);
380 if (!commitGot.ok) return commitGot;
381 const parsed = parseCommit(commitGot.value.data, limits);
382 if (!parsed.ok) return parsed;
383 oldTree = parsed.value.tree;
384 }
385 root.set({ 'git.push_tree.commit.old': parent === null ? '' : parent, 'git.push_tree.tree.old': oldTree === null ? '' : oldTree });
386 if (oldTree === s.built.root && !s.create) return outcome('noop', summarize({ s, parent, oldTree, hint, attempt }, null));
388 // 2. what the server has: the parent's trees along every directory whose oid changed (cache by oid, immutable).
389 // The operation's tracer, the one the root span is on: a caller's transport may carry a different one.
390 const diffed = await inSpan(root.tracer, 'git.push_tree.diff', { parent: root }, async span => {
391 const k = await parentTrees(t, cache, s.built, oldTree, limits);
392 if (!k.ok) return k;
393 span.set({ 'git.push_tree.diff.trees_read': k.value.read, 'git.push_tree.diff.cache_hits': k.value.hits, 'git.push_tree.diff.have': k.value.have.size });
394 return k;
395 });
396 if (!diffed.ok) return diffed;
397 const known = diffed.value;
398 const sel = selectObjects(s.built, known);
400 // 3. the commit, then one push whose old oid is the CAS
401 const who = ident(s.author);
402 if (!who.ok) return who;
403 // oxlint-disable-next-line typescript/strict-boolean-expressions, prefer-template -- bundle budget: the JS's own truthy test and concatenation, byte for byte
404 const encoded = encodeCommitOf({ tree: s.built.root, parents: parent ? [parent] : [], author: who.value, committer: who.value, message: s.message.endsWith('\n') ? s.message : s.message + '\n' });
405 if (!encoded.ok) return encoded;
406 let commitData = encoded.value;
407 if (signer !== null) {
408 const signed = await signCommit(commitData, signer);
409 if (!signed.ok) return signed;
410 commitData = signed.value; root.set({ 'git.push_tree.commit.signed': signer.kind, 'git.push_tree.commit.signer': getOrElse(fromNullish(signer.publicKeyLine), '') });
411 }
412 const newCommit = hashObject('commit', commitData);
413 const objects = [{ type: TYPE.COMMIT, data: commitData }, ...sel.trees, ...sel.blobs];
414 root.set({ 'git.push_tree.commit.new': newCommit, 'git.push_tree.send.trees': sel.trees.length, 'git.push_tree.send.tree_deltas': sel.deltas, 'git.push_tree.send.blobs': sel.blobs.length });
415 const sent = await push(t, { ref: s.ref, oldOid: s.create || parent === null ? ZERO_OID : parent, newOid: newCommit, objects });
416 if (!sent.ok) return sent;
417 const pushed = sent.value;
418 for (const tr of s.built.trees.values()) cache.set(tr.oid, tr.data);
419 if (verify) { const seen = await verifyRef(t, root, 'git.push_tree', s.ref, newCommit); if (!seen.ok) return seen; }
420 return outcome('ok', summarize({ s, parent, oldTree, hint, attempt }, { newCommit, sel, pushed, treesRead: known.read }), { 'git.push_tree.push.bytes': pushed.packBytes, 'git.push_tree.push.objects': pushed.entries.length });
421 })();
422 if (!done.ok) tagAttempt(done.error, attempt, hint);
423 return done;
424 });
425}
427// Same contract as editFile: `head` overlaps ls-refs with a speculative fetch of the hinted commit (ls-refs wins); a
428// cas_conflict on attempt 0 is redone once from a fresh ls-refs, the retry's span linked to the first; `strictHead`
429// makes the hint a precondition and is never retried; `verify` reads the ref back and an acknowledged push that does
430// not read back is `ambiguous`. A retry rebuilds on the new head: the tree is still exactly `files` (that is the
431// contract — another writer's files are not merged in), its parent is whatever won the race.
432// The files are hashed once: the retry reuses the validated spec (same commit time, same trees).
433// An Err carries the attempt's tag (attempt, hint, the root span).
434export async function pushTree(url: string, spec: TreeSpec, options: PushTreeOptions = {}): Promise<Result<PushTreeResult, PlyError>> {
435 const cfg = withDefaults(options, treeDefaults());
436 const needs = needsHead(cfg.strictHead, cfg.head);
437 if (!needs.ok) return needs;
438 // the limits are parsed once, for the spec and both attempts
439 const limits = limitsOf(options);
440 if (!limits.ok) return limits;
441 const planned = validateTreeSpec(spec, limits.value, cfg.head);
442 if (!planned.ok) return planned;
443 const s = planned.value;
444 const checked = { ...options, limits: limits.value };
445 const first = await pushTreeOnce(url, s, checked, cfg, { head: s.head, attempt: 0, linkTo: null, hintWas: null });
446 // only attempt 0's cas_conflict is redone, once: the retry's Err is the answer
447 // Only ply's own error is a lost race: a look-alike object a transport raises is returned as it is, not retried.
448 if (first.ok || !isPlyError(first.error) || first.error.code !== 'cas_conflict' || cfg.strictHead) return first;
449 return pushTreeOnce(url, s, checked, cfg, { head: null, attempt: 1, ...retryLink(first.error) });
450}
Diagnostics4 git calls · 23 ms
CallStatusSizeTime023 ms
discover200152 B2 ms
git.upload-pack discover http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=2 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 · hit2 ms
git.upload-pack ls-refs http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=2 git.response.bytes=145 git.response.cache=HIT git.response.duration_ms=2 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 · hit3 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=17 git.response.bytes=38434 git.response.cache=HIT git.response.duration_ms=3 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=55Open pack map
fetch20010.0 KiB · hit18 ms
git.upload-pack fetch http.response.status_code=200 git.response.bytes=10229 git.response.cache=HIT git.response.duration_ms=18 git.fetch.wants=9d9097edd6775b8565bc3f3178e331b6364cdac5 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=10229 git.pkt.payload.max=10208 git.sideband.band1.bytes=10207 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
- a5e1f9d57e7024ce
- Request
- 6598bf58…
- Protocol
- v2 · sha1
- Agent
- gitty/1.0
- Filter
- advertised
- Fetch
- shallow filter sideband-all
- Capabilities
- agent ls-refs fetch object-format