@futurelastic/colab-handbook 1.12.0-rc.31 → 1.12.0-rc.32

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 CHANGED
@@ -27,5 +27,5 @@
27
27
  "engines": {
28
28
  "node": ">=18"
29
29
  },
30
- "version": "1.12.0-rc.31"
30
+ "version": "1.12.0-rc.32"
31
31
  }
@@ -167,6 +167,33 @@ env:
167
167
  # a template
168
168
  HANDBOOK_REF: "stable"
169
169
  HANDBOOK_REPO: "https://github.com/futurelastic/colab-handbook.git"
170
+ # A TRANSIENT UPSTREAM ERROR NEVER TURNS MAIN RED (#464). This run fires on every landing, and a
171
+ # red run at main's head blocks every `colab ship` — so a GitHub / registry 5xx, a 429, a timeout
172
+ # or a dropped connection must not fail a step that a plain re-run would pass. Every step that
173
+ # talks to the network runs its call through `retry_transient` (each step `eval`s this block):
174
+ # the command is re-run with backoff while its output names a transient error, up to
175
+ # RETRY_ATTEMPTS times, and the last attempt's output and exit code are what the step sees. A
176
+ # persistent transient error still fails, with its message; anything else fails at once.
177
+ # Retrying is only safe because every retried call is idempotent — a read, or a write whose
178
+ # re-run after success is a no-op (`colab release cut/finalize/promote` read a head already done
179
+ # as a no-op; a Release or npm version that already exists is a skip). Keep that true if you add one.
180
+ RETRY_ATTEMPTS: "4" # EDIT: tries per call; backoff 5s, 10s, 20s between them.
181
+ RETRY_TRANSIENT: |
182
+ exec 3>&2
183
+ TRANSIENT_PATTERN='HTTP (5[0-9][0-9]|429)|returned error: (5[0-9][0-9]|429)|No server is currently available|Service Unavailable|Bad Gateway|Gateway Time-?out|Internal Server Error|secondary rate limit|rate limit exceeded|ETIMEDOUT|ECONNRESET|EAI_AGAIN|socket hang up|i/o timeout|TLS handshake timeout|connection reset|Could not resolve host|remote end hung up|early EOF|RPC failed|code E(5[0-9][0-9]|429)'
184
+ retry_transient() {
185
+ local attempt=1 max="${RETRY_ATTEMPTS:-4}" delay="${RETRY_DELAY:-5}" rc out err
186
+ out="$(mktemp)"; err="$(mktemp)"
187
+ while :; do
188
+ rc=0
189
+ "$@" > "$out" 2> "$err" || rc=$?
190
+ if [ "$rc" -eq 0 ] || [ "$attempt" -ge "$max" ] || ! cat "$err" "$out" | grep -Eiq "$TRANSIENT_PATTERN"; then
191
+ cat "$out"; cat "$err" >&2; rm -f "$out" "$err"; return "$rc"
192
+ fi
193
+ echo "::warning::$1: transient error (attempt $attempt/$max), retrying in ${delay}s — $(cat "$err" "$out" | grep -Eim1 "$TRANSIENT_PATTERN")" >&3
194
+ sleep "$delay"; attempt=$((attempt + 1)); delay=$((delay * 2))
195
+ done
196
+ }
170
197
 
171
198
  jobs:
172
199
  release:
@@ -227,7 +254,10 @@ jobs:
227
254
  - name: Fetch the colab CLI
228
255
  run: |
229
256
  set -euo pipefail
230
- git clone --quiet --depth 1 --branch "$HANDBOOK_REF" "$HANDBOOK_REPO" "$RUNNER_TEMP/colab-handbook"
257
+ eval "$RETRY_TRANSIENT"
258
+ # A clone that died half-way leaves a directory a second clone refuses — start clean each try.
259
+ fetch_cli() { rm -rf "$RUNNER_TEMP/colab-handbook"; git clone --quiet --depth 1 --branch "$HANDBOOK_REF" "$HANDBOOK_REPO" "$RUNNER_TEMP/colab-handbook"; }
260
+ retry_transient fetch_cli
231
261
  echo "COLAB=$RUNNER_TEMP/colab-handbook/tools/colab" >> "$GITHUB_ENV"
232
262
  # The tags are annotated; git needs an identity to write one.
233
263
  git config user.name "github-actions[bot]"
@@ -245,9 +275,10 @@ jobs:
245
275
  CI_WORKFLOW: "CI"
246
276
  run: |
247
277
  set -uo pipefail
278
+ eval "$RETRY_TRANSIENT"
248
279
  OUT="$RUNNER_TEMP/promote.json"
249
280
  rc=0
250
- node "$COLAB" promote --auto --json > "$OUT" || rc=$?
281
+ retry_transient node "$COLAB" promote --auto --json > "$OUT" || rc=$?
251
282
  if ! jq -e 'has("promoted")' "$OUT" > /dev/null 2>&1; then
252
283
  echo "::warning::colab promote --auto gave no verdict (exit $rc; a HANDBOOK_REF older than #440?) — nothing was promoted"
253
284
  exit 0
@@ -261,7 +292,7 @@ jobs:
261
292
  if [ "$(jq -r '.promoted' "$OUT")" = "true" ]; then
262
293
  echo "promoted=true" >> "$GITHUB_OUTPUT"
263
294
  echo "Promoted to main @ $(jq -r '.sha' "$OUT")" | tee -a "$GITHUB_STEP_SUMMARY"
264
- if gh workflow run "$CI_WORKFLOW" --ref main; then
295
+ if retry_transient gh workflow run "$CI_WORKFLOW" --ref main; then
265
296
  echo "Dispatched $CI_WORKFLOW on main — its green run cuts the candidate." | tee -a "$GITHUB_STEP_SUMMARY"
266
297
  else
267
298
  echo "::warning::promoted, but could not dispatch $CI_WORKFLOW on main (does it declare workflow_dispatch:?) — run it by hand to cut the candidate"
@@ -281,12 +312,14 @@ jobs:
281
312
  if: steps.gate.outputs.cut == 'true' && (github.event_name == 'workflow_run' || github.event_name == 'workflow_dispatch' || github.event_name == 'schedule') && steps.promote.outputs.promoted != 'true'
282
313
  run: |
283
314
  set -uo pipefail
315
+ eval "$RETRY_TRANSIENT"
284
316
  OUT="$RUNNER_TEMP/cut.json"
285
317
  rc=0
286
- node "$COLAB" release cut --auto --json > "$OUT" || rc=$?
318
+ retry_transient node "$COLAB" release cut --auto --json > "$OUT" || rc=$?
287
319
  # A verdict is JSON carrying `ok`; anything else is a run that never decided.
288
320
  if ! jq -e 'has("ok")' "$OUT" > /dev/null 2>&1; then
289
321
  echo "::error::colab release cut produced no verdict (exit $rc)"
322
+ echo "colab release cut produced no verdict (exit $rc) — the reason is in this step's log." >> "$GITHUB_STEP_SUMMARY"
290
323
  cat "$OUT"
291
324
  exit 1
292
325
  fi
@@ -319,11 +352,13 @@ jobs:
319
352
  if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
320
353
  run: |
321
354
  set -uo pipefail
355
+ eval "$RETRY_TRANSIENT"
322
356
  OUT="$RUNNER_TEMP/finalize.json"
323
357
  rc=0
324
- node "$COLAB" release finalize --auto --json > "$OUT" || rc=$?
358
+ retry_transient node "$COLAB" release finalize --auto --json > "$OUT" || rc=$?
325
359
  if ! jq -e 'has("state")' "$OUT" > /dev/null 2>&1; then
326
360
  echo "::error::colab release finalize produced no verdict (exit $rc)"
361
+ echo "colab release finalize produced no verdict (exit $rc) — the reason is in this step's log." >> "$GITHUB_STEP_SUMMARY"
327
362
  cat "$OUT"
328
363
  exit 1
329
364
  fi
@@ -385,6 +420,7 @@ jobs:
385
420
  TAGS: ${{ steps.cut.outputs.tag }} ${{ steps.finalize.outputs.tag }}
386
421
  run: |
387
422
  set -euo pipefail
423
+ eval "$RETRY_TRANSIENT"
388
424
  for TAG in $TAGS; do
389
425
  if gh release view "$TAG" > /dev/null 2>&1; then
390
426
  echo "$TAG already has a Release — skipping"
@@ -406,9 +442,10 @@ jobs:
406
442
  # The view above is a check, not a lock: `colab release cut` publishes a candidate's
407
443
  # pre-release itself, and the API can still answer 404 for it seconds later (#462 — a
408
444
  # trunk went red on exactly that 422). So a create refused because the Release already
409
- # exists is the skip case too, decided from the create's own answer.
445
+ # exists is the skip case too, decided from the create's own answer. That also covers a
446
+ # create the API applied but answered 5xx for: the retry's 422 is that skip (#464).
410
447
  ERR="$RUNNER_TEMP/create-$TAG.err"
411
- if ! gh release create "$TAG" --verify-tag --title "$TAG" --notes-file "$NOTES" --generate-notes "${KIND[@]}" 2> "$ERR"; then
448
+ if ! retry_transient gh release create "$TAG" --verify-tag --title "$TAG" --notes-file "$NOTES" --generate-notes "${KIND[@]}" 2> "$ERR"; then
412
449
  cat "$ERR" >&2
413
450
  if grep -qiE 'already[ _]exists' "$ERR"; then
414
451
  echo "$TAG already has a Release (published while this step ran) — skipping"
@@ -461,10 +498,14 @@ jobs:
461
498
  - name: Refuse a private repository, and any npm token
462
499
  run: |
463
500
  set -uo pipefail
464
- # Visibility from the API, never assumed: unknown is refused like private.
465
- PRIVATE="$(gh api "repos/$REPO" --jq '.private' 2> /dev/null || echo unknown)"
501
+ eval "$RETRY_TRANSIENT"
502
+ # Visibility from the API, never assumed: unknown is refused like private. A transient
503
+ # error on this read is retried (#464) — one 5xx here once turned a trunk red.
504
+ ERR="$RUNNER_TEMP/visibility.err"
505
+ PRIVATE="$(retry_transient gh api "repos/$REPO" --jq '.private' 2> "$ERR")" || PRIVATE=unknown
466
506
  if [ "$PRIVATE" != "false" ]; then
467
- echo "::error::$REPO is private (or its visibility could not be read: $PRIVATE) — a private repository never publishes to public npm (#432). Remove release.npm, or install from git."
507
+ WHY="$(grep -v '^::warning::' "$ERR" 2> /dev/null | tail -n 1)"
508
+ echo "::error::$REPO is private (or its visibility could not be read: $PRIVATE${WHY:+ — $WHY}) — a private repository never publishes to public npm (#432). Remove release.npm, or install from git."
468
509
  exit 1
469
510
  fi
470
511
  if [ -n "${NODE_AUTH_TOKEN:-}${NPM_TOKEN:-}" ]; then
@@ -484,8 +525,9 @@ jobs:
484
525
  - name: npm new enough for trusted publishing (>= 11.5.1)
485
526
  run: |
486
527
  set -euo pipefail
528
+ eval "$RETRY_TRANSIENT"
487
529
  if ! node -e 'const [a,b,c]=process.argv[1].split(".").map(Number);process.exit(a>11||(a===11&&(b>5||(b===5&&c>=1)))?0:1)' "$(npm --version)"; then
488
- npm install --global npm@11
530
+ retry_transient npm install --global npm@11
489
531
  fi
490
532
  npm --version
491
533
 
@@ -494,13 +536,15 @@ jobs:
494
536
  - name: Publish each tag (npm publish --provenance)
495
537
  run: |
496
538
  set -euo pipefail
539
+ eval "$RETRY_TRANSIENT"
497
540
  for TAG in $TAGS; do
498
541
  VERSION="${TAG#v}"
499
542
  case "$VERSION" in
500
543
  *-*) DIST=next ;;
501
544
  *) DIST=latest ;;
502
545
  esac
503
- if npm view "$PACKAGE@$VERSION" version > /dev/null 2>&1; then
546
+ # A 404 is "not published" and answers at once; a transient error is retried first (#464).
547
+ if retry_transient npm view "$PACKAGE@$VERSION" version > /dev/null 2>&1; then
504
548
  echo "$PACKAGE@$VERSION is already on npm — skipping" | tee -a "$GITHUB_STEP_SUMMARY"
505
549
  continue
506
550
  fi
@@ -508,7 +552,18 @@ jobs:
508
552
  git clean -fdxq
509
553
  (cd "$PKG_DIR" && npm pkg set "version=$VERSION")
510
554
  sh -c "$GATE"
511
- (cd "$PKG_DIR" && npm publish --tag "$DIST" --provenance --access public --ignore-scripts)
555
+ # The view above is a check, not a lock: a publish the registry applied but answered 5xx
556
+ # for, or one that landed between the view and here, is refused as a republish — the skip
557
+ # case again, decided from the publish's own answer (#464, the same shape as #462).
558
+ ERR="$RUNNER_TEMP/npm-publish-$VERSION.err"
559
+ if ! (cd "$PKG_DIR" && retry_transient npm publish --tag "$DIST" --provenance --access public --ignore-scripts) 2> "$ERR"; then
560
+ cat "$ERR" >&2
561
+ if grep -qiE 'EPUBLISHCONFLICT|cannot publish over (the )?previously published' "$ERR"; then
562
+ echo "$PACKAGE@$VERSION is already on npm (published while this step ran) — skipping" | tee -a "$GITHUB_STEP_SUMMARY"
563
+ continue
564
+ fi
565
+ exit 1
566
+ fi
512
567
  echo "Published $PACKAGE@$VERSION to npm (dist-tag $DIST)" | tee -a "$GITHUB_STEP_SUMMARY"
513
568
  done
514
569
 
@@ -533,10 +588,17 @@ jobs:
533
588
  - name: Record the npm outcome
534
589
  run: |
535
590
  set -euo pipefail
591
+ eval "$RETRY_TRANSIENT"
536
592
  for TAG in $TAGS; do
537
- BODY="$(gh release view "$TAG" --repo "$REPO" --json body --jq '.body' 2> /dev/null)" || {
538
- echo "$TAG has no Release — nothing to record on"
539
- continue
593
+ ERR="$RUNNER_TEMP/record-$TAG.err"
594
+ BODY="$(retry_transient gh release view "$TAG" --repo "$REPO" --json body --jq '.body' 2> "$ERR")" || {
595
+ # Only a Release that is not there is nothing to record on; a read that kept failing is a failure.
596
+ if grep -qiE 'release not found|HTTP 404|Not Found' "$ERR"; then
597
+ echo "$TAG has no Release — nothing to record on"
598
+ continue
599
+ fi
600
+ cat "$ERR" >&2
601
+ exit 1
540
602
  }
541
603
  VERSION="${TAG#v}"
542
604
  case "$VERSION" in *-*) DIST=next ;; *) DIST=latest ;; esac
@@ -548,7 +610,8 @@ jobs:
548
610
  NOTES="$RUNNER_TEMP/notes-$TAG.md"
549
611
  printf '%s\n' "$BODY" | sed '/^<!-- colab:npm -->$/,/^<!-- \/colab:npm -->$/d' > "$NOTES"
550
612
  printf '\n<!-- colab:npm -->\n%s\n<!-- /colab:npm -->\n' "$LINE" >> "$NOTES"
551
- gh release edit "$TAG" --repo "$REPO" --notes-file "$NOTES" > /dev/null
613
+ # Idempotent: the block between the colab:npm markers is replaced, never appended twice.
614
+ retry_transient gh release edit "$TAG" --repo "$REPO" --notes-file "$NOTES" > /dev/null
552
615
  echo "$TAG: $LINE" | tee -a "$GITHUB_STEP_SUMMARY"
553
616
  done
554
617