From 7c5ecbd695da1232ba15bfe7b90a7aaa25996ef3 Mon Sep 17 00:00:00 2001 From: Pigbibi <20649888+Pigbibi@users.noreply.github.com> Date: Sun, 15 Nov 2026 16:26:36 +0800 Subject: [PATCH] feat(workflows): add Worker deploy workflow and naming docs --- .../workflows/deploy-cloudflare-worker.yml | 181 ++++++++++++++++++ docs/deployment-workflows.md | 25 +++ docs/naming-conventions.md | 63 ++++++ scripts/test_worker_deployment_workflow.py | 113 +++++++++++ 4 files changed, 382 insertions(+) create mode 100644 .github/workflows/deploy-cloudflare-worker.yml create mode 100644 docs/naming-conventions.md create mode 100644 scripts/test_worker_deployment_workflow.py diff --git a/.github/workflows/deploy-cloudflare-worker.yml b/.github/workflows/deploy-cloudflare-worker.yml new file mode 100644 index 0000000..692015c --- /dev/null +++ b/.github/workflows/deploy-cloudflare-worker.yml @@ -0,0 +1,181 @@ +name: Release a pinned Cloudflare Worker version +on: + workflow_call: + inputs: + environment: + required: true + type: string + operation: + required: true + type: string + secrets: + CF_API_TOKEN: + required: true + CF_ACCOUNT_ID: + required: true + CF_WORKER_SCRIPT_NAME: + required: true + CF_EXPECTED_VERSION_ID: + required: true + CF_CANDIDATE_VERSION_ID: + required: false +permissions: {} +jobs: + release: + if: github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main' + runs-on: ubuntu-latest + timeout-minutes: 8 + environment: ${{ inputs.environment }} + concurrency: + group: worker-release-${{ inputs.environment }} + cancel-in-progress: false + permissions: + contents: read + steps: + - name: Verify or promote a pinned Worker version + env: + OPERATION: ${{ inputs.operation }} + CF_API_TOKEN: ${{ secrets.CF_API_TOKEN }} + CF_ACCOUNT_ID: ${{ secrets.CF_ACCOUNT_ID }} + CF_WORKER_SCRIPT_NAME: ${{ secrets.CF_WORKER_SCRIPT_NAME }} + CF_EXPECTED_VERSION_ID: ${{ secrets.CF_EXPECTED_VERSION_ID }} + CF_CANDIDATE_VERSION_ID: ${{ secrets.CF_CANDIDATE_VERSION_ID }} + shell: bash + run: | + python3 -u - <<'PY' + import json + import os + import re + from urllib.error import HTTPError + from urllib.request import HTTPRedirectHandler, Request, build_opener + + ACCOUNT_RE = re.compile(r"[0-9a-f]{32}") + SCRIPT_RE = re.compile(r"[a-z0-9][a-z0-9-]{1,62}") + UUID_RE = re.compile(r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}") + + + class NoRedirect(HTTPRedirectHandler): + def redirect_request(self, *args, **kwargs): + return None + + + class WorkerDeployer: + def __init__(self, account_id, script_name, credential): + if not ACCOUNT_RE.fullmatch(account_id or ""): + raise ValueError("Expected a 32-character hex Cloudflare account ID") + if not SCRIPT_RE.fullmatch(script_name or ""): + raise ValueError("Expected a valid Worker script name") + if not (credential or "").strip(): + raise ValueError("CF_API_TOKEN is required") + self.base_url = ( + f"https://api.cloudflare.com/client/v4/accounts/{account_id}" + f"/workers/scripts/{script_name}" + ) + self.auth_header = "Bearer " + credential.strip() + self.opener = build_opener(NoRedirect()) + + def request(self, method, suffix, body=None): + payload = None if body is None else json.dumps(body).encode("utf-8") + headers = { + "Authorization": self.auth_header, + "Content-Type": "application/json", + } + try: + req = Request(self.base_url + suffix, payload, headers, method=method) + with self.opener.open(req, timeout=30) as response: + parsed = json.loads((response.read() or b"{}").decode("utf-8")) + except HTTPError as error: + raise RuntimeError(f"Cloudflare API {method} returned HTTP {error.code}") from None + if not isinstance(parsed, dict) or parsed.get("success") is False: + raise RuntimeError(f"Cloudflare API {method} reported failure") + return parsed.get("result") + + def list_deployments(self): + result = self.request("GET", "/deployments") + if isinstance(result, dict): + deployments = result.get("deployments") + if deployments is None: + deployments = result.get("items") + elif isinstance(result, list): + deployments = result + else: + deployments = None + if not isinstance(deployments, list) or not deployments: + raise RuntimeError("Live Worker deployment list is empty") + return deployments + + def get_version(self, version_id): + result = self.request("GET", f"/versions/{version_id}") + if isinstance(result, dict) and result.get("id") and result["id"] != version_id: + raise RuntimeError("Fetched Worker version ID does not match requested version") + return result + + def deploy_version(self, version_id): + return self.request( + "POST", + "/deployments", + body={ + "strategy": "percentage", + "versions": [{"version_id": version_id, "percentage": 100}], + }, + ) + + + def extract_single_active_version(deployments): + current = deployments[0] + versions = current.get("versions") if isinstance(current, dict) else None + if not isinstance(versions, list) or len(versions) != 1: + raise RuntimeError("Expected exactly one active Worker version at 100%") + entry = versions[0] + version_id = entry.get("version_id") if isinstance(entry, dict) else None + percentage = entry.get("percentage") if isinstance(entry, dict) else None + if not version_id or float(percentage if percentage is not None else -1) != 100.0: + raise RuntimeError("Expected single active Worker version serving 100% traffic") + return version_id + + + def validate_inputs(previous_id, candidate_id, operation): + if operation not in {"verify", "deploy", "rollback"}: + raise ValueError("Expected verify, deploy or rollback") + if not UUID_RE.fullmatch(previous_id or ""): + raise ValueError("Expected a UUID for CF_EXPECTED_VERSION_ID") + if operation != "verify": + if not UUID_RE.fullmatch(candidate_id or "") or candidate_id == previous_id: + raise ValueError("Expected a distinct UUID for CF_CANDIDATE_VERSION_ID") + + + def release(deployer, previous_id, candidate_id, operation): + validate_inputs(previous_id, candidate_id, operation) + live_version = extract_single_active_version(deployer.list_deployments()) + expected_live = candidate_id if operation == "rollback" else previous_id + if live_version != expected_live: + raise RuntimeError("Live Worker version does not match the expected baseline") + if operation == "verify": + print("Verified: live Worker serves 100% of the expected version") + return + target_id = previous_id if operation == "rollback" else candidate_id + deployer.get_version(target_id) + deployer.deploy_version(target_id) + confirmed_version = extract_single_active_version(deployer.list_deployments()) + if confirmed_version != target_id: + raise RuntimeError("Worker deployment readback does not match the target version") + print(f"{operation} verified: live Worker serves 100% of the target version") + + + def main(): + deployer = WorkerDeployer( + os.environ["CF_ACCOUNT_ID"], + os.environ["CF_WORKER_SCRIPT_NAME"], + os.environ["CF_API_TOKEN"], + ) + release( + deployer, + os.environ["CF_EXPECTED_VERSION_ID"], + os.environ.get("CF_CANDIDATE_VERSION_ID", ""), + os.environ["OPERATION"], + ) + + + if __name__ == "__main__": + main() + PY diff --git a/docs/deployment-workflows.md b/docs/deployment-workflows.md index f6160a4..8054da7 100644 --- a/docs/deployment-workflows.md +++ b/docs/deployment-workflows.md @@ -112,3 +112,28 @@ when the repository uses a different CI workflow or branch. The caller selects when to run the check and owns the market-specific validation, storage credentials and write plan. + +## Cloudflare Workers + +Call `.github/workflows/deploy-cloudflare-worker.yml` at an immutable commit from a +manual workflow (`workflow_dispatch` on `refs/heads/main`). Use a protected GitHub +Environment whose scoped Cloudflare API token only permits Worker Scripts and +Deployments on the target account (``). + +Store target identifiers and pinned version UUIDs as protected Environment secrets +and pass them explicitly in the caller's `secrets` map so public workflow logs do +not disclose account or script names (`example-worker`): + +| Secret | Purpose | +| --- | --- | +| `CF_API_TOKEN` | Scoped Cloudflare Workers edit token | +| `CF_ACCOUNT_ID` | 32-character hex Cloudflare account identifier | +| `CF_WORKER_SCRIPT_NAME` | Target Worker script name | +| `CF_EXPECTED_VERSION_ID` | Expected baseline Worker version UUID | +| `CF_CANDIDATE_VERSION_ID` | Candidate Worker version UUID (`deploy` and `rollback`) | + +Use `verify` to check that a single version serves 100% traffic and matches +`CF_EXPECTED_VERSION_ID` with no writes. Use `deploy` to confirm the baseline, +verify that `CF_CANDIDATE_VERSION_ID` exists, promote it to 100% traffic, and read +back `/deployments`. Use `rollback` with the same pair of UUIDs to restore +`CF_EXPECTED_VERSION_ID` when the candidate is live. diff --git a/docs/naming-conventions.md b/docs/naming-conventions.md new file mode 100644 index 0000000..de5ce2f --- /dev/null +++ b/docs/naming-conventions.md @@ -0,0 +1,63 @@ +# Naming conventions + +This repository organization uses one naming layout across GitHub repositories, +Google Cloud projects, Secret Manager secrets, Artifact Registry repositories, +and Cloudflare Workers so automation, access policies, and cleanup rules apply +uniformly without per-target special cases. + +## GitHub repositories + +Repository names use `PascalCase` without underscores or hyphens, grouped by +role: + +- Shared libraries, runtime configuration, AI coordination, and internal + operations use the `Quant` prefix (`QuantPlatformKit`, `QuantRuntimeSettings`, + `QuantAIService`, `QuantInternalOps`). +- Broker integration repositories use `Platform` (`BinancePlatform`, + `CharlesSchwabPlatform`, `FirstradePlatform`, `InteractiveBrokersPlatform`, + `LongBridgePlatform`). +- Market strategy and snapshot pipeline repositories use + `Strategies` and `SnapshotPipelines` (`UsEquityStrategies`, + `HkEquityStrategies`, `CnEquityStrategies`). +- Dedicated infrastructure and static site exceptions keep their established + names (`IBKRGatewayManager`, `SchwabTokenAutoRefresher`, + `.github`, `quantstrategylab.github.io`). + +## Google Cloud projects + +- Project IDs use lowercase `kebab-case`: `qsl--` for new + projects, avoiding spaces in project display names. +- Every active quant project carries the canonical resource labels: + - `owner`: `qsl` + - `system`: `qsl` + - `platform`: `binance`, `schwab`, `firstrade`, `ibkr`, `longbridge`, or `qsl` + - `env`: `prod`, `paper`, or `shared` + +## Google Cloud Secret Manager + +- New and migrated secret IDs use lowercase `kebab-case` matching + `^[a-z0-9]+(-[a-z0-9]+)*$`: + `--[-]` + (for example, `-oauth-token-`). +- Every secret carries at minimum `owner=qsl`, `platform=`, and + `env=`. Add `account=` or `purpose=` when + scoping per-account or auxiliary credentials. +- Legacy `snake_case` secrets remain tagged with + `naming_status=legacy-snake-case` until cut over cleanly inside a scheduled + maintenance window; never maintain duplicate live values under both names. +- Only the active secret version stays `ENABLED`; rotated older versions are + `DESTROY`ed once no Cloud Run template, active revision, or job pins them. + +## Artifact Registry + +- Docker repositories use lowercase `kebab-case` names. +- Releases deploy by immutable digest rather than mutable floating tags. +- Automated cleanup policies protect tags prefixed with `keep-`, `prod-`, + `live-`, and `lkg-` alongside the most recent 5 versions. + +## Cloudflare Workers and KV + +- Worker script names use lowercase `kebab-case` (`qsl-`). +- KV namespace titles use lowercase `kebab-case` (`qsl--`), + with Worker environment bindings written in `UPPER_SNAKE_CASE` + (`STRATEGY_SWITCH_CONFIG`, `OAUTH_KV`). diff --git a/scripts/test_worker_deployment_workflow.py b/scripts/test_worker_deployment_workflow.py new file mode 100644 index 0000000..dfc5121 --- /dev/null +++ b/scripts/test_worker_deployment_workflow.py @@ -0,0 +1,113 @@ +"""Regression tests for the shared Cloudflare Worker release contract.""" + +from pathlib import Path +from textwrap import dedent +import unittest +from unittest.mock import Mock, patch + + +WORKFLOW = Path(__file__).resolve().parents[1] / ".github/workflows/deploy-cloudflare-worker.yml" +PREVIOUS_ID = "11111111-1111-4111-8111-111111111111" +CANDIDATE_ID = "22222222-2222-4222-8222-222222222222" +OTHER_ID = "33333333-3333-4333-8333-333333333333" +ACCOUNT_ID = "0123456789abcdef0123456789abcdef" +SCRIPT_NAME = "example-worker" + + +class CloudflareWorkerReleaseTests(unittest.TestCase): + def setUp(self): + script = WORKFLOW.read_text(encoding="utf-8").split("python3 -u - <<'PY'\n", 1)[1].rsplit("\n PY", 1)[0] + self.module = {"__name__": "worker_release"} + exec(compile(dedent(script), str(WORKFLOW), "exec"), self.module) + self.deployer = Mock() + + def test_verify_reads_deployments_without_mutating(self): + self.deployer.list_deployments.return_value = [ + {"versions": [{"version_id": PREVIOUS_ID, "percentage": 100}]} + ] + self.module["release"](self.deployer, PREVIOUS_ID, "", "verify") + self.deployer.list_deployments.assert_called_once_with() + self.deployer.get_version.assert_not_called() + self.deployer.deploy_version.assert_not_called() + + def test_deploy_checks_baseline_and_candidate_then_reads_back(self): + self.deployer.list_deployments.side_effect = [ + [{"versions": [{"version_id": PREVIOUS_ID, "percentage": 100}]}], + [{"versions": [{"version_id": CANDIDATE_ID, "percentage": 100}]}], + ] + self.deployer.get_version.return_value = {"id": CANDIDATE_ID} + self.module["release"](self.deployer, PREVIOUS_ID, CANDIDATE_ID, "deploy") + self.deployer.get_version.assert_called_once_with(CANDIDATE_ID) + self.deployer.deploy_version.assert_called_once_with(CANDIDATE_ID) + self.assertEqual(self.deployer.list_deployments.call_count, 2) + + def test_rollback_checks_candidate_is_live_then_restores_previous(self): + self.deployer.list_deployments.side_effect = [ + [{"versions": [{"version_id": CANDIDATE_ID, "percentage": 100}]}], + [{"versions": [{"version_id": PREVIOUS_ID, "percentage": 100}]}], + ] + self.deployer.get_version.return_value = {"id": PREVIOUS_ID} + self.module["release"](self.deployer, PREVIOUS_ID, CANDIDATE_ID, "rollback") + self.deployer.get_version.assert_called_once_with(PREVIOUS_ID) + self.deployer.deploy_version.assert_called_once_with(PREVIOUS_ID) + + def test_rejects_split_traffic_before_any_mutation(self): + self.deployer.list_deployments.return_value = [ + { + "versions": [ + {"version_id": PREVIOUS_ID, "percentage": 50}, + {"version_id": CANDIDATE_ID, "percentage": 50}, + ] + } + ] + with self.assertRaisesRegex(RuntimeError, "one active Worker version"): + self.module["release"](self.deployer, PREVIOUS_ID, CANDIDATE_ID, "deploy") + self.deployer.get_version.assert_not_called() + self.deployer.deploy_version.assert_not_called() + + def test_rejects_drifted_live_version_before_mutation(self): + self.deployer.list_deployments.return_value = [ + {"versions": [{"version_id": OTHER_ID, "percentage": 100}]} + ] + with self.assertRaisesRegex(RuntimeError, "expected baseline"): + self.module["release"](self.deployer, PREVIOUS_ID, CANDIDATE_ID, "deploy") + self.deployer.deploy_version.assert_not_called() + + def test_rejects_unconfirmed_readback(self): + self.deployer.list_deployments.side_effect = [ + [{"versions": [{"version_id": PREVIOUS_ID, "percentage": 100}]}], + [{"versions": [{"version_id": PREVIOUS_ID, "percentage": 100}]}], + ] + self.deployer.get_version.return_value = {"id": CANDIDATE_ID} + with self.assertRaisesRegex(RuntimeError, "readback"): + self.module["release"](self.deployer, PREVIOUS_ID, CANDIDATE_ID, "deploy") + + def test_rejects_invalid_identifiers_without_leaking_values(self): + with self.assertRaises(ValueError) as ctx_acct: + self.module["WorkerDeployer"]("secret-acct-123", SCRIPT_NAME, "synthetic-token") + self.assertNotIn("secret-acct-123", str(ctx_acct.exception)) + + with self.assertRaises(ValueError) as ctx_script: + self.module["WorkerDeployer"](ACCOUNT_ID, "Bad_Script_Name", "synthetic-token") + self.assertNotIn("Bad_Script_Name", str(ctx_script.exception)) + + with self.assertRaisesRegex(ValueError, "distinct UUID"): + self.module["release"](self.deployer, PREVIOUS_ID, PREVIOUS_ID, "deploy") + + def test_deployer_http_error_suppresses_account_and_script(self): + from io import BytesIO + from urllib.error import HTTPError + + deployer = self.module["WorkerDeployer"](ACCOUNT_ID, SCRIPT_NAME, "synthetic-token") + err = HTTPError("https://api.cloudflare.com/hidden", 403, "Forbidden", {}, BytesIO(b"secret detail")) + with patch.object(deployer.opener, "open", side_effect=err): + with self.assertRaises(RuntimeError) as ctx: + deployer.list_deployments() + self.assertNotIn(ACCOUNT_ID, str(ctx.exception)) + self.assertNotIn(SCRIPT_NAME, str(ctx.exception)) + self.assertNotIn("secret detail", str(ctx.exception)) + self.assertIn("HTTP 403", str(ctx.exception)) + + +if __name__ == "__main__": + unittest.main()