GitHubivarvong

ply

main
ply6 git calls30 ms24 KiB5 cachedprotocol v2
200 lines13 KiBRaw
1// Recent history of a ref in one fetch, without a clone (#56).
2//
3// readLog(url, { ref, limit = 20 }, opts) → { ref, oid, commits: [{ oid, tree, parents, author, committer, message, signed }], truncated }
4// logOn(transport, { commit, limit = 20 }) → Result<{ commits, truncated, cut, filter, window }>
5//
6// readLog resolves the ref, then logOn does the window on that transport. A caller that already holds the transport
7// (and a commit id) uses logOn and keeps the harvested trees.
8//
9// Order: first parent, newest first: exactly `git rev-list --first-parent -n <limit> <ref>` (and `git log
10// --first-parent`). That is the line a branch's history follows (one merge commit per landed branch, not the branch's own
11// commits), and it is the only order a window of `limit` commits answers exactly from one fetch with no date heuristics.
12// `parents` lists every parent, as git does. `truncated` is true when history continues past the last commit returned: it
13// has a parent. Fewer than `limit` commits with `truncated` true means the server's history is cut there (a shallow
14// repository on the server says so with a `shallow` line).
15//
16// The fetch: `want <commit> deepen <limit> filter tree:0`. A server that refuses tree:0 (Cloudflare Artifacts answers
17// only blob:none) gets `blob:none` instead, learned from that answer and remembered in `quirks` (fetchpack.js
18// fetchPackTree0): that pack also carries every tree of every commit in the window, which is checked and harvested so a
19// following readFile/listTree on the same transport costs no round trip. Every commit, tree and tag in the pack passes
20// assertFetched; a malformed one fails the read (`pack_corrupt`).
21//
22// The window is held to the deepen contract (#37, merge.js ancestors): the wanted commit is in the pack; every commit in
23// it is an ancestor of the wanted one through the pack; a commit whose parent the pack lacks is one the server named
24// `shallow`. Commits are hash-verified, so history cannot be forged, only withheld or padded; a pack that does either
25// without saying so is `pack_corrupt`, never a short or foreign log.
26//
27// `path` (commits touching a path) is not supported: under tree:0 the window carries no trees, and comparing trees per
28// commit would cost a fetch per commit on a tree:0 server. Passing one is `bad_request`.
29//
30// Errors are values: readLog, logOn and logWindow return a Result.
31import { fail, type CommitMiss, type PlyError } from './errors.js';
32import { at, fromNullable, fromNullish, mapGet, withDefaults } from './absent.js';
33import type { Input } from './absent.js';
34import { ok, assertNever, flatMapOption, none } from './result.js';
35import type { Option, Result } from './result.js';
36import { operation } from './operation.js';
37import { resolveCommit, commitView } from './read.js';
38import { fetchPackTree0 } from './fetchpack.js';
39import { parseCommit, TYPE, nonCommitType } from './objects.js';
40import { limitsOf } from './limits.js';
41import type { CheckedLimits } from './limits.js';
42import type { CommitView, ReadOptions } from './read.js';
43import type { FetchPackResult } from './fetchpack.js';
44import type { Transport } from './transport.js';
45import { thrownReasonIs } from './boundary.js';
46// oxlint-disable-next-line import/max-dependencies -- the read path's edge to the modules not yet converted to Result
48type FetchedPack = FetchPackResult & { readonly filter: string | null };
49type PackObjects = NonNullable<FetchPackResult['objects']>;
50type PackObject = PackObjects extends Map<string, infer O> ? O : never;
52export const DEFAULT_LOG_LIMIT = 20;
53const isObject = (v: unknown): v is object => v !== null && typeof v === 'object';
55type Parents = { readonly parents: readonly string[] };
56// Pure: the first-parent log of `head` over a deepen window. `commits` is oid → { parents } (every commit the pack held),
57// `shallow` the server's shallow lines. Err pack_corrupt when the window breaks the deepen contract. Returns
58// { chain: [oid], truncated, cut } where `cut` says the chain stopped at a shallow commit before `limit`.
59export type LogWindow = { readonly chain: string[]; readonly truncated: boolean; readonly cut: boolean };
60export function logWindow(commits: ReadonlyMap<string, Parents>, shallow: Iterable<string>, head: string, limit: number): Result<LogWindow, PlyError> {
61 if (!commits.has(head)) return fail('pack_corrupt', `commit ${head} not in the pack that wanted it`);
62 // every oid in q is in `commits`: head was checked, and a parent joins only when present
63 const reach = new Set([head]); const q = [head];
64 // oxlint-disable-next-line typescript/no-unsafe-type-assertion, typescript/non-nullable-type-assertion-style -- see above (and no `!`: docs/STACK.md)
65 for (const c of q) for (const p of (commits.get(c) as Parents).parents) if (commits.has(p) && !reach.has(p)) { reach.add(p); q.push(p); }
66 const cut = new Set(shallow);
67 for (const [oid, c] of commits) {
68 if (!reach.has(oid)) return fail('pack_corrupt', `commit ${oid} sent but not an ancestor of ${head}`);
69 const missing: Option<string> = cut.has(oid) ? none : fromNullable(c.parents.find(p => !commits.has(p)));
70 if (missing.tag === 'some') return fail('pack_corrupt', `parent ${missing.value} of ${oid} withheld and ${oid} not reported shallow`);
71 }
72 const chain: string[] = [];
73 for (let c = head; ;) {
74 chain.push(c);
75 // c is head or a first parent the window holds (checked below before stepping to it)
76 // oxlint-disable-next-line typescript/no-unsafe-type-assertion, typescript/non-nullable-type-assertion-style -- see above (and no `!`: docs/STACK.md)
77 const first = at((commits.get(c) as Parents).parents, 0);
78 if (first.tag === 'none') return ok({ chain, truncated: false, cut: false });
79 if (chain.length === limit) return ok({ chain, truncated: true, cut: false });
80 if (!commits.has(first.value)) return ok({ chain, truncated: true, cut: true });
81 c = first.value;
82 }
85// Effect: the window's pack, with a want that is not a commit (or not on the server) as the caller's not_found.
86async function fetchWindow(t: Transport, commit: string, limit: number): Promise<Result<FetchedPack, PlyError>> {
87 const got = await fetchPackTree0(t, { wants: [commit], filter: 'tree:0', deepen: limit });
88 if (!got.ok) {
89 if (got.error.code === 'remote_error' && thrownReasonIs(got.error, 'not_our_ref')) return fail('not_found', `commit ${commit} not found on the remote`, { miss: { kind: 'commit', miss: { kind: 'absent', oid: commit } } });
90 return got;
91 }
92 const r = got.value;
93 const want = flatMapOption(fromNullish(r.objects), objects => mapGet(objects, commit));
94 if (want.tag === 'some' && want.value.type !== TYPE.COMMIT) {
95 const wantType = want.value.type;
96 const found = nonCommitType(wantType);
97 const detail = ((): { readonly shown: string; readonly miss: CommitMiss } => {
98 switch (found.tag) {
99 case 'notCommit':
100 return { shown: found.name, miss: { kind: 'not_commit', oid: commit, type: found.name } };
101 case 'delta':
102 return { shown: found.name, miss: { kind: 'absent', oid: commit } };
103 case 'commit':
104 return { shown: 'commit', miss: { kind: 'absent', oid: commit } };
105 case 'invalid':
106 return { shown: String(wantType), miss: { kind: 'absent', oid: commit } };
107 }
108 // Stryker disable next-line ConditionalExpression,CallExpression: unreachable, the compiler's exhaustiveness check
109 return assertNever(found);
110 })();
111 return fail('not_found', `${commit} is not a commit (${detail.shown})`, { miss: { kind: 'commit', miss: detail.miss } });
112 }
113 return ok(r);
116// What readLog takes. `ref: null` is the remote's HEAD; `path` is refused unless absent or null (see above).
117export type LogConfig = { readonly ref: string | null; readonly limit: number; readonly path: unknown };
118export type LogSpec = Input<LogConfig>;
119export type LogCommit = CommitView & { readonly oid: string };
120export type LogResult = { readonly ref: string; readonly oid: string; readonly commits: readonly LogCommit[]; readonly truncated: boolean };
121// The window readLog returns, plus what the span already recorded: which filter answered, and how big the pack's
122// commit set was. `cut` is true when the chain stopped on a shallow commit before `limit` (a shallow server).
123export type LogOnValue = {
124 readonly commits: readonly LogCommit[];
125 readonly truncated: boolean;
126 readonly cut: boolean;
127 readonly filter: string | null;
128 readonly window: { readonly commits: number; readonly shallow: number };
129};
130type LogOnFields = { readonly commit: unknown; readonly limit: unknown };
131export type LogOnSpec = Input<LogOnFields>;
132// Effect: one first-parent window of `commit` on the caller's transport. Trees of a blob:none answer are harvested
133// into `t.objects`. A bad limit is bad_request; a pack that breaks the deepen contract is pack_corrupt.
134export async function logOn(t: Transport, spec: LogOnSpec | null): Promise<Result<LogOnValue, PlyError>> {
135 if (!isObject(spec)) return fail('bad_request', 'logOn: the second argument must be an object ({ commit, limit })', { what: 'spec' });
136 if (typeof spec.commit !== 'string') return fail('bad_request', 'logOn: commit must be a string', { what: 'commit' });
137 // A missing limit is the default. Null is not a limit: the caller passed it.
138 const givenLimit = fromNullable(spec.limit);
139 const limit = givenLimit.tag === 'none' ? DEFAULT_LOG_LIMIT : givenLimit.value;
140 const commit = spec.commit;
141 const cap = t.limits.maxMergeDepth;
142 // A rejected limit is not a number. Null would pass a bare `< 1` by coercion, so it stays its own case.
143 const depth = typeof limit === 'number' && Number.isSafeInteger(limit) ? limit : null;
144 if (depth === null || depth < 1 || depth > cap) return fail('bad_request', `logOn: limit must be an integer from 1 to ${cap} (limits.maxMergeDepth)`, { what: 'limit' });
145 const fetched = await fetchWindow(t, commit, depth);
146 if (!fetched.ok) return fetched;
147 const r = fetched.value;
148 const objects: PackObjects = r.objects === null ? new Map<string, PackObject>() : r.objects;
149 const parsed = new Map<string, Parents>();
150 for (const [oid, o] of objects) {
151 if (o.type !== TYPE.COMMIT) continue;
152 const c = parseCommit(o.data, t.limits);
153 if (!c.ok) return c;
154 parsed.set(oid, c.value);
155 }
156 const w = logWindow(parsed, r.shallow, commit, depth);
157 if (!w.ok) return w;
158 const commits: LogCommit[] = [];
159 for (const oid of w.value.chain) {
160 // every oid in the chain is a commit the pack held (logWindow walked them), so the object is there
161 // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- see above
162 const view = commitView((objects.get(oid) as { readonly data: Uint8Array }).data, t.limits);
163 if (!view.ok) return view;
164 commits.push({ oid, ...view.value });
165 }
166 const answered = fromNullable(r.filter);
167 return ok({ commits, truncated: w.value.truncated, cut: w.value.cut, filter: answered.tag === 'some' ? answered.value : null, window: { commits: parsed.size, shallow: r.shallow.length } });
170// readLog's arguments, checked in the order the entry always checked them. `opts.tracer` is optional (operation()).
171function logArgs(spec: LogSpec, opts: ReadOptions): Result<{ readonly ref: string | null; readonly limit: number; readonly limits: CheckedLimits }, PlyError> {
172 if (!isObject(spec)) return fail('bad_request', 'readLog: the second argument must be an object ({ ref, limit })');
173 if (!isObject(opts)) return fail('bad_request', 'readLog: the third argument must be an object (options)');
174 const { ref, limit, path } = withDefaults<LogConfig>(spec, { ref: null, limit: DEFAULT_LOG_LIMIT, path: null });
175 if (path !== null) return fail('bad_request', 'readLog: path filtering is not supported');
176 // A null limits record is the default, as the nullish read had it; the record is parsed once, here.
177 const limits = limitsOf(opts);
178 if (!limits.ok) return limits;
179 const cap = limits.value.maxMergeDepth;
180 if (!Number.isSafeInteger(limit) || limit < 1 || limit > cap) return fail('bad_request', `readLog: limit must be an integer from 1 to ${cap} (limits.maxMergeDepth)`, { what: 'limit' });
181 return ok({ ref, limit, limits: limits.value });
183// oxlint-disable-next-line require-await -- async: a refused argument is an Err in a promise, like every other answer
184export async function readLog(url: string, spec: LogSpec = {}, opts: ReadOptions = {}): Promise<Result<LogResult, PlyError>> {
185 const args = logArgs(spec, opts);
186 if (!args.ok) return args;
187 const { ref, limit, limits } = args.value;
188 return operation('read_log', url, { ...opts, limits, attrs: { 'git.read_log.ref': typeof ref === 'string' ? ref : 'HEAD', 'git.read_log.limit': limit } }, async ({ t, outcome }) => {
189 const resolved = await resolveCommit(t, ref);
190 if (!resolved.ok) return resolved;
191 const { name, commit } = resolved.value;
192 const window = await logOn(t, { commit, limit });
193 if (!window.ok) return window;
194 const got = window.value;
195 return outcome('ok', { ref: name, oid: commit, commits: got.commits, truncated: got.truncated }, {
196 'git.read_log.oid': commit, 'git.read_log.commits': got.commits.length, 'git.read_log.truncated': got.truncated, 'git.read_log.cut': got.cut,
197 'git.read_log.window.commits': got.window.commits, 'git.read_log.window.shallow': got.window.shallow, 'git.read_log.filter': got.filter,
198 });
199 });
Diagnostics6 git calls · 30 ms
CallStatusSizeTime030 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=2
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 · hit2 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=2
git.response.bytes=11990
git.response.cache=HIT
git.response.duration_ms=2
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 · 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=4347
git.response.cache=HIT
git.response.duration_ms=2
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=3
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 · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=21
git.response.bytes=2507
git.response.cache=HIT
git.response.duration_ms=3
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 KiB · hit21 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=4649
git.response.cache=HIT
git.response.duration_ms=21
git.fetch.wants=5790ac6a7cc59ebdab16694e1ae2c4a31d9d9269
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
a5e0fd741f5b332c
Request
7fdeae81…
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