Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
181 changes: 181 additions & 0 deletions .github/workflows/deploy-cloudflare-worker.yml
Original file line number Diff line number Diff line change
@@ -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
25 changes: 25 additions & 0 deletions docs/deployment-workflows.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 (`<account-id>`).

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.
63 changes: 63 additions & 0 deletions docs/naming-conventions.md
Original file line number Diff line number Diff line change
@@ -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 `<Broker>Platform` (`BinancePlatform`,
`CharlesSchwabPlatform`, `FirstradePlatform`, `InteractiveBrokersPlatform`,
`LongBridgePlatform`).
- Market strategy and snapshot pipeline repositories use
`<Market>Strategies` and `<Market>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-<platform>-<env>` 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]+)*$`:
`<platform>-<component>-<credential>[-<scope>]`
(for example, `<platform>-oauth-token-<scope>`).
- Every secret carries at minimum `owner=qsl`, `platform=<platform>`, and
`env=<prod|paper|shared>`. Add `account=<alias>` or `purpose=<role>` 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-<service>`).
- KV namespace titles use lowercase `kebab-case` (`qsl-<service>-<purpose>`),
with Worker environment bindings written in `UPPER_SNAKE_CASE`
(`STRATEGY_SWITCH_CONFIG`, `OAUTH_KV`).
113 changes: 113 additions & 0 deletions scripts/test_worker_deployment_workflow.py
Original file line number Diff line number Diff line change
@@ -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()
Loading