main
ply4 git calls436 ms44 KiB2 cachedprotocol v2
237 lines9.1 KiBRaw
1// The only module allowed to spell JavaScript's `undefined`, optional members (`?:`),
2// optional chaining (`?.`), or nullish coalescing (`??`). `scripts/absence-gate.ts`
3// exempts this path and no other. Grep here.
4//
5// Host APIs (Request, URL, headers, Worker env, the Cache API, R2 get, JSON, OTel)
6// speak null and `undefined`. Domain code speaks Option or a closed union. Convert once, here.
7// `undefined` leaves this file only as the branded `PlatformAbsent` value inside a converter.
9import { none, some, type Option } from "./option.ts";
11declare const platformAbsentBrand: unique symbol;
13/**
14 * JavaScript's `undefined`, branded so a mention is a boundary crossing.
15 * The brand is a unique symbol: another module cannot forge the type without this symbol.
16 * The runtime value is still the host's absent value. Only this module reads or writes it.
17 * Also published globally so an ambient host declaration can name it without becoming a module.
18 */
19export type PlatformAbsent = undefined & { readonly [platformAbsentBrand]: "platform-absent" };
21declare global {
22 type PlatformAbsent = undefined & { readonly [platformAbsentBrand]: "platform-absent" };
25/** True for the host's absent value. Tests use this. Domain code matches on Option. */
26export function isPlatformAbsent(value: unknown): value is PlatformAbsent {
27 return value === undefined;
30/**
31 * Map the host's absent value to none. Null stays a present value (`some(null)`),
32 * which is what JSON null and a stored null mean.
33 */
34export function fromAbsent<T>(value: T): Option<Exclude<T, undefined>> {
35 if (value === undefined) return none();
36 return some(value as Exclude<T, undefined>);
39/**
40 * Map null and the host's absent value to none. This is the converter for APIs that
41 * use the two interchangeably (headers, query strings, R2 get, Cache.match).
42 */
43export function fromNullable<T>(value: T): Option<NonNullable<T>> {
44 if (value === undefined || value === null) return none();
45 return some(value as NonNullable<T>);
48export function mapGet<K, V>(map: ReadonlyMap<K, V>, key: K): Option<Exclude<V, undefined>> {
49 // Map#get cannot tell a missing key from a stored absent value. This codebase does not store one.
50 return fromAbsent(map.get(key));
53export function recordGet<V>(record: Readonly<Record<string, V>> | null | undefined, key: string): Option<Exclude<V, undefined>> {
54 if (record === undefined || record === null) return none();
55 if (!Object.hasOwn(record, key)) return none();
56 return fromAbsent(record[key]);
59/** One property, the way `?.` reads it: a null receiver, a missing key, and a null property are all none. */
60export function chainGet(value: unknown, key: string): Option<unknown> {
61 if (value === undefined || value === null) return none();
62 if (typeof value !== "object" && typeof value !== "function") return none();
63 if (!(key in value)) return none();
64 return fromNullable((value as Record<string, unknown>)[key]);
67/** `a?.b?.c`, as one Option. An empty key list is the value itself, with null counted as none. */
68export function dig(value: unknown, keys: readonly string[]): Option<unknown> {
69 let current: Option<unknown> = fromNullable(value);
70 for (const key of keys) {
71 if (current.tag === "none") return none();
72 current = chainGet(current.value, key);
73 }
74 return current;
77/**
78 * Index into a list. Out of range is none. A hole (the host's absent element, including an
79 * unmatched capture group) is none. A stored null is `some(null)`.
80 */
81export function atIndex<T>(items: readonly T[], index: number): Option<Exclude<T, undefined>> {
82 if (!Number.isInteger(index) || index < 0 || index >= items.length) return none();
83 return fromAbsent(items[index]);
86/** One character. Out of range is none. A string has no holes, so an in-range index is present. */
87export function textAt(text: string, index: number): Option<string> {
88 if (!Number.isInteger(index) || index < 0 || index >= text.length) return none();
89 return some(text[index]);
92export function captureGroup(match: RegExpMatchArray | RegExpExecArray | null, index: number): Option<string> {
93 if (match === null) return none();
94 return atIndex(match, index);
97export function header(headers: Headers, name: string): Option<string> {
98 return fromNullable(headers.get(name));
101export function queryParam(params: URLSearchParams, name: string): Option<string> {
102 return fromNullable(params.get(name));
105export function requestHeader(request: Request, name: string): Option<string> {
106 return header(request.headers, name);
109export function requestQuery(request: Request, name: string): Option<string> {
110 return queryParam(new URL(request.url).searchParams, name);
113/** A Worker binding or text var. Both null and a missing binding are none. Empty text stays present. */
114export function envBinding<T>(value: T): Option<NonNullable<T>> {
115 return fromNullable(value);
118/** Cache.match returns the host's absent value on a miss. A hit is the Response. */
119export async function cacheMatch(
120 cache: { match(request: RequestInfo | URL): Promise<Response | null | undefined> },
121 request: RequestInfo | URL,
122): Promise<Option<Response>> {
123 return fromNullable(await cache.match(request));
126/** R2 get returns null when the key is absent. */
127export async function r2Get<T>(
128 bucket: { get(key: string): Promise<T | null> },
129 key: string,
130): Promise<Option<NonNullable<T>>> {
131 return fromNullable(await bucket.get(key));
134export type JsonDecoded =
135 | { readonly tag: "value"; readonly value: unknown }
136 | { readonly tag: "invalid"; readonly reason: "syntax" };
138/** A JSON value, or syntax failure. Failure is not absence: the text was not JSON. */
139export function decodeJson(text: string): JsonDecoded {
140 try {
141 const value: unknown = JSON.parse(text);
142 if (value === undefined) return { tag: "invalid", reason: "syntax" };
143 return { tag: "value", value };
144 } catch {
145 return { tag: "invalid", reason: "syntax" };
146 }
149/**
150 * One own field of a JSON object. A missing field is none. JSON null is `some(null)`.
151 * Arrays and non-objects are none: index with `atIndex` instead.
152 */
153export function jsonField(value: unknown, key: string): Option<unknown> {
154 if (typeof value !== "object" || value === null || Array.isArray(value)) return none();
155 if (!Object.hasOwn(value, key)) return none();
156 return fromAbsent((value as Record<string, unknown>)[key]);
159export type OtelAttribute = string | number | boolean;
161/** One OTel attribute on a string-keyed bag. A missing key, null, or a non-attribute type is none. */
162export function otelAttribute(attrs: unknown, key: string): Option<OtelAttribute> {
163 const field = jsonField(attrs, key);
164 if (field.tag === "none") return none();
165 const value = field.value;
166 if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return some(value);
167 return none();
170/**
171 * One OTLP attribute from a `{ key, value }` list (span.attributes). The first matching key wins.
172 * A missing list, key, or value is none. JSON null is `some(null)`.
173 */
174export function otelListField(list: unknown, key: string): Option<unknown> {
175 if (!Array.isArray(list)) return none();
176 for (const entry of list) {
177 if (typeof entry !== "object" || entry === null || Array.isArray(entry)) continue;
178 const record = entry as Record<string, unknown>;
179 if (!Object.hasOwn(record, "key") || record.key !== key) continue;
180 if (!Object.hasOwn(record, "value")) return none();
181 return fromAbsent(record.value);
182 }
183 return none();
186/** `error.code` / `error.message`, including fields that live on the prototype. Null and missing are none. */
187export function thrownField(value: unknown, key: string): Option<unknown> {
188 return chainGet(value, key);
191export type ManualInit = {
192 readonly method: string;
193 readonly headers: HeadersInit;
194 readonly body: Option<BodyInit>;
195 readonly signal: Option<AbortSignal>;
196};
198/**
199 * Fetch init for a manual-redirect hop. `none` becomes the host's absent value, which is what
200 * `body ?? undefined` and `signal ?? undefined` pass today (null is not a body and not a signal).
201 */
202export function manualInit(parts: ManualInit): RequestInit {
203 const body = parts.body.tag === "some" ? parts.body.value : undefined;
204 const signal = parts.signal.tag === "some" ? parts.signal.value : undefined;
205 return {
206 method: parts.method,
207 headers: parts.headers,
208 body,
209 redirect: "manual",
210 signal,
211 };
214/**
215 * `span.setAttribute`, when the tracer gave us a span and when it did not.
216 * A throw is swallowed: telemetry must not change the request.
217 */
218export function writeSpanAttribute(span: unknown, key: string, value: OtelAttribute): void {
219 try {
220 const write = chainGet(span, "setAttribute");
221 if (write.tag === "none" || typeof write.value !== "function") return;
222 write.value.call(span, key, value);
223 } catch {
224 // Telemetry must not change the request.
225 }
228/** `span.end`, with the same swallow as `writeSpanAttribute`. */
229export function endOptionalSpan(span: unknown): void {
230 try {
231 const end = chainGet(span, "end");
232 if (end.tag === "none" || typeof end.value !== "function") return;
233 end.value.call(span);
234 } catch {
235 // Telemetry must not change the request.
236 }
Diagnostics4 git calls · 436 ms
CallStatusSizeTime0436 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 · hit7 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=7
git.response.bytes=145
git.response.cache=HIT
git.response.duration_ms=7
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
fetch2002.9 KiB427 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=427
git.response.bytes=2937
git.response.cache=MISS
git.response.duration_ms=427
git.fetch.wants=7202ed45474674186367e1b0b64bb138090074fa
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=2937
git.pkt.payload.max=2916
git.sideband.band1.bytes=2915
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
a5e2f8ee8a6390c0
Request
8f1ea6d4…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format