Artifactspublic-v0

ply

main
ply4 git calls365 ms49 KiB2 cachedprotocol v2
688 lines38 KiBRaw
1// One commit from an ordered list of path changes, including the first commit of an empty repository.
2// editFile stays the O(1) stream for a single find/replace of an existing blob. Everything else — create, write,
3// delete, rename, more than one change, a root commit — edits an in-memory tree of the paths it touches and pushes
4// the commit plus the trees and blobs that edit created.
5//
6// Choices, where git's commands disagree: `create` of a path that exists is bad_request (git add overwrites; `write`
7// is that). A result tree equal to the parent does not create an empty commit, and does not create a new ref
8// (that is createRef). A 40-hex base that is not the tip of an existing target is bad_request, not a silent rebase.
9// Every decision returns a Result, and so does commitChanges, as editFile and pushTree do; inside the operation an Err
10// is the operation's, which operation() records on its span.
11/* oxlint-disable import/max-dependencies -- an entry composes the protocol from one import per module */
12import { fail, isPlyError } from './errors.js';
13import type { ErrorOf, PlyError } from './errors.js';
14import { operation, verifyRef } from './operation.js';
15import { lsRefs, parseUnbornLine } from './lsrefs.js';
16import type { LsRefsResult } from './lsrefs.js';
17import { discover } from './discover.js';
18import { objectAt, treeEntries } from './fetch.js';
19import { commitById } from './commit.js';
20import { push, ZERO_OID } from './push.js';
21import type { PackObject } from './push.js';
22import { parseOid, parseCommitId, type Oid } from './oid.js';
23import { hashObject, TYPE } from './objects.js';
24import type { Mode } from './objects.js';
25import { bytesOf } from './bytes.js';
26import { LIMIT_OBJECT_OVERHEAD, limitExceeded, limitsOf } from './limits.js';
27import type { CheckedLimits } from './limits.js';
28import { validateIdent, validateRef, validatePushRef, validatePath, validateMessage } from './validate.js';
29import type { IdentInput, ValidatedIdent } from './validate.js';
30import { editFile, inSpan, isLfsPointerPrefix, refuseRebase } from './edit.js';
31import { expecting } from './editexpect.js';
32import type { Author } from './edit.js';
33import { signCommit } from './sign.js';
34import type { Signer } from './sign.js';
35import {
36 emptyDir, lazyNode, fileLeaf, putAt, removeAt, renameAt, replaceOnce, encodeMem, insertChild, blobOids, requireDir,
37} from './memtree.js';
38import type { BlobMode, Dir, Mem } from './memtree.js';
39import { MODE_TREE } from './format.js';
40import { assertNever, err, getOrElse, map, mapOption, none, ok, some } from './result.js';
41import type { Err, Ok, Option, Result } from './result.js';
42import type { EntryOptions } from './boundary.js';
43import type { Transport } from './transport.js';
44import type { Span } from './otel.js';
45import { buildCommitData } from './commit-build.js';
46import type { Path } from './path.js';
47import { parsePath } from './path.js';
48import { parseRefname } from './refname.js';
49import type { Refname } from './refname.js';
50import type { Input } from './absent.js';
51import { at, field, fromNullable, fromNullish, mapGet, withDefaults } from './absent.js';
53const HEX40 = /^[0-9a-fA-F]{40}$/u;
54// git's empty tree (hash of no entries)
55const EMPTY_TREE = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
57export type { BlobMode };
58// `mode` given always wins. `mode` left out: a `write` over an existing regular file keeps that file's mode (100644
59// or 100755), as rewriting a file's content does in git; a `create`, and a `write` where there is no regular file
60// (a new path, or a symlink being replaced), is 100644. Paths are plain strings, checked (validatePath) before any I/O.
61type Content = { readonly path: string; readonly content: string | Uint8Array } & Input<{ readonly mode: BlobMode }>;
62export type Change =
63 | ({ readonly kind: 'create' } & Content)
64 | ({ readonly kind: 'write' } & Content)
65 | { readonly kind: 'edit'; readonly path: string; readonly find: string | Uint8Array; readonly replace: string | Uint8Array }
66 | { readonly kind: 'delete'; readonly path: string }
67 | { readonly kind: 'rename'; readonly from: string; readonly to: string };
69// `ref` null: the remote's HEAD. `base` null: the target's tip. `committer` null: the author. `time` null: now.
70export type CommitChangesConfig = { readonly ref: string | null; readonly base: string | null; readonly committer: Author | null; readonly time: number | null };
71export type CommitChangesSpec = Input<CommitChangesConfig> & {
72 readonly changes: readonly Change[];
73 readonly author: Author;
74 readonly message: string;
75};
76const specDefaults = (): { -readonly [K in keyof CommitChangesConfig]: CommitChangesConfig[K] } => ({ ref: null, base: null, committer: null, time: null });
77// `head` null: no expected tip. `signer` null: the commit is not signed.
78export type CommitChangesConfigOptions = { readonly head: string | null; readonly verify: boolean; readonly signer: Signer | null; readonly allowLfsPointer: boolean };
79export type CommitChangesOptions = EntryOptions & Input<CommitChangesConfigOptions>;
80const optionDefaults = (): { -readonly [K in keyof CommitChangesConfigOptions]: CommitChangesConfigOptions[K] } => ({ head: null, verify: false, signer: null, allowLfsPointer: false });
81export type CommitChangesResult = {
82 readonly outcome: 'commit' | 'noop';
83 readonly ref: string;
84 readonly oid: string;
85 readonly tree: string;
86 readonly parent: string | null;
87 readonly oldOid: string | null;
88 readonly pushBytes: number;
89 readonly created: boolean;
90};
92// `mode` null: not given; decided where the change is applied (modeFor), against the tree the earlier changes left.
93type Stored = { readonly path: string; readonly comps: readonly string[]; readonly mode: BlobMode | null; readonly data: Uint8Array };
94type Norm =
95 | (Stored & { readonly kind: 'create' })
96 | (Stored & { readonly kind: 'write' })
97 | { readonly kind: 'edit'; readonly path: string; readonly comps: readonly string[]; readonly find: Uint8Array; readonly replace: Uint8Array }
98 | { readonly kind: 'delete'; readonly path: string; readonly comps: readonly string[] }
99 | { readonly kind: 'rename'; readonly from: string; readonly to: string; readonly fromComps: readonly string[]; readonly toComps: readonly string[] };
100type BasePlan = { readonly kind: 'tip' } | { readonly kind: 'ref'; readonly ref: string } | { readonly kind: 'oid'; readonly oid: Oid };
101type Plan = {
102 readonly ref: string | null;
103 readonly base: BasePlan;
104 readonly baseText: string;
105 readonly changes: readonly Norm[];
106 readonly author: ValidatedIdent;
107 readonly committer: ValidatedIdent;
108 readonly message: string;
109 readonly head: string | null;
110};
111type Tip = { readonly ref: string; readonly oid: Oid | null };
112type Parent = {
113 readonly oid: Oid | null;
114 readonly tree: Oid | null;
115 readonly commitParent: string | null;
116 readonly creating: boolean;
117 readonly baseRef: string | null;
118 readonly baseOid: string | null;
119};
120type Applied = { readonly tree: Oid; readonly objects: readonly PackObject[] };
121type BadRequest = ErrorOf<'bad_request'>;
123function modeOf(mode: Option<unknown>, path: string): Result<BlobMode | null, BadRequest> {
124 if (mode.tag === 'none') return ok(null);
125 const given = mode.value;
126 if (given === '100644' || given === '100755' || given === '120000') return ok(given);
127 return fail('bad_request', `${path}: mode ${JSON.stringify(given)} is not 100644, 100755 or 120000`, { what: 'mode', path });
129function bytes(raw: unknown, path: string, what: string): Result<Uint8Array, BadRequest> {
130 if (typeof raw !== 'string' && !(raw instanceof Uint8Array)) return fail('bad_request', `${path}: ${what} must be a string or Uint8Array`, { what, path });
131 return ok(bytesOf(raw));
133function fields(raw: object): Record<string, unknown> {
134 // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- a change is an untyped object; each field is checked below
135 return raw as Record<string, unknown>;
137const pathOf = (raw: unknown, limits: CheckedLimits): Result<string[], PlyError> => map(validatePath(raw, limits), p => p.components);
138function normalize(raw: unknown, limits: CheckedLimits): Result<Norm, PlyError> {
139 if (raw === null || typeof raw !== 'object') return fail('bad_request', 'change must be an object with a kind', { what: 'change' });
140 const rec = fields(raw);
141 const kind = rec['kind'];
142 if (kind === 'create' || kind === 'write') {
143 const comps = pathOf(rec['path'], limits);
144 if (!comps.ok) return comps;
145 const joined = comps.value.join('/');
146 // a mode left out is decided when the change is applied; any other value (null included) is the caller's, and checked
147 const mode = modeOf(fromNullable(rec['mode']), joined);
148 if (!mode.ok) return mode;
149 const data = bytes(rec['content'], joined, 'content');
150 if (!data.ok) return data;
151 const stored = { path: joined, comps: comps.value, mode: mode.value, data: data.value };
152 if (kind === 'create') return ok({ kind, ...stored });
153 return ok({ kind, ...stored });
154 }
155 if (kind === 'edit') {
156 const comps = pathOf(rec['path'], limits);
157 if (!comps.ok) return comps;
158 const joined = comps.value.join('/');
159 const find = bytes(rec['find'], joined, 'find');
160 if (!find.ok) return find;
161 if (find.value.length === 0) return fail('bad_request', 'find must be non-empty', { what: 'find', path: joined });
162 const replace = bytes(rec['replace'], joined, 'replace');
163 if (!replace.ok) return replace;
164 return ok({ kind, path: joined, comps: comps.value, find: find.value, replace: replace.value });
165 }
166 if (kind === 'delete') {
167 const comps = pathOf(rec['path'], limits);
168 if (!comps.ok) return comps;
169 return ok({ kind, path: comps.value.join('/'), comps: comps.value });
170 }
171 if (kind === 'rename') {
172 const from = pathOf(rec['from'], limits);
173 if (!from.ok) return from;
174 const to = pathOf(rec['to'], limits);
175 if (!to.ok) return to;
176 return ok({ kind, from: from.value.join('/'), to: to.value.join('/'), fromComps: from.value, toComps: to.value });
177 }
178 return fail('bad_request', `unknown change kind ${JSON.stringify(kind)}`, { what: 'change', got: kind });
180// The bytes a change adds before its blob is built: the content written, the replacement spliced in, none for a delete
181// or rename (the blob is the server's already).
182function newBytes(n: Norm): number {
183 switch (n.kind) {
184 case 'create': case 'write': return n.data.length;
185 case 'edit': return n.replace.length;
186 case 'delete': case 'rename': return 0;
187 }
188 // Stryker disable next-line ConditionalExpression: unreachable, the compiler's exhaustiveness check
189 return assertNever(n);
191function validateBase(base: string | null): Result<BasePlan, PlyError> {
192 if (base === null) return ok({ kind: 'tip' });
193 if (HEX40.test(base)) {
194 const id = parseCommitId(base);
195 return id.ok ? ok({ kind: 'oid', oid: id.value }) : id;
196 }
197 const ref = validateRef(base);
198 return ref.ok ? ok({ kind: 'ref', ref: ref.value }) : ref;
200function validateHead(head: string | null): Result<string | null, PlyError> {
201 if (head === null) return ok(null);
202 return parseOid(head);
204function baseLabel(base: BasePlan): string {
205 if (base.kind === 'tip') return '';
206 if (base.kind === 'ref') return base.ref;
207 return base.oid;
209// One person as validateIdent takes it: the name and email as given (a missing person has none, and is refused there),
210// the time, and the zone only when one is given (UTC otherwise).
211function identInput(who: Option<Author>, time: number): IdentInput {
212 if (who.tag === 'none') return { time };
213 const { name, email } = who.value;
214 const tz = fromNullish(who.value.tz);
215 return tz.tag === 'some' ? { name, email, time, tz: tz.value } : { name, email, time };
217function validatePlan(spec: CommitChangesSpec, limits: CheckedLimits, head: string | null): Result<Plan, PlyError> {
218 const given = withDefaults(spec, specDefaults());
219 const refIn = given.ref;
220 const ref = refIn === null ? ok(null) : validatePushRef(refIn, false);
221 if (!ref.ok) return ref;
222 const base = validateBase(given.base);
223 if (!base.ok) return base;
224 const list: unknown = spec.changes;
225 if (!Array.isArray(list) || list.length === 0) return fail('bad_request', 'changes must be a non-empty list', { what: 'changes' });
226 const max = limits.maxPackObjects;
227 if (list.length > max) return err(limitExceeded('changes', list.length, max));
228 const maxPush = limits.maxPushBytes;
229 // As pushTree's files (tree.ts fileEntries): each change's new bytes plus LIMIT_OBJECT_OVERHEAD, so a list of many
230 // tiny changes is refused before its blobs and tree entries exist (#142). Exactly the cap is allowed.
231 let pushBytes = 0;
232 const changes: Norm[] = [];
233 for (const c of list) {
234 const norm = normalize(c, limits);
235 if (!norm.ok) return norm;
236 pushBytes += newBytes(norm.value) + LIMIT_OBJECT_OVERHEAD;
237 if (pushBytes > maxPush) return err(limitExceeded('push bytes', pushBytes, maxPush));
238 changes.push(norm.value);
239 }
240 const author = fromNullish<Author>(spec.author);
241 const authorTime = mapOption(author, a => fromNullish(a.time));
242 let time = getOrElse(fromNullish(given.time), Math.floor(Date.now() / 1000));
243 if (authorTime.tag === 'some' && authorTime.value.tag === 'some') time = authorTime.value.value;
244 const authorIdent = validateIdent(identInput(author, time));
245 if (!authorIdent.ok) return authorIdent;
246 const committer = fromNullish(given.committer);
247 const written = committer.tag === 'none'
248 ? authorIdent
249 : validateIdent(identInput(committer, getOrElse(fromNullish(committer.value.time), time)));
250 if (!written.ok) return written;
251 const message = validateMessage(spec.message);
252 if (!message.ok) return message;
253 const pinned = validateHead(head);
254 if (!pinned.ok) return pinned;
255 return ok({ ref: ref.value, base: base.value, baseText: baseLabel(base.value), changes, author: authorIdent.value, committer: written.value, message: spec.message, head: pinned.value });
258// The target is not where the caller (or our own read) said: a compare-and-swap lost. `cause`: what reported it.
259function lost(ref: string, expected: string, actual: string | null, ...cause: [] | [unknown]): Err<ErrorOf<'cas_conflict'>> {
260 const where = actual === null ? 'absent' : actual;
261 const want = expected === ZERO_OID ? 'absent' : expected;
262 return fail('cas_conflict', `${ref} is ${where}, not ${want}`, { expected, actual, ...(cause.length === 0 ? {} : { cause: cause[0] }) });
264function nothing(): Err<BadRequest> {
265 return fail('bad_request', 'nothing to commit');
267function person(p: ValidatedIdent): Author {
268 return { name: p.name, email: p.email, time: p.time, tz: p.tz };
270// A cas_conflict that says where the ref is (a string: a fresh read is not needed).
271const actualKnown = (e: unknown): boolean => { const actual = field(e, 'actual'); return actual.tag === 'some' && typeof actual.value === 'string'; };
272const whatIs = (e: unknown, what: string): boolean => { const w = field(e, 'what'); return w.tag === 'some' && w.value === what; };
273const tipOf = (refs: ReadonlyMap<string, { readonly oid: Oid }>, ref: string): Oid | null => getOrElse<Oid | null>(mapOption(mapGet(refs, ref), r => r.oid), null);
275async function resolveTarget(t: Transport, ref: string | null): Promise<Result<Tip, PlyError>> {
276 if (ref === null) {
277 const discovered = await discover(t); if (!discovered.ok) return discovered;
278 const listing = await lsRefs(t, ['HEAD'], discovered.value.lsRefsUnborn ? { unborn: parseUnbornLine } : {}); if (!listing.ok) return listing;
279 const listed = listing.value;
280 const headLine = mapGet(listed.refs, 'HEAD');
281 const unborn = listed.unborn;
282 if (unborn !== null) {
283 const target = validatePushRef(unborn.target, false);
285 return target.ok ? ok({ ref: target.value, oid: null }) : target;
286 }
287 if (listed.head !== null && headLine.tag === 'some') return ok({ ref: listed.head, oid: headLine.value.oid });
288 if (headLine.tag === 'some') return fail('bad_request', 'remote HEAD is detached; pass ref explicitly');
289 return fail('not_found', 'remote HEAD is absent; pass ref explicitly', { miss: { kind: 'head_absent' } });
290 }
291 return map(await lsRefs(t, [ref]), ({ refs }) => ({ ref, oid: tipOf(refs, ref) }));
294async function mustCommit(t: Transport, oid: Oid): Promise<Result<{ readonly tree: Oid; readonly parent: string | null }, PlyError>> {
295 const got = await commitById(t, oid);
296 if (!got.ok) return got;
297 return ok({ tree: got.value.commit.tree, parent: getOrElse<string | null>(at(got.value.commit.parents, 0), null) });
300async function resolveParent(t: Transport, target: Tip, base: BasePlan): Promise<Result<Parent, PlyError>> {
301 if (base.kind === 'ref' && base.ref !== target.ref) {
302 if (target.oid !== null) return lost(target.ref, ZERO_OID, target.oid);
303 const listed = await lsRefs(t, [base.ref]); if (!listed.ok) return listed;
304 const rec = mapGet(listed.value.refs, base.ref);
305 if (rec.tag === 'none') return fail('not_found', `ref ${base.ref} not found`, { what: 'ref', path: base.ref, miss: { kind: 'ref', ref: base.ref, candidates: [base.ref] } });
306 const oid = getOrElse(fromNullish(rec.value.peeled), rec.value.oid);
307 const commit = await mustCommit(t, oid);
308 if (!commit.ok) return commit;
309 return ok({ oid, tree: commit.value.tree, commitParent: commit.value.parent, creating: true, baseRef: base.ref, baseOid: null });
310 }
311 if (base.kind === 'oid') {
312 if (target.oid !== null && target.oid !== base.oid) return refuseRebase(target.ref, base.oid, target.oid);
313 const commit = await mustCommit(t, base.oid);
314 if (!commit.ok) return commit;
315 return ok({ oid: base.oid, tree: commit.value.tree, commitParent: commit.value.parent, creating: target.oid === null, baseRef: null, baseOid: base.oid });
316 }
317 if (target.oid === null) return ok({ oid: null, tree: null, commitParent: null, creating: true, baseRef: null, baseOid: null });
318 const commit = await mustCommit(t, target.oid);
319 if (!commit.ok) return commit;
320 return ok({ oid: target.oid, tree: commit.value.tree, commitParent: commit.value.parent, creating: false, baseRef: target.ref, baseOid: null });
323// What a stored tree says, by oid: read-only, so one fetch and one parse serve every path that has this tree.
324type StoredEntry = { readonly name: string; readonly mode: Mode; readonly oid: Oid };
325type Walk = {
326 readonly t: Transport;
327 readonly limits: CheckedLimits;
328 readonly have: Set<string>;
329 readonly cache: Map<string, readonly StoredEntry[]>;
330 readonly allowLfs: boolean;
331};
333// The directory at one path, as a tree the server has. Every call builds its own Dir: an oid names content, not a
334// place, and two paths with one tree oid (template or locale copies) are two directories that change separately.
335// Only the parsed entries are cached by oid, and nothing writes to them (a Lazy is read-only, and each directory
336// gets its own).
337async function loadTree(walk: Walk, oid: Oid): Promise<Result<Dir, PlyError>> {
338 let stored = mapGet(walk.cache, oid);
339 if (stored.tag === 'none') {
340 const got = await objectAt(walk.t, oid, { filter: 'tree:0', expectType: TYPE.TREE });
341 if (!got.ok) return got;
342 const parsed = treeEntries(got.value, walk.limits);
343 if (!parsed.ok) return parsed;
344 // copied: the fetched object's own entry list is not this cache's to hold a reference into
345 const entries: readonly StoredEntry[] = parsed.value.map(e => ({ name: e.name, mode: e.mode, oid: e.oid }));
346 for (const entry of entries) walk.have.add(entry.oid);
347 walk.have.add(oid);
348 walk.cache.set(oid, entries);
349 stored = some(entries);
350 }
351 const dir = emptyDir();
352 for (const entry of stored.value) dir.entries.set(entry.name, lazyNode(entry.mode, entry.oid));
353 return ok(dir);
356// A missing directory is fetched before the next component is named, so the walk is ordered.
357async function descend(walk: Walk, root: Dir, names: readonly string[], create: boolean): Promise<Result<null, PlyError>> {
358 let here = root;
359 let walked = '';
360 for (const name of names) {
361 const full = walked === '' ? name : `${walked}/${name}`;
362 const child = mapGet(here.entries, name);
363 if (child.tag === 'none') {
364 if (!create) return fail('not_found', `${full} not found`, { what: 'path', path: full, miss: { kind: 'path', missing: name, existingPath: walked } });
365 const next = emptyDir();
366 const inserted = insertChild(here.entries, name, next, walk.limits);
367 if (!inserted.ok) return inserted;
368 here = next;
369 } else if (child.value.kind === 'dir') here = child.value;
370 else if (child.value.mode === MODE_TREE) {
371 // oxlint-disable-next-line no-await-in-loop -- the next component is inside this directory
372 const loaded = await loadTree(walk, child.value.oid);
373 if (!loaded.ok) return loaded;
374 here.entries.set(name, loaded.value);
375 here = loaded.value;
376 } else return fail('bad_request', `${full} is not a directory`, { what: 'path', path: full });
377 walked = full;
378 }
379 return ok(null);
382function leafAt(root: Dir, comps: readonly string[]): Result<Mem, PlyError> {
383 let here: Mem = root;
384 let walked = '';
385 for (const name of comps) {
386 const entries = requireDir(here, walked === '' ? '.' : walked);
387 if (!entries.ok) return entries;
388 const parent = walked;
389 walked = walked === '' ? name : `${walked}/${name}`;
390 const child = mapGet(entries.value, name);
391 if (child.tag === 'none') return fail('not_found', `${walked} not found`, { what: 'path', path: walked, miss: { kind: 'path', missing: name, existingPath: parent } });
392 here = child.value;
393 }
394 return ok(here);
397// Put one new blob at its path (`write`: over a file that is there) and remember its bytes for the pack.
398type NewLeaf = { readonly comps: readonly string[]; readonly mode: BlobMode; readonly data: Uint8Array; readonly path: string; readonly overwrite: boolean };
399function putLeaf(walk: Walk, root: Dir, leafIn: NewLeaf, created: Map<string, Uint8Array>): Result<null, PlyError> {
400 const leaf = fileLeaf(leafIn.mode, leafIn.data, walk.limits, leafIn.path);
401 if (!leaf.ok) return leaf;
402 const put = putAt(root, leafIn.comps, lazyNode(leaf.value.mode, leaf.value.oid), leafIn.overwrite, walk.limits);
403 if (!put.ok) return put;
404 created.set(leaf.value.oid, leaf.value.data);
405 return ok(null);
408// One find/replace of a file that exists: the blob fetched whole (the in-memory path), replaced, put back.
409async function applyEdit(walk: Walk, root: Dir, change: Extract<Norm, { readonly kind: 'edit' }>, created: Map<string, Uint8Array>): Promise<Result<null, PlyError>> {
410 const walked = await descend(walk, root, change.comps.slice(0, -1), false);
411 if (!walked.ok) return walked;
412 const found = leafAt(root, change.comps);
413 if (!found.ok) return found;
414 const node = found.value;
415 const mode = node.kind === 'lazy' && (node.mode === '100644' || node.mode === '100755') ? node.mode : null;
416 if (node.kind !== 'lazy' || mode === null) {
417 const shown = node.kind === 'dir' ? MODE_TREE : node.mode;
418 const miss = node.kind === 'lazy' && node.mode === '160000'
419 ? { kind: 'submodule' as const, path: change.path, commit: node.oid }
420 : { kind: 'not_directory' as const, path: change.path, mode: shown };
421 return fail('not_found', `${change.path} is not a regular file (mode ${shown})`, { what: 'path', path: change.path, miss });
422 }
423 walk.have.add(node.oid);
424 const fetched = await objectAt(walk.t, node.oid, { filter: '', expectType: TYPE.BLOB }); if (!fetched.ok) return fetched;
425 const blob = fetched.value;
426 if (isLfsPointerPrefix(blob.data) && !walk.allowLfs) return fail('lfs_pointer', `${node.oid} is a Git LFS pointer (${blob.data.length} bytes); the file's content is in the LFS store, not in git. Pass allowLfsPointer to edit the pointer itself.`);
427 const next = replaceOnce(blob.data, change.find, change.replace);
428 if (!next.ok) return next;
429 return putLeaf(walk, root, { comps: change.comps, mode, data: next.value, path: change.path, overwrite: true }, created);
432// The mode a create or write stores. Given: that one. Not given: a write over a regular file keeps the file's mode
433// (git: new content does not change a mode); anything else is a plain file. Read after descend, so the parent
434// directory is expanded and the entry is what the earlier changes of this list left there.
435function modeFor(root: Dir, change: Extract<Norm, { readonly kind: 'create' | 'write' }>): BlobMode {
436 if (change.mode !== null) return change.mode;
437 if (change.kind === 'create') return '100644';
438 const there = leafAt(root, change.comps);
439 if (there.ok && there.value.kind === 'lazy' && there.value.mode === '100755') return '100755';
440 return '100644';
443// Each change walks the tree the previous change left, so the steps cannot run together.
444/* oxlint-disable no-await-in-loop */
445async function applyChange(walk: Walk, root: Dir, change: Norm, created: Map<string, Uint8Array>): Promise<Result<null, PlyError>> {
446 switch (change.kind) {
447 case 'create':
448 case 'write': {
449 const walked = await descend(walk, root, change.comps.slice(0, -1), true);
450 if (!walked.ok) return walked;
451 return putLeaf(walk, root, { comps: change.comps, mode: modeFor(root, change), data: change.data, path: change.path, overwrite: change.kind === 'write' }, created);
452 }
453 case 'edit': return applyEdit(walk, root, change, created);
454 case 'delete': {
455 const walked = await descend(walk, root, change.comps.slice(0, -1), false);
456 if (!walked.ok) return walked;
457 return removeAt(root, change.comps);
458 }
459 case 'rename': {
460 const into = change.to.startsWith(`${change.from}/`);
461 if (change.from !== change.to && !into) {
462 const from = await descend(walk, root, change.fromComps.slice(0, -1), false);
463 if (!from.ok) return from;
464 const to = await descend(walk, root, change.toComps.slice(0, -1), false);
465 if (!to.ok) return to;
466 }
467 return renameAt(root, change.fromComps, change.toComps);
468 }
469 }
470 return assertNever(change);
473async function apply(walk: Walk, root: Dir, changes: readonly Norm[]): Promise<Result<Applied, PlyError>> {
474 const created = new Map<string, Uint8Array>();
475 // change N reads the tree change N-1 wrote
476 for (const change of changes) {
477 const applied = await applyChange(walk, root, change, created);
478 if (!applied.ok) return applied;
479 }
480 const encoded = encodeMem(root, walk.limits);
481 if (!encoded.ok) return encoded;
482 const referenced = new Set<string>();
483 blobOids(root, referenced);
484 const objects: PackObject[] = [];
485 for (const tree of encoded.value.trees) if (!walk.have.has(tree.oid)) objects.push({ type: TYPE.TREE, data: tree.data });
486 for (const [oid, data] of created) if (referenced.has(oid) && !walk.have.has(oid)) objects.push({ type: TYPE.BLOB, data });
487 return ok({ tree: encoded.value.oid, objects });
489/* oxlint-enable no-await-in-loop */
491type Built = { readonly tree: string; readonly oid: string; readonly pushBytes: number; readonly outcome: 'commit' | 'noop' };
492function resultOf(ref: string, parent: Parent, built: Built): CommitChangesResult {
493 if (built.outcome === 'noop') {
494 return { outcome: built.outcome, ref, oid: parent.oid === null ? built.oid : parent.oid, tree: parent.tree === null ? built.tree : parent.tree, parent: parent.commitParent, oldOid: parent.oid, pushBytes: 0, created: false };
495 }
496 return { outcome: built.outcome, ref, oid: built.oid, tree: built.tree, parent: parent.oid, oldOid: parent.creating ? null : parent.oid, pushBytes: built.pushBytes, created: parent.creating };
499type StreamOpts = {
500 readonly rest: EntryOptions;
501 readonly limits: CheckedLimits;
502 readonly verify: boolean;
503 readonly signer: Signer | null;
504 readonly allowLfs: boolean;
505 readonly pinned: boolean;
506};
508// Only ply's own cas_conflict is a lost race: a look-alike object a transport raises is returned as it is.
509const lostRace = (e: PlyError): boolean => isPlyError(e) && e.code === 'cas_conflict';
510// A lost race, reported against a fresh read of the ref (`listed`; that read's own Err when it failed). Synchronous,
511// so the cas_conflict is built in its caller's frame.
512const lostAt = (listed: Result<LsRefsResult, PlyError>, ref: string, expected: string, cause: unknown): Err<PlyError> =>
513 (listed.ok ? lost(ref, expected, tipOf(listed.value.refs, ref), cause) : listed);
515// What one attempt answers on either path: the commit, or `retry` (an unpinned commit on a ref that existed lost its
516// push to another writer: the call reads the target again and redoes it once).
517type MemOutcome = { readonly retry: false; readonly done: CommitChangesResult; readonly objects: number } | { readonly retry: true };
518type StreamJob = {
519 readonly plan: Plan;
520 readonly target: Tip;
521 readonly parent: Parent & { readonly oid: string };
522 readonly edit: Extract<Norm, { readonly kind: 'edit' }>;
523 readonly opts: StreamOpts;
524 readonly attempt: number;
525};
526function parseEditInputs(targetRef: string, editPath: string, limits: CheckedLimits): Result<{ readonly ref: Refname; readonly path: Path }, BadRequest> {
527 const branded = parseRefname(targetRef);
528 if (!branded.ok) return branded;
529 // editPath is normalize()'s join of the components validatePath took under these limits: parsePath only brands it
530 return map(parsePath(editPath, limits), p => ({ ref: branded.value, path: p.path }));
532// The single edit of an existing file, streamed by editFile. Its Err is read here: a lost race (or a rebase refusal on a
533// new ref) is this commit's cas_conflict; any other Err is the commit's as it is. editFile never redoes a lost push
534// itself (`retry: false`): the redo is this commit's, from its own fresh read of the target, as on the in-memory path
535// (writeMem), so both paths answer one race the same way and every push asserts what the commit read.
536async function streamEdit(url: string, t: Transport, root: Span, job: StreamJob): Promise<Result<MemOutcome, PlyError>> {
537 const { plan, target, parent, edit, opts, attempt } = job;
538 const creating = parent.creating;
539 const strict = opts.pinned && !creating && parent.baseOid === null;
540 root.set({ 'git.commit.stream': true });
541 const inputs = parseEditInputs(target.ref, edit.path, opts.limits);
542 if (!inputs.ok) return inputs;
543 const { ref, path } = inputs.value;
544 // The base goes to editFile as the caller named it (its span says so; it peels a tag as resolveParent did). The
545 // compare-and-swap does not: `creating` is what this commit read for its target, and editFile's push asserts it
546 // (zero old oid for an absent target) whatever its own later read of the ref sees.
547 const result = await editFile(url, {
548 ref, base: getOrElse(fromNullish(parent.baseOid), getOrElse(fromNullish(parent.baseRef), target.ref)), path, find: edit.find, replace: edit.replace,
549 author: person(plan.author), committer: person(plan.committer), message: plan.message, time: plan.author.time,
550 }, expecting({
551 ...opts.rest, transport: t, parent: root, head: parent.oid, strictHead: strict, retry: false,
552 verify: opts.verify, allowLfsPointer: opts.allowLfs, ...(opts.signer === null ? {} : { signer: opts.signer }),
553 }, creating));
554 if (!result.ok) {
555 const e = result.error;
556 const rebase = creating && e.code === 'bad_request' && whatIs(e, 'rebase');
557 if (e.code !== 'cas_conflict' && !rebase) return result;
558 if (lostRace(e) && attempt === 0 && !opts.pinned && !creating) return ok({ retry: true });
559 if (e.code === 'cas_conflict' && !creating && actualKnown(e)) return result;
560 return lostAt(await lsRefs(t, [target.ref]), target.ref, creating ? ZERO_OID : parent.oid, e);
561 }
562 const edited = result.value;
563 if (edited.noop) {
564 if (creating) return nothing();
565 return ok({ retry: false, objects: 0, done: resultOf(target.ref, parent, { tree: edited.oldTree, oid: edited.oldCommit, pushBytes: 0, outcome: 'noop' }) });
566 }
567 // editFile corrects a stale head hint before it pushes. That commit's parent is the tip it won on.
568 return ok({ retry: false, objects: 0, done: resultOf(target.ref, { ...parent, oid: edited.oldCommit }, { tree: edited.newTree, oid: edited.newCommit, pushBytes: edited.pushBytes, outcome: 'commit' }) });
571function treeDecision(parent: Parent, tree: string): 'noop' | 'empty' | 'commit' {
572 if (parent.tree !== null && tree === parent.tree) return parent.creating ? 'empty' : 'noop';
573 if (parent.oid === null && tree === EMPTY_TREE) return 'empty';
574 return 'commit';
577type MemJob = {
578 readonly t: Transport;
579 readonly root: Span;
580 readonly plan: Plan;
581 readonly target: Tip;
582 readonly parent: Parent;
583 readonly limits: CheckedLimits;
584 readonly verify: boolean;
585 readonly signer: Signer | null;
586 readonly allowLfs: boolean;
587 readonly pinned: boolean;
588 readonly attempt: number;
589};
590function oldOidOf(parent: Parent): string {
591 if (parent.creating || parent.oid === null) return ZERO_OID;
592 return parent.oid;
594async function writeMem(job: MemJob): Promise<Result<MemOutcome, PlyError>> {
595 const { t, root, plan, target, parent, limits, verify, signer, allowLfs, pinned, attempt } = job;
596 root.set({ 'git.commit.stream': false });
597 const walk: Walk = { t, limits, have: new Set(), cache: new Map(), allowLfs };
598 const loaded = parent.tree === null ? ok(emptyDir()) : await loadTree(walk, parent.tree);
599 if (!loaded.ok) return loaded;
600 const mem = loaded.value;
601 const applied = await inSpan(root.tracer, 'git.commit.apply', { parent: root, attrs: { 'git.commit.applied': plan.changes.length } }, async () => { const r = await apply(walk, mem, plan.changes); return r; });
603 if (!applied.ok) return applied;
604 const decision = treeDecision(parent, applied.value.tree);
605 if (decision === 'empty') return nothing();
606 if (decision === 'noop') return ok({ retry: false, objects: 0, done: resultOf(target.ref, parent, { tree: applied.value.tree, oid: parent.oid === null ? applied.value.tree : parent.oid, pushBytes: 0, outcome: 'noop' }) });
607 const message = plan.message.endsWith('\n') ? plan.message : `${plan.message}\n`;
608 const parents = parent.oid === null ? [] : [parent.oid];
609 const encoded = buildCommitData({ tree: applied.value.tree, parents, author: plan.author, committer: plan.committer, time: plan.author.time, message });
610 if (!encoded.ok) return encoded;
611 let built = encoded.value;
612 if (signer !== null) {
613 const signed = await signCommit(built.data, signer);
614 if (!signed.ok) return signed;
615 built = { data: signed.value, oid: hashObject('commit', signed.value) };
616 }
617 const commitData = built.data;
618 const oid = built.oid;
619 const objects: PackObject[] = [{ type: TYPE.COMMIT, data: commitData }, ...applied.value.objects];
620 const oldOid = oldOidOf(parent);
621 const branded = parseRefname(target.ref);
622 if (!branded.ok) return branded;
623 const pushed = await push(t, { ref: branded.value, oldOid, newOid: oid, objects });
624 if (!pushed.ok) {
625 // a lost race is redone once, or reported against a fresh read; any other Err is the commit's
626 if (!lostRace(pushed.error)) return pushed;
627 if (attempt === 0 && !pinned && !parent.creating) return ok({ retry: true });
628 return lostAt(await lsRefs(t, [target.ref]), target.ref, oldOid, pushed.error);
629 }
630 // the read-back's Err (ambiguous) is the commit's
631 if (verify) { const seen = await verifyRef(t, root, 'git.commit', target.ref, oid); if (!seen.ok) return seen; }
632 return ok({ retry: false, objects: objects.length, done: resultOf(target.ref, parent, { tree: applied.value.tree, oid, pushBytes: pushed.value.packBytes, outcome: 'commit' }) });
634type StreamTry = { readonly plan: Plan; readonly target: Tip; readonly parent: Parent; readonly opts: StreamOpts; readonly attempt: number };
635// One edit of a file that exists on a parent that exists: streamed (Some). Anything else is the in-memory tree (None).
636async function streamIfEdit(url: string, t: Transport, root: Span, job: StreamTry): Promise<Result<Option<MemOutcome>, PlyError>> {
637 const { plan, target, parent, opts, attempt } = job;
638 const only = at(plan.changes, 0);
639 if (plan.changes.length !== 1 || only.tag === 'none' || only.value.kind !== 'edit' || parent.oid === null) return ok(none);
640 const edited = await streamEdit(url, t, root, { plan, target, parent: { ...parent, oid: parent.oid }, edit: only.value, opts, attempt });
641 return edited.ok ? ok(some(edited.value)) : edited;
644// oxlint-disable-next-line require-await -- async, as before: the spec's refusal is an Err the promise resolves with
645export async function commitChanges(url: string, spec: CommitChangesSpec, options: CommitChangesOptions = {}): Promise<Result<CommitChangesResult, PlyError>> {
646 const { head, verify, signer, allowLfsPointer } = withDefaults(options, optionDefaults());
647 const checked = limitsOf(options);
648 if (!checked.ok) return checked;
649 const limits = checked.value;
650 const planned = validatePlan(spec, limits, head);
651 if (!planned.ok) return planned;
652 const plan = planned.value;
653 const pinned = plan.head !== null;
654 const attrs = {
655 'git.commit.ref': plan.ref === null ? '' : plan.ref, 'git.commit.base': plan.baseText, 'git.commit.changes': plan.changes.length,
656 'git.commit.ops': plan.changes.map(c => c.kind), 'git.commit.head': plan.head === null ? '' : plan.head, 'git.commit.stream': false,
657 'git.commit.creating': false, 'git.commit.attempt': 0,
658 };
659 const opts: StreamOpts = { rest: options, limits, verify, signer, allowLfs: allowLfsPointer, pinned };
660 return operation('commit', url, { ...options, limits, attrs }, async ({ t, root, outcome }) => {
661 const finish = (done: CommitChangesResult, objects: number): Ok<CommitChangesResult> => outcome(done.outcome, done, {
662 'git.commit.tree': done.tree, 'git.commit.oid': done.oid, 'git.commit.push.bytes': done.pushBytes, ...(objects > 0 ? { 'git.commit.objects': objects } : {}),
663 });
664 const run = async (attempt: number): Promise<Result<CommitChangesResult, PlyError>> => {
665 root.set({ 'git.commit.attempt': attempt });
666 const target = await resolveTarget(t, plan.ref);
667 if (!target.ok) return target;
668 const tip = target.value;
669 root.set({ 'git.commit.ref': tip.ref });
670 if (plan.head !== null && (tip.oid === null ? ZERO_OID : tip.oid) !== plan.head) return lost(tip.ref, plan.head, tip.oid);
671 const parent = await resolveParent(t, tip, plan.base);
672 if (!parent.ok) return parent;
673 root.set({ 'git.commit.creating': parent.value.creating, 'git.commit.parent': parent.value.oid === null ? '' : parent.value.oid });
674 const streamed = await streamIfEdit(url, t, root, { plan, target: tip, parent: parent.value, opts, attempt });
675 if (!streamed.ok) return streamed;
676 if (streamed.value.tag === 'some') {
677 if (streamed.value.value.retry) return run(1);
678 return finish(streamed.value.value.done, 0);
679 }
680 const wrote = await writeMem({ t, root, plan, target: tip, parent: parent.value, limits, verify, signer, allowLfs: allowLfsPointer, pinned, attempt });
681 if (!wrote.ok) return wrote;
682 if (wrote.value.retry) return run(1);
683 return finish(wrote.value.done, wrote.value.objects);
684 };
685 const done = await run(0);
686 return done;
687 });
Diagnostics4 git calls · 365 ms
CallStatusSizeTime0365 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
fetch20011 KiB360 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=360
git.response.bytes=11187
git.response.cache=MISS
git.response.duration_ms=360
git.fetch.wants=37bc5103f76616860510a2c81949ddc88f02e89f
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=11187
git.pkt.payload.max=11166
git.sideband.band1.bytes=11165
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
a5e1d6431f55a151
Request
5b0bd26a…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format