@futurelastic/colab-handbook 1.13.0-rc.1 → 1.13.0-rc.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/tools/colab +19 -6
- package/tools/lib/ci-wait.js +28 -8
- package/tools/lib/git.js +22 -1
package/package.json
CHANGED
package/tools/colab
CHANGED
|
@@ -14222,13 +14222,15 @@ Wait for CI and exit with its outcome. The ONE way to wait for a run: never hand
|
|
|
14222
14222
|
--sha <sha> wait for EVERY repo-owned workflow at the sha (the verdict colab ship reads:
|
|
14223
14223
|
newest run per workflow, dynamic workflows dropped — #451/#461; only runs that
|
|
14224
14224
|
verify the code, so a post-CI release/deploy run is set aside — #503); a sha
|
|
14225
|
-
with no run yet counts as pending until the deadline
|
|
14225
|
+
with no run yet counts as pending until the deadline. An abbreviated sha is
|
|
14226
|
+
resolved in the repo first, and refused (exit 2) when it does not resolve — #529
|
|
14226
14227
|
--branch <b> narrow --sha to runs on that branch
|
|
14227
14228
|
--timeout <d> deadline: 45m (default), 90s, 1h, or seconds
|
|
14228
14229
|
|
|
14229
14230
|
Polls at 0s, then +30s, +60s, +120s, +120s … until the deadline. Every poll after the first is a
|
|
14230
|
-
conditional request (If-None-Match); a 304 is not counted against the REST rate limit.
|
|
14231
|
-
|
|
14231
|
+
conditional request (If-None-Match); a 304 is not counted against the REST rate limit. After two
|
|
14232
|
+
304s in a row, and on the last poll before the deadline, it re-reads unconditionally: a stale ETag
|
|
14233
|
+
can cost one paid call, never the whole wait (#505). A 15-minute run costs about 10 requests. One wait per run per checkout: a second waiter is refused.
|
|
14232
14234
|
|
|
14233
14235
|
Exit codes — branch on these, never on the text:
|
|
14234
14236
|
0 GREEN the run (every judged run at the sha) succeeded
|
|
@@ -14240,7 +14242,7 @@ Exit codes — branch on these, never on the text:
|
|
|
14240
14242
|
6 ALREADY_WAITING another live ci-wait on this checkout holds the same run/sha
|
|
14241
14243
|
|
|
14242
14244
|
It prints the wait it did: outcome, elapsed time, polls, and how many were 304s.
|
|
14243
|
-
--json { outcome, exit, target, polls, notModified, waitedSec, detail, status, conclusion, url }`;
|
|
14245
|
+
--json { outcome, exit, target, polls, notModified, forced, waitedSec, detail, status, conclusion, url }`;
|
|
14244
14246
|
|
|
14245
14247
|
function cmdCiWait(argv) {
|
|
14246
14248
|
const opts = parseArgs(argv, {
|
|
@@ -14256,6 +14258,17 @@ function cmdCiWait(argv) {
|
|
|
14256
14258
|
const deadlineSec = opts.timeout !== undefined ? ciWait.parseDuration(opts.timeout) : ciWait.DEFAULT_DEADLINE_SEC;
|
|
14257
14259
|
if (!deadlineSec) { warn(`--timeout: cannot read "${opts.timeout}" (try 45m, 90s, 1h)`); return ciWait.EXIT.USAGE; }
|
|
14258
14260
|
const repoAbs = resolveRepo(opts);
|
|
14261
|
+
if (opts.sha) {
|
|
14262
|
+
// #529: the API reports a 40-hex head_sha and the rows are matched by equality, so an
|
|
14263
|
+
// abbreviated --sha would match nothing and wait out the whole deadline as "pending" — on a run
|
|
14264
|
+
// that finished green in minutes. Resolve it here, or refuse; never poll with it.
|
|
14265
|
+
const full = git.fullSha(repoAbs, opts.sha);
|
|
14266
|
+
if (!full) {
|
|
14267
|
+
warn(`--sha ${opts.sha}: not a full 40-hex sha and it does not resolve to one commit in ${repoAbs} — pass the full sha (\`git rev-parse <sha>\`), or fetch first`);
|
|
14268
|
+
return ciWait.EXIT.USAGE;
|
|
14269
|
+
}
|
|
14270
|
+
opts.sha = full;
|
|
14271
|
+
}
|
|
14259
14272
|
if (!git.ghInstalled()) { warn('gh is not installed — cannot read CI'); return ciWait.EXIT.UNKNOWN; }
|
|
14260
14273
|
|
|
14261
14274
|
const target = runId ? `run ${runId}` : `sha ${shortSha(opts.sha)}${opts.branch ? ` on ${opts.branch}` : ''}`;
|
|
@@ -14294,7 +14307,7 @@ function cmdCiWait(argv) {
|
|
|
14294
14307
|
try {
|
|
14295
14308
|
res = ciWait.waitLoop({
|
|
14296
14309
|
poll, sleep: ciWait.sleepSync, deadlineSec,
|
|
14297
|
-
onPoll: (p) => { if (!opts.json) process.stderr.write(`ci-wait: poll ${p.poll} at +${ciWait.fmtDuration(p.elapsedMs)} — ${p.state}${p.notModified ? ' (304, not counted)' : ''}\n`); },
|
|
14310
|
+
onPoll: (p) => { if (!opts.json) process.stderr.write(`ci-wait: poll ${p.poll} at +${ciWait.fmtDuration(p.elapsedMs)} — ${p.state}${p.notModified ? ' (304, not counted)' : ''}${p.forced ? ' (unconditional re-read — #505)' : ''}\n`); },
|
|
14298
14311
|
});
|
|
14299
14312
|
} finally {
|
|
14300
14313
|
lock.release();
|
|
@@ -14302,7 +14315,7 @@ function cmdCiWait(argv) {
|
|
|
14302
14315
|
const s = (res.last && res.last.summary) || {};
|
|
14303
14316
|
const code = ciWait.EXIT[res.outcome];
|
|
14304
14317
|
const out = {
|
|
14305
|
-
outcome: res.outcome, exit: code, target, polls: res.polls, notModified: res.notModified,
|
|
14318
|
+
outcome: res.outcome, exit: code, target, polls: res.polls, notModified: res.notModified, forced: res.forced,
|
|
14306
14319
|
waitedSec: Math.round(res.waitedMs / 1000), detail: res.detail || null,
|
|
14307
14320
|
status: s.status || null, conclusion: s.conclusion || null, url: s.url || null,
|
|
14308
14321
|
...(Array.isArray(s.setAside) && s.setAside.length ? { setAside: s.setAside } : {}),
|
package/tools/lib/ci-wait.js
CHANGED
|
@@ -13,7 +13,8 @@
|
|
|
13
13
|
* run costs ~10 polls instead of ~180 at `sleep 5`;
|
|
14
14
|
* - conditional requests: every poll after the first sends `If-None-Match`, and a `304 Not
|
|
15
15
|
* Modified` is not counted against the primary rate limit (GitHub REST docs, "conditional
|
|
16
|
-
* requests")
|
|
16
|
+
* requests") — capped (#505): after two 304s in a row, and on the deadline's poll, it re-reads
|
|
17
|
+
* unconditionally, because a validator that never changes would otherwise pin a stale state;
|
|
17
18
|
* - a rate limit (403 with remaining 0, or 429) ENDS the wait with its own outcome — never a retry;
|
|
18
19
|
* - an unreadable or unrecognised state ends it too (UNKNOWN), never "keep waiting";
|
|
19
20
|
* - one wait per run per checkout: a second waiter on the same key is refused (ALREADY_WAITING).
|
|
@@ -112,19 +113,32 @@ function runState(s) {
|
|
|
112
113
|
return 'unknown';
|
|
113
114
|
}
|
|
114
115
|
|
|
116
|
+
/**
|
|
117
|
+
* #505: how many 304s in a row may stand for the state before the next poll re-reads without
|
|
118
|
+
* `If-None-Match`. Measured: the runs-list read kept answering 304 for ten minutes while every run
|
|
119
|
+
* at the sha had completed green — the validator never changed, so a loop that trusted it would
|
|
120
|
+
* have reported TIMEOUT on a green sha. A cap of 2 bounds that to one paid call per three polls.
|
|
121
|
+
*/
|
|
122
|
+
const DEFAULT_MAX_NOT_MODIFIED = 2;
|
|
123
|
+
|
|
115
124
|
/**
|
|
116
125
|
* The wait loop. `poll(etag)` returns a classifyResponse() result, plus `state` (runState) and
|
|
117
|
-
* `summary` on `ok`. `sleep(ms)` blocks; `now()` is epoch ms. A 304 keeps the previous state
|
|
126
|
+
* `summary` on `ok`. `sleep(ms)` blocks; `now()` is epoch ms. A 304 keeps the previous state — but
|
|
127
|
+
* only for `maxNotModified` polls in a row, and never on the last poll before the deadline: those
|
|
128
|
+
* polls send no ETag (`poll(null)`), so a stale validator costs one paid read, not the wait (#505).
|
|
118
129
|
*
|
|
119
|
-
* Returns `{ outcome, polls, notModified, waitedMs, last, detail }`, outcome one of the
|
|
130
|
+
* Returns `{ outcome, polls, notModified, forced, waitedMs, last, detail }`, outcome one of the
|
|
131
|
+
* EXIT keys; `forced` counts the unconditional re-reads #505 added.
|
|
120
132
|
*/
|
|
121
133
|
function waitLoop({ poll, sleep, now = Date.now, deadlineSec = DEFAULT_DEADLINE_SEC,
|
|
122
|
-
schedule = DEFAULT_SCHEDULE_SEC, onPoll = () => {} }) {
|
|
134
|
+
schedule = DEFAULT_SCHEDULE_SEC, maxNotModified = DEFAULT_MAX_NOT_MODIFIED, onPoll = () => {} }) {
|
|
123
135
|
const start = now();
|
|
124
136
|
let etag = null;
|
|
125
137
|
let last = null;
|
|
126
138
|
let polls = 0;
|
|
127
139
|
let notModified = 0;
|
|
140
|
+
let streak = 0; // consecutive 304s
|
|
141
|
+
let forced = 0;
|
|
128
142
|
for (let i = 0; ; i++) {
|
|
129
143
|
const d = delayFor(i, schedule) * 1000;
|
|
130
144
|
if (d) {
|
|
@@ -132,25 +146,31 @@ function waitLoop({ poll, sleep, now = Date.now, deadlineSec = DEFAULT_DEADLINE_
|
|
|
132
146
|
if (left <= 0) return done('TIMEOUT', `still ${last ? last.state : 'unread'} at the ${fmtDuration(deadlineSec * 1000)} deadline`);
|
|
133
147
|
sleep(Math.min(d, left));
|
|
134
148
|
}
|
|
135
|
-
|
|
149
|
+
// The poll that lands on the deadline is the last one: it must read the truth, not a 304.
|
|
150
|
+
const final = now() - start >= deadlineSec * 1000;
|
|
151
|
+
const force = Boolean(etag) && (streak >= maxNotModified || final);
|
|
152
|
+
if (force) forced++;
|
|
153
|
+
const r = poll(force ? null : etag);
|
|
136
154
|
polls++;
|
|
137
155
|
if (r.kind === 'rate-limited') return done('RATE_LIMITED', r.detail + (r.resetAt ? ` — quota resets ${new Date(r.resetAt).toISOString()}` : ''), r);
|
|
138
156
|
if (r.kind === 'error') return done('UNKNOWN', `read failed: ${r.detail}`, r);
|
|
139
157
|
if (r.kind === 'not-modified') {
|
|
140
158
|
notModified++;
|
|
159
|
+
streak++;
|
|
141
160
|
if (!last) return done('UNKNOWN', '304 on the first read — nothing to compare against', r);
|
|
142
161
|
} else {
|
|
162
|
+
streak = 0;
|
|
143
163
|
etag = r.etag || etag;
|
|
144
164
|
last = r;
|
|
145
165
|
}
|
|
146
|
-
onPoll({ poll: polls, state: last.state, notModified: r.kind === 'not-modified', elapsedMs: now() - start });
|
|
166
|
+
onPoll({ poll: polls, state: last.state, notModified: r.kind === 'not-modified', forced: force, elapsedMs: now() - start });
|
|
147
167
|
if (last.state === 'green') return done('GREEN', null);
|
|
148
168
|
if (last.state === 'red') return done('RED', null);
|
|
149
169
|
if (last.state !== 'pending') return done('UNKNOWN', `unrecognised state (${JSON.stringify(last.summary || null)})`);
|
|
150
170
|
if (now() - start >= deadlineSec * 1000) return done('TIMEOUT', `still pending at the ${fmtDuration(deadlineSec * 1000)} deadline`);
|
|
151
171
|
}
|
|
152
172
|
function done(outcome, detail, r) {
|
|
153
|
-
return { outcome, polls, notModified, waitedMs: now() - start, last: last || r || null, detail };
|
|
173
|
+
return { outcome, polls, notModified, forced, waitedMs: now() - start, last: last || r || null, detail };
|
|
154
174
|
}
|
|
155
175
|
}
|
|
156
176
|
|
|
@@ -197,7 +217,7 @@ function sleepSync(ms) {
|
|
|
197
217
|
}
|
|
198
218
|
|
|
199
219
|
module.exports = {
|
|
200
|
-
EXIT, DEFAULT_SCHEDULE_SEC, DEFAULT_DEADLINE_SEC,
|
|
220
|
+
EXIT, DEFAULT_SCHEDULE_SEC, DEFAULT_DEADLINE_SEC, DEFAULT_MAX_NOT_MODIFIED,
|
|
201
221
|
delayFor, parseHttp, classifyResponse, restRow, runState, waitLoop, fmtDuration, parseDuration,
|
|
202
222
|
acquireLock, sleepSync,
|
|
203
223
|
};
|
package/tools/lib/git.js
CHANGED
|
@@ -886,6 +886,10 @@ function ghRunForSha(repo, branch, limit = 10, remote = remoteInfo(repo).name ||
|
|
|
886
886
|
* branch head.
|
|
887
887
|
*/
|
|
888
888
|
function ghRunsForCommit(repo, branch, sha, limit = 10) {
|
|
889
|
+
// #529: every row filter below is strict equality against a 40-hex head_sha. An abbreviated sha
|
|
890
|
+
// would filter to [] — read by every caller as "no runs yet" — so resolve it, and when it cannot
|
|
891
|
+
// be resolved answer null ("the read failed"), never an empty set.
|
|
892
|
+
sha = fullSha(repo, sha);
|
|
889
893
|
if (!sha) return null;
|
|
890
894
|
|
|
891
895
|
// #495: one REST call (`actions/runs?head_sha=&branch=`) instead of `gh run list`'s two (runs +
|
|
@@ -940,12 +944,29 @@ function ghApiConditional(repo, apiPath, etag) {
|
|
|
940
944
|
return ciWait.classifyResponse({ ...http, stderr: r.stderr });
|
|
941
945
|
}
|
|
942
946
|
|
|
947
|
+
/**
|
|
948
|
+
* #529: `sha` as the full 40-hex object name the Actions API reports as `head_sha`, or null. A
|
|
949
|
+
* 40-hex value passes through (lowercased) without a local lookup — the commit may exist only on
|
|
950
|
+
* the remote. Anything shorter is resolved with `git rev-parse --verify <sha>^{commit}` in `repo`;
|
|
951
|
+
* unresolvable (unknown here, or ambiguous) is null. Never a prefix match: a short sha can be
|
|
952
|
+
* ambiguous across runs, and a match against the wrong run is worse than a refusal.
|
|
953
|
+
*/
|
|
954
|
+
function fullSha(repo, sha) {
|
|
955
|
+
const s = String(sha || '').trim();
|
|
956
|
+
if (/^[0-9a-f]{40}$/i.test(s)) return s.toLowerCase();
|
|
957
|
+
if (!/^[0-9a-f]{4,39}$/i.test(s)) return null;
|
|
958
|
+
const r = git(['rev-parse', '--verify', '--quiet', `${s}^{commit}`], repo);
|
|
959
|
+
const out = r.ok ? r.stdout.trim() : '';
|
|
960
|
+
return /^[0-9a-f]{40}$/.test(out) ? out : null;
|
|
961
|
+
}
|
|
962
|
+
|
|
943
963
|
/**
|
|
944
964
|
* Every workflow run at `sha` in ONE REST call (#495) — `actions/runs?head_sha=<sha>[&branch=<b>]`,
|
|
945
965
|
* rows in `gh run list --json` shape. Returns `{ rows }` on success, `{ rateLimited: true }` on a
|
|
946
966
|
* rate limit, `{}` on any other failure (the caller decides whether to fall back).
|
|
947
967
|
*/
|
|
948
968
|
function ghRunsAtShaRest(repo, sha, branch) {
|
|
969
|
+
sha = fullSha(repo, sha); // #529: the API's head_sha is 40-hex; an abbreviated one matches no row
|
|
949
970
|
if (!sha) return {};
|
|
950
971
|
const ciWait = require('./ci-wait');
|
|
951
972
|
const q = `head_sha=${encodeURIComponent(sha)}${branch ? `&branch=${encodeURIComponent(branch)}` : ''}&per_page=100`;
|
|
@@ -1311,7 +1332,7 @@ module.exports = {
|
|
|
1311
1332
|
claimRemote, remoteHeads,
|
|
1312
1333
|
worktreeList, worktreeListDetailed, resolveWorktreePathForBranch, gitFailureLine,
|
|
1313
1334
|
dirtyTracked, dirtyUntracked, dirtyAny,
|
|
1314
|
-
ghAvailable, ghState, ghInstalled, ghApiConditional, ghRunsAtShaRest, ghIssueEdit, ghListLabels, ghOpenIssueNumbersByLabel, ghAssignedIssues,
|
|
1335
|
+
ghAvailable, ghState, ghInstalled, ghApiConditional, ghRunsAtShaRest, fullSha, ghIssueEdit, ghListLabels, ghOpenIssueNumbersByLabel, ghAssignedIssues,
|
|
1315
1336
|
ghCurrentLogin, ghIssueView, ghIssueComment, ghRunForSha, ghRunForCommit, ghRunsForCommit, ghRunsForRef, ghRunsAtCommit, ghRunForCommitAnyRef, commitTimeMs, ghRunsSince, summarizeRunsForCommit, isRepoOwnedRun,
|
|
1316
1337
|
ghRunJobCount, ghRunJobs, ghWorkflowDispatch,
|
|
1317
1338
|
ghIssueListByLabel, ghLabelDelete, ghLabelCreate, ghListLabelsDetailed, ghLabelEditDescription,
|