Artifactspublic-v0

ply

main
ply4 git calls438 ms47 KiB2 cachedprotocol v2
403 lines27 KiBRaw
1// Saved pack index (#260): a pack's index (scanPackIndex, #236) and its resolved columns (resolvePackRange, #248) as
2// bytes, so a resumed transfer step (#238) reads them back instead of scanning and resolving the spooled pack again.
3// For a 1.09 GB Artifacts pack the rescan is ~111 s in a Worker; the saved form is ~190 KB. Storage stays the caller's
4// (an object store, a file, memory): ply gives bytes out and takes bytes in.
5//
6// Format, version 1, little-endian throughout:
7// header (64 B) magic "PLYI", version u16, flags u16 (1 oids, 2 refs, 4 resolved), the pack's version u32, its
8// header count u32, entries u32, the pack's length f64, its trailer (20 B), resolved entries u32 (0
9// without them), 12 reserved zero bytes
10// index offset f64, compressed f64, size f64, baseIndex i32, headerBytes u8, storedType u8, type u8 per
11// entry (31 B); the whole-object ids (20 B per entry) with flag 1; the REF base ids (20 B) with flag 2
12// resolved (flag 4) size f64, base i32, depth i32, oid 20 B, type u8 per entry (37 B); the run's stats, 9 f64
13// check (20 B) SHA-1 of everything before it
14// Bytes per entry: 31, +20 with oids (the default), +20 when the pack has a REF_DELTA, +37 with resolved columns; a
15// REF-only pack (what Artifacts sends) with resolved columns is 108 B per entry, plus 64 + 72 + 20 B.
16//
17// Decoding refuses, as a SavedIndexRefusal: bytes that are not a saved index, another version, a length the header does
18// not give (truncated), a check that does not match (corrupt), an index of another pack (the caller's expected
19// trailer and length: a stale index is never used), and columns no scan plus resolve could produce (malformed: entries
20// not contiguous from the pack header to the trailer, a type or base out of range, a REF delta's base that is not the
21// whole object its REF id names (where the index carries ids) or any base at all (where it carries none: a scan
22// without ids finds no REF base), resolved columns the index
23// contradicts or whose bases do not form chains ending at a whole object or a thin base: see checkResolved).
24// loadTransferPack (transferload.ts) turns any refusal into a fresh scan and says why on its span.
25import type { PlyError } from './errors.js';
26import { fail } from './errors.js';
27import { isArgObject } from './absent.js';
28import type { Option, Result } from './result.js';
29import { ok, err, some, none, isSome, assertNever } from './result.js';
30import type { RangeSource, Halt, Halted } from './rangesource.js';
31import { UNCANCELLABLE, HALTED, haltOn, drop, cancelRange, cancelLate, aborted } from './rangesource.js';
32import type { ScannedPack, ScanColumns } from './packscanindex.js';
33import { scannedPackOf, SCAN_INDEX_ENTRY_BYTES } from './packscanindex.js';
34import type { ResolvedIndex, ResolvedColumns, ResolveStats } from './packrangeresolve.js';
35import { resolvedIndexOf, NO_BASE, THIN_BASE } from './packrangeresolve.js';
36import { DEFAULT_LIMITS } from './limits.js';
37import { Sha1, toHex, fromHex } from './sha1.js';
38import { OID_BYTES, OBJ_COMMIT, OBJ_TREE, OBJ_BLOB, OBJ_TAG, OBJ_OFS_DELTA, OBJ_REF_DELTA, PACK_TRAILER_BYTES } from './format.js';
40export const SAVED_INDEX_VERSION = 1;
41const MAGIC = [0x50, 0x4c, 0x59, 0x49];
42const HEADER = 64;
43const CHECK = 20;
44const FLAG_OIDS = 1;
45const FLAG_REFS = 2;
46const FLAG_RESOLVED = 4;
47const FLAGS_KNOWN = FLAG_OIDS | FLAG_REFS | FLAG_RESOLVED;
48// pack header "PACK" + version + count: the first entry's offset
49const PACK_HEADER_BYTES = 12;
50const RESOLVED_BYTES = 37;
51const STATS: ReadonlyArray<keyof ResolveStats> = ['inflated', 'applied', 'reads', 'readBytes', 'cacheHits', 'rebuilt', 'thinBases', 'work', 'workMax'];
52const STATS_BYTES = STATS.length * 8;
53export const SAVED_INDEX_ENTRY_BYTES: Readonly<{ index: number; oid: number; ref: number; resolved: number }> = Object.freeze({ index: SCAN_INDEX_ENTRY_BYTES, oid: OID_BYTES, ref: OID_BYTES, resolved: RESOLVED_BYTES });
54export const SAVED_INDEX_FIXED_BYTES: number = HEADER + STATS_BYTES + CHECK;
56// What a saved index must be the index of: the pack's trailer (40 hex) and its length in bytes.
57export type PackIdentity = { readonly trailer: string; readonly bytes: number };
58export type SavedIndex = { readonly pack: ScannedPack; readonly resolved: Option<ResolvedIndex> };
59export type SavedIndexRefusal =
60 | { readonly tag: 'not_saved_index' }
61 | { readonly tag: 'version'; readonly version: number }
62 | { readonly tag: 'truncated'; readonly bytes: number; readonly want: number }
63 | { readonly tag: 'corrupt' }
64 | { readonly tag: 'other_pack'; readonly saved: PackIdentity; readonly want: PackIdentity }
65 | { readonly tag: 'malformed'; readonly field: string; readonly index: number }
66 | { readonly tag: 'limit_exceeded'; readonly what: 'pack objects'; readonly got: number; readonly max: number }
67 // decodeSavedIndex's own arguments of the wrong shape (#296): `bytes` not a Uint8Array, `want` not an object. A
68 // tag like every other refusal, so the error stays one union a caller switches on by `tag` (README, #301-3).
69 | { readonly tag: 'bad_argument'; readonly what: 'bytes' | 'want' };
71const refused = (r: SavedIndexRefusal): Result<never, SavedIndexRefusal> => err(r);
72const malformed = (field: string, index = -1): Result<never, SavedIndexRefusal> => refused({ tag: 'malformed', field, index });
73const isWhole = (t: number): boolean => t === OBJ_COMMIT || t === OBJ_TREE || t === OBJ_BLOB || t === OBJ_TAG;
74const isStored = (t: number): boolean => isWhole(t) || t === OBJ_OFS_DELTA || t === OBJ_REF_DELTA;
76// At most `max` bytes are waited for: a range that serves more is cancelled there, and what was read (more than `max`)
77// is the caller's refusal to make. Each read is raced against the halt (rangesource.ts).
78async function readAll(stream: ReadableStream<Uint8Array>, max: number, halt: Halt): Promise<Uint8Array | Halted> {
79 const parts: Uint8Array[] = [];
80 let n = 0;
81 const reader = stream.getReader();
82 halt.reading(reader);
83 for (;;) {
84 // oxlint-disable-next-line no-await-in-loop -- one stream, read in order
85 const r = await halt.race(reader.read(), drop);
86 if (r === HALTED) return HALTED;
87 if (r.done) break;
88 parts.push(r.value);
89 n += r.value.length;
90 if (n > max) { cancelRange(reader, null); break; }
91 }
92 halt.reading(null);
93 const out = new Uint8Array(n);
94 let at = 0;
95 for (const p of parts) { out.set(p, at); at += p.length; }
96 return out;
98// The spool's identity: its length and its last 20 bytes, read through the source. `signal` aborts the read: the call
99// settles `aborted` at once even when the source never answers.
100export async function packIdentity(source: RangeSource, signal: AbortSignal = UNCANCELLABLE): Promise<Result<PackIdentity, PlyError>> {
101 // aborted before the call: nothing is asked of the storage, not even a range to cancel
102 if (signal.aborted) return err(aborted('pack identity'));
103 if (!Number.isSafeInteger(source.size) || source.size < 32) return fail('bad_request', `saved index: a spool of ${source.size} bytes holds no pack`, { what: 'spool' });
104 const halt = haltOn(signal);
105 try {
106 const got = await halt.race(source.read(source.size - PACK_TRAILER_BYTES, PACK_TRAILER_BYTES, halt.signal), cancelLate);
107 if (got === HALTED) return err(aborted('pack identity'));
108 if (!got.ok) return got;
109 const tail = await readAll(got.value, PACK_TRAILER_BYTES, halt);
110 if (tail === HALTED) return err(aborted('pack identity'));
111 if (tail.length !== PACK_TRAILER_BYTES) return fail('bad_request', `saved index: the spool's last ${PACK_TRAILER_BYTES} bytes read back as ${tail.length}`, { what: 'spool' });
112 return ok({ trailer: toHex(tail), bytes: source.size });
113 } finally {
114 halt.release();
115 }
118// A refusal in words, for a span or a log line.
119export function describeRefusal(r: SavedIndexRefusal): string {
120 switch (r.tag) {
121 case 'not_saved_index': return 'not a saved pack index';
122 case 'version': return `saved index version ${r.version}, this ply reads ${SAVED_INDEX_VERSION}`;
123 case 'truncated': return `saved index is ${r.bytes} bytes, its header gives ${r.want}`;
124 case 'corrupt': return 'saved index check does not match its bytes';
125 case 'other_pack': return `saved index is of pack ${r.saved.trailer} (${r.saved.bytes} B), not ${r.want.trailer} (${r.want.bytes} B)`;
126 case 'limit_exceeded': return `saved index has ${r.got} entries by its header, over limits.maxPackObjects ${r.max}`;
127 case 'malformed': return `saved index ${r.field} is not one a scan gives${r.index >= 0 ? ` (entry ${r.index})` : ''}`;
128 case 'bad_argument': return r.what === 'bytes' ? 'decodeSavedIndex: bytes must be a Uint8Array' : 'decodeSavedIndex: want must be an object';
129 }
130 // Stryker disable next-line ConditionalExpression,BlockStatement,CallExpression: unreachable, the compiler's exhaustiveness check
131 return assertNever(r);
134type Layout = { readonly n: number; readonly flags: number; readonly total: number };
135const layoutOf = (n: number, flags: number): Layout => {
136 const per = SCAN_INDEX_ENTRY_BYTES + ((flags & FLAG_OIDS) === 0 ? 0 : OID_BYTES) + ((flags & FLAG_REFS) === 0 ? 0 : OID_BYTES) + ((flags & FLAG_RESOLVED) === 0 ? 0 : RESOLVED_BYTES);
137 return { n, flags, total: HEADER + n * per + ((flags & FLAG_RESOLVED) === 0 ? 0 : STATS_BYTES) + CHECK };
138};
140// A cursor over one buffer: each put/get moves it on.
141type Cursor = { readonly bytes: Uint8Array; readonly view: DataView; at: number };
142const cursorOf = (bytes: Uint8Array): Cursor => ({ bytes, view: new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength), at: 0 });
143function putF64s(c: Cursor, col: Float64Array): void { for (const v of col) { c.view.setFloat64(c.at, v, true); c.at += 8; } }
144function putI32s(c: Cursor, col: Int32Array): void { for (const v of col) { c.view.setInt32(c.at, v, true); c.at += 4; } }
145function putBytes(c: Cursor, b: Uint8Array): void { c.bytes.set(b, c.at); c.at += b.length; }
146// Decoded columns are views into the saved bytes where the platform allows (#299): byte columns always, number columns
147// on a little-endian platform where the column is aligned in its buffer; otherwise a copy. The decoded index then holds
148// one copy of the columns, not the saved bytes plus a second one, and a Node Buffer behaves as any Uint8Array.
149const LITTLE_ENDIAN = new Uint8Array(new Uint16Array([1]).buffer)[0] === 1;
150function getF64s(c: Cursor, n: number): Float64Array {
151 const at = c.bytes.byteOffset + c.at;
152 if (LITTLE_ENDIAN && at % 8 === 0) { c.at += n * 8; return new Float64Array(c.bytes.buffer, at, n); }
153 const out = new Float64Array(n); for (let i = 0; i < n; i++) { out[i] = c.view.getFloat64(c.at, true); c.at += 8; } return out;
155function getI32s(c: Cursor, n: number): Int32Array {
156 const at = c.bytes.byteOffset + c.at;
157 if (LITTLE_ENDIAN && at % 4 === 0) { c.at += n * 4; return new Int32Array(c.bytes.buffer, at, n); }
158 const out = new Int32Array(n); for (let i = 0; i < n; i++) { out[i] = c.view.getInt32(c.at, true); c.at += 4; } return out;
160function getBytes(c: Cursor, n: number): Uint8Array { const out = c.bytes.subarray(c.at, c.at + n); c.at += n; return out; }
162// `pack` (complete: every entry the header counts) and, when given, its resolved columns, as bytes (see the top).
163export function encodeSavedIndex(pack: ScannedPack, resolved: Option<ResolvedIndex>): Result<Uint8Array, PlyError> {
164 const cols = pack.columns;
165 const n = cols.offset.length;
166 if (n !== pack.count) return fail('bad_request', `saved index: the index holds ${n} of the pack's ${pack.count} entries`, { what: 'pack' });
167 if (!/^[0-9a-f]{40}$/u.test(pack.trailer)) return fail('bad_request', 'saved index: the index has no trailer', { what: 'pack' });
168 if (isSome(resolved) && resolved.value.count !== n) return fail('bad_request', `saved index: ${resolved.value.count} resolved entries for ${n} in the index`, { what: 'resolved' });
169 const oids = cols.oids.length === n * OID_BYTES && n > 0;
170 const refs = cols.refs.length === n * OID_BYTES && n > 0;
171 const flags = (oids ? FLAG_OIDS : 0) | (refs ? FLAG_REFS : 0) | (isSome(resolved) ? FLAG_RESOLVED : 0);
172 const { total } = layoutOf(n, flags);
173 const c = cursorOf(new Uint8Array(total));
174 putBytes(c, Uint8Array.from(MAGIC));
175 c.view.setUint16(4, SAVED_INDEX_VERSION, true);
176 c.view.setUint16(6, flags, true);
177 c.view.setUint32(8, pack.version, true);
178 c.view.setUint32(12, pack.count, true);
179 c.view.setUint32(16, n, true);
180 c.view.setFloat64(20, pack.bytes, true);
181 c.bytes.set(fromHex(pack.trailer), 28);
182 c.view.setUint32(48, isSome(resolved) ? n : 0, true);
183 c.at = HEADER;
184 putF64s(c, cols.offset);
185 putF64s(c, cols.compressed);
186 putF64s(c, cols.size);
187 putI32s(c, cols.baseIndex);
188 putBytes(c, cols.headerBytes);
189 putBytes(c, cols.storedType);
190 putBytes(c, cols.type);
191 if (oids) putBytes(c, cols.oids);
192 if (refs) putBytes(c, cols.refs);
193 if (isSome(resolved)) {
194 const r = resolved.value.columns;
195 putF64s(c, r.size);
196 putI32s(c, r.base);
197 putI32s(c, r.depth);
198 putBytes(c, r.oid);
199 putBytes(c, r.type);
200 putF64s(c, Float64Array.from(STATS.map(k => resolved.value.stats[k])));
201 }
202 c.bytes.set(new Sha1().update(c.bytes.subarray(0, c.at)).digest(), c.at);
203 return ok(c.bytes);
206type Header = { readonly flags: number; readonly version: number; readonly count: number; readonly n: number; readonly bytes: number; readonly trailer: string; readonly resolvedN: number };
207function readHeader(bytes: Uint8Array, maxObjects: number): Result<Header, SavedIndexRefusal> {
208 if (bytes.length < HEADER + CHECK) return MAGIC.every((m, i) => i >= bytes.length || bytes[i] === m) ? refused({ tag: 'truncated', bytes: bytes.length, want: HEADER + CHECK }) : refused({ tag: 'not_saved_index' });
209 if (!MAGIC.every((m, i) => bytes[i] === m)) return refused({ tag: 'not_saved_index' });
210 const v = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
211 const version = v.getUint16(4, true);
212 if (version !== SAVED_INDEX_VERSION) return refused({ tag: 'version', version });
213 const flags = v.getUint16(6, true);
214 const n = v.getUint32(16, true);
215 const want = layoutOf(n, flags & FLAGS_KNOWN).total;
216 // the scan's own cap (maxPackObjects on the header count, packstream.ts), so a saved index is never bigger than one a
217 // scan under the same limits builds; the limit as the caller passed it, as maxDeltaChain below: NaN is within nothing
218 const within = n <= maxObjects;
219 if (!within) return refused({ tag: 'limit_exceeded', what: 'pack objects', got: n, max: maxObjects });
220 if (bytes.length < want) return refused({ tag: 'truncated', bytes: bytes.length, want });
221 const body = bytes.subarray(0, bytes.length - CHECK);
222 if (toHex(new Sha1().update(body).digest()) !== toHex(bytes.subarray(bytes.length - CHECK))) return refused({ tag: 'corrupt' });
223 if (bytes.length !== want) return malformed('length');
224 if ((flags & ~FLAGS_KNOWN) !== 0) return malformed('flags');
225 if (!bytes.subarray(52, HEADER).every(b => b === 0)) return malformed('reserved');
226 return ok({ flags, version: v.getUint32(8, true), count: v.getUint32(12, true), n, bytes: v.getFloat64(20, true), trailer: toHex(bytes.subarray(28, 48)), resolvedN: v.getUint32(48, true) });
229// Where each column starts, in a buffer whose header says `n` entries and `flags`.
230type Regions = { readonly offset: number; readonly compressed: number; readonly size: number; readonly baseIndex: number; readonly headerBytes: number; readonly storedType: number; readonly type: number; readonly oids: number; readonly refs: number; readonly resolved: number };
231function regionsOf(n: number, flags: number): Regions {
232 const offset = HEADER;
233 const compressed = offset + n * 8;
234 const size = compressed + n * 8;
235 const baseIndex = size + n * 8;
236 const headerBytes = baseIndex + n * 4;
237 const storedType = headerBytes + n;
238 const type = storedType + n;
239 const oids = type + n;
240 const refs = oids + ((flags & FLAG_OIDS) === 0 ? 0 : n * OID_BYTES);
241 const resolved = refs + ((flags & FLAG_REFS) === 0 ? 0 : n * OID_BYTES);
242 return { offset, compressed, size, baseIndex, headerBytes, storedType, type, oids, refs, resolved };
245// Entry i's columns read from the buffer: where it ends, or the field no scan gives.
246type EntryCheck = { readonly tag: 'end'; readonly end: number; readonly ref: boolean } | { readonly tag: 'bad'; readonly field: string };
247const bad = (field: string): EntryCheck => ({ tag: 'bad', field });
248// Two 20-byte ids in the buffer, compared as five 32-bit words (the same bytes; a quarter of the reads).
249function sameId(v: DataView, a: number, b: number): boolean {
250 for (let k = 0; k < OID_BYTES; k += 4) if (v.getUint32(a + k) !== v.getUint32(b + k)) return false;
251 return true;
253// A REF delta's scan base: none (-1: the scan found no whole object with the delta's REF id), or a whole object in the
254// pack, and where the index carries both ids the one whose id the delta names: the scan finds a REF base by id and no
255// other way. So an index without ids has none: a base recorded there is refused, there is no id to hold it to. With
256// the ids flag and no REF ids the columns are not compared here; checkIndex refuses those flags.
257const IDS_AND_REFS = FLAG_OIDS | FLAG_REFS;
258function refBaseOk(v: DataView, h: Header, at: Regions, i: number, base: number): boolean {
259 if (base === -1) return true;
260 if (base < -1 || base >= h.n || (h.flags & FLAG_OIDS) === 0 || !isWhole(v.getUint8(at.storedType + base))) return false;
261 return (h.flags & IDS_AND_REFS) !== IDS_AND_REFS || sameId(v, at.oids + base * OID_BYTES, at.refs + i * OID_BYTES);
263function checkEntry(v: DataView, h: Header, at: Regions, i: number, start: number): EntryCheck {
264 const storedOf = (k: number): number => v.getUint8(at.storedType + k);
265 const typeOf = (k: number): number => v.getUint8(at.type + k);
266 const comp = v.getFloat64(at.compressed + i * 8, true);
267 const size = v.getFloat64(at.size + i * 8, true);
268 const base = v.getInt32(at.baseIndex + i * 4, true);
269 const headerBytes = v.getUint8(at.headerBytes + i);
270 const stored = storedOf(i);
271 const type = typeOf(i);
272 if (v.getFloat64(at.offset + i * 8, true) !== start) return bad('offset');
273 if (!Number.isSafeInteger(comp) || comp < 2 || !Number.isSafeInteger(size) || size < 0 || headerBytes < 1) return bad('size');
274 if (!isStored(stored)) return bad('storedType');
275 const end: EntryCheck = { tag: 'end', end: start + headerBytes + comp, ref: stored === OBJ_REF_DELTA };
276 if (isWhole(stored)) return type === stored && base === -1 ? end : bad('type');
277 const baseOk = stored === OBJ_OFS_DELTA ? base >= 0 && base < i : refBaseOk(v, h, at, i, base);
278 if (!baseOk) return bad('baseIndex');
279 return type === (base < 0 ? 0 : typeOf(base)) ? end : bad('type');
281// Every entry where the previous ended, from the pack header to the trailer; each type and base where a scan puts it.
282function checkIndex(v: DataView, h: Header, at: Regions): Result<true, SavedIndexRefusal> {
283 if (h.n !== h.count || !Number.isSafeInteger(h.bytes)) return malformed('count');
284 let end = PACK_HEADER_BYTES;
285 let anyRef = false;
286 for (let i = 0; i < h.n; i++) {
287 const e = checkEntry(v, h, at, i, end);
288 if (e.tag === 'bad') return malformed(e.field, i);
289 end = e.end;
290 anyRef = anyRef || e.ref;
291 }
292 if (end !== h.bytes - PACK_TRAILER_BYTES) return malformed('offset', h.n);
293 return anyRef === ((h.flags & FLAG_REFS) !== 0) ? ok(true) : malformed('flags');
295// Resolved columns, held to the index beside them (already checked) in one pass: what resolvePackRange gives for it.
296// whole object no base, depth 0, the scan's type and size, and the scan's id when the index has ids
297// OFS_DELTA the base is the scan's baseIndex
298// REF_DELTA the base is an entry whose resolved id is the delta's REF id, or THIN_BASE where the scan found no
299// whole object with that id in the pack
300// any delta depth = its base's depth + 1 (1 on a thin base), at most `maxChain`; the type of its base
301// The depth rule is what makes the base column a forest: along a chain depth falls by one per link, so a cycle of k
302// links would need depth = depth + k. Every chain therefore ends at a whole object or a thin base, within maxChain links.
303// Not checked, because only a resolve can: a delta's id and size, the type under a thin base, and that a THIN_BASE
304// delta's base is not some other delta in the pack. A lie there changes which objects a push names, not how much ply
305// does: the receiver indexes the pushed pack itself and refuses a base it does not have, an object the pushed commit
306// reaches but the pack lacks, or a tree pushed before its blobs, and the transfer fails definitely.
307type ResolvedAt = { readonly size: number; readonly base: number; readonly depth: number; readonly oid: number; readonly type: number; readonly stats: number };
308type ResolvedRow = { readonly i: number; readonly base: number; readonly depth: number; readonly size: number; readonly type: number; readonly stored: number };
309// A whole object's row: the field that is not the scan's, or null.
310function wholeBad(v: DataView, h: Header, at: Regions, r: ResolvedAt, e: ResolvedRow): string | null {
311 if (e.base !== NO_BASE) return 'resolved.base';
312 if (e.depth !== 0) return 'resolved.depth';
313 if (e.type !== e.stored) return 'resolved.type';
314 if (e.size !== v.getFloat64(at.size + e.i * 8, true)) return 'resolved.size';
315 const ids = (h.flags & FLAG_OIDS) !== 0;
316 return ids && !sameId(v, r.oid + e.i * OID_BYTES, at.oids + e.i * OID_BYTES) ? 'resolved.oid' : null;
318function deltaBaseOk(v: DataView, at: Regions, r: ResolvedAt, e: ResolvedRow): boolean {
319 const scanBase = v.getInt32(at.baseIndex + e.i * 4, true);
320 if (e.stored === OBJ_OFS_DELTA) return e.base === scanBase;
321 if (e.base >= 0) return sameId(v, r.oid + e.base * OID_BYTES, at.refs + e.i * OID_BYTES);
322 return e.base === THIN_BASE && scanBase < 0;
324// A delta's row: the field its base (or the scan) contradicts, or null.
325function deltaBad(v: DataView, at: Regions, r: ResolvedAt, e: ResolvedRow, maxChain: number): string | null {
326 if (!deltaBaseOk(v, at, r, e)) return 'resolved.base';
327 const want = e.base === THIN_BASE ? 1 : v.getInt32(r.depth + e.base * 4, true) + 1;
328 // the limit as the caller passed it (see decodeSavedIndex): NaN is within nothing, every delta is refused
329 const within = e.depth <= maxChain;
330 if (e.depth !== want || !within) return 'resolved.depth';
331 return e.base >= 0 && e.type !== v.getUint8(r.type + e.base) ? 'resolved.type' : null;
333function checkResolved(v: DataView, h: Header, at: Regions, maxChain: number): Result<true, SavedIndexRefusal> {
334 const n = h.n;
335 const r: ResolvedAt = { size: at.resolved, base: at.resolved + n * 8, depth: at.resolved + n * 12, oid: at.resolved + n * 16, type: at.resolved + n * (16 + OID_BYTES), stats: at.resolved + n * RESOLVED_BYTES };
336 for (let i = 0; i < n; i++) {
337 const e: ResolvedRow = { i, base: v.getInt32(r.base + i * 4, true), depth: v.getInt32(r.depth + i * 4, true), size: v.getFloat64(r.size + i * 8, true), type: v.getUint8(r.type + i), stored: v.getUint8(at.storedType + i) };
338 if (!isWhole(e.type)) return malformed('resolved.type', i);
339 if (e.base < THIN_BASE || e.base >= n || e.base === i) return malformed('resolved.base', i);
340 if (!Number.isSafeInteger(e.size) || e.size < 0) return malformed('resolved.size', i);
341 const field = isWhole(e.stored) ? wholeBad(v, h, at, r, e) : deltaBad(v, at, r, e, maxChain);
342 if (field !== null) return malformed(field, i);
343 }
344 const statsAt = r.stats;
345 return STATS.every((_, k) => { const s = v.getFloat64(statsAt + k * 8, true); return Number.isFinite(s) && s >= 0; }) ? ok(true) : malformed('resolved.stats');
347function statsOf(v: DataView, at: number): ResolveStats {
348 const f = (k: number): number => v.getFloat64(at + k * 8, true);
349 return { inflated: f(0), applied: f(1), reads: f(2), readBytes: f(3), cacheHits: f(4), rebuilt: f(5), thinBases: f(6), work: f(7), workMax: f(8) };
352// Saved bytes → the index and, when saved, its resolved columns; refused unless they are an intact saved index of
353// exactly the pack `want` names (see the top of this file). `maxDeltaChain` is the chain limit the caller resolves
354// under, the limits.maxDeltaChain it gives resolvePackRange: resolved columns with a deeper chain are refused
355// (malformed, resolved.depth), as a resolve would refuse the pack. It is the caller's to pass: left out it is the
356// default (64), so an index saved from a pack resolved under a raised limit is refused unless the same limit is passed
357// here. loadTransferPack passes its opts.resolve.limits, parsed. The value is not parsed here: it is the right side of
358// one comparison (depth <= maxDeltaChain), so one JavaScript reads as a number there ('200', 200n, [200], true) acts as
359// that number, and one the comparison is false for (NaN, an object) refuses every delta. `maxPackObjects` (limits,
360// #299; the cap scanPackIndex holds a pack's header count to) refuses, as limit_exceeded, an index whose header counts
361// more entries than it, before the check or any column.
362// The columns returned are views into `bytes` where they can be (see getF64s): keep `bytes` unchanged while the index
363// is in use, as loadTransferPack does (it hands the same bytes back as `saved`).
364export function decodeSavedBytes(bytes: Uint8Array, want: PackIdentity, maxDeltaChain: number, maxPackObjects: number): Result<SavedIndex, SavedIndexRefusal> {
365 const head = readHeader(bytes, maxPackObjects);
366 if (!head.ok) return head;
367 const h = head.value;
368 if (h.trailer !== want.trailer || h.bytes !== want.bytes) return refused({ tag: 'other_pack', saved: { trailer: h.trailer, bytes: h.bytes }, want });
369 const hasResolved = (h.flags & FLAG_RESOLVED) !== 0;
370 if (h.resolvedN !== (hasResolved ? h.n : 0)) return malformed('resolved.count');
371 const n = h.n;
372 const at = regionsOf(n, h.flags);
373 const c = cursorOf(bytes);
374 const checked = checkIndex(c.view, h, at);
375 if (!checked.ok) return checked;
376 if (hasResolved) {
377 const good = checkResolved(c.view, h, at, maxDeltaChain);
378 if (!good.ok) return good;
379 }
380 c.at = HEADER;
381 const offset = getF64s(c, n);
382 const compressed = getF64s(c, n);
383 const size = getF64s(c, n);
384 const baseIndex = getI32s(c, n);
385 const headerBytes = getBytes(c, n);
386 const storedType = getBytes(c, n);
387 const type = getBytes(c, n);
388 const oids = (h.flags & FLAG_OIDS) === 0 ? new Uint8Array(0) : getBytes(c, n * OID_BYTES);
389 const refs = (h.flags & FLAG_REFS) === 0 ? new Uint8Array(0) : getBytes(c, n * OID_BYTES);
390 const columns: ScanColumns = { offset, headerBytes, compressed, size, storedType, type, baseIndex, oids, refs };
391 const pack = scannedPackOf({ version: h.version, count: h.count, trailer: h.trailer, bytes: h.bytes, heldBytes: n * SCAN_INDEX_ENTRY_BYTES + oids.length + refs.length }, columns);
392 if (!hasResolved) return ok({ pack, resolved: none });
393 const r: ResolvedColumns = { size: getF64s(c, n), base: getI32s(c, n), depth: getI32s(c, n), oid: getBytes(c, n * OID_BYTES), type: getBytes(c, n) };
394 return ok({ pack, resolved: some(resolvedIndexOf(r, statsOf(c.view, c.at))) });
397// The public entry: the arguments' shape first (#296: a non-Uint8Array `bytes` or a non-object `want` is the
398// `bad_argument` refusal naming it, not a TypeError). loadTransferPack calls decodeSavedBytes on bytes it checked.
399export function decodeSavedIndex(bytes: Uint8Array, want: PackIdentity, maxDeltaChain: number = DEFAULT_LIMITS.maxDeltaChain, maxPackObjects: number = DEFAULT_LIMITS.maxPackObjects): Result<SavedIndex, SavedIndexRefusal> {
400 if (!(bytes instanceof Uint8Array)) return refused({ tag: 'bad_argument', what: 'bytes' });
401 if (!isArgObject(want)) return refused({ tag: 'bad_argument', what: 'want' });
402 return decodeSavedBytes(bytes, want, maxDeltaChain, maxPackObjects);
Diagnostics4 git calls · 438 ms
CallStatusSizeTime0438 ms
discover200152 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
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 · hit8 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=427
git.response.bytes=38434
git.response.cache=HIT
git.response.duration_ms=8
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
fetch2008.7 KiB427 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=8916
git.response.cache=MISS
git.response.duration_ms=427
git.fetch.wants=dce39873eaff1c3c89b8b38eead46a629dd21a0c
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=8916
git.pkt.payload.max=8895
git.sideband.band1.bytes=8894
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
a5e30b1d0cabee28
Request
f6c818d5…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format