GitHubivarvong
ply
main
1// Git object encoding/decoding. All pure. Every function that can refuse returns a Result.
2import { fail } from './errors.js';
3import type { Err, Ok, Option, Result } from './result.js';
4import { ok, err, none, some, assertNever } from './result.js';
5import type { ErrorOf } from './errors.js';
6import { Sha1, toOid, fromHex } from './sha1.js';
7import { parseOid, type Oid } from './oid.js';
8import { te, shortRead, decodeBytes, encodeBytes } from './bytes.js';
9import { isDotGitName, isDotFileName, isValidatedIdent, validateRef } from './validate.js';
10import type { ValidatedIdent } from './validate.js';
11import { DEFAULT_LIMITS, limitError, parseLimits } from './limits.js';
12import type { LimitsInput } from './limits.js';
13import { atOr, isMissing, type Input } from './absent.js';
14import type { ObjType, ObjectTypeName, PackKind } from './format.js';
15import {
16 OID_BYTES, OID_HEX_CHARS, TREE_MODE_SEP, TREE_NUL, MODE_TREE, MODE_BLOB, MODE_EXEC, MODE_LINK, MODE_COMMIT, IDENT_TZ_DIGITS, IDENT_TIMESTAMP_MAX,
17 MODE_S_IFREG, MODE_S_IFLNK, MODE_OWNER_EXEC, TREE_MAX_NAME_BYTES,
18 MODE_S_IFMT, MODE_S_IFDIR, MODE_BITS, MODE_LOW_DIGITS, TREE_SORT_SLASH, TREE_ENTRY_MIN,
19 OBJ_COMMIT, OBJ_TREE, OBJ_BLOB, OBJ_TAG, OBJ_OFS_DELTA, OBJ_REF_DELTA,
20 COMMIT_HEADER_TREE, COMMIT_HEADER_PARENT, COMMIT_HEADER_AUTHOR, COMMIT_HEADER_COMMITTER, COMMIT_HEADER_ENCODING,
21 TAG_HEADER_OBJECT, TAG_HEADER_TYPE, TAG_HEADER_TAG, TAG_HEADER_TAGGER,
22} from './format.js';
24export type { ObjType };
26export const TYPE: {
27 readonly COMMIT: typeof OBJ_COMMIT; readonly TREE: typeof OBJ_TREE; readonly BLOB: typeof OBJ_BLOB; readonly TAG: typeof OBJ_TAG;
28 readonly OFS_DELTA: typeof OBJ_OFS_DELTA; readonly REF_DELTA: typeof OBJ_REF_DELTA;
29} = Object.freeze({ COMMIT: OBJ_COMMIT, TREE: OBJ_TREE, BLOB: OBJ_BLOB, TAG: OBJ_TAG, OFS_DELTA: OBJ_OFS_DELTA, REF_DELTA: OBJ_REF_DELTA });
30export const TYPE_NAME: {
31 readonly [OBJ_COMMIT]: 'commit'; readonly [OBJ_TREE]: 'tree'; readonly [OBJ_BLOB]: 'blob'; readonly [OBJ_TAG]: 'tag';
32 readonly [OBJ_OFS_DELTA]: 'ofs_delta'; readonly [OBJ_REF_DELTA]: 'ref_delta';
33} = Object.freeze({ [OBJ_COMMIT]: 'commit', [OBJ_TREE]: 'tree', [OBJ_BLOB]: 'blob', [OBJ_TAG]: 'tag', [OBJ_OFS_DELTA]: 'ofs_delta', [OBJ_REF_DELTA]: 'ref_delta' });
34export const TYPE_ID: {
35 readonly commit: typeof OBJ_COMMIT; readonly tree: typeof OBJ_TREE; readonly blob: typeof OBJ_BLOB; readonly tag: typeof OBJ_TAG;
36} = Object.freeze({ commit: OBJ_COMMIT, tree: OBJ_TREE, blob: OBJ_BLOB, tag: OBJ_TAG });
38export function nameOfTypeId(type: ObjType): PackKind {
39 switch (type) {
40 case OBJ_COMMIT: return 'commit';
41 case OBJ_TREE: return 'tree';
42 case OBJ_BLOB: return 'blob';
43 case OBJ_TAG: return 'tag';
44 case OBJ_OFS_DELTA: return 'ofs_delta';
45 case OBJ_REF_DELTA: return 'ref_delta';
46 }
47 // Stryker disable next-line ConditionalExpression: unreachable, the compiler's exhaustiveness check
48 return assertNever(type);
49}
51// A type id git writes, or invalid (0, 5, and anything else a pack header can carry).
52type WireType = { readonly tag: 'named'; readonly name: PackKind } | { readonly tag: 'invalid' };
53function wireTypeId(type: number): WireType {
54 switch (type) {
55 case OBJ_COMMIT:
56 case OBJ_TREE:
57 case OBJ_BLOB:
58 case OBJ_TAG:
59 case OBJ_OFS_DELTA:
60 case OBJ_REF_DELTA:
61 return { tag: 'named', name: nameOfTypeId(type) };
62 default:
63 return { tag: 'invalid' };
64 }
65}
66function wireTypeName(typeName: string): WireType {
67 switch (typeName) {
68 case 'commit':
69 case 'tree':
70 case 'blob':
71 case 'tag':
72 case 'ofs_delta':
73 case 'ref_delta':
74 return { tag: 'named', name: typeName };
75 default:
76 return { tag: 'invalid' };
77 }
78}
80/** What a wire type id is, for a caller that only stores a tree, blob, or tag as `not_commit`. */
81export type NonCommit =
82 | { readonly tag: 'notCommit'; readonly name: Exclude<ObjectTypeName, 'commit'> }
83 | { readonly tag: 'commit' }
84 | { readonly tag: 'delta'; readonly name: Exclude<PackKind, ObjectTypeName> }
85 | { readonly tag: 'invalid' };
87function nonCommitName(name: PackKind): NonCommit {
88 switch (name) {
89 case 'tree':
90 case 'blob':
91 case 'tag':
92 return { tag: 'notCommit', name };
93 case 'commit':
94 return { tag: 'commit' };
95 case 'ofs_delta':
96 case 'ref_delta':
97 return { tag: 'delta', name };
98 }
99 // Stryker disable next-line ConditionalExpression: unreachable, the compiler's exhaustiveness check
100 return assertNever(name);
101}
103// A pack type id. `notCommit` is a tree, blob, or tag. A commit, a delta, or an unknown id is its own variant.
104export function nonCommitType(type: number): NonCommit {
105 const found = wireTypeId(type);
106 switch (found.tag) {
107 case 'invalid': return { tag: 'invalid' };
108 case 'named': return nonCommitName(found.name);
109 }
110 // Stryker disable next-line ConditionalExpression: unreachable, the compiler's exhaustiveness check
111 return assertNever(found);
112}
114export const objectHeader = (typeName: string, len: number): Uint8Array => te.encode(`${typeName} ${len}\0`);
116export function hashObject(typeName: string, data: Uint8Array): Oid {
117 return new Sha1().update(objectHeader(typeName, data.length)).update(data).hex();
118}
120const cmpBytes = (a: Uint8Array, b: Uint8Array): number => {
121 const n = Math.min(a.length, b.length);
122 for (let i = 0; i < n; i++) {
123 // oxlint-disable-next-line typescript/no-unsafe-type-assertion, typescript/non-nullable-type-assertion-style -- i < n, the shorter length: both reads are in range (`as`, not the `!` src/ forbids)
124 if (a[i] !== b[i]) return (a[i] as number) - (b[i] as number);
125 }
126 return a.length - b.length;
127};
129// ---- tree ----
130// fsck.c verify_ordered sorts an entry as a directory when S_ISDIR holds for the low 16 bits of its mode: `40755` sorts
131// as a directory (fsck only warns about the mode), `160000` as a file.
132const lowBits = (mode: string): number => Number.parseInt(mode.slice(-MODE_LOW_DIGITS), 8) & MODE_BITS;
133// object.h canon_mode on the low 16 bits (tree-walk keeps the mode in a uint16_t): every reader of a tree but fsck sees
134// this. A regular file is 100755 if the owner may execute it, else 100644 (100664 → 100644, 100700 → 100755); S_IFLNK is
135// a symlink, S_IFDIR a tree (40755 → 40000); every other type is a gitlink (1, 160644, 777777 → 160000). `7100644`
136// and `300644` are 100644 to git, without even a badFilemode warning.
137export type Mode = typeof MODE_BLOB | typeof MODE_EXEC | typeof MODE_LINK | typeof MODE_TREE | typeof MODE_COMMIT;
138// canon_mode of a mode's low 16 bits
139function canonBits(m: number): Mode {
140 const type = m & MODE_S_IFMT;
141 if (type === MODE_S_IFREG) return m & MODE_OWNER_EXEC ? MODE_EXEC : MODE_BLOB;
142 if (type === MODE_S_IFLNK) return MODE_LINK;
143 if (type === MODE_S_IFDIR) return MODE_TREE;
144 return MODE_COMMIT;
145}
146export function canonMode(mode: string): Mode {
147 return canonBits(lowBits(mode));
148}
149// The tree order of fsck verify_ordered on two names, a directory's read as if it ended in `/`, without building that
150// key (#207): the sign of cmpBytes(a + '/'?, b + '/'?).
151/* oxlint-disable typescript/no-unsafe-type-assertion, typescript/non-nullable-type-assertion-style -- i < a.length, i < b.length: both reads are in range (`as`, not the `!` src/ forbids) */
152// oxlint-disable-next-line eslint/max-params -- two names and whether each is a directory
153function cmpTreeKeys(a: Uint8Array, aDir: boolean, b: Uint8Array, bDir: boolean): number {
154 const la = aDir ? a.length + 1 : a.length, lb = bDir ? b.length + 1 : b.length;
155 const n = Math.min(la, lb);
156 for (let i = 0; i < n; i++) {
157 const x = i < a.length ? (a[i] as number) : TREE_SORT_SLASH;
158 const y = i < b.length ? (b[i] as number) : TREE_SORT_SLASH;
159 if (x !== y) return x - y;
160 }
161 return la - lb;
162}
163/* oxlint-enable typescript/no-unsafe-type-assertion, typescript/non-nullable-type-assertion-style */
164// A tree entry's mode, read from its bytes [p, sp) without decoding them (#207): lowBits of the mode, or NOT_OCTAL when a byte is
165// not an octal digit (what /^[0-7]+$/ refused of the decoded text: any other byte decodes to a non-digit). Each digit
166// is 3 bits, so the low 16 bits of the whole mode are those of its last MODE_LOW_DIGITS digits, which lowBits reads:
167// the value is kept to its low 16 bits as it is read, however long the mode. Empty (p === sp) is 0; the caller refuses
168// it first.
169/* oxlint-disable typescript/no-unsafe-type-assertion, typescript/non-nullable-type-assertion-style -- p <= i < sp <= data.length: every read is in range (`as`, not the `!` src/ forbids) */
170const OCTAL_0 = 0x30;
171const OCTAL_7 = 0x37;
172const OCTAL_BITS = 3;
173const NOT_OCTAL = -1;
174function modeBits(data: Uint8Array, p: number, sp: number): number {
175 let m = 0;
176 for (let i = p; i < sp; i++) {
177 const c = data[i] as number;
178 if (c < OCTAL_0 || c > OCTAL_7) return NOT_OCTAL;
179 m = ((m << OCTAL_BITS) | (c - OCTAL_0)) & MODE_BITS;
180 }
181 return m;
182}
183// The OID_BYTES at o are all zero (fsck nullSha1)
184function nullOid(data: Uint8Array, o: number): boolean {
185 for (let i = o; i < o + OID_BYTES; i++) if ((data[i] as number) !== 0) return false;
186 return true;
187}
188/* oxlint-enable typescript/no-unsafe-type-assertion, typescript/non-nullable-type-assertion-style */
190export type TreeEntry = { readonly mode: Mode; readonly name: string; readonly oid: Oid; readonly oidOffset: number; readonly entryOffset: number };
191// What encodeTree takes from a caller: plain strings, parsed once (treeEntryOf) into an EntryOf.
192export type TreeEntryInput = { readonly mode: string; readonly name: string; readonly oid: string };
193// An entry to encode, parsed: one of the five modes git writes and a full object id. A parsed TreeEntry is one.
194export type EntryOf = { readonly mode: Mode; readonly name: string; readonly oid: Oid };
195// The five modes git writes in a tree (canon_mode's results), spelled exactly: a mode git would canonicalize first
196// (`100664`, `040000`) is not one of them.
197export function isMode(mode: unknown): mode is Mode {
198 switch (mode) {
199 case MODE_BLOB:
200 case MODE_EXEC:
201 case MODE_LINK:
202 case MODE_TREE:
203 case MODE_COMMIT:
204 return true;
205 default:
206 return false;
207 }
208}
209// A caller's value quoted in a refusal. The types say string, a JavaScript caller's value is whatever it is, and a
210// refusal must not throw: JSON.stringify throws on a BigInt and on a cycle, so only a string is quoted; a number, a
211// boolean and null are spelled, and anything else (an absent value included) is named by its type.
212// An error never grows with a caller's text: at most QUOTE_UNITS UTF-16 units of a string are quoted (http.ts's
213// ERROR_QUOTE: 200), with the true length after it, and the `entry` field holds the same cut (cutName). A name over
214// TREE_MAX_NAME_BYTES is refused for its length, so without the cut that refusal alone is as large as the caller likes.
215// The cut never ends on the first half of a surrogate pair (a unit in d800..dbff): it stops one unit earlier, so what is
216// quoted of a well-formed name is well-formed, and an error about a name with a byte form holds no string without one.
217const QUOTE_UNITS = 200;
218const HIGH_SURROGATE_FIRST = 0xd8_00;
219const HIGH_SURROGATE_LAST = 0xdb_ff;
220function cut(text: string): string {
221 const last = text.charCodeAt(QUOTE_UNITS - 1); // oxlint-disable-line unicorn/prefer-code-point -- the unit itself: codePointAt would pair it with the next one
222 return text.slice(0, last >= HIGH_SURROGATE_FIRST && last <= HIGH_SURROGATE_LAST ? QUOTE_UNITS - 1 : QUOTE_UNITS);
223}
224const cutName = (name: string): string => (typeof name === 'string' && name.length > QUOTE_UNITS ? cut(name) : name);
225function quoted(value: unknown): string {
226 if (typeof value === 'string') return value.length > QUOTE_UNITS ? `${JSON.stringify(cut(value))}… (${value.length} UTF-16 units)` : JSON.stringify(value);
227 return value === null || typeof value === 'number' || typeof value === 'boolean' ? String(value) : typeof value;
228}
229// A caller's entry, parsed once: the mode is one of the five (`tree: entry "n": invalid mode`, what `mode`) and the oid
230// 40 lowercase hex (parseOid's refusal, what `oid`), each with the entry's name.
231export function treeEntryOf(e: TreeEntryInput): Result<EntryOf, BadRequest> {
232 const { mode, name } = e;
233 if (!isMode(mode)) return fail('bad_request', `tree: entry ${quoted(name)}: invalid mode ${quoted(mode)}`, { what: 'mode', entry: cutName(name) });
234 const oid = parseOid(e.oid);
235 if (!oid.ok) return fail('bad_request', `tree: entry ${quoted(name)}: ${oid.error.message}`, { what: 'oid', entry: cutName(name) });
236 return ok({ mode, name, oid: oid.value });
237}
239type Corrupt = ErrorOf<'pack_corrupt'>;
240type BadRequest = ErrorOf<'bad_request'>;
241// What a parser refuses: corrupt bytes, a limit, or a caller's limit that bounds nothing.
242export type ObjectError = Corrupt | ErrorOf<'limit_exceeded'> | BadRequest;
243// A check that passed: one shared value, so a check that succeeds allocates nothing.
244const DONE: Ok<null> = ok(null);
246// Every tree refusal is pack_corrupt with this prefix (one constructor: the code and prefix ship once).
247const badTree = (why: string): Err<Corrupt> => fail('pack_corrupt', `tree: ${why}`);
249// How many entries are fully framed (mode, space, name, NUL, OID_BYTES). A short tail is not an entry: the parser
250// reports that as pack_corrupt. Stops at one past the cap, so a huge tree is not scanned twice end to end.
251const completeTreeFrames = (data: Uint8Array, maxEntries: number): number => {
252 const stop = maxEntries + 1;
253 let p = 0;
254 let n = 0;
255 while (p < data.length && n < stop) {
256 const sp = data.indexOf(TREE_MODE_SEP, p);
257 if (sp < p) return n;
258 const nul = data.indexOf(TREE_NUL, sp + 1);
259 if (nul < sp + 1 || data.length - (nul + 1) < OID_BYTES) return n;
260 n += 1;
261 p = nul + 1 + OID_BYTES;
262 }
263 return n;
264};
266// The hex id is computed when a reader asks. Caching it on the entry would put a 40-character string beside every
267// name, which is what exhausted a 128 MiB heap at the cap. The tree's buffer is a private field: not enumerable, not in
268// JSON, not a key, so equality and JSON see the mode, the name, and the offsets. Entries are ordinary objects of one
269// shape, built by one constructor (#207: an Object.create of a per-tree prototype, then Object.assign of a record, was
270// a fifth of parseTree's CPU); defineProperty on every entry puts it in dictionary mode, which is what exhausted a
271// 128 MiB heap at the cap, and a private field does not.
272class ParsedEntry implements TreeEntry {
273 public readonly mode: Mode;
274 public readonly name: string;
275 public readonly oidOffset: number;
276 public readonly entryOffset: number;
277 readonly #bytes: Uint8Array;
278 // oxlint-disable-next-line eslint/max-params -- the tree's bytes and one entry's four fields, on every entry: no record to allocate
279 public constructor(bytes: Uint8Array, mode: Mode, name: string, oidOffset: number, entryOffset: number) {
280 this.mode = mode; this.name = name; this.oidOffset = oidOffset; this.entryOffset = entryOffset;
281 this.#bytes = bytes;
282 }
283 public get oid(): Oid {
284 return toOid(this.#bytes.subarray(this.oidOffset, this.oidOffset + OID_BYTES));
285 }
286}
288// entry: { mode: '100644'|'100755'|'120000'|'40000'|'160000', name, oid (hex), oidOffset }
289// Duplicates and order are git's rules (fsck duplicateEntries and treeNotSorted, both errors under --strict) on the
290// raw name bytes. A file `d` and a directory `d` need not be neighbours (`d` < `d.x` < `d/`), so the duplicate check is
291// over the whole tree, as fsck's verify_ordered does with its stack of file names a later directory could repeat. It
292// runs before the order check: by then every earlier pair was in order, and on a sorted prefix fsck's stack finds
293// exactly the duplicates this set finds, so the message is one fsck prints. Names decode losslessly (decodeBytes, #43):
294// distinct bytes are distinct names, so the set holds that name and not a second hex copy of the bytes.
295// A tree that cannot fit in maxTreeEntries is counted before any entry object exists. The cap still fires as
296// `tree entries <max+1>`, and bytes past it are not validated: a bad mode there stays limit_exceeded.
297// @decoder parseTree prefix=tree
298// oxlint-disable-next-line eslint/complexity -- fsck_tree's checks in fsck's order, inline: a helper costs bytes on every entry
299export function parseTree(data: Uint8Array, limits: LimitsInput = DEFAULT_LIMITS): Result<TreeEntry[], ObjectError> {
300 const checked = parseLimits(limits);
301 if (!checked.ok) return checked;
302 const maxEntries = checked.value.maxTreeEntries;
303 // Shorter than one minimum entry per allowed slot: the count cannot pass the cap, so skip the frame scan.
304 // A flipped comparison here still agrees with the frame count (max+1 minimum frames cannot fit in fewer bytes).
305 // Stryker disable next-line ConditionalExpression,EqualityOperator,ArithmeticOperator: byte length only skips the scan; the frame count decides the cap
306 const wide = data.length > maxEntries * TREE_ENTRY_MIN;
307 // Stryker disable next-line ConditionalExpression,EqualityOperator: past the cap the loop refuses either way; this flag only skips retaining entries the caller never sees
308 const over = wide && completeTreeFrames(data, maxEntries) > maxEntries;
309 const entries: TreeEntry[] = [];
310 const seen = new Set<string>();
311 let p = 0;
312 let count = 0;
313 let prevName: Uint8Array | null = null;
314 // Stryker disable next-line BooleanLiteral: read only once prevName is set, and set with it
315 let prevDir = false;
316 while (p < data.length) {
317 if (count >= maxEntries) return err(limitError('tree entries', count + 1, maxEntries));
318 const sp = data.indexOf(TREE_MODE_SEP, p);
319 // A negative fromIndex would wrap; indexOf returns -1 when the separator is absent.
320 if (sp < p) return badTree('malformed entry');
321 const nul = data.indexOf(TREE_NUL, sp + 1);
322 if (nul < sp + 1) return badTree('malformed entry');
323 // p <= sp < nul < data.length (the two checks above): the mode and the name are in range, they cannot be short
324 // The name is bytes to git: decodeBytes keeps a leading BOM and escapes ill-formed UTF-8, so the string maps back (#43)
325 const nameBytes: Uint8Array = data.subarray(sp + 1, nul);
326 const name: string = decodeBytes(nameBytes);
327 // The id starts at nul+1 and needs OID_BYTES bytes there (take's short read); the old `nul + OID_BYTES > length`
328 // guard counted from the NUL and let a 19-byte id through.
329 if (data.length - (nul + 1) < OID_BYTES) return err(shortRead('pack_corrupt', nul + 1, OID_BYTES, data.length));
330 if (sp === p) return badTree('empty mode');
331 // the mode's bytes, not a decode of them (#207)
332 const bits = modeBits(data, p, sp);
333 if (bits === NOT_OCTAL) return badTree('malformed mode');
334 // decode_tree_entry refuses an empty name before fsck_tree looks at the mode's first byte
335 if (name.length === 0) return badTree('empty name');
336 if (data[p] === OCTAL_0) return badTree('zero-padded mode');
337 const mode = canonBits(bits);
338 if (name.includes('/')) return badTree('full pathname');
339 if (name === '.' || name === '..' || isDotGitName(nameBytes)) return badTree('bad name');
340 if (nameBytes.length > TREE_MAX_NAME_BYTES) return badTree('large pathname');
341 if (nullOid(data, nul + 1)) return badTree('null sha1');
342 // fsck_tree: a .gitmodules (any spelling) that is a symlink is gitmodulesSymlink; one that is not a blob (a tree, or a
343 // gitlink, whose commit is never in the repository) is gitmodulesBlob / gitmodulesMissing in fsck_finish. The same
344 // for .gitattributes, except that as a symlink it is only a warning (gitattributesSymlink, INFO)
345 if (isDotFileName(nameBytes, 'gitmodules')) {
346 if (mode === MODE_LINK) return badTree('.gitmodules is a symbolic link');
347 if (mode === MODE_TREE || mode === MODE_COMMIT) return badTree('.gitmodules is not a blob');
348 }
349 if ((mode === MODE_TREE || mode === MODE_COMMIT) && isDotFileName(nameBytes, 'gitattributes')) return badTree('.gitattributes is not a blob');
350 if (seen.has(name)) return badTree(`duplicate entry ${JSON.stringify(name)}`);
351 seen.add(name);
352 const dir = (bits & MODE_S_IFMT) === MODE_S_IFDIR;
353 // Stryker disable next-line EqualityOperator: equal keys are equal names (a name holds no '/'), which the duplicate check above refused
354 if (prevName !== null && cmpTreeKeys(prevName, prevDir, nameBytes, dir) >= 0) return badTree('not strictly sorted');
355 prevName = nameBytes;
356 prevDir = dir;
357 // Past the cap, keep the name set (a bad prefix is still pack_corrupt) and do not retain the entry.
358 // Always pushing still refuses on the next entry, so the returned array is the same; never pushing is a length assertion.
359 // Stryker disable next-line ConditionalExpression: retaining the entries past the cap does not change the refusal or the array a caller sees
360 if (!over) entries.push(new ParsedEntry(data, mode, name, nul + 1, p));
361 count += 1;
362 p = nul + 1 + OID_BYTES;
363 }
364 return ok(entries);
365}
367type Sortable = { readonly mode: string; readonly name: string };
368// git's tree order on the names' bytes (a directory sorts as its name and a `/`). A name with no byte form is refused.
369// Each key is computed once, before the sort: an entry's name and mode are read once and encoded once, where encoding
370// both keys inside the comparator cost two encodes (and, for a directory, two string concatenations) per comparison,
371// about 2 log2(n) per entry. The comparator and the keys are the ones the sort always used, and Array.prototype.sort
372// is stable, so the order is unchanged for every input. What changed with it: every name is encoded, compared or not,
373// so the refusal is the first entry in the caller's order with no byte form, and a list of one such entry is refused.
374type SortRow<T> = { readonly key: Uint8Array; readonly entry: T };
375export function treeSort<T extends Sortable>(entries: Iterable<T>): Result<T[], BadRequest> {
376 const rows: Array<SortRow<T>> = [];
377 for (const entry of entries) {
378 // The entry's type is not checked at run time. An entry that is no object (null, or the missing value) has no name,
379 // and a name that is not a string (null, missing, a Symbol, an object whose toString throws) is never concatenated:
380 // the `/` is added to a string only, and anything else goes to encodeBytes as it is, which refuses it (`tree entry
381 // name must be a string`). So the refusal is the same at every list length, and nothing here can throw on a name.
382 const given: unknown = entry;
383 const name: unknown = given === null || isMissing(given) ? null : entry.name;
384 const key = encodeBytes(typeof name === 'string' && entry.mode === MODE_TREE ? `${name}/` : name, 'tree entry name');
385 if (!key.ok) return key;
386 rows.push({ key: key.value, entry });
387 }
388 // oxlint-disable-next-line unicorn/no-array-sort -- sorts its own array; any iterable a caller passes still works
389 rows.sort((a, b) => cmpBytes(a.key, b.key));
390 return ok(rows.map(row => row.entry));
391}
393// The one tree encoder: every tree ply writes (encodeTree, pushTree, commitChanges, merge, memtree, buildTree) is built
394// here, and none of them can write a tree `git fsck --strict` refuses. Each entry is held to fsck.c fsck_tree's rules,
395// the ones parseTree reads by, before a byte is written: an empty name (git: `empty filename in tree entry`, badTree),
396// a NUL (it would end the name field early: the rest of the name would be read as an object id and further entries)
397// or a `/` in a name (fullPathname), `.` (hasDot), `..` (hasDotdot), any spelling of `.git` git checks (hasDotgit: case
398// folded, NTFS short and stream forms, HFS ignorable code points, after a backslash), a name over TREE_MAX_NAME_BYTES
399// (largePathname), the null id (nullSha1), `.gitmodules` as a symlink (gitmodulesSymlink) or as a tree or gitlink
400// (gitmodulesBlob, gitmodulesMissing), and `.gitattributes` as a tree or gitlink (gitattributesBlob).
401// duplicateEntries: one name twice in one tree, whatever the modes. A file `a` and a directory `a` do not sort next to
402// each other (`a` < `a.b` < `a/`), so the check is by name, not by neighbour. Case-only twins (`README` and `readme`)
403// are two names to git and to fsck; they collide only on a case-insensitive checkout, and are accepted here too.
404// treeNotSorted cannot happen: the entries are sorted here, in fsck verify_ordered's order (cmpTreeKeys), on name bytes
405// encoded once per entry. zeroPaddedFilemode and badFilemode cannot happen either: the encoder checks every field
406// itself, whatever the entry's type says. The name must be a string with a byte form, the mode one of the five git
407// writes (isMode) and the id 40 lowercase hex (parseOid); anything else is bad_request (what `tree entry name`, `mode`,
408// `oid`), never a throw and never a written byte. A mode that is not one of the five has no fixed width (a fullwidth
409// digit is one UTF-16 unit and three bytes), so it is refused before the output is sized.
410const NULL_OID = '0'.repeat(OID_HEX_CHARS);
411type TreeRow = { readonly mode: Mode; readonly name: Uint8Array; readonly oid: Oid };
412// Why fsck refuses one entry (parseTree's words for it), or null: the entry and its name's bytes
413// oxlint-disable-next-line eslint/complexity -- fsck_tree's checks in fsck's order, as in parseTree
414function entryRefusal(e: EntryOf, name: Uint8Array): string | null {
415 const { mode } = e;
416 if (name.length === 0) return 'empty name';
417 if (name.includes(TREE_NUL)) return 'NUL in name';
418 if (name.includes(TREE_SORT_SLASH)) return 'full pathname';
419 if (e.name === '.' || e.name === '..' || isDotGitName(name)) return 'bad name';
420 if (name.length > TREE_MAX_NAME_BYTES) return 'large pathname';
421 if (e.oid === NULL_OID) return 'null sha1';
422 const notBlob = mode === MODE_TREE || mode === MODE_COMMIT;
423 if (isDotFileName(name, 'gitmodules')) {
424 if (mode === MODE_LINK) return '.gitmodules is a symbolic link';
425 if (notBlob) return '.gitmodules is not a blob';
426 }
427 if (notBlob && isDotFileName(name, 'gitattributes')) return '.gitattributes is not a blob';
428 return null;
429}
430export function encodeEntries(entries: readonly EntryOf[]): Result<Uint8Array, BadRequest> {
431 const names = new Set<string>();
432 const rows: TreeRow[] = [];
433 let size = 0;
434 for (const e of entries) {
435 const { mode } = e;
436 const encoded = encodeBytes(e.name, 'tree entry name');
437 if (!encoded.ok) return encoded;
438 const name = encoded.value;
439 if (!isMode(mode)) return fail('bad_request', `tree: entry ${quoted(e.name)}: invalid mode ${quoted(mode)}`, { what: 'mode', entry: cutName(e.name) });
440 const oid = parseOid(e.oid);
441 if (!oid.ok) return fail('bad_request', `tree: entry ${quoted(e.name)}: ${oid.error.message}`, { what: 'oid', entry: cutName(e.name) });
442 const why = entryRefusal(e, name);
443 if (why !== null) return fail('bad_request', `tree: entry ${quoted(e.name)}: ${why}`, { what: 'tree entry', entry: cutName(e.name) });
444 if (names.has(e.name)) return fail('bad_request', `tree: duplicate entry ${quoted(e.name)}`, { what: 'tree entry', entry: cutName(e.name) });
445 names.add(e.name);
446 rows.push({ mode, name, oid: e.oid });
447 size += mode.length + 1 + name.length + 1 + OID_BYTES;
448 }
449 // oxlint-disable-next-line unicorn/no-array-sort -- sorts its own array
450 rows.sort((a, b) => cmpTreeKeys(a.name, a.mode === MODE_TREE, b.name, b.mode === MODE_TREE));
451 const out = new Uint8Array(size);
452 let p = 0;
453 for (const row of rows) {
454 // the mode is ASCII digits: one byte each
455 p += te.encodeInto(row.mode, out.subarray(p)).written;
456 out[p] = TREE_MODE_SEP;
457 out.set(row.name, p + 1);
458 p += row.name.length + 1;
459 out[p] = TREE_NUL;
460 out.set(fromHex(row.oid), p + 1);
461 p += OID_BYTES + 1;
462 }
463 return ok(out);
464}
466// A caller's entries, each parsed once (treeEntryOf, in the caller's order), then encoded.
467export function encodeTree(entries: readonly TreeEntryInput[]): Result<Uint8Array, BadRequest> {
468 const parsed: EntryOf[] = [];
469 for (const e of entries) {
470 const one = treeEntryOf(e);
471 if (!one.ok) return one;
472 parsed.push(one.value);
473 }
474 return encodeEntries(parsed);
475}
477// Replace the oid of one entry in place; returns new bytes + coordinates for a structural delta.
478export function treeReplaceOid(data: Uint8Array, entry: { readonly oidOffset: number }, newOidHex: Oid): Uint8Array {
479 const out = data.slice();
480 out.set(fromHex(newOidHex), entry.oidOffset);
481 return out;
482}
484// ---- commit and tag: git fsck.c, rule for rule (issue #59) ----
485// parseCommit and parseTag are the only readers of a commit or tag header, and each refuses exactly the objects
486// `git fsck --strict` reports an error for, with git's msgId in the message (`commit: badDate: …`). The decision space
487// and git's verdict on every cell are in test/fsck-space.test.js. What fsck does not read, ply does not judge: a commit
488// is checked up to its committer line and a tag up to its tagger; every later header line is kept verbatim in `extra`.
489// One allowed typed refusal (PR #7): a second copy of a single-valued header after the committer or tagger (tree,
490// parent, author, committer, encoding; object, type, tag, tagger) is fsck-clean, but git's own views of that object disagree (pretty.c's
491// %an/%cn show the last author/committer line, %T, %e and the commit date the first; cat-file shows a late parent that
492// %P ignores, and a second tag object/type/name that the parsed tag ignores), so whatever ply showed, some git view would contradict it: an author-spoofing differential. Those are refused as
493// `duplicateHeader` (`commit: duplicate tree`). A missing tagger and a tag name that is not a refname are warnings git accepts (INFO
494// under --strict), so ply accepts them too. The object is decoded losslessly (decodeBytes, #43): a leading BOM is kept,
495// so a BOM before `tree` is a missing tree, as in git, and an ill-formed UTF-8 byte becomes an escape (a lone surrogate)
496// that encodeBytes maps back to the same byte, so a Latin-1 message or ident re-encodes to its own bytes. No rule here
497// matches an escape, and an escape can never form a NUL, a newline or any other delimiter.
498const DIGIT = /^[0-9]$/u;
500const BLANK_LINE = '\n\n';
501const NO_BODY = -1;
502const corrupt = (kind: string, msgId: string, why: string): Err<Corrupt> => fail('pack_corrupt', `${kind}: ${msgId}: ${why}`, { msgId });
504// fsck.c verify_headers: no NUL before the first blank line, and a header without a blank line ends in a newline.
505// The index of the blank line's first newline, or -1 when there is no body section.
506function verifyHeaders(s: string, kind: string): Result<number, Corrupt> {
507 for (let i = 0; i < s.length; i++) {
508 const ch = s[i];
509 if (ch === '\0') return corrupt(kind, 'nulInHeader', `unterminated header: NUL at offset ${i}`);
510 if (ch === '\n' && s[i + 1] === '\n') return ok(i);
511 }
512 if (s.length > 0 && s.endsWith('\n')) return ok(NO_BODY);
513 return corrupt(kind, 'unterminatedHeader', 'unterminated header');
514}
516// parse_oid_hex then '\n': 40 hex digits of either case (git stores the binary id, so it prints lowercase). The id is
517// parsed once, lowercased (only A-F lowercase to hex digits, as in lsrefs.ts): a slice cut short by the end of the
518// object is the length refusal, and a non-hex character the digit one; either is git's bad sha1.
519function oidLine(s: string, p: number, kind: string, msgId: string, what: string): Result<Oid, Corrupt> {
520 const id = parseOid(s.slice(p, p + OID_HEX_CHARS).toLowerCase());
521 if (!id.ok || s[p + OID_HEX_CHARS] !== '\n') return corrupt(kind, msgId, `invalid '${what}' line format - bad sha1`);
522 return id;
523}
526// fsck.c fsck_ident on the line that starts at p (after "author "); returns [the ident text, the index after its
527// newline]. The checks and their order are git's: a leading '<', a '>' before the '<', no '<', no space before '<',
528// no '>' after the email, no space after '>', then spaces or tabs, a digit, no leading zero unless the date is "0",
529// no overflow past git's timestamp range, one space, a sign, IDENT_TZ_DIGITS digits, and the newline.
530// The digits of the greatest timestamp fsck accepts (2^63 - 1: 19).
531const IDENT_TIMESTAMP_DIGITS = String(IDENT_TIMESTAMP_MAX).length;
532// `digit` classifies one character; the parsers pass DIGIT, and a test counts through its own (test/ident-timestamp).
533// oxlint-disable-next-line eslint/complexity -- fsck_ident line for line, inline: a helper costs bytes on every entry
534export function fsckIdent(s: string, p: number, kind: string, role: string, digit: RegExp = DIGIT): Result<readonly [ident: string, next: number], Corrupt> {
535 const eol = s.indexOf('\n', p);
536 const end = eol < 0 ? s.length : eol;
537 const bad = (msgId: string, why: string): Err<Corrupt> => corrupt(kind, msgId, `invalid ${role} line - ${why}`);
538 if (s[p] === '<') return bad('missingNameBeforeEmail', 'missing space before email');
539 let q = p;
540 while (q < end && s[q] !== '<' && s[q] !== '>') q++;
541 if (s[q] === '>') return bad('badName', 'bad name');
542 if (s[q] !== '<') return bad('missingEmail', 'missing email');
543 if (s[q - 1] !== ' ') return bad('missingSpaceBeforeEmail', 'missing space before email');
544 q++;
545 while (q < end && s[q] !== '<' && s[q] !== '>') q++;
546 if (s[q] !== '>') return bad('badEmail', 'bad email');
547 q++;
548 if (s[q] !== ' ') return bad('missingSpaceBeforeDate', 'missing space before date');
549 q++;
550 while (s[q] === ' ' || s[q] === '\t') q++;
551 // charAt past the end is '', which is no digit
552 if (!digit.test(s.charAt(q))) return bad('badDate', 'bad date');
553 if (s[q] === '0' && s[q + 1] !== ' ') return bad('zeroPaddedDate', 'zero-padded date');
554 const start = q;
555 // By length first: the run has no leading zero (above), so more digits than the limit has is past the limit, and
556 // fsck reports the overflow before it reads what follows the digits. The run is the remote's and as long as the
557 // object, so it is read one digit past the limit's and no further, and BigInt (superlinear) only ever sees a short one.
558 while (q - start <= IDENT_TIMESTAMP_DIGITS && digit.test(s.charAt(q))) q++;
559 if (q - start > IDENT_TIMESTAMP_DIGITS || BigInt(s.slice(start, q)) > IDENT_TIMESTAMP_MAX) return bad('badDateOverflow', 'date causes integer overflow');
560 if (s[q] !== ' ') return bad('badDate', 'bad date');
561 q++;
562 if (s[q] !== '+' && s[q] !== '-') return bad('badTimezone', 'bad time zone');
563 for (let i = 1; i <= IDENT_TZ_DIGITS; i++) if (!digit.test(s.charAt(q + i))) return bad('badTimezone', 'bad time zone');
564 if (s[q + IDENT_TZ_DIGITS + 1] !== '\n') return bad('badTimezone', 'bad time zone');
565 return ok([s.slice(p, end), end + 1]);
566}
568// The header lines after the last one fsck reads, up to the blank line (or the end), and the message after it.
569function rest(s: string, p: number, blank: number): { extra: string[]; message: string | null } {
570 const headEnd = blank === NO_BODY ? s.length : blank + 1;
571 const tail = s.slice(p, headEnd);
572 // every header line ends in a newline (verify_headers), so the tail is whole lines; drop the last terminator
573 return { extra: tail.length > 0 ? tail.slice(0, tail.length - 1).split('\n') : [], message: blank === NO_BODY ? null : s.slice(blank + BLANK_LINE.length) };
574}
576// The allowed typed refusal above: fsck accepts the object, git's views of it disagree, ply refuses. A line after the
577// committer that starts `parent ` is a parent cat-file shows and %P does not; PR #7 named it a bad header order.
578const COMMIT_SHADOWED = [COMMIT_HEADER_TREE, COMMIT_HEADER_PARENT, COMMIT_HEADER_AUTHOR, COMMIT_HEADER_COMMITTER];
579const TAG_SHADOWED = [TAG_HEADER_OBJECT, TAG_HEADER_TYPE, TAG_HEADER_TAG, TAG_HEADER_TAGGER];
580const duplicate = (kind: string, key: string): Err<Corrupt> => fail('pack_corrupt', key === COMMIT_HEADER_PARENT && kind === 'commit' ? 'commit: bad header order' : `${kind}: duplicate ${key}`, { msgId: 'duplicateHeader' });
581function refuseShadowed(kind: string, extra: readonly string[], keys: readonly string[]): Result<null, Corrupt> {
582 for (const l of extra) for (const key of keys) if (l.startsWith(`${key} `)) return duplicate(kind, key);
583 return DONE;
584}
586// tree and parents are parsed once (oidLine): Oids.
587export type Commit = {
588 readonly tree: Oid; readonly parents: Oid[]; readonly author: string; readonly committer: string;
589 readonly encoding: string | null; readonly extra: string[]; readonly message: string | null;
590};
591// @decoder parseCommit prefix=commit
592export function parseCommit(data: Uint8Array, limits: LimitsInput = DEFAULT_LIMITS): Result<Commit, ObjectError> {
593 const checked = parseLimits(limits);
594 if (!checked.ok) return checked;
595 const maxParents = checked.value.maxCommitParents;
596 const s: string = decodeBytes(data);
597 const headers = verifyHeaders(s, 'commit');
598 if (!headers.ok) return headers;
599 const blank = headers.value;
600 const has = (p: number, key: string): boolean => s.startsWith(`${key} `, p);
601 if (!has(0, COMMIT_HEADER_TREE)) return corrupt('commit', 'missingTree', "invalid format - expected 'tree' line");
602 let p = COMMIT_HEADER_TREE.length + 1;
603 const tree = oidLine(s, p, 'commit', 'badTreeSha1', COMMIT_HEADER_TREE);
604 if (!tree.ok) return tree;
605 p += OID_HEX_CHARS + 1;
606 const parents: Oid[] = [];
607 while (has(p, COMMIT_HEADER_PARENT)) {
608 p += COMMIT_HEADER_PARENT.length + 1;
609 const parent = oidLine(s, p, 'commit', 'badParentSha1', COMMIT_HEADER_PARENT);
610 if (!parent.ok) return parent;
611 parents.push(parent.value);
612 if (parents.length > maxParents) return err(limitError('commit parents', parents.length, maxParents));
613 p += OID_HEX_CHARS + 1;
614 }
615 const authors: string[] = [];
616 while (has(p, COMMIT_HEADER_AUTHOR)) {
617 const who = fsckIdent(s, p + COMMIT_HEADER_AUTHOR.length + 1, 'commit', COMMIT_HEADER_AUTHOR);
618 if (!who.ok) return who;
619 authors.push(who.value[0]);
620 p = who.value[1];
621 }
622 const [author] = authors;
623 if (typeof author !== 'string') return corrupt('commit', 'missingAuthor', "invalid format - expected 'author' line");
624 if (authors.length > 1) return corrupt('commit', 'multipleAuthors', "invalid format - multiple 'author' lines");
625 if (!has(p, COMMIT_HEADER_COMMITTER)) return corrupt('commit', 'missingCommitter', "invalid format - expected 'committer' line");
626 const committed = fsckIdent(s, p + COMMIT_HEADER_COMMITTER.length + 1, 'commit', COMMIT_HEADER_COMMITTER);
627 if (!committed.ok) return committed;
628 const [committer, next] = committed.value;
629 // fsck_commit's last check is over the whole object; verify_headers already refused a NUL in the header
630 if (s.includes('\0')) return corrupt('commit', 'nulInCommit', 'NUL byte in the commit object body');
631 const { extra, message } = rest(s, next, blank);
632 const shadowed = refuseShadowed('commit', extra, COMMIT_SHADOWED);
633 if (!shadowed.ok) return shadowed;
634 const at = extra.findIndex(l => l.startsWith(`${COMMIT_HEADER_ENCODING} `));
635 // splice returns a one-element array; String() of it is that line
636 const encoding = at < 0 ? null : String(extra.splice(at, 1)).slice(COMMIT_HEADER_ENCODING.length + 1);
637 // a second encoding is a second copy of a single-valued header
638 if (extra.some(l => l.startsWith(`${COMMIT_HEADER_ENCODING} `))) return duplicate('commit', COMMIT_HEADER_ENCODING);
639 return ok({ tree: tree.value, parents, author, committer, encoding, extra, message });
640}
642export function ident(person: ValidatedIdent): Result<string, BadRequest> {
643 if (!isValidatedIdent(person)) return fail('bad_request', 'ident: unvalidated identity', { what: 'ident' });
644 return ok(`${person.name} <${person.email}> ${person.time} ${person.tz}`);
645}
647// The inverse, as git's split_ident_line reads it: name up to the first '<' (trailing spaces trimmed), email up to the
648// next '>', then "<epoch> <tz>" after the last '>'. Fields git would print as empty are '' (time null when the date is missing).
649// @decoder parseIdent prefix=ident
650export type ParsedIdent = { readonly name: string; readonly email: string; readonly time: string | null; readonly tz: string };
651export function parseIdent(line: unknown): ParsedIdent | null {
652 if (typeof line !== 'string') return null;
653 const lt = line.indexOf('<');
654 if (lt < 0) return { name: line.trim(), email: '', time: null, tz: '' };
655 const gt = line.indexOf('>', lt + 1);
656 // Stryker disable next-line EqualityOperator: indexOf from lt + 1 cannot return 0, so <= and < reject the same missing '>'
657 if (gt < 0) return { name: line.trim(), email: '', time: null, tz: '' };
658 const parts = line.slice(line.lastIndexOf('>') + 1).trim().split(/\s+/u);
659 // Stryker disable next-line StringLiteral: a missing time fails the digit test the same way any non-numeric default does
660 const time = atOr(parts, 0, '');
661 const tz = atOr(parts, 1, '');
662 return { name: line.slice(0, lt).trimEnd(), email: line.slice(lt + 1, gt), time: /^\d+$/u.test(time) ? time : null, tz };
663}
665// ---- tag (annotated): fsck.c fsck_tag_standalone ----
666export type Tag = {
667 readonly object: string; readonly type: string; readonly tag: string; readonly tagger: string | null;
668 readonly extra: string[]; readonly message: string | null;
669};
670// @decoder parseTag prefix=tag
671export function parseTag(data: Uint8Array): Result<Tag, Corrupt> {
672 const s: string = decodeBytes(data);
673 const headers = verifyHeaders(s, 'tag');
674 if (!headers.ok) return headers;
675 const blank = headers.value;
676 const has = (p: number, key: string): boolean => s.startsWith(`${key} `, p);
677 if (!has(0, TAG_HEADER_OBJECT)) return corrupt('tag', 'missingObject', "invalid format - expected 'object' line");
678 let p = TAG_HEADER_OBJECT.length + 1;
679 const object = oidLine(s, p, 'tag', 'badObjectSha1', TAG_HEADER_OBJECT);
680 if (!object.ok) return object;
681 p += OID_HEX_CHARS + 1;
682 if (!has(p, TAG_HEADER_TYPE)) return corrupt('tag', 'missingTypeEntry', "invalid format - expected 'type' line");
683 p += TAG_HEADER_TYPE.length + 1;
684 // verify_headers guarantees a newline after every header line, so the type and tag lines always end
685 let eol = s.indexOf('\n', p);
686 const type = s.slice(p, eol);
687 if (!Object.hasOwn(TYPE_ID, type)) return corrupt('tag', 'badType', "invalid 'type' value");
688 p = eol + 1;
689 if (!has(p, TAG_HEADER_TAG)) return corrupt('tag', 'missingTagEntry', "invalid format - expected 'tag' line");
690 p += TAG_HEADER_TAG.length + 1;
691 eol = s.indexOf('\n', p);
692 // badTagName (not a refname under refs/tags/) is INFO: git warns and accepts, and so does ply
693 const tag = s.slice(p, eol);
694 p = eol + 1;
695 // missingTaggerEntry is INFO: tags before git 0.99.1 have none
696 let tagger: string | null = null;
697 if (has(p, TAG_HEADER_TAGGER)) {
698 const who = fsckIdent(s, p + TAG_HEADER_TAGGER.length + 1, 'tag', TAG_HEADER_TAGGER);
699 if (!who.ok) return who;
700 [tagger, p] = who.value;
701 }
702 // extraHeaderEntry is IGNORE, and fsck never reads a tag's body: a NUL there is accepted, unlike in a commit
703 const { extra, message } = rest(s, p, blank);
704 const shadowed = refuseShadowed('tag', extra, TAG_SHADOWED);
705 if (!shadowed.ok) return shadowed;
706 return ok({ object: object.value, type, tag, tagger, extra, message });
707}
709// Every object fetch passes through here once it hashes to the oid the server advertised (fetchObject, checkWide on a
710// pack before any of it is returned or harvested). It is the same parser every reader calls, so a commit or tag no
711// reader would accept never reaches one. A tree's entries are its answer (#208): the parse is the reader's too, so a fetched
712// tree is parsed once (fetch.ts treeEntries); any other type answers none.
713const NOTHING_PARSED: Ok<Option<TreeEntry[]>> = ok(none);
714export function assertFetched(typeName: string, data: Uint8Array, limits: LimitsInput = DEFAULT_LIMITS): Result<Option<TreeEntry[]>, ObjectError> {
715 const found = wireTypeName(typeName);
716 switch (found.tag) {
717 case 'invalid': return fail('pack_corrupt', `object: bad type ${typeName}`);
718 case 'named': {
719 switch (found.name) {
720 case 'blob': case 'ofs_delta': case 'ref_delta': return NOTHING_PARSED;
721 case 'tree': { const r = parseTree(data, limits); return r.ok ? ok(some(r.value)) : r; }
722 case 'commit': { const r = parseCommit(data, limits); return r.ok ? NOTHING_PARSED : r; }
723 case 'tag': { const r = parseTag(data); return r.ok ? NOTHING_PARSED : r; }
724 }
725 // Stryker disable next-line ConditionalExpression,CallExpression: unreachable, the compiler's exhaustiveness check
726 return assertNever(found.name);
727 }
728 }
729 // Stryker disable next-line ConditionalExpression,CallExpression: unreachable, the compiler's exhaustiveness check
730 return assertNever(found);
731}
733// A header value is one line. LF or NUL, from any caller, would open a new header. The message is the body: LF is
734// legal there, NUL is not. withGpgsig splices signature continuation lines after this returns, so those bytes are
735// not re-checked here.
736const headerValue = (value: unknown, what: string): Result<null, BadRequest> =>
737 (typeof value !== 'string' || /[\0\n]/u.test(value) ? fail('bad_request', `${what} must not contain NUL or newline`, { what }) : DONE);
738// The first of (value, what) that is not one header line, in order.
739function headerValues(values: ReadonlyArray<readonly [unknown, string]>): Result<null, BadRequest> {
740 for (const [value, what] of values) {
741 const r = headerValue(value, what);
742 if (!r.ok) return r;
743 }
744 return DONE;
745}
746const messageBody = (message: unknown): Result<null, BadRequest> =>
747 (message !== null && (typeof message !== 'string' || message.includes('\0')) ? fail('bad_request', 'message must not contain NUL', { what: 'message' }) : DONE);
749// Faithful: the message is written verbatim after the blank line; null means no body section. Callers that want
750// git's conventional trailing newline add it themselves (editFile does). parents, committer (the author), encoding,
751// message and extra may be left out. tree and parents are plain strings in, parsed once (parseOid) at encodeCommit.
752export type CommitConfig = {
753 readonly tree: string; readonly parents: readonly string[]; readonly author: string; readonly committer: string;
754 readonly encoding: string | null; readonly message: string | null; readonly extra: readonly string[];
755};
756export type CommitInput = { readonly tree: string; readonly author: string } & Input<Omit<CommitConfig, 'tree' | 'author'>>;
757// The same, the ids parsed: what ply's own writers hold (a built tree, a resolved commit).
758export type CommitIds = { readonly tree: Oid; readonly parents: readonly Oid[]; readonly author: string } & Input<Omit<CommitConfig, 'tree' | 'author' | 'parents'>>;
759// A commit's tree or parent id: 40 hex digits, parsed once (parseOid's refusal, named for the header it would be written
760// in, what `tree` or `parent`). git's fsck reads either case (hash-object keeps the case it was given); git commit-tree
761// writes the id lowercase, and so does ply: an upper-case id is the same object (test/want-oracle.test.js).
762function headerOid(value: string, what: 'tree' | 'parent'): Result<Oid, BadRequest> {
763 const id = parseOid(value.toLowerCase());
764 return id.ok ? id : fail('bad_request', `commit: ${what}: ${id.error.message}`, { what, got: value });
765}
766const COMMIT_FIELDS = ['tree', 'parents', 'author', 'committer', 'encoding', 'extra', 'message'] as const;
767// A commit field read back against the one given: a string or null, or a list of strings, element for element.
768function sameField(back: string | null | readonly string[], given: string | null | readonly string[]): boolean {
769 if (typeof back === 'string' || back === null || typeof given === 'string' || given === null) return back === given;
770 return back.length === given.length && back.every((line, i) => line === given[i]);
771}
772export function encodeCommitOf({ tree, parents, author, committer = author, encoding = null, message = null, extra = [] }: CommitIds): Result<Uint8Array<ArrayBuffer>, BadRequest> {
773 const values: Array<readonly [unknown, string]> = [[author, 'author'], [committer, 'committer']];
774 if (encoding !== null) values.push([encoding, 'encoding']);
775 for (const line of extra) values.push([line, 'extra']);
776 const headed = headerValues(values);
777 if (!headed.ok) return headed;
778 const body = messageBody(message);
779 if (!body.ok) return body;
780 const lines = [
781 `${COMMIT_HEADER_TREE} ${tree}`,
782 ...parents.map(p => `${COMMIT_HEADER_PARENT} ${p}`),
783 `${COMMIT_HEADER_AUTHOR} ${author}`,
784 `${COMMIT_HEADER_COMMITTER} ${committer}`,
785 ];
786 if (encoding !== null) lines.push(`${COMMIT_HEADER_ENCODING} ${encoding}`);
787 lines.push(...extra);
788 const bytes = encodeBytes(`${lines.join('\n')}\n${message === null ? '' : `\n${message}`}`, 'commit');
789 if (!bytes.ok) return bytes;
790 // Held to the reader, as encodeTag is: what parseCommit refuses (an ident fsck refuses, an extra line that shadows
791 // tree, parent, author, committer or encoding) is the caller's bad request, and so is a commit that would read back
792 // as another one (an empty extra line ends the header; an `encoding ` extra line is the encoding). The parent bound
793 // is the reader's own choice, so it is not applied here. Every message below is fixed text.
794 const parsed = parseCommit(bytes.value, parents.length > DEFAULT_LIMITS.maxCommitParents ? { maxCommitParents: parents.length } : DEFAULT_LIMITS);
795 if (!parsed.ok) return fail('bad_request', parsed.error.message, { what: 'commit' });
796 const back = parsed.value;
797 const given: Commit = { tree, parents: [...parents], author, committer, encoding, extra: [...extra], message };
798 for (const field of COMMIT_FIELDS) {
799 if (!sameField(back[field], given[field])) return fail('bad_request', `commit: ${field} would not read back as given`, { what: field });
800 }
801 return bytes;
802}
804// A caller's commit, its ids parsed once: the tree and parent header values are checked first (a NUL or newline is that
805// refusal, as before), then the tree id, then each parent's in order, then the rest (encodeCommitOf).
806export function encodeCommit(input: CommitInput): Result<Uint8Array<ArrayBuffer>, BadRequest> {
807 const { tree, parents = [] } = input;
808 const headed = headerValues([[tree, 'tree'], ...parents.map((p): readonly [unknown, string] => [p, 'parent'])]);
809 if (!headed.ok) return headed;
810 const treeId = headerOid(tree, 'tree');
811 if (!treeId.ok) return treeId;
812 const parentIds: Oid[] = [];
813 for (const p of parents) {
814 const id = headerOid(p, 'parent');
815 if (!id.ok) return id;
816 parentIds.push(id.value);
817 }
818 return encodeCommitOf({ ...input, tree: treeId.value, parents: parentIds });
819}
821// The four types a tag can name (git's type_from_string_gently: object_type_strings, nothing else).
822export type TagTargetType = keyof typeof TYPE_ID;
823// An annotated tag: `tag` is the short name (`v1`, not `refs/tags/v1`); `tagger` an ident line (ident(validateIdent(…))).
824// message and extra may be left out.
825export type TagConfig = {
826 readonly object: string; readonly type: TagTargetType; readonly tag: string; readonly tagger: string;
827 readonly message: string | null; readonly extra: readonly string[];
828};
829export type TagInput = Pick<TagConfig, 'object' | 'type' | 'tag' | 'tagger'> & Input<Pick<TagConfig, 'message' | 'extra'>>;
830// git's annotated-tag object bytes (`git tag -a`, `git mktag`): object, type, tag and tagger lines, the extra header
831// lines, then a blank line and the message verbatim (null: no body section; git's own tags end the message with a
832// newline, which the caller adds). A signature is part of the message, as `git tag -s` appends its armored block to
833// the body. Refuses (bad_request) what `git hash-object -t tag` refuses, which is fsck_tag_standalone with every
834// message an error: a bad object id, a type outside the four, a tag name that is not a refname under refs/tags/
835// (check_refname_format), a bad tagger ident; and a NUL or newline in a header value or a NUL in the message. So the
836// bytes hash (hashObject('tag', …)) to an object git stores as is.
837export function encodeTag({ object, type, tag, tagger, message = null, extra = [] }: TagInput): Result<Uint8Array<ArrayBuffer>, BadRequest> {
838 const values: Array<readonly [unknown, string]> = [[object, 'object'], [type, 'type'], [tag, 'tag'], [tagger, 'tagger']];
839 for (const line of extra) values.push([line, 'extra']);
840 const headed = headerValues(values);
841 if (!headed.ok) return headed;
842 const body = messageBody(message);
843 if (!body.ok) return body;
844 const lines = [
845 `${TAG_HEADER_OBJECT} ${object}`, `${TAG_HEADER_TYPE} ${type}`, `${TAG_HEADER_TAG} ${tag}`, `${TAG_HEADER_TAGGER} ${tagger}`,
846 ...extra,
847 ];
848 const bytes = encodeBytes(`${lines.join('\n')}\n${message === null ? '' : `\n${message}`}`, 'tag');
849 if (!bytes.ok) return bytes;
850 // fsck_tag_standalone's badTagName is check_refname_format("refs/tags/<tag>", 0), validateRef's rule; the rest
851 // (badObjectSha1, badType, the tagger's fsck_ident) is parseTag's. Either refusal is the caller's bad request.
852 if (!validateRef(`refs/tags/${tag}`).ok) return fail('bad_request', "tag: badTagName: invalid 'tag' name", { what: 'tag' });
853 const parsed = parseTag(bytes.value);
854 if (!parsed.ok) return fail('bad_request', parsed.error.message, { what: 'tag' });
855 return bytes;
856}
Diagnostics6 git calls · 211 ms
CallStatusSizeTime0211 ms
discover200191 B2 ms
git.upload-pack discover http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=1 git.response.bytes=191 git.server.agent=git/github-9922ec520325-Linux git.server.object_format=sha1 git.server.caps=agent ls-refs fetch server-option object-format git.server.fetch=shallow wait-for-done filter git.protocol.version=2 git.pkt.frames=9 git.pkt.data=7 git.pkt.flush=2 git.pkt.delim=0 git.pkt.bytes=191 git.pkt.payload.max=36
ls-refs20012 KiB · hit1 ms
git.upload-pack ls-refs http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=1 git.response.bytes=11990 git.response.cache=HIT git.response.duration_ms=1 git.protocol.version=2 git.pkt.frames=152 git.pkt.data=151 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=11990 git.pkt.payload.max=122 git.ls_refs.count=151 git.ls_refs.head=refs/heads/main
fetchtree:0 · deepen 102004.2 KiB · hit1 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=4347 git.response.cache=HIT git.response.duration_ms=1 git.fetch.filter=tree:0 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=7 git.pkt.data=5 git.pkt.flush=1 git.pkt.delim=1 git.pkt.bytes=4347 git.pkt.payload.max=4247 git.sideband.band1.bytes=4247 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=10 git.pack.bytes=4247 git.pack.ofs_delta=0 git.pack.ref_delta=0 git.pack.chain.max=0 git.pack.trailer=a6caf8e129bea82c9bae4cbc7c130c9205add400 git.pack.full=10Open pack map
fetchtree:0200919 B · 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=919 git.response.cache=HIT git.response.duration_ms=2 git.fetch.filter=tree:0 git.fetch.wants=800d30ba8923860bfc460ca884b7f9ba22083588 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=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=919 git.pkt.payload.max=892 git.sideband.band1.bytes=892 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=1 git.pack.bytes=892 git.pack.trailer=5323b9266eea5ded637285d1c5320699f12be76eOpen pack map
fetchtree:02002.4 KiB · hit2 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=204 git.response.bytes=2507 git.response.cache=HIT git.response.duration_ms=2 git.fetch.filter=tree:0 git.fetch.wants=8f720d29ff85ce682ffdad9c393b04a3834c3203 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=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=2507 git.pkt.payload.max=2480 git.sideband.band1.bytes=2480 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=1 git.pack.bytes=2480 git.pack.trailer=723b6bf1d4d6021fe5eb940c622b9ff00ee4a381Open pack map
fetch20016 KiB204 ms
git.upload-pack fetch http.response.status_code=200 git.response.bytes=16603 git.response.cache=MISS git.response.duration_ms=204 git.fetch.wants=332c8d600a8336acabd3d752334b07b4093574a2 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=5 git.pkt.data=4 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=16603 git.pkt.payload.max=16384 git.sideband.band1.bytes=16571 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://github.com/ivarvong/ply
- Ref
- refs/heads/main
- Commit
- 19912563f540228593df0c489082e5e2508e21e4
- cf-ray
- a5e0f82508c1332c
- Request
- c963cb97…
- Protocol
- v2 · sha1
- Agent
- git/github-9922ec520325-Linux
- Filter
- advertised
- Fetch
- shallow wait-for-done filter
- Capabilities
- agent ls-refs fetch server-option object-format