main
ply4 git calls30 ms43 KiB3 cachedprotocol v2
101 lines4.6 KiBRaw
1// HEAD, including an unborn symref, as ply's lsRefs reports it.
2//
3// Asking for `unborn` costs one advertisement GET the first time an origin is seen in this isolate: ply sends the
4// argument only when unwrapAsync(discover()) shows `ls-refs=unborn`, which is git's own rule (connect.c server_supports_feature).
5// The bit is a fact about the server. It is remembered here and passed back as `info`, the option ply provides so a
6// discover result already in hand does not fetch the advertisement again. A later HEAD read on that origin is one
7// ls-refs. The first is discover + ls-refs. Sending `unborn` without that check would be this module speaking the
8// protocol, which is the code this adapter replaced.
9import { discover, KIND, lsRefs, parseOid, type Oid, type Span } from 'ply';
10import { unwrapAsync } from '../ply-result.ts';
11import { mapGet } from '../absent.ts';
12import { type GitTransport } from './call.ts';
14export type HeadState =
15 | { readonly kind: 'born'; readonly ref: string; readonly oid: Oid }
16 | { readonly kind: 'detached'; readonly oid: Oid }
17 | { readonly kind: 'unborn'; readonly ref: string }
18 | { readonly kind: 'absent' };
20/** What `lsRefs` returns that decides HEAD. Structural so a listing can be built in a test. */
21export type HeadListing = {
22 readonly refs: ReadonlyMap<string, { readonly oid: string }>;
23 readonly head: string | null;
24 readonly unborn: { readonly target: string } | null;
25};
27const HEAD_NAME = 'HEAD';
28const DISCOVER_FETCHED = 'discover';
29const DISCOVER_CACHED = 'cached';
31/** Origins whose `ls-refs=unborn` advertisement this isolate has already read. Same bound as the quirks map. */
32const MAX_UNBORN_ORIGINS = 256;
33const unbornAdvertised = new Map<string, boolean>();
34const unbornInflight = new Map<string, Promise<boolean>>();
36type DiscoverSource = typeof DISCOVER_FETCHED | typeof DISCOVER_CACHED;
38function rememberUnborn(origin: string, advertised: boolean): boolean {
39 if (!unbornAdvertised.has(origin) && unbornAdvertised.size >= MAX_UNBORN_ORIGINS) unbornAdvertised.clear();
40 unbornAdvertised.set(origin, advertised);
41 return advertised;
44/**
45 * ply's readCommit learns `ls-refs=unborn` while answering an empty repository, and does not tell this cache.
46 * Record the bit so a later HEAD read in this isolate is ls-refs only, the same as a readHead that discovered it.
47 */
48export function noteUnbornAdvertised(url: string): void {
49 rememberUnborn(new URL(url).origin, true);
52/** ply's `lsRefsUnborn` for this origin: one discover per isolate, then the cached bit. */
53async function lsRefsUnbornOf(t: GitTransport): Promise<{ readonly advertised: boolean; readonly source: DiscoverSource }> {
54 const origin = new URL(t.url).origin;
55 const known = mapGet(unbornAdvertised, origin);
56 if (known.tag === 'some') return { advertised: known.value, source: DISCOVER_CACHED };
57 let flight = unbornInflight.get(origin);
58 if (!flight) {
59 flight = unwrapAsync(discover(t)).then(info => rememberUnborn(origin, info.lsRefsUnborn)).finally(() => { unbornInflight.delete(origin); });
60 unbornInflight.set(origin, flight);
61 }
62 return { advertised: await flight, source: DISCOVER_FETCHED };
65/**
66 * unborn wins (an empty repository). A listed HEAD with a symref target is born. A listed HEAD with no target is
67 * detached. Anything else is absent, including a server that does not advertise `ls-refs=unborn`.
68 */
69function oidOf(value: string): Oid {
70 const parsed = parseOid(value);
71 if (!parsed.ok) throw parsed.error;
72 return parsed.value;
75export function headFromListing(listed: HeadListing): HeadState {
76 if (listed.unborn) return { kind: 'unborn', ref: listed.unborn.target };
77 const rec = listed.refs.get(HEAD_NAME);
78 if (rec && listed.head !== null) return { kind: 'born', ref: listed.head, oid: oidOf(rec.oid) };
79 if (rec) return { kind: 'detached', oid: oidOf(rec.oid) };
80 return { kind: 'absent' };
83export async function readHead(t: GitTransport): Promise<HeadState> {
84 return t.tracer.span('git.head', {
85 parent: t.parent,
86 kind: KIND.CLIENT,
87 attrs: { 'git.command': 'ls-refs', 'git.ls_refs.unborn': true, 'git.ls_refs.prefixes': [HEAD_NAME] },
88 }, async (span: Span) => {
89 const cap = await lsRefsUnbornOf(t);
90 const listed = await unwrapAsync(lsRefs(t, [HEAD_NAME], { unborn: true, info: { lsRefsUnborn: cap.advertised } }));
91 const head = headFromListing(listed);
92 span.set({
93 'git.head.kind': head.kind,
94 'git.head.ref': head.kind === 'born' || head.kind === 'unborn' ? head.ref : '',
95 'git.head.discover': cap.source,
96 'git.head.unborn_advertised': cap.advertised,
97 'git.head.oid': head.kind === 'born' || head.kind === 'detached' ? head.oid : '',
98 });
99 return head;
100 });
Diagnostics4 git calls · 30 ms
CallStatusSizeTime030 ms
discover200152 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
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 1020040 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=41349
git.response.cache=HIT
git.response.duration_ms=2
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=526b305930b8ef382f2d7a1f9c0238730a585921
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=41349
git.pkt.payload.max=41254
git.sideband.band1.bytes=41253
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=61
git.pack.bytes=41253
git.pack.ofs_delta=0
git.pack.ref_delta=0
git.pack.chain.max=0
git.pack.trailer=ab60efef4b7243678c75de64a4386986ee885c1c
git.pack.full=61
Open pack map
fetch2001.8 KiB · hit25 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=25
git.response.bytes=1875
git.response.cache=HIT
git.response.duration_ms=25
git.fetch.wants=162158af0456ccfd178d0917e771f2ed99824ff3
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=1875
git.pkt.payload.max=1854
git.sideband.band1.bytes=1853
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-web.git
Ref
refs/heads/main
Commit
526b305930b8ef382f2d7a1f9c0238730a585921
cf-ray
a5e2c0767c8e89da
Request
c01fa6f3…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format