GitHubivarvong

ply

main
ply6 git calls264 ms24 KiB4 cachedprotocol v2
181 lines12 KiBRaw
1// Byte helpers.
2import type { ErrorOf } from './errors.js';
3import { fail, plyError } from './errors.js';
4import type { Result } from './result.js';
5import { ok, err } from './result.js';
6import { BYTE_VALUES, PKT_HEX_BASE } from './format.js';
7import { atOr, byteInRange } from './absent.js';
9// The declarations name no DOM-lib global type: a Node consumer (lib ES2022 + @types/node) has `TextEncoder`,
10// `TextDecoder` and `CryptoKey` as values only, so their instance types are derived from the value, which the DOM lib,
11// @types/node and @cloudflare/workers-types all declare (test/dist-types.test.js compiles dist under each).
12type Utf8Encoder = InstanceType<typeof TextEncoder>;
13type Utf8Decoder = InstanceType<typeof TextDecoder>;
14export const te: Utf8Encoder = new TextEncoder();
15// git keeps every byte: a leading U+FEFF is part of a tree entry's name (`git ls-tree` prints it, `show HEAD:README`
16// does not find `<U+FEFF>README`), so no decoder here swallows it the way the default one does (#43). `td` is for text
17// git itself only prints (sideband progress, remote errors): an invalid sequence there becomes U+FFFD.
18export const td: Utf8Decoder = new TextDecoder('utf-8', { ignoreBOM: true });
19const strict = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
21// ---- git bytes as strings, losslessly (#43) ----
22// Names, messages, idents and ref names are bytes to git; it never requires UTF-8 and never interprets a BOM. ply hands
23// them out as strings, so the mapping must be a bijection on bytes: well-formed UTF-8 decodes as UTF-8 (a BOM anywhere
24// stays), and each byte of an ill-formed sequence (Latin-1, an overlong, an encoded surrogate, a truncated or stray
25// continuation byte) becomes the lone surrogate U+DC00 + byte (U+DC80..U+DCFF), which no UTF-8 decode can produce
26// (PEP 383's surrogateescape). `encodeBytes` is the inverse, so a name read from a tree goes back into a tree, a ref,
27// or a commit as the bytes git had. A string `encodeBytes` cannot map back exactly is a typed refusal, never U+FFFD.
28/* oxlint-disable no-magic-numbers -- UTF-8 is Unicode Table 3-7: lead and continuation byte ranges and sequence lengths */
29const LEAD2 = 0xc2;
30const LEAD3 = 0xe0;
31const LEAD4 = 0xf0;
32const LEAD_END = 0xf4;
33const CONT = 0x80;
34const CONT_END = 0xbf;
35const ASCII_END = 0x80;
36const ESCAPE = 0xdc_00;
37const ESCAPE_LO = 0xdc_80;
38const ESCAPE_HI = 0xdc_ff;
39const SUR_LO = 0xd8_00;
40const SUR_HI = 0xdf_ff;
41const HIGH_END = 0xdb_ff;
42// A UTF-16 code unit in [lo, hi]. Past the end of a string charCodeAt is NaN, which is in no range.
43const inRange = (c: number, lo: number, hi: number): boolean => c >= lo && c <= hi;
44// A byte read through absent.ts's checked read (atOr). Past the end is NaN, which every byte comparison here finds in no
45// range: the arithmetic meaning of no byte. Every caller below reads in range.
46const byteOrNaN = (b: Uint8Array, i: number): number => atOr(b, i, Number.NaN);
47// Length of the well-formed UTF-8 sequence at i (Unicode Table 3-7), or 0. `i` is always < b.length (both callers).
48function wellFormedAt(b: Uint8Array, i: number): number {
49 const c = byteOrNaN(b, i);
50 if (c < ASCII_END) return 1;
51 if (c < LEAD2) return 0;
52 if (c < LEAD3) return byteInRange(b, i + 1, CONT, CONT_END) ? 2 : 0;
53 // E0 needs A0..BF (no overlong), ED needs 80..9F (no surrogate); F0 needs 90..BF (no overlong), F4 needs 80..8F (≤ U+10FFFF)
54 if (c < LEAD4) return byteInRange(b, i + 1, c === LEAD3 ? 0xa0 : CONT, c === 0xed ? 0x9f : CONT_END) && byteInRange(b, i + 2, CONT, CONT_END) ? 3 : 0;
55 if (c <= LEAD_END) return byteInRange(b, i + 1, c === LEAD4 ? 0x90 : CONT, c === LEAD_END ? 0x8f : CONT_END) && byteInRange(b, i + 2, CONT, CONT_END) && byteInRange(b, i + 3, CONT, CONT_END) ? 4 : 0;
56 return 0;
59export function decodeBytes(b: Uint8Array): string {
60 // Stryker disable next-line BlockStatement: the fast path; the loop below returns the same string for well-formed bytes
61 try { return strict.decode(b); } catch { /* ill-formed: escape byte by byte below */ }
62 let s = '';
63 let run = 0;
64 let i = 0;
65 while (i < b.length) {
66 const n = wellFormedAt(b, i);
67 if (n) { i += n; continue; }
68 s += strict.decode(b.subarray(run, i)) + String.fromCodePoint(ESCAPE + byteOrNaN(b, i)); // i < b.length (the loop)
69 run = ++i;
70 }
71 return s + strict.decode(b.subarray(run));
74// The byte-array rule: every input is a plain `Uint8Array` (any backing buffer); a function that allocates returns
75// `Uint8Array<ArrayBuffer>`. A Web API typed `BufferSource` (Blob, fetch's body, a stream writer, crypto.subtle) takes
76// only ArrayBuffer-backed views. A view of anything else (a SharedArrayBuffer) is copied into a fresh ArrayBuffer;
77// every ply buffer takes the no-copy branch. The predicate is the narrowing: there is no cast.
78const arrayBufferBacked = (b: Uint8Array): b is Uint8Array<ArrayBuffer> => b.buffer instanceof ArrayBuffer;
79export const bufferSource = (b: Uint8Array): Uint8Array<ArrayBuffer> => (arrayBufferBacked(b) ? b : b.slice());
81export function concat(parts: readonly Uint8Array[]): Uint8Array<ArrayBuffer> {
82 let n = 0;
83 for (const p of parts) n += p.length;
84 const out = new Uint8Array(n);
85 let o = 0;
86 for (const p of parts) { out.set(p, o); o += p.length; }
87 return out;
90export function encodeBytes(s: unknown, what = 'string'): Result<Uint8Array<ArrayBuffer>, ErrorOf<'bad_request'>> {
91 if (typeof s !== 'string') return fail('bad_request', `${what} must be a string`, { what });
92 // Stryker disable next-line ConditionalExpression: the fast path; the loop below writes the same bytes for a well-formed string
93 if (s.isWellFormed()) return ok(te.encode(s));
94 const parts: Uint8Array[] = [];
95 let run = 0;
96 for (let i = 0; i < s.length; i++) {
97 // UTF-16 code units, not code points: the loop looks at each surrogate on its own
98 const c = s.charCodeAt(i); // oxlint-disable-line unicorn/prefer-code-point -- see above
99 if (c < SUR_LO || c > SUR_HI) continue;
100 if (c <= HIGH_END && inRange(s.charCodeAt(i + 1), HIGH_END + 1, SUR_HI)) { i++; continue; } // oxlint-disable-line unicorn/prefer-code-point -- see above
101 if (c < ESCAPE_LO || c > ESCAPE_HI) return fail('bad_request', `${what}: lone surrogate U+${c.toString(16).toUpperCase()} is no byte sequence`, { what });
102 // Stryker disable next-line ArithmeticOperator: c ± 0xDC00 are one byte mod 256 (0xDC00 is a multiple of 256), which is what the array keeps
103 parts.push(te.encode(s.slice(run, i)), Uint8Array.of(c - ESCAPE));
104 run = i + 1;
105 }
106 parts.push(te.encode(s.slice(run)));
107 const bytes = concat(parts);
108 // `\udcc3\udca9` would write C3 A9, which reads back as `é`: two strings, one byte sequence. Refuse the spelling no read returns.
109 if (decodeBytes(bytes) !== s) return fail('bad_request', `${what}: escaped bytes spell well-formed UTF-8; pass the characters`, { what });
110 return ok(bytes);
113// Text that arrives in pieces (sideband band 2): a sequence cut by a frame boundary waits in `carry` for its
114// tail instead of decoding as two U+FFFD. Pure: returns { text, carry }.
115export function decodeChunk(carry: Uint8Array, chunk: Uint8Array): { text: string; carry: Uint8Array } {
116 // Stryker disable next-line ConditionalExpression,EqualityOperator: concat of an empty carry is a copy of the chunk, the same bytes
117 const buf = carry.length > 0 ? concat([carry, chunk]) : chunk;
118 let cut = buf.length;
119 // Stryker disable next-line ConditionalExpression,LogicalOperator: past k = 3 a lead needs at most 4 ≤ k bytes (no cut), and past the start a read is no byte (neither branch)
120 for (let k = 1; k <= 3 && k <= buf.length; k++) {
121 const c = byteOrNaN(buf, buf.length - k); // k <= buf.length (the loop)
122 if (c < ASCII_END) break;
123 // the lead byte's sequence length (Table 3-7) in one expression, as git-facing hot paths keep it small
124 // oxlint-disable-next-line no-nested-ternary -- see above
125 if (c >= LEAD2) { if (k < (c >= LEAD4 ? 4 : c >= LEAD3 ? 3 : 2)) cut = buf.length - k; break; }
126 }
127 return { text: td.decode(buf.subarray(0, cut)), carry: buf.slice(cut) };
129/* oxlint-enable no-magic-numbers */
131/**
132 * Bounded read. `subarray` / `slice` clamp a range that runs past the end and return a short view; parsers that
133 * trusted that view accepted truncated fields (the tree-oid off-by-one). `take` returns the typed short read
134 * instead, so the length is the bound. The error carries `reason: 'short_read'`: a stream parser that may get more
135 * bytes switches on that, never on the message (#76). No buffer (null, or a JavaScript caller's missing argument) is a
136 * short read of an empty one.
137 */
138export type ShortReadCode = 'pack_corrupt' | 'protocol';
139const shortReadMessage = (off: number, n: number, have: number): string => `short read: need ${n} bytes at ${off}, have ${have}`;
140// The short-read error itself, for a parser that reads byte by byte without a take() per byte.
141export const shortRead = <C extends ShortReadCode>(code: C, off: number, n: number, have: number): ErrorOf<C> =>
142 // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- plyError's member for C; the compiler cannot resolve Payload<C> for a type parameter
143 plyError<ShortReadCode>(code, shortReadMessage(off, n, have), { reason: 'short_read' }) as ErrorOf<C>;
144// A buffer is an object. Null and a JavaScript caller's missing argument are not (typeof), so neither is read.
145const isBuffer = (buf: Uint8Array | null): buf is Uint8Array => typeof buf === 'object' && buf !== null;
146const haveOf = (buf: Uint8Array | null): number => (isBuffer(buf) ? buf.length : 0);
147const inBounds = (buf: Uint8Array | null, off: number, n: number): buf is Uint8Array =>
148 isBuffer(buf) && Number.isInteger(off) && Number.isInteger(n) && off >= 0 && n >= 0 && off + n <= buf.length;
149// an omitted code is C's default, 'pack_corrupt'; the compiler cannot tie a default value to a type parameter
150// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- see above
151export function take<C extends ShortReadCode = 'pack_corrupt'>(buf: Uint8Array | null, off: number, n: number, code: C = 'pack_corrupt' as C): Result<Uint8Array, ErrorOf<C>> {
152 return inBounds(buf, off, n) ? ok(buf.subarray(off, off + n)) : err(shortRead(code, off, n, haveOf(buf)));
155// Hex digit value of each byte value, either case; -1 for a byte that is not a hex digit. The one hex table: the
156// pkt-line length reader and fromHex (sha1.ts) read it.
157// oxlint-disable-next-line no-magic-numbers -- sentinel: this byte is not a hex digit
158export const HEXV: Int8Array = new Int8Array(BYTE_VALUES).fill(-1);
159// ASCII digits: a code unit is the code point
160// Stryker disable next-line EqualityOperator: one more pass reads charCodeAt(16), NaN, and a typed array ignores a NaN key
161for (let i = 0; i < PKT_HEX_BASE; i++) { HEXV['0123456789abcdef'.charCodeAt(i)] = i; HEXV['0123456789ABCDEF'.charCodeAt(i)] = i; } // oxlint-disable-line unicorn/prefer-code-point -- see above
163// First index of needle in hay at or after from; -1 if none.
164export function indexOfBytes(hay: Uint8Array, needle: Uint8Array, from = 0): number {
165 const n = needle.length;
166 if (n === 0) return from;
167 const first = needle[0];
168 // Stryker disable next-line ArithmeticOperator: an end index past hay only reads past the end, which is never a needle byte
169 const last = hay.length - n;
170 outer: for (let i = from; i <= last; i++) {
171 if (hay[i] !== first) continue;
172 for (let j = 1; j < n; j++) if (hay[i + j] !== needle[j]) continue outer;
173 return i;
174 }
175 // oxlint-disable-next-line no-magic-numbers -- not-found sentinel, the same value String#indexOf returns
176 return -1;
179export function bytesOf(x: string | Uint8Array): Uint8Array {
180 return typeof x === 'string' ? te.encode(x) : x;
Diagnostics6 git calls · 264 ms
CallStatusSizeTime0264 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=3
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 · hit3 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=3
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=10
Open 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=5323b9266eea5ded637285d1c5320699f12be76e
Open 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=255
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=723b6bf1d4d6021fe5eb940c622b9ff00ee4a381
Open pack map
fetch2004.5 KiB255 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=4649
git.response.cache=MISS
git.response.duration_ms=255
git.fetch.wants=059aa101e467f8fb95729a720399e7de2440afea
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=4649
git.pkt.payload.max=4622
git.sideband.band1.bytes=4622
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
a5e0f8325adf332c
Request
e27f6b93…
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