main
1// Resumable transfer, the effects (#238): each function is one exchange with one outcome; the plan is transferplan.ts.
2//
3// transferStatus(dst, plan, { ref }) ls-refs on the target and temp refs → the next step, or done
4// transferStep(dst, from, plan, step, { commit, ref }) one push: that batch's entries, read from the spool, plus its generated
5// objects; a batch moves the temp ref one temp commit on (compare-and-swap),
6// the final push creates the ref and deletes the temp ref (atomic)
7// runTransfer(dst, from, plan, opts) the loop: status, step, status... until done or `maxSteps`. After every push
8// the refs are read back until they show it (settling: a host's ls-refs can
9// lag a push it acknowledged). A push that is not a clean ok (ambiguous,
10// rejected, partial) is judged by those refs: the step landed (by this push
11// or another runner's) is progress; it did not and the push was refused is
12// that refusal; it did not and the push was ambiguous is sent again, then
13// `ambiguous`; the refs could not be read is `ambiguous`
14// copyTree(dst, from, opts) planTransfer then runTransfer
15// sweepTransfers(dst, opts) delete temp refs left by abandoned transfers
16//
17// The caller owns where the loop runs and the spool (a RangeSource over the fetched pack): a Worker that cannot finish
18// in one request runs `maxSteps` steps, keeps the plan (plain JSON, checked against its hash) and resumes in the next.
19// Nothing about progress is held locally: the next step is read from the destination every time, so a step that
20// landed is never sent again (a replay would be `ng … stale ref` anyway: every update is a compare-and-swap).
21//
22// Spans (each under the transport's parent): git.transfer.run > git.transfer.status, git.transfer.step (> the push's
23// wire spans), git.transfer.settle; git.transfer.sweep. Every one carries git.transfer.plan.hash and an outcome.
24import type { PlyError } from './errors.js';
25import { fail, argsError } from './errors.js';
26import type { Option, Result } from './result.js';
27import { assertNever, ok, some, none, isSome, getOrElse } from './result.js';
28import type { Input } from './absent.js';
29import { at, mapGet, withDefaults } from './absent.js';
30import { ZERO_OID } from './oid.js';
31import type { TransferOpts, TransferPack, TransferPlan, TransferStepPlan, GeneratedObject, PlanExpect } from './transferplan.js';
32import { checkTransferPlan, planFitsPack, planTransfer, rootCommit, sweepPrefix, tempFor, isTempKey, transferKey, TRANSFER_REF_PREFIX } from './transferplan.js';
33import { packSubset } from './packsubset.js';
34import { pushPackOutcome, pushWithOptions } from './receivecaps.js';
35import { lsRefs } from './lsrefs.js';
36import type { Span } from './otel.js';
37import { KIND } from './otel.js';
38import type { Transport, SpanOpts } from './transport.js';
39import { spanned, withParent } from './transport.js';
41type Oid = TransferPlan['head'];
42type PlannedBatch = TransferPlan['pack']['batches'][number];
43export type TransferNext = { readonly tag: 'step'; readonly step: number } | { readonly tag: 'done'; readonly head: Oid; readonly tempLeft: boolean };
44// done: the ref is at the planned head; tempLeft: a temp ref is still on the destination (a non-atomic last push that
45// did not delete it, or a host that kept it), for sweepTransfers. paused: `step` is next; 'max_steps' when this run used
46// its pushes, 'settling' when the last push was acknowledged but the refs had not shown it after `settle.reads` reads.
47// A pause states two facts about the last push this run made, in two fields, because they can differ:
48// `lastPush` is what the server answered THIS run's push: 'none' the run made no push; 'acknowledged' its report said
49// ok; 'refused' the server refused it; 'unanswered' no report reached this run.
50// `lastStep` is what the refs then showed of the step that push carried, whoever landed it: 'none' the run made no
51// push; 'landed' the refs show the step (by this push or by another runner's: `lastPush: 'refused'` beside
52// `lastStep: 'landed'` is another runner having landed it first); 'not_shown' they did not after `settle.reads` reads.
53// 'max_steps' pauses only after a step shown landed (or no push); 'settling' is 'acknowledged' and 'not_shown'. A step
54// whose outcome is unknown is never a pause: the run ends `ambiguous` (the push's own error is its `cause`).
55export type LastPush = 'none' | 'acknowledged' | 'refused' | 'unanswered';
56export type LastStep = 'none' | 'landed' | 'not_shown';
57export type TransferRun =
58 | { readonly tag: 'done'; readonly head: Oid; readonly pushes: number; readonly tempLeft: boolean }
59 | { readonly tag: 'paused'; readonly step: number; readonly pushes: number; readonly reason: 'max_steps' | 'settling'; readonly lastPush: LastPush; readonly lastStep: LastStep };
60// After a push, reads of the refs (at most `reads`, `delayMs` apart) until they show it.
61export type SettleConfig = { readonly reads: number; readonly delayMs: number };
62// maxSteps: pushes this run may make (default no limit); retries: sends of one step that may stay unsettled (default 2)
63export type RunConfig = { readonly maxSteps: number; readonly retries: number; readonly settle: SettleConfig };
64// with what the plan is held to (PlanExpect): the ref to create, named on every call, and the temp prefix the plan was
65// made under when it is not the default
66export type RunOpts = Input<RunConfig> & PlanExpect;
67export type SweepOpts = Input<{ readonly prefix: string; readonly keep: readonly string[] }>;
68// Measured on Cloudflare Artifacts (2026-11-10, n=64 pushes): the first ls-refs after every ack showed the push (reads
69// p50 = p99 = max = 1; ls-refs p50 129 ms, max 448 ms), so 3 reads 200 ms apart cover every lag seen, with headroom.
70export const SETTLE_DEFAULTS: SettleConfig = Object.freeze({ reads: 3, delayMs: 200 });
72const internal = (t: Transport, attrs: SpanOpts['attrs']): SpanOpts => ({ parent: t.parent, kind: KIND.INTERNAL, attrs, scrub: t.scrub });
73const planAttrs = (plan: TransferPlan): SpanOpts['attrs'] => ({ 'git.transfer.plan.hash': plan.hash, 'git.transfer.steps': plan.steps.length });
74const optionOr = (o: Option<Oid>, fallback: string): string => getOrElse<string>(o, fallback);
75const optionOid = (o: Option<Oid>): string => optionOr(o, '');
76// The step whose temp commit `oid` is (none: no step writes it).
77function stepOf(plan: TransferPlan, oid: string): Option<number> {
78 const found = plan.steps.findIndex(s => s.kind === 'batch' && s.temp === oid);
79 return found < 0 ? none : some(found);
80}
82// Where a checked plan's transfer stands on `dst`, from its refs alone.
83async function readStatus(dst: Transport, plan: TransferPlan): Promise<Result<TransferNext, PlyError>> {
84 const r = await spanned(dst, 'git.transfer.status', internal(dst, planAttrs(plan)), async (span: Span): Promise<Result<TransferNext, PlyError>> => {
85 const listed = await lsRefs(withParent(dst, span), [plan.ref, plan.tempRef]);
86 if (!listed.ok) return listed;
87 const target = mapGet(listed.value.refs, plan.ref);
88 const temp = mapGet(listed.value.refs, plan.tempRef);
89 span.set({ 'git.transfer.status.target': isSome(target) ? target.value.oid : '', 'git.transfer.status.temp': isSome(temp) ? temp.value.oid : '' });
90 if (isSome(target)) {
91 if (target.value.oid !== plan.head) {
92 span.set({ 'git.transfer.status.outcome': 'ref_taken' });
93 return fail('cas_conflict', `transfer: ${plan.ref} already exists at ${target.value.oid}, not the planned ${plan.head}`, { expected: null, actual: target.value.oid, what: 'ref' });
94 }
95 span.set({ 'git.transfer.status.outcome': 'done', 'git.transfer.temp_left': isSome(temp) });
96 return ok({ tag: 'done', head: plan.head, tempLeft: isSome(temp) });
97 }
98 const found = isSome(temp) ? stepOf(plan, temp.value.oid) : some(-1);
99 if (found.tag === 'none') {
100 span.set({ 'git.transfer.status.outcome': 'temp_foreign' });
101 return fail('cas_conflict', `transfer: ${plan.tempRef} is at ${isSome(temp) ? temp.value.oid : ''}, which this plan never writes`, { expected: null, actual: isSome(temp) ? temp.value.oid : null, what: 'ref' });
102 }
103 span.set({ 'git.transfer.status.outcome': 'step', 'git.transfer.step': found.value + 1 });
104 return ok({ tag: 'step', step: found.value + 1 });
105 });
106 return r;
107}
109// Where the transfer stands on `dst`, from its refs alone. The plan is checked first (checkTransferPlan): nothing is
110// read for, and no answer is given from, a plan that does not pass.
111export async function transferStatus(dst: Transport, plan: TransferPlan, expect: PlanExpect): Promise<Result<TransferNext, PlyError>> {
112 const checked = checkTransferPlan(plan, expect);
113 if (!checked.ok) return checked;
114 const next = await readStatus(dst, checked.value);
115 return next;
116}
118// The objects a step adds to its batch: a batch's temp trees and commit, the final step's new commit.
119type StepWork = { readonly s: TransferStepPlan; readonly batch: PlannedBatch; readonly objects: readonly GeneratedObject[] };
120function generated(from: TransferPack, plan: TransferPlan, step: number, commit: Uint8Array): Result<StepWork, PlyError> {
121 const sAt = at(plan.steps, step);
122 const batchAt = at(plan.pack.batches, step);
123 if (!isSome(sAt) || !isSome(batchAt)) return fail('bad_request', `transfer: step ${step} is not in the plan (${plan.steps.length} steps)`, { what: 'step' });
124 const s = sAt.value;
125 const batch = batchAt.value;
126 if (s.kind === 'final') {
127 const root = rootCommit(commit);
128 if (!root.ok) return root;
129 return root.value.commit.oid === plan.head ? ok({ s, batch, objects: [root.value.commit] }) : fail('bad_request', 'transfer: the commit does not give the planned head', { what: 'commit' });
130 }
131 const made = tempFor(from.resolved, batch.entries, { key: transferKey(plan), step, steps: plan.steps.length, prev: s.prev });
132 if (!made.ok) return made;
133 return made.value.commit.oid === s.temp ? ok({ s, batch, objects: made.value.objects }) : fail('bad_request', `transfer: step ${step}'s objects do not give the planned temp commit; the pack is not the one planned`, { what: 'pack' });
134}
136// A step's ref updates: a batch moves the temp ref (created when there is no prev); the final step creates the ref and,
137// when there is a temp ref, deletes it in the same push.
138type Command = { readonly ref: string; readonly oldOid: string; readonly newOid: string };
139function commandsOf(plan: TransferPlan, s: TransferStepPlan): readonly [Command, ...Command[]] {
140 if (s.kind === 'batch') return [{ ref: plan.tempRef, oldOid: optionOr(s.prev, ZERO_OID), newOid: s.temp }];
141 const create: Command = { ref: plan.ref, oldOid: ZERO_OID, newOid: plan.head };
142 return isSome(s.prev) ? [create, { ref: plan.tempRef, oldOid: s.prev.value, newOid: ZERO_OID }] : [create];
143}
145// What one push reads: the plan, the spool and the source commit's bytes (the final step rebuilds the new commit).
146type StepInput = { readonly from: TransferPack; readonly plan: TransferPlan; readonly step: number; readonly commit: Uint8Array };
147// Err: refused here, before any request to the destination (nothing can have landed). Ok: the push was made, and
148// `pushed` is what it came to.
149type Pushed = Result<{ readonly step: number }, PlyError>;
150async function sendStep(dst: Transport, span: Span, { from, plan, step, commit }: StepInput): Promise<Result<{ readonly pushed: Pushed }, PlyError>> {
151 const extras = generated(from, plan, step, commit);
152 if (!extras.ok) return extras;
153 const { s, batch, objects } = extras.value;
154 span.set({ 'git.transfer.step.kind': s.kind, 'git.transfer.step.prev': optionOid(s.prev), 'git.transfer.batch.entries': batch.entries.length, 'git.transfer.batch.planned_bytes': batch.packBytes, 'git.transfer.generated.objects': objects.length });
155 const subset = await packSubset(from.source, from.pack, batch.entries, { extras: objects.map(o => ({ type: o.type, data: o.data })), outsideBase: plan.pack.crossBatchRef ? 'ref' : 'refuse', resolved: from.resolved });
156 if (!subset.ok) return subset;
157 span.set({ 'git.transfer.batch.bytes': subset.value.length, 'git.transfer.batch.objects': subset.value.count });
158 const commands = commandsOf(plan, s);
159 const sent = await pushPackOutcome(dst, { commands, pack: subset.value.stream, length: subset.value.length, atomic: commands.length > 1 && plan.atomic });
160 switch (sent.sent) {
161 // no push request reached receive-pack (refused here, the advertisement not read, or the body never pulled): the
162 // failure as it is, no settle, not counted (README, Resumable transfer)
163 case 'no': return sent.result;
164 case 'yes': return ok({ pushed: sent.result.ok ? ok({ step }) : sent.result });
165 }
166 // Stryker disable next-line ConditionalExpression: unreachable, the compiler's exhaustiveness check
167 return assertNever(sent);
168}
170// One push: step `step` of `plan` (checked, and held to the pack: planFitsPack), its entries read from `from.source`. `commit` is the source commit's bytes (the
171// final step rebuilds the new commit from them). Every update is a compare-and-swap, so a step that already landed is
172// refused by the server (`ng … stale ref`), never applied twice.
173async function stepSpan(dst: Transport, input: StepInput): Promise<Result<{ readonly pushed: Pushed }, PlyError>> {
174 const r = await spanned(dst, 'git.transfer.step', internal(dst, { ...planAttrs(input.plan), 'git.transfer.step': input.step }), async (span: Span): Promise<Result<{ readonly pushed: Pushed }, PlyError>> => {
175 const sent = await sendStep(withParent(dst, span), span, input);
176 const outcome: Pushed = sent.ok ? sent.value.pushed : sent;
177 span.set({ 'git.transfer.step.outcome': outcome.ok ? 'landed' : outcome.error.code });
178 if (sent.ok && !sent.value.pushed.ok) span.error(sent.value.pushed.error);
179 return sent;
180 });
181 return r;
182}
183// The plan is checked first (checkTransferPlan). `given` is the source commit's bytes with what the plan is held to on
184// this call (PlanExpect: the ref it creates, the temp prefix it was planned under). A call that names no ref (the bare
185// bytes an earlier version took) is refused.
186export type StepCommit = PlanExpect & { readonly commit: Uint8Array };
187export async function transferStep(dst: Transport, from: TransferPack, plan: TransferPlan, step: number, given: StepCommit): Promise<Result<{ readonly step: number }, PlyError>> {
188 const checked = checkTransferPlan(plan, given);
189 if (!checked.ok) return checked;
190 if (!(given.commit instanceof Uint8Array)) return fail('bad_request', 'transfer: `commit` is the source commit\'s bytes', { what: 'commit' });
191 const fits = planFitsPack(checked.value, from.pack, from.resolved);
192 if (!fits.ok) return fits;
193 const r = await stepSpan(dst, { from, plan: checked.value, step, commit: given.commit });
194 return r.ok ? r.value.pushed : r;
195}
197const pause = async (ms: number): Promise<void> => { if (ms > 0) await new Promise<void>(resolve => { setTimeout(resolve, ms); }); };
198// readStatus fails two ways: the refs were read and show a state this plan cannot go on from (`cas_conflict`, which
199// no read returns), or they could not be read.
200const refsConflict = (e: PlyError): boolean => e.code === 'cas_conflict';
201// Settling: the refs read back after a push of `step` until they show it (the transfer past `step`, or done), at most
202// `cfg.reads` reads. 'moved' carries the status that showed it; 'still' the reads that did not; 'conflict' the refs
203// show another writer's state; 'unread' a read failed: where the destination stands is not known.
204type Settled =
205 | { readonly tag: 'moved'; readonly next: TransferNext }
206 | { readonly tag: 'still'; readonly reads: number }
207 | { readonly tag: 'conflict'; readonly error: PlyError }
208 | { readonly tag: 'unread'; readonly error: PlyError };
209async function settleFrom(dst: Transport, plan: TransferPlan, step: number, cfg: SettleConfig, reads: number): Promise<Settled> {
210 if (reads >= cfg.reads) return { tag: 'still', reads };
211 if (reads > 0) await pause(cfg.delayMs);
212 const next = await readStatus(dst, plan);
213 if (!next.ok) return { tag: refsConflict(next.error) ? 'conflict' : 'unread', error: next.error };
214 if (next.value.tag === 'done' || next.value.step > step) return { tag: 'moved', next: next.value };
215 return settleFrom(dst, plan, step, cfg, reads + 1);
216}
217async function settle(dst: Transport, plan: TransferPlan, step: number, cfg: SettleConfig): Promise<Settled> {
218 const settled = await spanned(dst, 'git.transfer.settle', internal(dst, { ...planAttrs(plan), 'git.transfer.step': step }), async (span: Span): Promise<Result<Settled, PlyError>> => {
219 const r = await settleFrom(withParent(dst, span), plan, step, cfg, 0);
220 span.set({ 'git.transfer.settle.outcome': r.tag, 'git.transfer.settle.reads': r.tag === 'still' ? r.reads : 0 });
221 if (r.tag === 'conflict' || r.tag === 'unread') span.error(r.error);
222 return ok(r);
223 });
224 // the span's function never fails; a tracer that does leaves the destination unread
225 return settled.ok ? settled.value : { tag: 'unread', error: settled.error };
226}
228type Loop = { readonly pushes: number; readonly tries: number; readonly lastPush: LastPush; readonly lastStep: LastStep };
229type Run = { readonly dst: Transport; readonly span: Span; readonly from: TransferPack; readonly plan: TransferPlan; readonly commit: Uint8Array; readonly cfg: RunConfig };
230type Turn = { readonly step: number; readonly pushes: number; readonly tries: number };
231// The step's outcome is unknown: its push's is, and the refs do not show it (or could not be read).
232const unknown = (step: number, why: string, cause: PlyError): Result<TransferRun, PlyError> =>
233 fail('ambiguous', `transfer: step ${step} ${why}`, { what: 'step', cause, original: cause.code });
234// What the run does after a push and the refs read back: end with `result`, or go on from `next` (`tries`: sends of
235// that step so far whose outcome is unknown).
236type After = { readonly tag: 'end'; readonly result: Result<TransferRun, PlyError> } | { readonly tag: 'go'; readonly next: TransferNext; readonly tries: number; readonly lastStep: LastStep };
237const end = (result: Result<TransferRun, PlyError>): After => ({ tag: 'end', result });
239// A push the server acknowledged, then the refs: shown, the run goes on; not shown yet, a later run reads them again
240// (never sent again on a lagging read); unread after the final push, the acknowledgement is the outcome (every command
241// ok: the ref created, the temp ref deleted); unread after a batch, the read's failure (the transfer is not done).
242function acknowledged(plan: TransferPlan, settled: Settled, { step, pushes }: Turn): After {
243 switch (settled.tag) {
244 case 'moved': return { tag: 'go', next: settled.next, tries: 0, lastStep: 'landed' };
245 case 'still': return end(ok({ tag: 'paused', step, pushes, reason: 'settling', lastPush: 'acknowledged', lastStep: 'not_shown' }));
246 case 'unread': return end(step === plan.steps.length - 1 ? ok({ tag: 'done', head: plan.head, pushes, tempLeft: false }) : { ok: false, error: settled.error });
247 case 'conflict': return end({ ok: false, error: settled.error });
248 }
249 return assertNever(settled);
250}
251// A push that was not a clean ok (ambiguous, rejected, partial), judged by the destination: the step landed (this push
252// or another runner's) is progress; the refs could not be read is ambiguous, carrying the push's own error; it did not
253// land and the push was refused is that refusal; it did not land and the push was ambiguous is sent again, at most
254// `retries` times and within `maxSteps`, then ambiguous (never a pause: the caller owns the retry policy).
255function unclean(cfg: RunConfig, error: PlyError, settled: Settled, { step, pushes, tries }: Turn): After {
256 const refused = error.code !== 'ambiguous';
257 switch (settled.tag) {
258 case 'moved': return { tag: 'go', next: settled.next, tries: 0, lastStep: 'landed' };
259 case 'unread': return end(unknown(step, `was pushed (${error.code}) and the refs could not be read: whether it landed is not known`, error));
260 case 'conflict': return end({ ok: false, error: refused ? error : settled.error });
261 case 'still': {
262 if (refused) return end({ ok: false, error });
263 if (tries > cfg.retries) return end(unknown(step, `did not land after ${tries} tries`, error));
264 if (pushes >= cfg.maxSteps) return end(unknown(step, `did not land: its push's outcome is not known and the refs do not show it (${tries} sent, maxSteps reached)`, error));
265 return { tag: 'go', next: { tag: 'step', step }, tries, lastStep: 'not_shown' };
266 }
267 }
268 return assertNever(settled);
269}
271// What the server answered a push this run made (`ambiguous` is ply's class for a push with no report).
272function answered(pushed: Pushed): LastPush {
273 if (pushed.ok) return 'acknowledged';
274 return pushed.error.code === 'ambiguous' ? 'unanswered' : 'refused';
275}
276// One turn of the loop, then the next by recursion (each push waits on the status the last one left). `next` is where
277// the destination stands; a pause here follows a landed push or none (an unknown one never reaches it).
278async function turn(run: Run, next: TransferNext, st: Loop): Promise<Result<TransferRun, PlyError>> {
279 const { dst, span, from, plan, commit, cfg } = run;
280 if (next.tag === 'done') return ok({ tag: 'done', head: next.head, pushes: st.pushes, tempLeft: next.tempLeft });
281 const { step } = next;
282 if (st.pushes >= cfg.maxSteps) return ok({ tag: 'paused', step, pushes: st.pushes, reason: 'max_steps', lastPush: st.lastPush, lastStep: st.lastStep });
283 const sent = await stepSpan(dst, { from, plan, step, commit });
284 // refused here, before any request: nothing to read
285 if (!sent.ok) return sent;
286 const pushes = st.pushes + 1;
287 span.set({ 'git.transfer.pushes': pushes });
288 const settled = await settle(dst, plan, step, cfg.settle);
289 const { pushed } = sent.value;
290 const after = pushed.ok ? acknowledged(plan, settled, { step, pushes, tries: 0 }) : unclean(cfg, pushed.error, settled, { step, pushes, tries: st.tries + 1 });
291 return after.tag === 'end' ? after.result : turn(run, after.next, { pushes, tries: after.tries, lastPush: answered(pushed), lastStep: after.lastStep });
292}
294// The loop (see the top of this file). The destination is the only commit point, so after every push the refs are read
295// back (settle) and the run's result is what they show: see `acknowledged` and `unclean`. The plan is checked first
296// (checkTransferPlan, held to `opts.tempPrefix` and `opts.ref`), and `commit` must give the planned head, so `done` is
297// never answered from a plan that does not pass or for a head the caller's commit does not give.
298export async function runTransfer(dst: Transport, from: TransferPack, stored: TransferPlan, commit: Uint8Array, opts: RunOpts): Promise<Result<TransferRun, PlyError>> {
299 const cfg = withDefaults<RunConfig>(opts, { maxSteps: Number.POSITIVE_INFINITY, retries: 2, settle: SETTLE_DEFAULTS });
300 const checked = checkTransferPlan(stored, opts);
301 if (!checked.ok) return checked;
302 // the same refusal transferStep gives, before any use of the bytes
303 if (!(commit instanceof Uint8Array)) return fail('bad_request', 'transfer: `commit` is the source commit\'s bytes', { what: 'commit' });
304 const plan = checked.value;
305 const fits = planFitsPack(plan, from.pack, from.resolved);
306 if (!fits.ok) return fits;
307 const root = rootCommit(commit);
308 if (!root.ok) return root;
309 if (root.value.commit.oid !== plan.head) return fail('bad_request', 'transfer: the commit does not give the planned head', { what: 'commit' });
310 const run = await spanned(dst, 'git.transfer.run', internal(dst, { ...planAttrs(plan), 'git.transfer.ref': plan.ref, 'git.transfer.head': plan.head }), async (span: Span): Promise<Result<TransferRun, PlyError>> => {
311 const t = withParent(dst, span);
312 const first = await readStatus(t, plan);
313 const r = first.ok ? await turn({ dst: t, span, from, plan, commit, cfg }, first.value, { pushes: 0, tries: 0, lastPush: 'none', lastStep: 'none' }) : first;
314 if (r.ok) span.set({ 'git.transfer.outcome': r.value.tag === 'done' ? 'done' : `paused_${r.value.reason}`, 'git.transfer.pushes': r.value.pushes, 'git.transfer.temp_left': r.value.tag === 'done' && r.value.tempLeft });
315 else span.set({ 'git.transfer.outcome': r.error.code });
316 return r;
317 });
318 return run;
319}
321// Plan and run in one call (a caller with the time to finish, or the first request of several: keep the plan it gives).
322export async function copyTree(dst: Transport, from: TransferPack, opts: TransferOpts & RunOpts): Promise<Result<{ readonly plan: TransferPlan; readonly run: TransferRun }, PlyError>> {
323 const shape = argsError('copyTree', [['dst', dst, 'object'], ['from', from, 'object'], ['options', opts, 'object']]);
324 if (shape !== null) return shape;
325 const plan = planTransfer(from.pack, from.resolved, opts);
326 if (!plan.ok) return plan;
327 const run = await runTransfer(dst, from, plan.value, opts.commit, opts);
328 return run.ok ? ok({ plan: plan.value, run: run.value }) : run;
329}
331// Delete temp refs under `prefix` (default refs/ply/transfer/) but those in `keep`: what an abandoned transfer left.
332// Only names of a temp ref's shape (`<prefix><40 hex key>`) are deleted; a prefix outside refs/ply/transfer/ is
333// bad_request (what: 'prefix') before any request.
334export async function sweepTransfers(dst: Transport, opts: SweepOpts = {}): Promise<Result<readonly string[], PlyError>> {
335 const { prefix: asked, keep: kept } = withDefaults<{ readonly prefix: string; readonly keep: readonly string[] }>(opts, { prefix: TRANSFER_REF_PREFIX, keep: [] });
336 const checked = sweepPrefix(asked, TRANSFER_REF_PREFIX);
337 if (!checked.ok) return checked;
338 const prefix = checked.value;
339 const swept = await spanned(dst, 'git.transfer.sweep', internal(dst, { 'git.transfer.sweep.prefix': prefix, 'git.transfer.sweep.kept': kept.length }), async (span: Span): Promise<Result<readonly string[], PlyError>> => {
340 const t = withParent(dst, span);
341 const keep = new Set(kept);
342 const listed = await lsRefs(t, [prefix]);
343 if (!listed.ok) return listed;
344 const gone = [...listed.value.refs.values()].filter(r => r.name.startsWith(prefix) && isTempKey(r.name.slice(prefix.length)) && !keep.has(r.name));
345 const deletes = gone.map(r => ({ ref: r.name, oldOid: r.oid, newOid: ZERO_OID }));
346 span.set({ 'git.transfer.sweep.deleted': deletes.length });
347 const head = at(deletes, 0);
348 if (!isSome(head)) return ok([]);
349 const pushed = await pushWithOptions(t, { commands: [head.value, ...deletes.slice(1)] });
350 return pushed.ok ? ok(gone.map(r => r.name)) : pushed;
351 });
352 return swept;
353}
Diagnostics4 git calls · 335 ms
CallStatusSizeTime0335 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 B3 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=UPDATING 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 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=55Open pack map
fetch2007.8 KiB329 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=329 git.response.bytes=7986 git.response.cache=MISS git.response.duration_ms=329 git.fetch.wants=dcf6d435883439f693fe31fa1c47459b18d301c5 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=7986 git.pkt.payload.max=7965 git.sideband.band1.bytes=7964 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
- a5e2a4520e391293
- Request
- 1133b163…
- Protocol
- v2 · sha1
- Agent
- gitty/1.0
- Filter
- advertised
- Fetch
- shallow filter sideband-all
- Capabilities
- agent ls-refs fetch object-format