GitHubivarvong
ply
main
1// Smart-HTTP transport: one POST per git command, body chunks yielded as they arrive, every request a CLIENT span.
2// Implements the contract in transport.js. `createTransport` is its constructor (the name every caller used first).
3// The constructor, the checks (credential forms, redirect policy, header names, the Location rule, status and redirect
4// errors, capped reads) and `advertise` return Result. `frames` is a stream: it fails through the stream protocol (its
5// iterator rejects with the PlyError). The platform's fetch() and body reads are caught where they are made.
6/* oxlint-disable require-unicode-regexp -- URL, header and credential text; `u` costs a byte per literal and changes what /i matches (U+017F, U+212A) */
7import type { Code, Detail, ErrorOf, Extra, PlyError } from './errors.js';
8import type { Result } from './result.js';
9import { field, fillIn, fromNullable, withDefaults } from './absent.js';
10import type { Input } from './absent.js';
11import { assertNever, err, ok } from './result.js';
12import type { CheckedLimits, LimitsInput } from './limits.js';
13import type { Span } from './otel.js';
14import { Tracer } from './otel.js';
15import type { Attrs, ExchangeClock, Frame, Hints, Quirks, RequestBody, Scrub, Transport } from './transport.js';
16import { fail, plyError, remoteQuoted, remoteText } from './errors.js';
17import { pktInit, pktStep, pktFinish, pktAttrs } from './pktline.js';
18import type { PktState } from './pktline.js';
19import { bufferSource, concat, td, te } from './bytes.js';
20import { scrubber, secretShaped, secretUser } from './scrub.js';
21import { DEFAULT_LIMITS, limitExceeded, parseLimits } from './limits.js';
22import { validateFieldValue, validateWire } from './validate.js';
23import type { WireField } from './validate.js';
24import { exchangeClock, readAbortable, watchedUpload, NO_HINTS, UA, forgetRedirect, freshQuirks, quirksKeyOf, recalledRedirect, rememberRedirect, rememberedQuirks, plyMade, wrapNet } from './transport.js';
26export const redactUrl = (u: string | URL): string => { try { const x = new URL(u); x.username = ''; x.password = ''; return x.toString(); } catch { return '<invalid url>'; } };
27export type HttpCode = Extract<Code, 'auth' | 'not_found' | 'rate_limited' | 'upstream_5xx' | 'http'>;
28export const httpCode = (status: number): HttpCode => {
29 if (status === 401 || status === 403) return 'auth';
30 if (status === 404) return 'not_found';
31 if (status === 429) return 'rate_limited';
32 return status >= 500 ? 'upstream_5xx' : 'http';
33};
34// The named statuses (kept as a branded union for exhaustive type tests).
35export type NamedHttpStatus = 401 | 403 | 404 | 429;
36type BadRequest = ErrorOf<'bad_request'>;
38// An error page is quoted, not stored. Past this many bytes the rest cannot change the message and must not be buffered.
39const ERROR_PREVIEW = 4096;
40const ERROR_QUOTE = 200;
42// Opt-in response headers on the exchange span (`http.response.header.<lowercased name>`). A name has to be a token the
43// telemetry key grammar already allows (letters, digits, `.`, `_`, `-`): that is an RFC 7230 tchar subset, and a name
44// outside it would mint an attribute key no dashboard contract accepts. Values are scrubbed (the transport's credential
45// scrub, same as every other span string) then cut. The cap is a support id (cf-ray, x-github-request-id, x-request-id),
46// not a body. Too many names is a caller's bug and is refused before any request.
47export const HEADER_VALUE_MAX = 128;
48export const MAX_RECORDED_HEADERS = 8;
49const HEADER_NAME = /^[0-9A-Za-z._-]+$/;
50// Private channel to cachingFetch (packcache.ts keeps the same literals). The edit bundle must not import that module.
51// The hint is set only when fetchImpl is cachingFetch, and that wrapper strips it before the origin fetch.
52const RECORD_HEADERS_REQUEST = 'x-ply-record-headers';
53const CACHING_FETCH_BRAND = 'plyCachingFetch';
54const PACK_CACHE_HEADER = 'x-ply-pack-cache';
56// A response header's value, '' when the response did not send it.
57const headerText = (res: Response, name: string): string => { const v = res.headers.get(name); return v === null ? '' : v; };
59function recordResponseHeaderNames(list: unknown): Result<readonly string[], BadRequest> {
60 if (!Array.isArray(list)) return fail('bad_request', 'recordResponseHeaders: expected a list of header names', { what: 'recordResponseHeaders' });
61 if (list.length > MAX_RECORDED_HEADERS) return fail('bad_request', `recordResponseHeaders: at most ${MAX_RECORDED_HEADERS} names`, { what: 'recordResponseHeaders' });
62 const out: string[] = [];
63 const seen = new Set<string>();
64 for (const name of list) {
65 if (typeof name !== 'string' || !HEADER_NAME.test(name)) {
66 const shown = typeof name === 'string' ? JSON.stringify(name) : 'not a string';
67 return fail('bad_request', `recordResponseHeaders: ${shown} is not a header name`, { what: 'recordResponseHeaders' });
68 }
69 const lower = name.toLowerCase();
70 if (seen.has(lower)) continue;
71 seen.add(lower);
72 out.push(lower);
73 }
74 return ok(out);
75}
77// Scrub the whole value, then cap: slicing first could leave a secret fragment shorter than the scrubber's window.
78function recordedHeaderAttrs(res: Response, names: readonly string[], scrub: Scrub | null): Attrs {
79 const attrs: Attrs = {};
80 for (const name of names) {
81 const raw = res.headers.get(name);
82 if (raw === null) continue;
83 const text = scrub ? scrub(raw) : raw;
84 attrs[`http.response.header.${name}`] = text.length > HEADER_VALUE_MAX ? text.slice(0, HEADER_VALUE_MAX) : text;
85 }
86 if (res.headers.get(PACK_CACHE_HEADER) === 'HIT') attrs['http.response.headers.from_cache'] = true;
87 return attrs;
88}
90// A header field the caller gave (null: none given) is one line.
91const headerField = (value: string | null, what: string): Result<unknown, PlyError> => (value === null ? ok(null) : validateWire(value, what));
93// URL userinfo → the bytes git sends for it (git 2.50, measured against http-backend behind Basic auth), as a byte
94// string `btoa` takes as is: `%XX` is that byte (`%FF` → 0xFF, UTF-8 as its bytes), anything else as written (`%ZZ`
95// stays `%ZZ`; WHATWG URL has already percent-encoded every non-ASCII character). A NUL, CR or LF is refused: git
96// refuses LF ("credential url cannot be parsed") and NUL (curl: "bad/illegal format") and sends CR; Basic would carry
97// any of them, but no host means one.
98const userinfo = (s: string): Result<string, BadRequest> => {
99 // oxlint-disable-next-line unicorn/prefer-string-replace-all, unicorn/prefer-number-properties, unicorn/prefer-code-point -- same results (a /g regex; one global parseInt; bytes 0-255), fewer bytes
100 const b = s.replace(/%([0-9a-f]{2})/gi, (_: string, h: string) => String.fromCharCode(parseInt(h, 16)));
101 if (/[\0\r\n]/.test(b)) return fail('bad_request', 'invalid url userinfo: must not contain NUL, CR, or LF', { what: 'url userinfo' });
102 return ok(b);
103};
104// WHATWG URL drops an empty userinfo (`http://@h`, `http://:@h` → `http://h/`); git sends Basic `:` for both (measured).
105// A `\` ends the authority of a special URL, as `/` does.
106const emptyUserinfo = (url: string | URL): boolean => /^[a-z][a-z0-9+.-]*:\/\/[^/?#\\]*@/i.test(String(url));
107// oxlint-disable-next-line unicorn/prefer-code-point -- a byte, 0-255
108const latin1 = (bytes: Uint8Array): string => { let s = ''; for (const b of bytes) s += String.fromCharCode(b); return s; };
109// oxlint-disable-next-line unicorn/prefer-code-point -- atob() output: one char per byte, 0-255
110const utf8 = (b: string): string => td.decode(Uint8Array.from(b, c => c.charCodeAt(0)));
111// An Authorization value or a Bearer token goes on the wire as written: printable ASCII (and tab) only. A raw
112// non-ASCII or control character is refused before any request: fetch throws an untyped TypeError on a character past
113// U+00FF, git sends UTF-8 as raw bytes (measured, `http.extraHeader`) that no grammar for either scheme admits, and a
114// control character is a 400 from a strict server (measured: git's `Bearer t\x01k` → HTTP 400). Basic credentials are
115// any text (below).
116const ASCII_VALUE = /^[\t -~]+$/; // tab, and space (0x20) through tilde (0x7E)
117const noCredential = (why: string): Result<never, BadRequest> => fail('bad_request', `invalid auth: ${why}`, { what: 'auth' });
119// The explicit `auth` → [Authorization value, its Basic parts or null]. Every form yields a credential or is refused:
120// an `auth` that sends nothing is the silent trap #32 was (every request anonymous, a 401 saying nothing about why).
121// { header } the value verbatim (a proxy forwarding its caller's credential)
122// { token, user? } Basic `user:token`, user defaulting to `x-access-token`; the text is sent as its UTF-8 bytes, as git
123// sends a credential helper's (measured: `username=tëst password=päss` → those bytes)
124// { bearer } Bearer
125// { user } refused. git's own credential API asks for the password when a helper gives a user alone (measured:
126// "could not read Password", nothing sent) and a library cannot ask; `token: ''` is the explicit
127// empty password and sends `user:` (git, helper `password=` empty: `ivar:`), the URL `user@` form.
128// The explicit credential forms, total: null is a form not given. A caller may leave any of them out (HttpAuth).
129export type HttpAuthConfig = { readonly header: string | null; readonly token: string | null; readonly user: string | null; readonly bearer: string | null };
130export type HttpAuth = Input<HttpAuthConfig>;
131const noAuth = (): HttpAuthConfig => ({ header: null, token: null, user: null, bearer: null });
132type Basic = { readonly user: string; readonly pass: string };
133function explicitAuth({ header, token, user, bearer }: HttpAuthConfig): Result<[string, Basic | null], BadRequest> {
134 if (header !== null) {
135 if (!ASCII_VALUE.test(header)) return noCredential('the authorization header must be non-empty printable ASCII');
136 return ok([header, null]);
137 }
138 if (token !== null) {
139 if (token === '' && user === null) return noCredential('an empty token with no user carries no credential');
140 const name = user === null ? 'x-access-token' : user;
141 return ok([`Basic ${btoa(latin1(te.encode(`${name}:${token}`)))}`, { user: name, pass: token }]);
142 }
143 if (bearer !== null) {
144 if (!ASCII_VALUE.test(bearer)) return noCredential('the bearer token must be non-empty printable ASCII');
145 return ok([`Bearer ${bearer}`, null]);
146 }
147 if (user !== null) return noCredential('a user with no token; pass the token, or token: \'\' to send the user alone (Basic `user:`)');
148 return noCredential('no token, bearer or header; omit auth to send none');
149}
151// A 3xx is never followed unless the caller opts in (fetch `redirect: 'manual'` either way). Following hands the
152// Authorization header to whatever the server names, under the runtime's own rules: undici strips it cross-origin,
153// workerd 2026-10-23 forwards it (measured, SAFETY I6c). The default stays that refusal. `followRedirects: 'initial'`
154// is git's `http.followRedirects=initial`: only the first GET info/refs is followed, and only when the Location keeps
155// the `/info/refs?service=<service>` suffix (http.c update_url_from_redirect). The base URL is then rewritten and every
156// later request, including a POST, uses it. A 3xx on a POST is still this error. A cross-origin rebase drops
157// Authorization; the caller does not get the Location's userinfo installed as a credential. Browsers answer `manual`
158// with an opaque redirect (status 0): same error. The error names where the server pointed (origin and path only, scrubbed).
159// maxRedirects defaults to 3, the hop cap ply-web used, and is refused above 16 (under curl's default of 50).
160export const DEFAULT_MAX_REDIRECTS = 3;
161export const MAX_REDIRECT_HOPS = 16;
162export type FollowRedirects = 'never' | 'initial';
163export type AllowUrl = (url: URL) => Result<URL, PlyError>;
164export type RedirectPolicy = { readonly follow: FollowRedirects; readonly max: number };
165const shown = (v: unknown): string => (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean' || v === null ? JSON.stringify(v) : typeof v);
166export function redirectPolicy(follow: unknown, max: unknown): Result<RedirectPolicy, BadRequest> {
167 const f = fromNullable(follow);
168 if (f.tag === 'some' && f.value !== 'never' && f.value !== 'initial') return fail('bad_request', `followRedirects must be 'never' or 'initial', got ${shown(f.value)}`, { what: 'followRedirects' });
169 const m = fromNullable(max);
170 const raw = m.tag === 'none' ? DEFAULT_MAX_REDIRECTS : m.value;
171 const n = typeof raw === 'number' && Number.isSafeInteger(raw) ? raw : null;
172 if (n === null || n < 0 || n > MAX_REDIRECT_HOPS) return fail('bad_request', `maxRedirects must be an integer from 0 to ${MAX_REDIRECT_HOPS}`, { what: 'maxRedirects' });
173 return ok({ follow: f.tag === 'some' && f.value === 'initial' ? 'initial' : 'never', max: n });
174}
175// The new base is the Location with the asked URL's `/info/refs?service=` suffix removed. Anything else is not a
176// rebase git would accept (update_url_from_redirect dies), so the caller gets the redirect error instead.
177export function baseFromRedirect(asked: string, got: URL, service: string): string | null {
178 const tail = `/info/refs?service=${service}`;
179 if (!asked.endsWith(tail) || !got.href.endsWith(tail)) return null;
180 const next = got.href.slice(0, got.href.length - tail.length).replace(/\/$/, '');
181 try {
182 const b = new URL(next);
183 if (b.protocol !== 'http:' && b.protocol !== 'https:') return null;
184 b.username = ''; b.password = ''; b.hash = '';
185 return b.toString().replace(/\/$/, '');
186 } catch { return null; }
187}
188// A caller may not return a Result even though the type says so. `ok` is read off an unknown object so a
189// non-boolean still fails, which a boolean compare on the Result type cannot see.
190function isUrlResult(v: unknown): v is Result<URL, PlyError> {
191 if (v === null || typeof v !== 'object' || !('ok' in v)) return false;
192 return v.ok === true || v.ok === false;
193}
194// The caller's allowUrl, applied. Its own Err is the answer as given; an allowUrl that throws throws through.
195function useAllowed(allow: AllowUrl | null, url: URL): Result<URL, PlyError> {
196 if (allow === null) return ok(url);
197 const got: unknown = allow(url);
198 if (!isUrlResult(got)) return fail('bad_request', 'allowUrl must return a Result', { what: 'allowUrl' });
199 if (!got.ok) return got;
200 const next = got.value;
201 if (!(next instanceof URL) || (next.protocol !== 'http:' && next.protocol !== 'https:')) return fail('bad_request', 'allowUrl must return an http(s) URL', { what: 'allowUrl' });
202 next.username = ''; next.password = ''; next.hash = '';
203 return ok(next);
204}
205// The Location ply would rebase to, or null when it does not keep the info/refs suffix (the caller then reports the
206// redirect and does not request it). git's curl requests the Location first and update_url_from_redirect dies after;
207// refusing first is that die, without handing the next host a request. allowUrl sees the Location and its URL is the
208// one the suffix rule is applied to. Userinfo on the Location is removed and is never installed as a credential.
209// `location` is that Location as the redirect memo keeps it: absolute, without userinfo or fragment, before allowUrl.
210type Rebase = { readonly base: string; readonly location: string };
211function locationBase(asked: string, location: string | null, service: string, allow: AllowUrl | null): Result<Rebase | null, PlyError> {
212 if (location === null || location === '') return ok(null);
213 let got: URL;
214 try { got = new URL(location, asked); } catch { return ok(null); }
215 got.username = ''; got.password = ''; got.hash = '';
216 const kept = got.href;
217 const allowed = useAllowed(allow, got);
218 if (!allowed.ok) return allowed;
219 const base = baseFromRedirect(asked, allowed.value, service);
220 return ok(base === null ? null : { base, location: kept });
221}
222const isRedirect = (res: Response): boolean => res.type === 'opaqueredirect' || (res.status >= 300 && res.status < 400);
223// A body a test double may not implement `cancel` on, and a real one whose `cancel()` rejects. The rejection is the
224// body's, not the caller's: it must be awaited, or it is an unhandled rejection the surrounding `try` cannot catch.
225async function cancelBody(body: unknown): Promise<void> {
226 const cancel = field(body, 'cancel');
227 // A `cancel` that is not a function was a TypeError, caught here: skipping it is the same outcome.
228 try { if (cancel.tag === 'some' && typeof cancel.value === 'function') await Reflect.apply(cancel.value, body, []); } catch { /* unopened or already closed */ }
229}
230// A 2xx whose body is missing never reached the pkt-line parser. Iterating it threw TypeError, and wrapNet reported
231// `network`. There is no git message to parse: that is `protocol`. A body is present or it is not: no third reading.
232type Body = { readonly tag: 'body'; readonly stream: ReadableStream<Uint8Array> } | { readonly tag: 'missing' };
233const bodyOf = (res: Response): Body => {
234 const b = field(res, 'body');
235 // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- a present Response body is its stream
236 return b.tag === 'some' ? { tag: 'body', stream: b.value as ReadableStream<Uint8Array> } : { tag: 'missing' };
237};
238async function redirectError(res: Response, url: string, what: string, scrub: Scrub | null): Promise<ErrorOf<'http'>> {
239 let to = '';
240 const loc = res.headers.get('location');
241 // oxlint-disable-next-line typescript/strict-boolean-expressions -- null and '' are no Location, as before
242 if (loc) try { const x = new URL(loc, url); to = `${x.origin}${x.pathname}`; } catch { /* unparseable Location */ }
243 if (scrub) to = scrub(to);
244 await cancelBody(res.body);
245 return plyError('http', `HTTP ${res.status} ${what}: redirected${to ? ` to ${to}` : ''}; ply does not follow redirects (update the remote URL)`, { status: res.status, location: to } as Detail['http'] & Extra);
246}
248// Read a body without ever holding more than `max` bytes. `truncate` keeps a prefix (error pages);
249// otherwise the first chunk that would pass the cap is the error and is not retained. A body read is a platform edge:
250// its failure is the network error it is (wrapNet), as on a POST's body.
251type CapRead = { readonly what: string; readonly truncate: boolean; readonly signal: AbortSignal; readonly progress: () => void };
252async function readCapped(body: ReadableStream<Uint8Array> | null, max: number, { what, truncate, signal, progress }: CapRead): Promise<Result<Uint8Array, PlyError>> {
253 // oxlint-disable-next-line typescript/no-unnecessary-condition -- a fetch double may hand back a body that is not async-iterable
254 if (!body || typeof body[Symbol.asyncIterator] !== 'function') return ok(new Uint8Array(0));
255 const chunks: Uint8Array[] = [];
256 let n = 0;
257 const read = readAbortable(body, signal);
258 try {
259 for await (const chunk of read.chunks) {
260 progress();
261 const bytes = chunk instanceof Uint8Array ? chunk : new Uint8Array(chunk);
262 if (n + bytes.length > max) {
263 if (!truncate) return err(limitExceeded(what, n + bytes.length, max));
264 if (max > n) chunks.push(bytes.subarray(0, max - n));
265 break;
266 }
267 chunks.push(bytes);
268 n += bytes.length;
269 }
270 } catch (e) { return err(wrapNet(e, signal)); } finally { await cancelBody(body); }
271 // the exchange's signal ended the read: its reason is the error (a timeout names its limit)
272 if (read.cut()) return err(wrapNet(signal.reason, signal));
273 return ok(concat(chunks));
274}
276// A non-2xx answer: a prefix of the body for the message (credential-scrubbed), the rest cancelled. A truncating read
277// keeps a prefix: its only error is the body read failing, and that is the exchange's error.
278async function statusError(res: Response, service: string, scrub: Scrub | null, clock: ExchangeClock): Promise<PlyError> {
279 const read = await readCapped(res.body, ERROR_PREVIEW, { what: 'response bytes', truncate: true, signal: clock.signal, progress: () => { clock.feed('body_chunk'); } });
280 if (!read.ok) return read.error;
281 const preview = td.decode(read.value);
282 const quoted = remoteText(scrub ? scrub(preview) : preview, ERROR_QUOTE);
283 const miss = res.status === 404 ? { miss: { kind: 'repository' as const } } : {};
284 return plyError(httpCode(res.status), `HTTP ${res.status} ${service}: ${quoted}`, { status: res.status, ...miss } as Detail['http'] & Extra);
285}
286// What the transport calls: the platform fetch, or a wrapper with its signature (packcache.ts cachingFetch).
287export type FetchLike = (url: string | URL, init: RequestInit) => Promise<Response>;
288// The transport's configuration, total. `null` is "none given": no credential, no parent span, no abort signal, no
289// allowUrl hook. recordResponseHeaders names the response headers copied onto each exchange span (none by default, so
290// the span contract is unchanged).
291export type HttpConfig = {
292 readonly auth: HttpAuth | null;
293 readonly tracer: Tracer | null;
294 readonly parent: Span | null;
295 readonly fetchImpl: FetchLike;
296 readonly userAgent: string;
297 // any subset: a key left out is DEFAULT_LIMITS's (parseLimits, when the transport is made)
298 readonly limits: LimitsInput;
299 readonly signal: AbortSignal | null;
300 // null (the default): the remote's remembered record (transport.ts rememberedQuirks, #136)
301 readonly quirks: Input<Quirks> | null;
302 readonly followRedirects: FollowRedirects;
303 readonly allowUrl: AllowUrl | null;
304 readonly maxRedirects: number;
305 readonly recordResponseHeaders: readonly string[];
306};
307export type HttpOptions = Input<HttpConfig>;
308// quirks: null takes the record remembered for this remote (keyed without the credential); a caller's own record wins.
309const httpDefaults = (): { -readonly [K in keyof HttpConfig]: HttpConfig[K] } => ({
310 auth: null, tracer: null, parent: null, fetchImpl: globalThis.fetch, userAgent: UA, limits: DEFAULT_LIMITS, signal: null,
311 quirks: null, followRedirects: 'never', allowUrl: null, maxRedirects: DEFAULT_MAX_REDIRECTS, recordResponseHeaders: [],
312});
313export type HttpTransport = Transport & { readonly kind: 'http' };
315// The URL's userinfo as the Basic parts git sends for it, or null when the URL carries none (or `auth` is explicit).
316function urlCredential(auth: HttpAuth | null, u: URL, url: string | URL): Result<Basic | null, BadRequest> {
317 if (auth !== null || !(u.username || u.password || emptyUserinfo(url))) return ok(null);
318 const user = userinfo(u.username);
319 if (!user.ok) return user;
320 const pass = userinfo(u.password);
321 if (!pass.ok) return pass;
322 return ok({ user: user.value, pass: pass.value });
323}
324// The Basic parts of an Authorization value as a server would echo them, or null when it is not Basic or not base64.
325const basicOf = (authorization: string | null): Basic | null => {
326 if (authorization === null || !/^Basic\s/i.test(authorization)) return null;
327 try {
328 const d = atob(authorization.replace(/^Basic\s+/i, ''));
329 const c = d.indexOf(':');
330 return c < 0 ? { user: d, pass: '' } : { user: d.slice(0, c), pass: d.slice(c + 1) };
331 } catch { return null; }
332};
333// The redirect mode of a streamed POST: 'error' where the platform takes it (undici, browsers), else 'manual'. workerd
334// refuses 'error' at `new Request` ("does not make sense at the edge", measured on the pinned workerd); its fetch is
335// not the JS fetch that clones a request, and a 3xx there is the redirect error as on any POST.
336export type StreamRedirect = 'manual' | 'error';
337export const streamRedirect = (): StreamRedirect => {
338 try { return new Request('http://localhost/', { redirect: 'error' }).redirect === 'error' ? 'error' : 'manual'; } catch { return 'manual'; }
339};
341// HttpOptions parsed once (#156): every check the transport makes of its options, here and nowhere after it. The limits
342// record is parsed here too (parseLimits), so a bad one is refused when the transport is made, not at its first request
343// or at the read that uses it. The brand is a module symbol: only parseHttpOptions writes it.
344const CHECKED_HTTP: unique symbol = Symbol('checkedHttp');
345export type HttpSettings = {
346 readonly [CHECKED_HTTP]: true;
347 // the URL as approved (allowUrl), without userinfo or hash; crossOrigin: allowUrl moved it to another origin
348 readonly url: URL;
349 readonly crossOrigin: boolean;
350 readonly policy: RedirectPolicy;
351 readonly userAgent: WireField;
352 readonly recordNames: readonly string[];
353 // the explicit credential forms, total (all null without auth); the Authorization value and its Basic parts
354 readonly given: HttpAuthConfig;
355 readonly authorization: string | null;
356 readonly explicitBasic: Basic | null;
357 readonly quirks: Quirks;
358 // the caller's fetch, bound when it is the platform's (Workers: "Illegal invocation" with another `this`, SAFETY.md)
359 readonly fetch: FetchLike;
360 // 'fetchImpl' when the caller supplied the fetch: its failure names it (error.what); the platform's own names none
361 readonly fetchWhat: string | null;
362 readonly tracer: Tracer | null;
363 readonly parent: Span | null;
364 readonly signal: AbortSignal | null;
365 readonly allowUrl: AllowUrl | null;
366 readonly limits: CheckedLimits;
367 readonly requestTimeoutMs: number;
368 readonly firstByteTimeoutMs: number;
369 readonly idleTimeoutMs: number;
370 readonly heldTimeoutMs: number;
371 readonly maxPackBytes: number;
372 readonly streamRedirect: StreamRedirect;
373};
374// @decoder parseHttpOptions prefix=http-options
375// oxlint-disable-next-line complexity, max-lines-per-function -- every option and credential form, checked in one place, in the order the refusals have always come
376export function parseHttpOptions(url: string | URL, options: HttpOptions = {}): Result<HttpSettings, PlyError> {
377 const { auth, tracer, parent, fetchImpl, userAgent, limits, signal, quirks: givenQuirks, recordResponseHeaders, followRedirects, allowUrl, maxRedirects } = withDefaults(options, httpDefaults());
378 const checkedPolicy = redirectPolicy(followRedirects, maxRedirects);
379 if (!checkedPolicy.ok) return checkedPolicy;
380 const agent = validateFieldValue(userAgent, 'userAgent');
381 if (!agent.ok) return agent;
382 const names = recordResponseHeaderNames(recordResponseHeaders);
383 if (!names.ok) return names;
384 // The explicit forms, total (all null without auth).
385 const given = withDefaults(auth, noAuth());
386 for (const [value, what] of [[given.header, 'authorization'], [given.token, 'token'], [given.bearer, 'bearer'], [given.user, 'auth user']] as const) {
387 const fieldOk = headerField(value, what);
388 if (!fieldOk.ok) return fieldOk;
389 }
390 // `new URL` puts what it was given on the TypeError (`input`): a credential in a malformed URL would ride out on it.
391 let u: URL;
392 try { u = new URL(url); } catch { return fail('bad_request', 'invalid url: not an absolute URL', { what: 'url' }); }
393 // userinfo in the URL becomes the Basic credential git sends for it, byte for byte: `user:password`; a user alone is
394 // `user:` (a token given as the user, which GitHub and GitLab accept; git sends it without asking for a password and
395 // asks only once it is refused), a password alone `:password`, an empty userinfo `:`. Explicit `auth` wins. It never
396 // appears again: not in requests, not in spans, not in error messages.
397 const credential = urlCredential(auth, u, url);
398 if (!credential.ok) return credential;
399 const fromUrl = credential.value;
400 u.username = ''; u.password = ''; u.hash = '';
401 // the caller's record, filled in place: every later call that passes it sees what this transport learns. Without one,
402 // the record remembered for this remote (origin + path, never the credential), shared by every transport made for it.
403 const quirks: Quirks = givenQuirks === null ? rememberedQuirks(quirksKeyOf(u)) : fillIn(givenQuirks, freshQuirks());
404 // allowUrl runs before any request, including the base. A different origin does not inherit this transport's credential.
405 const offeredOrigin = u.origin;
406 const approved = useAllowed(allowUrl, u);
407 if (!approved.ok) return approved;
408 // Only http: and https: are ever fetched, and the rule is held on the URL that will be requested: after allowUrl,
409 // so a caller's own scheme that allowUrl maps to https still works and a caller's refusal is still the answer as
410 // given (useAllowed holds an allowUrl result to http(s) itself; without an allowUrl the URL here is the base).
411 // Anything else (file:, data:, blob:, ssh:, git:, ext::) is refused before any I/O and before the fetch
412 // implementation sees it, as a definite failure and not a retry-shaped `network`. The message is fixed text.
413 if (approved.value.protocol !== 'http:' && approved.value.protocol !== 'https:') return fail('bad_request', 'invalid url: only http: and https: remotes are supported', { what: 'url' });
414 // The explicit credential, checked before anything is built from it.
415 // urlCredential reads the URL only when there is no auth, so a URL credential implies auth === null
416 const explicit = auth === null ? ok<[string | null, Basic | null]>([null, null]) : explicitAuth(given);
417 if (!explicit.ok) return explicit;
418 const checkedLimits = parseLimits(limits);
419 if (!checkedLimits.ok) return checkedLimits;
420 const [authorization, explicitBasic]: [string | null, Basic | null] = fromUrl ? [`Basic ${btoa(`${fromUrl.user}:${fromUrl.pass}`)}`, null] : explicit.value;
421 return ok({
422 [CHECKED_HTTP]: true, url: approved.value, crossOrigin: approved.value.origin !== offeredOrigin, policy: checkedPolicy.value,
423 userAgent: agent.value, recordNames: names.value, given, authorization, explicitBasic, quirks,
424 fetch: fetchImpl === globalThis.fetch ? fetchImpl.bind(globalThis) : fetchImpl, fetchWhat: fetchImpl === globalThis.fetch ? null : 'fetchImpl', tracer, parent, signal, allowUrl, limits: checkedLimits.value,
425 requestTimeoutMs: checkedLimits.value.requestTimeoutMs, firstByteTimeoutMs: checkedLimits.value.firstByteTimeoutMs, idleTimeoutMs: checkedLimits.value.idleTimeoutMs, heldTimeoutMs: checkedLimits.value.heldTimeoutMs, maxPackBytes: checkedLimits.value.maxPackBytes, streamRedirect: streamRedirect(),
426 });
427}
429// git asks for protocol v2 on upload-pack only: remote-curl downgrades every other service to v0 and sends no
430// Git-Protocol header, and a server may answer a v2-flagged receive-pack GET with a list that names no push capability.
431const protocolHeader = (service: string): Record<string, string> => (service === 'git-upload-pack' ? { 'Git-Protocol': 'version=2' } : {});
433// oxlint-disable-next-line max-lines-per-function -- the transport's state and its two methods share one closure
434function transportOf(settings: HttpSettings): HttpTransport {
435 const { policy, userAgent, recordNames, given, authorization, explicitBasic, quirks, fetch: f, fetchWhat, tracer, parent, signal, allowUrl, limits, requestTimeoutMs, firstByteTimeoutMs, idleTimeoutMs, heldTimeoutMs, maxPackBytes } = settings;
436 const startBase = settings.url.toString().replace(/\/$/, '');
437 let base = startBase;
438 // cachingFetch reads this and strips it (packcache.ts). Any other fetchImpl must not see it: it would go to the origin.
439 const recordHint = (): Record<string, string> => recordNames.length > 0 && Object.hasOwn(f, CACHING_FETCH_BRAND) ? { [RECORD_HEADERS_REQUEST]: recordNames.join(',') } : {};
440 // Whatever form, the value never reaches a span or an error message (`scrub`), even echoed.
441 // The credential sent from here on. A cross-origin rebase (or an allowUrl that moved the base) clears it; the
442 // scrubber above still redacts the original, so an echo of it cannot leak.
443 const startAuth = settings.crossOrigin ? null : authorization;
444 let liveAuth = startAuth;
445 let rebasedFrom: string | null = null;
446 let redirectCount = 0;
447 let initialSettled = false;
448 // The redirect memo (transport.ts): this remote's key, the base it starts from, and whether the current base came
449 // from a memo that no answer has confirmed yet (a 3xx then means the memo is stale).
450 const memoKey = quirksKeyOf(settings.url);
451 let memoUnconfirmed = false;
452 let replayed = false;
453 // The GET that settles the initial exchange, while it is in flight, and its service. A POST that starts meanwhile (a
454 // caller running discover and ls-refs side by side on a fresh transport) waits for that GET instead of making its own:
455 // one advertisement per settlement, not one per concurrent caller.
456 let settling: { readonly service: string; readonly done: Promise<unknown> } | null = null;
457 // The Basic parts as a server would echo them (UTF-8 text). From a header they are decoded, as bytes and as UTF-8.
458 const decoded = basicOf(authorization);
459 // oxlint-disable-next-line no-nested-ternary -- the explicit parts, else the decoded ones, else none
460 const basic = explicitBasic === null ? (decoded === null ? null : { user: utf8(decoded.user), pass: utf8(decoded.pass) }) : explicitBasic;
461 const basicUserOrNull = basic ? basic.user : null;
462 const user = given.user === null ? basicUserOrNull : given.user;
463 const userSecret = basic ? secretUser(basic.user, basic.pass !== '') : secretShaped(user);
464 // Every string a server can send back (error bodies, ERR lines, band-2/3 text, ng reasons, hook output) passes through
465 // `scrub` before it reaches an error or a span: the transport carries it (`t.scrub`) and otel.js applies it.
466 const authHeaderScrub = authorization === null ? null : authorization.replace(/^\S+\s+/, '');
467 const basicPass = basic ? basic.pass : null;
468 const decodedPass = decoded ? decoded.pass : null;
469 const echoedUser = basic ? basic.user : user;
470 const decodedUserOrNull = decoded ? decoded.user : null;
471 const basicUser = userSecret ? echoedUser : null;
472 const decodedUser = userSecret ? decodedUserOrNull : null;
473 const scrub = scrubber([authorization, given.token, given.bearer, authHeaderScrub, basicPass, decodedPass, basicUser, decodedUser, secretShaped(user) ? user : null]);
474 const hostOf = (): string => new URL(base).host;
475 // Only once a redirect was actually followed, so a transport that never rebases keeps today's span shape.
476 const redirectAttrs = (): Attrs => {
477 if (redirectCount === 0 || rebasedFrom === null) return {};
478 const from = redactUrl(rebasedFrom);
479 return { 'http.redirect.count': redirectCount, 'git.remote.rebased_from': scrub ? scrub(from) : from };
480 };
481 const rebase = (next: string): void => {
482 if (new URL(next).origin !== new URL(base).origin) liveAuth = null;
483 if (rebasedFrom === null) rebasedFrom = base;
484 base = next;
485 redirectCount += 1;
486 };
487 // The initial exchange settled from the memo, with no request: each remembered Location is approved again by this
488 // transport's allowUrl and the suffix rule, from the base this transport started at. Anything the replay cannot take
489 // (a refusal, a list past maxRedirects) leaves the transport as it was, to ask the network. It runs once, before the
490 // transport's first exchange (every exchange that can settle the initial one replays first), so it always starts
491 // unsettled, at the start base.
492 const replay = (service: string): void => {
493 if (policy.follow !== 'initial' || replayed) return;
494 replayed = true;
495 const locations = recalledRedirect(memoKey, service);
496 if (locations === null || locations.length > policy.max) return;
497 const bases: string[] = [];
498 let at = base;
499 for (const location of locations) {
500 const next = locationBase(`${at}/info/refs?service=${service}`, location, service, allowUrl);
501 if (!next.ok || next.value === null) return;
502 at = next.value.base;
503 bases.push(at);
504 }
505 for (const b of bases) rebase(b);
506 initialSettled = true;
507 memoUnconfirmed = true;
508 };
509 // A memo answered with a 3xx: drop it and start over from the original base, as a transport that never had one.
510 const unsettle = (service: string): void => {
511 forgetRedirect(memoKey, service);
512 base = startBase;
513 liveAuth = startAuth;
514 rebasedFrom = null;
515 redirectCount = 0;
516 initialSettled = false;
517 memoUnconfirmed = false;
518 };
519 const headers = (service: string, extra: Record<string, string> = {}): Record<string, string> => {
520 const h: Record<string, string> = { 'Content-Type': `application/x-${service}-request`, Accept: `application/x-${service}-result`, 'User-Agent': userAgent, ...extra };
521 // oxlint-disable-next-line typescript/strict-boolean-expressions -- null and '' send no Authorization, as before
522 if (liveAuth) h['Authorization'] = liveAuth;
523 return h;
524 };
525 // The exchange's clock (src/deadline.ts): first byte, idle, and the opt-in total. The span records the limit that
526 // fired. It is cancelled when the exchange ends, so a finished request does not abort later.
527 const timeouts = { firstByteMs: firstByteTimeoutMs, idleMs: idleTimeoutMs, heldMs: heldTimeoutMs, totalMs: requestTimeoutMs };
528 const requestClock = (span: Span): ExchangeClock =>
529 exchangeClock(timeouts, signal, (key, ms) => { span.set({ 'git.timeout.limit': key, 'git.timeout.ms': ms }); });
530 const limitAttrs = (): Attrs => ({ 'git.limits.request_timeout_ms': requestTimeoutMs, 'git.limits.first_byte_timeout_ms': firstByteTimeoutMs, 'git.limits.idle_timeout_ms': idleTimeoutMs, 'git.limits.held_timeout_ms': heldTimeoutMs });
531 // The platform's fetch(): its rejection is the network error it is (wrapNet). The one catch of each request.
532 // `redirect`: 'manual' (a 3xx is read as the redirect error) unless the body is a stream: undici answers 'manual' and
533 // 'follow' by cloning the request, which tees the body and holds every chunk the unread branch never takes (a 64 MiB
534 // push held 64 MiB, measured). 'error' takes no clone; a 3xx then fails the request as a network error. Neither follows.
535 const send = async (target: string, init: RequestInit, sig: AbortSignal, redirect: StreamRedirect = 'manual'): Promise<Result<Response, PlyError>> => {
536 try { return ok(await f(target, { ...init, signal: sig, redirect })); } catch (e) { return err(wrapNet(e, sig, fetchWhat)); }
537 };
539 const fetchAdvertisement = async (asked: string, service: string, span: Span, sig: AbortSignal): Promise<Result<Response, PlyError>> => {
540 const t0 = Date.now();
541 const res = await send(asked, { headers: headers(service, { ...protocolHeader(service), ...recordHint() }) }, sig);
542 if (res.ok) span.set({ 'http.response.status_code': res.value.status, 'http.response.ttfb_ms': Date.now() - t0, 'http.response.header.content-type': headerText(res.value, 'content-type') });
543 return res;
544 };
545 const advertisementBody = async (res: Response, service: string, span: Span, clock: ExchangeClock): Promise<Result<Uint8Array, PlyError>> => {
546 if (!res.ok) return fail(httpCode(res.status), `HTTP ${res.status} ${service} advertisement`, { status: res.status, ...(res.status === 404 ? { miss: { kind: 'repository' as const } } : {}) } as Detail['http'] & Extra);
547 if (!headerText(res, 'content-type').startsWith(`application/x-${service}-advertisement`)) return fail('not_git', `unexpected content-type from ${service} advertisement`);
548 const declared = Number(res.headers.get('content-length'));
549 if (Number.isFinite(declared) && declared > maxPackBytes) {
550 await cancelBody(res.body);
551 return err(limitExceeded('advertisement bytes', declared, maxPackBytes));
552 }
553 const body = bodyOf(res);
554 switch (body.tag) {
555 case 'missing': return fail('protocol', `${service} advertisement: HTTP ${res.status} response has no body`);
556 case 'body': {
557 const buf = await readCapped(body.stream, maxPackBytes, { what: 'advertisement bytes', truncate: false, signal: clock.signal, progress: () => { clock.feed('body_chunk'); } });
558 if (buf.ok) span.set({ 'git.response.bytes': buf.value.length, 'http.response.body.size': buf.value.length, ...redirectAttrs() });
559 return buf;
560 }
561 }
562 // Stryker disable next-line ConditionalExpression: unreachable, the compiler's exhaustiveness check
563 return assertNever(body);
564 };
565 // A 3xx on the initial GET. Returns the next base, or null when `res` is not a redirect. A redirect that is not
566 // followed (the default, a hop past maxRedirects, a Location that fails the suffix rule) is the existing http error.
567 async function redirectHop(res: Response, asked: string, service: string, following: boolean): Promise<Result<Rebase | null, PlyError>> {
568 if (!isRedirect(res)) return ok(null);
569 const room = following && redirectCount < policy.max;
570 if (!room) {
571 initialSettled = true;
572 return err(await redirectError(res, asked, `${service} advertisement`, scrub));
573 }
574 let next: Result<Rebase | null, PlyError> | null = null;
575 // allowUrl is the caller's code: if it throws, the body is still released before that propagates.
576 try { next = locationBase(asked, res.headers.get('location'), service, allowUrl); }
577 finally { if (next === null) await cancelBody(res.body); }
578 if (!next.ok) { await cancelBody(res.body); return next; }
579 if (next.value === null) {
580 initialSettled = true;
581 return err(await redirectError(res, asked, `${service} advertisement`, scrub));
582 }
583 await cancelBody(res.body);
584 return next;
585 }
586 // GET info/refs?service=… . With followRedirects 'initial' and no settled exchange yet, a suffix-preserving 3xx
587 // rebases `base` (up to maxRedirects) and the GET is retried there. A network failure leaves the exchange unsettled
588 // so a retry continues from the base already reached.
589 async function advertiseOnce(service: string, span: Span): Promise<Result<Uint8Array, PlyError>> {
590 const followed: string[] = [];
591 // Each hop's URL is the previous response's Location, so the next GET cannot start until this one has been read.
592 // oxlint-disable no-await-in-loop
593 for (;;) {
594 const following = policy.follow === 'initial' && !initialSettled;
595 const asked = `${base}/info/refs?service=${service}`;
596 span.set({ 'git.transport': 'http', 'http.request.method': 'GET', 'url.full': redactUrl(asked), 'server.address': hostOf(), ...redirectAttrs() });
597 const sig = requestClock(span);
598 try {
599 const res = await fetchAdvertisement(asked, service, span, sig.signal);
600 if (!res.ok) return res;
601 sig.feed('headers');
602 if (recordNames.length > 0) span.set(recordedHeaderAttrs(res.value, recordNames, scrub));
603 // A stale memo: this GET is replayable, so the exchange starts over from the original base.
604 if (memoUnconfirmed && isRedirect(res.value)) { await cancelBody(res.value.body); unsettle(service); continue; }
605 const next = await redirectHop(res.value, asked, service, following);
606 if (!next.ok) return next;
607 if (next.value !== null) { followed.push(next.value.location); rebase(next.value.base); continue; }
608 initialSettled = true;
609 memoUnconfirmed = false;
610 const body = await advertisementBody(res.value, service, span, sig);
611 if (following && body.ok) rememberRedirect(memoKey, service, followed);
612 return body;
613 } finally { sig.cancel(); }
614 }
615 // oxlint-enable no-await-in-loop
616 }
617 // advertiseOnce, published as `settling` while it is the GET that settles the initial exchange.
618 async function advertise(service: string, span: Span): Promise<Result<Uint8Array, PlyError>> {
619 replay(service);
620 if (policy.follow !== 'initial' || initialSettled) return advertiseOnce(service, span);
621 const done = advertiseOnce(service, span);
622 const mine = { service, done };
623 settling = mine;
624 try { return await done; } finally { if (settling === mine) settling = null; }
625 }
626 // The POST's answer, checked before its body is read: a redirect, a non-2xx, a foreign content type, a missing body.
627 const postStream = async (res: Response, service: string, target: string, clock: ExchangeClock): Promise<Result<ReadableStream<Uint8Array>, PlyError>> => {
628 if (isRedirect(res)) return err(await redirectError(res, target, service, scrub));
629 // Keep a prefix for the message (and for credential scrubbing). The rest of a huge error page is cancelled.
630 if (!res.ok) return err(await statusError(res, service, scrub, clock));
631 const ct = headerText(res, 'content-type');
632 if (!ct.startsWith(`application/x-${service}-result`)) return fail('not_git', `unexpected content-type ${remoteQuoted(ct)} from ${service}`);
633 const body = bodyOf(res);
634 switch (body.tag) {
635 case 'missing': return fail('protocol', `${service}: HTTP ${res.status} response has no body`);
636 case 'body': return ok(body.stream);
637 }
638 // Stryker disable next-line ConditionalExpression: unreachable, the compiler's exhaustiveness check
639 return assertNever(body);
640 };
641 // The POST itself, and where it went. A 3xx on a base the memo gave means the memo is stale: bytes are sent again,
642 // once, after the exchange is settled over the network. A stream was consumed: it gets the redirect error (or, where a
643 // stream is sent with redirect 'error' (undici), the network failure a 3xx is there, which cannot be told apart from a
644 // dead link), and the memo is dropped all the same, so the next transport asks again.
645 async function sendPost(service: string, body: RequestBody, extra: Record<string, string>, span: Span, clock: ExchangeClock): Promise<Result<{ readonly res: Response; readonly target: string }, PlyError>> {
646 const target = `${base}/${service}`;
647 const bytes = body instanceof Uint8Array ? body : null;
648 const sig = clock.signal;
649 // A streamed body's pulls by the platform are the clock's progress marks (what ply can see, not what reached the
650 // server); its end starts the wait for the headers, unless they are already here.
651 if (bytes === null) clock.feed('upload_started');
652 const init: { readonly body: BodyInit } | { readonly body: BodyInit; readonly duplex: 'half' } = body instanceof Uint8Array ? { body: bufferSource(body) } : { body: watchedUpload(body.stream, clock), duplex: 'half' };
653 const res = await send(target, { method: 'POST', headers: headers(service, extra), ...init }, sig, bytes === null ? settings.streamRedirect : 'manual');
654 const stale = memoUnconfirmed && (res.ok ? isRedirect(res.value) : bytes === null);
655 if (!stale) return res.ok ? ok({ res: res.value, target }) : res;
656 if (bytes === null || !res.ok) { forgetRedirect(memoKey, service); return res.ok ? ok({ res: res.value, target }) : res; }
657 await cancelBody(res.value.body);
658 unsettle(service);
659 const ad = await advertise(service, span);
660 if (!ad.ok) return ad;
661 const again = `${base}/${service}`;
662 span.set({ 'url.full': redactUrl(again), 'server.address': hostOf(), ...redirectAttrs() });
663 clock.feed('request_sent');
664 const retried = await send(again, { method: 'POST', headers: headers(service, extra), body: bufferSource(bytes) }, sig, 'manual');
665 return retried.ok ? ok({ res: retried.value, target: again }) : retried;
666 }
667 // POST and yield body chunks, filling span with HTTP attrs. Async generator keeps memory at one chunk. A failure is
668 // yielded as its Err and ends the stream (frames raises it). A streamed body is read as the request goes out (undici
669 // requires `duplex: 'half'` for it; workerd accepts the field), chunked like git's own bodies past http.postBuffer.
670 async function* post(service: string, body: RequestBody, span: Span, hints: Hints): AsyncGenerator<Result<Uint8Array, PlyError>, void, unknown> {
671 if (policy.follow === 'initial' && !initialSettled) {
672 // the memo first: a hit settles the exchange with no request; a miss is the GET git makes
673 replay(service);
674 // Another exchange's GET for this service is settling it: wait for that one. If it did not settle the exchange (it
675 // failed), this POST makes its own GET, as it would have without it.
676 const shared = settling !== null && settling.service === service ? settling.done : null;
677 if (shared !== null) await shared.catch(() => null);
678 const ad = initialSettled ? null : await advertise(service, span);
679 if (ad !== null && !ad.ok) { yield ad; return; }
680 }
681 const target = `${base}/${service}`;
682 // oxlint-disable-next-line typescript/strict-boolean-expressions -- an absent hint is no hint
683 const extra = { ...protocolHeader(service), ...recordHint(), ...(hints.bypassCache ? { 'x-ply-cache': 'bust' } : {}) };
684 span.set({ 'git.transport': 'http', 'http.request.method': 'POST', 'url.full': redactUrl(target), 'server.address': hostOf(), 'git.request.bytes': body.length, 'http.request.body.size': body.length, 'git.service': service, ...limitAttrs(), ...redirectAttrs() });
685 const t0 = Date.now();
686 const sig = requestClock(span);
687 try {
688 const sent = await sendPost(service, body, extra, span, sig);
689 if (!sent.ok) { yield sent; return; }
690 sig.feed('headers');
691 const res = sent.value.res;
692 const posted = sent.value.target;
693 memoUnconfirmed = false;
694 const cache = headerText(res, PACK_CACHE_HEADER);
695 span.set({ 'http.response.status_code': res.status, 'http.response.header.content-type': headerText(res, 'content-type'), 'http.response.ttfb_ms': Date.now() - t0, 'git.response.cache': cache, 'git.pack.cache': cache });
696 if (recordNames.length > 0) span.set(recordedHeaderAttrs(res, recordNames, scrub));
697 const stream = await postStream(res, service, posted, sig);
698 if (!stream.ok) { yield stream; return; }
699 let bytes = 0, chunks = 0, first = -1, maxChunk = 0;
700 // The body read: a platform failure mid-stream is the network error it is.
701 const read = readAbortable(stream.value, sig.signal);
702 try { for await (const chunk of read.chunks) {
703 if (chunks === 0) first = Date.now() - t0;
704 bytes += chunk.length; chunks++; if (chunk.length > maxChunk) maxChunk = chunk.length;
705 // The chunk arrived and goes straight to the consumer (no await between). The take reads no clock: the hold
706 // (heldTimeoutMs) starts at the clock's next read (src/deadline.ts); the consumer's time with it
707 // is not the server's silence: the idle wait starts again when it asks.
708 sig.feed('consumer_took');
709 yield ok(chunk);
710 sig.feed('consumer_asked');
711 } } catch (e) { yield err(wrapNet(e, sig.signal)); return; }
712 // the exchange's signal ended the read: its reason is the error (a timeout names its limit)
713 if (read.cut()) { yield err(wrapNet(sig.signal.reason, sig.signal)); return; }
714 span.set({ 'git.response.bytes': bytes, 'git.response.first_byte_ms': first, 'git.response.duration_ms': Date.now() - t0, 'http.response.body.size': bytes, 'http.response.chunks': chunks, 'http.response.chunk.max': maxChunk, 'http.response.first_byte_ms': first, 'http.response.duration_ms': Date.now() - t0 });
715 } finally { sig.cancel(); }
716 }
718 // plyMade: these frames() and advertise() are ply's own (transportFrom keeps the transport as it is, unguarded)
719 return plyMade({
720 // quirks: what this server was found to need (shared by every view of the transport; a caller may pass one object to
721 // many transports for the same server). objects: commits/trees harvested from over-wide packs (fetch.js).
722 // scrub: the credential's forms → '[redacted]' (null without auth); spans under this transport apply it (otel.js).
723 // tracer: a transport made without one gets a Tracer with no exporter (its spans are dropped), as every entry does
724 // (operation.ts); the low-level calls (lsRefs, fetchPack, push on this transport) span on it unconditionally.
725 kind: 'http', get url(): string { return base; }, tracer: tracer === null ? new Tracer() : tracer, parent, limits, signal, quirks, objects: new Map(), scrub,
726 // The stream: a failure (the request's, a frame's) is raised through the iterator, as a stream signals one.
727 async *frames(service: string, body: RequestBody, span: Span, hints: Hints = NO_HINTS): AsyncGenerator<Frame, void, unknown> {
728 let st: PktState = pktInit();
729 for await (const chunk of post(service, body, span, hints)) {
730 const r = chunk.ok ? pktStep(st, chunk.value) : chunk;
731 if (!r.ok) throw r.error;
732 st = r.value.state; yield* r.value.frames;
733 }
734 const end = pktFinish(st);
735 if (!end.ok) throw end.error;
736 span.set(pktAttrs(st));
737 },
738 // GET info/refs?service=… (capability advertisements). Returns the whole body; advertisements are small.
739 advertise,
740 });
741}
743// The transport for `url`: its options parsed (parseHttpOptions), then built from the settings, which nothing re-checks.
744export function createTransport(url: string | URL, options: HttpOptions = {}): Result<HttpTransport, PlyError> {
745 const settings = parseHttpOptions(url, options);
746 return settings.ok ? ok(transportOf(settings.value)) : settings;
747}
Diagnostics6 git calls · 288 ms
CallStatusSizeTime0288 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=1 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 · hit1 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=1 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=10Open 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=5323b9266eea5ded637285d1c5320699f12be76eOpen 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=278 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=723b6bf1d4d6021fe5eb940c622b9ff00ee4a381Open pack map
fetch20017 KiB281 ms
git.upload-pack fetch http.response.status_code=200 git.response.bytes=17037 git.response.cache=MISS git.response.duration_ms=281 git.fetch.wants=2de3b0cdfc9a003620d5b40a7e02273a01e65892 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=5 git.pkt.data=4 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=17037 git.pkt.payload.max=16384 git.sideband.band1.bytes=17005 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
- a5e0f8445f1c332c
- Request
- e3bbd4ba…
- 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