Artifactspublic-v0

ply

main
ply4 git calls25 ms42 KiB3 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 });
Diagnostics4 git calls · 25 ms
CallStatusSizeTime025 ms
discover200152 B2 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=2
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 · 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=145
git.response.cache=HIT
git.response.duration_ms=2
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 · hit3 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=38434
git.response.cache=HIT
git.response.duration_ms=3
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
fetch2004.5 KiB · hit20 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=20
git.response.bytes=4628
git.response.cache=HIT
git.response.duration_ms=20
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=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=4628
git.pkt.payload.max=4607
git.sideband.band1.bytes=4606
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
a5e29942edab2407
Request
51bf3481…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format