ci: IS-572: re-sync ported Cloudflare Workers pipeline files with rollingclaude/cf-port-circinus

The category-1 files in this port are byte-identical copies from `rolling`.
`rolling` has since moved: [vyos-documentation#2209](https://github.com/vyos/vyos-documentation/pull/2209)
merged as `3a1c6c30`, thirteen rounds of hardening on exactly these files.

Re-take all 14 category-1 paths from `origin/rolling` via
`git checkout origin/rolling -- <paths>`, so byte-identity holds by
construction rather than by hand-editing:

  .github/workflows/docs-build.yml
  scripts/docs_gates/{gates,parity,smoke,test_gates,test_parity,test_smoke}.py
  workers/.gitignore
  workers/apex/src/{index,special,uagate}.ts
  workers/apex/test/{router,uagate}.test.ts
  workers/apex/ua-policy.json

Thirteen of the fourteen carry
[vyos-documentation#2209](https://github.com/vyos/vyos-documentation/pull/2209)
exactly — the pre-change tree was byte-identical to `3a1c6c30^` for those
paths. `workers/.gitignore` additionally picks up the one-line `test-results/`
entry from
[vyos-documentation#2212](https://github.com/vyos/vyos-documentation/pull/2212);
inert on circinus, since only the deliberately-unported `apex-deploy.yml`
writes that directory.

Deliberate exclusions are unchanged: `docs-canary-qa.yml` (cron runs on the
default branch only, so it is not ported even though
[vyos-documentation#2209](https://github.com/vyos/vyos-documentation/pull/2209)
touched it on `rolling`), `apex-deploy.yml`, and the `docs-preview-*`
workflows. `docs/conf.py` stays hand-merged and circinus-specific, with its
ReadTheDocs fallback intact.

🤖 Generated by [robots](https://vyos.io)

1 files changed, 117 insertions, 0 deletions

diff --git a/scripts/docs_gates/test_smoke.py b/scripts/docs_gates/test_smoke.py
index a2654dcf..790f953d 100644
--- a/scripts/docs_gates/test_smoke.py
+++ b/scripts/docs_gates/test_smoke.py
@@ -1,11 +1,14 @@
 from __future__ import annotations
 
 import io
+import sys
 import urllib.error
 import urllib.request
 from email.message import Message
 from urllib.parse import urlsplit
 
+import pytest
+
 from scripts.docs_gates import smoke
 from scripts.docs_gates.conftest import REDIRECT_LOCATION, REDIRECT_PATH
 
@@ -364,3 +367,117 @@ def test_inter_round_sleep_capped_to_remaining_budget(monkeypatch):
     assert len(sleeps) == 1
     assert 0 < sleeps[0] <= smoke.DEADLINE_SECONDS  # capped to the ~10s remaining budget
     assert sleeps[0] < smoke.RETRY_SLEEP_SECONDS     # NOT the full 30s sleep
+
+
+# --- The PDF probe was structurally unpassable: it asserted X-Docs-Build, but 1.3's PDF is
+# served by the APEX Worker straight from R2 (spec §5, 29.2 MiB > the 25 MiB asset cap) and
+# that path sets only etag / accept-ranges / content-type / content-length. Observed nightly:
+# "/en/1.3/vyos-documentation.pdf: status=206 docs-build=None detail=status+docs-build". ---
+
+def test_pdf_probe_does_not_assert_docs_build():
+    plan = smoke.probe_plan("1.3", pdf="/en/1.3/vyos-documentation.pdf", critical=["index.html"])
+    pdf = next(p for p in plan if p.path.endswith(".pdf"))
+    assert pdf.assert_docs_build is False   # apex's R2 path legitimately never sets it
+    assert pdf.assert_apex_build is False   # nor does the content Worker set X-Apex-Build
+    # ...but the build SHA is still gated for this version, via the HTML probes:
+    assert next(p for p in plan if p.path.endswith("/index.html")).assert_docs_build is True
+
+
+def test_pdf_probe_still_demands_an_exact_200():
+    # The 206 seen alongside the docs-build failure was an apex defect (a 206 answered to a
+    # request carrying no Range header), fixed in workers/apex/src/index.ts — NOT something
+    # this gate should learn to tolerate.
+    plan = smoke.probe_plan("1.3", pdf="/en/1.3/vyos-documentation.pdf", critical=[])
+    assert next(p for p in plan if p.path.endswith(".pdf")).expect_status == 200
+
+
+# --- CF Access credentials: env by default (argv publishes secrets to the process table),
+# flags as a manual fallback, and an empty value is rejected rather than sent as a blank
+# header (every probe would then 403 and the report would blame the wrong thing). ---
+
+def _argv(monkeypatch, tmp_path, *extra):
+    crit = tmp_path / "critical.txt"
+    crit.write_text("index.html\n")
+    monkeypatch.setattr(sys, "argv", ["smoke", "--host", "h", "--slug", "rolling",
+                                      "--expect-sha", "SKIP",
+                                      "--critical-list", str(crit), *extra])
+    return crit
+
+
+def test_access_credentials_default_from_environment(monkeypatch, tmp_path):
+    _argv(monkeypatch, tmp_path)
+    monkeypatch.setenv("CF_ACCESS_CLIENT_ID", "env-id")
+    monkeypatch.setenv("CF_ACCESS_CLIENT_SECRET", "env-secret")
+    seen: dict[str, str] = {}
+    monkeypatch.setattr(smoke, "run",
+                        lambda host, slug, sha, aid, asec, pdf, critical:
+                        seen.update(id=aid, secret=asec) or 0)
+    assert smoke.main() == 0
+    assert seen == {"id": "env-id", "secret": "env-secret"}
+
+
+def test_secret_bearing_flags_are_rejected_not_silently_ignored(monkeypatch, tmp_path):
+    # --access-id/--access-secret are GONE, not deprecated: an argv-passed secret is readable
+    # from the process table and captured verbatim by `set -x` traces. argparse must reject
+    # them so the old muscle-memory invocation errors out instead of silently ignoring the
+    # credential the operator passed and then 403ing on every probe.
+    for flag, value in (("--access-id", "an-id"), ("--access-secret", "a-secret")):
+        _argv(monkeypatch, tmp_path, flag, value)
+        monkeypatch.setenv("CF_ACCESS_CLIENT_ID", "env-id")
+        monkeypatch.setenv("CF_ACCESS_CLIENT_SECRET", "env-secret")
+        monkeypatch.setattr(smoke, "run", lambda *a, **k: pytest.fail("must not probe"))
+        with pytest.raises(SystemExit) as exc:
+            smoke.main()
+        assert exc.value.code == 2
+
+
+def test_critical_list_is_read_through_a_path_without_resource_warnings(monkeypatch, tmp_path):
+    # `open(a.critical_list).read()` left the descriptor to be closed by GC; --critical-list
+    # is now `type=Path` and read via Path.read_text(), which closes deterministically.
+    # HONEST SCOPE: this is not a strict regression test for the close itself — CPython's
+    # refcounting also closes the bare-open form immediately, so no ResourceWarning fires
+    # either way and this test passes against the pre-fix source (verified). What it DOES
+    # pin is the argparse `type=Path` change (a str would have no .read_text()) plus
+    # warning-free reading on interpreters without refcounting, e.g. PyPy, where the
+    # bare-open form genuinely leaks until GC.
+    import warnings
+
+    crit = _argv(monkeypatch, tmp_path)
+    monkeypatch.setenv("CF_ACCESS_CLIENT_ID", "id")
+    monkeypatch.setenv("CF_ACCESS_CLIENT_SECRET", "sec")
+    seen: list[str] = []
+    monkeypatch.setattr(smoke, "run",
+                        lambda host, slug, sha, aid, asec, pdf, critical:
+                        seen.extend(critical) or 0)
+    with warnings.catch_warnings():
+        warnings.simplefilter("error", ResourceWarning)
+        assert smoke.main() == 0
+    assert seen == ["index.html"]
+    assert crit.exists()
+
+
+def test_missing_access_credentials_fail_loudly_without_probing(monkeypatch, tmp_path, capsys):
+    _argv(monkeypatch, tmp_path)
+    monkeypatch.delenv("CF_ACCESS_CLIENT_ID", raising=False)
+    monkeypatch.delenv("CF_ACCESS_CLIENT_SECRET", raising=False)
+    monkeypatch.setattr(smoke, "run", lambda *a, **k: pytest.fail("must not probe"))
+    assert smoke.main() == 2
+    err = capsys.readouterr().err
+    assert "CF_ACCESS_CLIENT_ID" in err and "CF_ACCESS_CLIENT_SECRET" in err
+
+
+def test_critical_list_strips_before_testing_for_comments(monkeypatch, tmp_path):
+    # An INDENTED comment used to survive the `line.startswith("#")` test (applied to the
+    # unstripped line) and become a live critical page — which can never exist as a file.
+    crit = tmp_path / "critical.txt"
+    crit.write_text("# leading comment\n   # indented comment\n\n  cli.html  \n")
+    monkeypatch.setenv("CF_ACCESS_CLIENT_ID", "id")
+    monkeypatch.setenv("CF_ACCESS_CLIENT_SECRET", "sec")
+    monkeypatch.setattr(sys, "argv", ["smoke", "--host", "h", "--slug", "rolling",
+                                      "--expect-sha", "SKIP", "--critical-list", str(crit)])
+    seen: list[str] = []
+    monkeypatch.setattr(smoke, "run",
+                        lambda host, slug, sha, aid, asec, pdf, critical:
+                        seen.extend(critical) or 0)
+    assert smoke.main() == 0
+    assert seen == ["cli.html"]