GitHubivarvong
ply
main
1// The operation() callback contract (#306, README "operation(): your body's outcomes"), pinned case by case. Breaking
2// since #277: a callback's own throw is never returned as itself unless it is a PlyError thrown before the push
3// request was handed to the transport. The expected values are the README contract, hand-derived:
4// 1. a non-ply throw before the hand-over -> Err bad_request, what 'callback', cause === the thrown value
5// 2. a PlyError throw before the hand-over -> Err that very PlyError (same object, same code)
6// 3. a throw after the hand-over -> Err ambiguous, what 'callback', cause === the thrown value
7// (a thrown PlyError's code goes to `original`), except that a
8// thrown `ambiguous` PlyError is returned as itself (no what, no cause)
9// 4. a returned value (Ok, or the caller's own discriminated union inside it) passes through unchanged
10// 5. outside body: a tracer whose start() throws, or a link whose span is null/undefined (or whose traceId/spanId
11// getter throws), rejects before body runs (README, same section, first paragraph)
12// No server: fetchImpl refuses every request, so nothing can reach a network; the hand-over is the frames() call.
13import { test } from 'vitest';
14import assert from 'node:assert/strict';
15// From their modules, not the package root (src/index.ts re-exports both): a static import of src/index.js makes every
16// module-level mutant of every module it re-exports static, run against all 412 mutation tests (#313).
17import { operation } from '../src/operation.js';
18import { plyError } from '../src/errors.js';
20const url = 'https://example.invalid/r.git';
21const opts = { fetchImpl: async () => { await null; throw new Error('no network in this test'); } };
22const empty = new Uint8Array(0);
24test('1. a non-ply value thrown before the hand-over is bad_request what callback, with the value as cause', async () => {
25 for (const thrown of [new Error('conflict'), { kind: 'ref_exists' }, 'a string', null]) {
26 const r = await operation('probe', url, opts, async () => { await null; throw thrown; });
27 assert.equal(r.ok, false);
28 assert.equal(r.error.code, 'bad_request');
29 assert.equal(r.error.what, 'callback');
30 assert.equal(r.error.cause, thrown);
31 assert.notEqual(r.error, thrown);
32 }
33 // an upload-pack request only reads: still before the hand-over
34 const thrown = new Error('after a read');
35 const r = await operation('probe', url, opts, async ({ t, root }) => { await null; t.frames('git-upload-pack', empty, root, {}); throw thrown; });
36 assert.equal(r.ok, false);
37 assert.equal(r.error.code, 'bad_request');
38 assert.equal(r.error.what, 'callback');
39 assert.equal(r.error.cause, thrown);
40});
42test('2. a PlyError thrown before the hand-over is returned as itself', async () => {
43 const thrown = plyError('cas_conflict', 'mine: someone else moved the ref');
44 const r = await operation('probe', url, opts, async () => { await null; throw thrown; });
45 assert.equal(r.ok, false);
46 assert.equal(r.error, thrown);
47 assert.equal(r.error.code, 'cas_conflict');
48});
50test('3. any throw after the push request was handed to the transport is ambiguous what callback, with the value as cause', async () => {
51 // README row 1 'after': a non-PlyError with a `code` (any value but null or undefined: a node network error's
52 // 'ECONNRESET', or a number) also puts that code in `original`; a thrown PlyError's code goes there too. Each case
53 // names its expected `original` by hand (undefined: no `original` key at all).
54 const cases = [
55 [new Error('boom'), undefined],
56 [{ kind: 'stale_expected' }, undefined],
57 [Object.assign(new Error('reset'), { code: 'ECONNRESET' }), 'ECONNRESET'],
58 [{ code: 42 }, 42],
59 [{ code: null }, undefined],
60 [plyError('cas_conflict', 'mine: a definite rejection, seen after the hand-over'), 'cas_conflict'],
61 ];
62 for (const [thrown, original] of cases) {
63 const r = await operation('probe', url, opts, async ({ t, root }) => { await null; t.frames('git-receive-pack', empty, root, {}); throw thrown; });
64 assert.equal(r.ok, false);
65 assert.equal(r.error.code, 'ambiguous');
66 assert.equal(r.error.what, 'callback');
67 assert.equal(r.error.cause, thrown);
68 assert.notEqual(r.error, thrown);
69 if (original === undefined) assert.equal('original' in r.error, false);
70 else assert.equal(r.error.original, original);
71 }
72});
74test('3b. an ambiguous PlyError thrown after the hand-over is returned as itself, not re-wrapped', async () => {
75 const thrown = plyError('ambiguous', 'mine: I already know the push outcome is unknown');
76 const r = await operation('probe', url, opts, async ({ t, root }) => { await null; t.frames('git-receive-pack', empty, root, {}); throw thrown; });
77 assert.equal(r.ok, false);
78 assert.equal(r.error, thrown);
79 assert.equal(r.error.code, 'ambiguous');
80 assert.equal(r.error.what, undefined);
81 assert.equal(r.error.cause, undefined);
82});
84test('4. a returned value passes through: expected outcomes as a discriminated union, before or after the hand-over', async () => {
85 const conflict = { tag: 'conflict', reason: 'ref_exists' };
86 const before = await operation('probe', url, opts, async ({ outcome }) => { await null; return outcome('conflict', conflict); });
87 assert.equal(before.ok, true);
88 assert.equal(before.value, conflict);
89 const after = await operation('probe', url, opts, async ({ t, root, outcome }) => { await null; t.frames('git-receive-pack', empty, root, {}); return outcome('conflict', conflict); });
90 assert.equal(after.ok, true);
91 assert.equal(after.value, conflict);
92 // a returned Err is the caller's Err, also as itself, after the hand-over too
93 const mine = plyError('cas_conflict', 'mine: definite');
94 const returned = await operation('probe', url, opts, async ({ t, root }) => { await null; t.frames('git-receive-pack', empty, root, {}); return { ok: false, error: mine }; });
95 assert.equal(returned.ok, false);
96 assert.equal(returned.error, mine);
97});
99test('5. outside body: a tracer whose start() throws, or a link whose span is null or undefined, rejects before body runs', async () => {
100 const boom = new Error('start failed');
101 let ran = 0;
102 const body = async () => { await null; ran++; return { ok: true, value: 'ran' }; };
103 const tracer = { start() { throw boom; } };
104 await assert.rejects(operation('probe', url, { ...opts, tracer }, body), e => e === boom);
105 // link() reads span.traceId and span.spanId before body's try: null or undefined (or a throwing getter) rejects there.
106 for (const span of [null, undefined]) {
107 await assert.rejects(operation('probe', url, { ...opts, link: { span, kind: 'retry' } }, body), TypeError);
108 }
109 const getterBoom = new Error('traceId getter');
110 const span = { get traceId() { throw getterBoom; }, spanId: 'x' };
111 await assert.rejects(operation('probe', url, { ...opts, link: { span, kind: 'retry' } }, body), e => e === getterBoom);
112 assert.equal(ran, 0);
113});
Diagnostics6 git calls · 98 ms
CallStatusSizeTime098 ms
discover200191 B3 ms
git.upload-pack discover http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=2 git.response.bytes=191 git.server.agent=git/github-9922ec520325-Linux git.server.object_format=sha1 git.server.caps=agent ls-refs fetch server-option object-format git.server.fetch=shallow wait-for-done filter git.protocol.version=2 git.pkt.frames=9 git.pkt.data=7 git.pkt.flush=2 git.pkt.delim=0 git.pkt.bytes=191 git.pkt.payload.max=36
ls-refs20012 KiB · 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=11990 git.response.cache=HIT git.response.duration_ms=3 git.protocol.version=2 git.pkt.frames=152 git.pkt.data=151 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=11990 git.pkt.payload.max=122 git.ls_refs.count=151 git.ls_refs.head=refs/heads/main
fetchtree:0 · deepen 102004.2 KiB · hit2 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=3 git.response.bytes=4347 git.response.cache=HIT git.response.duration_ms=2 git.fetch.filter=tree:0 git.fetch.wants=19912563f540228593df0c489082e5e2508e21e4 git.fetch.haves.count=0 git.fetch.deepen=10 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=7 git.pkt.data=5 git.pkt.flush=1 git.pkt.delim=1 git.pkt.bytes=4347 git.pkt.payload.max=4247 git.sideband.band1.bytes=4247 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=10 git.pack.bytes=4247 git.pack.ofs_delta=0 git.pack.ref_delta=0 git.pack.chain.max=0 git.pack.trailer=a6caf8e129bea82c9bae4cbc7c130c9205add400 git.pack.full=10Open pack map
fetchtree:0200919 B · 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=919 git.response.cache=HIT git.response.duration_ms=3 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:02005.6 KiB · hit3 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=87 git.response.bytes=5724 git.response.cache=HIT git.response.duration_ms=3 git.fetch.filter=tree:0 git.fetch.wants=58fabb6768b3f737ee9cd8bac647bdc27405fb4d 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=5724 git.pkt.payload.max=5697 git.sideband.band1.bytes=5697 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=1 git.pack.bytes=5697 git.pack.trailer=be7e0453974a5fe832f9065a33bb7e3434c10e9bOpen pack map
fetch2002.1 KiB87 ms
git.upload-pack fetch http.response.status_code=200 git.response.bytes=2131 git.response.cache=MISS git.response.duration_ms=87 git.fetch.wants=e6e5e7f1b2c331734b291680b8f754d3aa17cf63 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=2131 git.pkt.payload.max=2104 git.sideband.band1.bytes=2104 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
- a5e0fa280e15332c
- Request
- c7147bde…
- 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