feat(config): DOT_BULLETIN_RPC env override + nightly-chaos-rpc cell (Phase 6 S18)

Author: EnderOfWorlds007

.changeset/e2e-phase-6-rpc-failover.md

@@ -0,0 +1,5 @@
+---
+"playground-cli": patch
+---
+
+Adds `DOT_BULLETIN_RPC` env-var override to `getChainConfig()`, allowing tests (or operators in an emergency) to prepend a custom Bulletin RPC endpoint while keeping the built-in URL as a fallback. The new `nightly-chaos-rpc` cell exercises this by setting an unroutable primary URL and asserting the deploy still completes via failover.

.github/workflows/e2e.yml

@@ -141,6 +141,10 @@ jobs:
                     - cell: nightly-deploy-multi
                       # source: e2e/cli/deploy.test.ts → describe("dot deploy — multi …")
                       pattern: "deploy — multi"
+                    - cell: nightly-chaos-rpc
+                      # source: e2e/cli/chaos.test.ts → describe("dot deploy — chaos RPC failover")
+                      pattern: "chaos RPC failover"
+                      testFile: e2e/cli/chaos.test.ts
         steps:
             - uses: actions/checkout@v4
 

CLAUDE.md

@@ -56,7 +56,7 @@ These are things that aren't self-evident from reading the code and have bitten
 
 - **Local launcher:** `tools/e2e-local.sh [smoke|pr|nightly]` — also callable via `pnpm test:e2e:smoke`, `pnpm test:e2e:pr`, `pnpm test:e2e:nightly`.
 - **CI workflow:** `.github/workflows/e2e.yml` — runs on PR / push:main / cron 06:00 UTC / workflow_dispatch.
-- **CI matrix:** 12 cells across four matrices — `test-no-publish` (parallel: pr-install, pr-preflight, pr-mod, pr-init-session) + `test-publish` (max-parallel: 1: pr-deploy-frontend, pr-deploy-foundry) + `test-nightly-no-publish` (parallel, schedule/dispatch only: nightly-mod-miss, nightly-diagnostic, nightly-rejections, nightly-chaos-sigint) + `test-nightly-publish` (max-parallel: 1, schedule/dispatch only: nightly-deploy-hardhat, nightly-deploy-multi). Each cell runs a subset via `vitest -t "<pattern>"`.
+- **CI matrix:** 13 cells across four matrices — `test-no-publish` (parallel: pr-install, pr-preflight, pr-mod, pr-init-session) + `test-publish` (max-parallel: 1: pr-deploy-frontend, pr-deploy-foundry) + `test-nightly-no-publish` (parallel, schedule/dispatch only: nightly-mod-miss, nightly-diagnostic, nightly-rejections, nightly-chaos-sigint) + `test-nightly-publish` (max-parallel: 1, schedule/dispatch only: nightly-deploy-hardhat, nightly-deploy-multi, nightly-chaos-rpc). Each cell runs a subset via `vitest -t "<pattern>"`.
 - **Release smoke:** `.github/workflows/e2e-release.yml` fires on `release: prereleased`, downloads the `dot-linux-x64` SEA asset, and runs `e2e/cli/published.test.ts` against it. Validates the published binary before stable release.
 - **Test files:** `e2e/cli/*.test.ts` (vitest, spawned via `bun run src/index.ts`).
 - **Reports directory:** `e2e-reports/junit.xml` + `e2e-reports/dot-runs.log` (gitignored).

e2e/cli/chaos.test.ts

@@ -29,6 +29,26 @@ import { fixturePath } from "./fixtures/templates.js";
 const REPO_ROOT = resolve(import.meta.dirname, "../..");
 const CLI_ENTRY = resolve(REPO_ROOT, "src/index.ts");
 
+/** Common CLI args for a full playground deploy in chaos scenarios. */
+function chaosDeployArgs(domain: string, buildDir: string, dir: string): string[] {
+	return [
+		"run",
+		CLI_ENTRY,
+		"deploy",
+		"--signer",
+		"dev",
+		"--domain",
+		domain,
+		"--buildDir",
+		buildDir,
+		"--playground",
+		"--suri",
+		SIGNER.suri,
+		"--dir",
+		dir,
+	];
+}
+
 /** How long to wait for the storage-phase sentinel before sending SIGINT anyway. */
 const SENTINEL_WAIT_MS = 60_000;
 
@@ -41,22 +61,11 @@ describe("dot deploy — chaos", () => {
 
 		const child = execa(
 			"bun",
-			[
-				"run",
-				CLI_ENTRY,
-				"deploy",
-				"--signer",
-				"dev",
-				"--domain",
+			chaosDeployArgs(
 				E2E_DOMAINS.chaos,
-				"--buildDir",
 				resolve(frontendOnly, "dist"),
-				"--playground",
-				"--suri",
-				SIGNER.suri,
-				"--dir",
 				frontendOnly,
-			],
+			),
 			{
 				cwd: REPO_ROOT,
 				env: { ...process.env, DOT_TAG: "e2e-chaos-sigint", DOT_TELEMETRY: "1" },
@@ -121,3 +130,40 @@ describe("dot deploy — chaos", () => {
 		).toBeLessThan(MAX_EXIT_MS);
 	});
 });
+
+describe("dot deploy — chaos RPC failover", () => {
+	test("survives an unreachable primary bulletin RPC via failover", { timeout: 600_000 }, async () => {
+		// Set DOT_BULLETIN_RPC to an unroutable address. getChainConfig() will
+		// expose it as bulletinRpc and put the real endpoint in bulletinRpcFallbacks.
+		// bulletin-deploy's deploy() internally builds [override, DEFAULT] as its
+		// BULLETIN_ENDPOINTS list and polkadot-api's WS provider fails over
+		// automatically when the primary is unreachable. The deploy MUST still
+		// succeed — we're testing failover, not rejection.
+		const frontendOnly = fixturePath("frontend-only");
+
+		const result = await execa(
+			"bun",
+			chaosDeployArgs(
+				E2E_DOMAINS.chaos,
+				resolve(frontendOnly, "dist"),
+				frontendOnly,
+			),
+			{
+				cwd: REPO_ROOT,
+				env: {
+					...process.env,
+					DOT_TAG: "e2e-chaos-rpc",
+					DOT_TELEMETRY: "1",
+					DOT_BULLETIN_RPC: "ws://127.0.0.1:1/",
+				},
+				reject: false,
+				timeout: 580_000,
+			},
+		);
+
+		expect(
+			result.exitCode,
+			`deploy failed: ${result.stdout}\n${result.stderr}`,
+		).toBe(0);
+	});
+});

src/config.ts

@@ -17,6 +17,13 @@ export interface ChainConfig {
     assetHubRpc: string;
     /** WebSocket endpoint for Paseo Bulletin (immutable IPFS storage). */
     bulletinRpc: string;
+    /**
+     * Ordered fallback endpoints for Bulletin, used where the caller builds its
+     * own WS provider (e.g. the dedicated metadata-upload client in
+     * `src/utils/deploy/playground.ts`). Always excludes `bulletinRpc` itself.
+     * Typically empty; populated when `DOT_BULLETIN_RPC` overrides the primary.
+     */
+    bulletinRpcFallbacks: string[];
     /** WebSocket endpoints for the People chain (SSO / session discovery). */
     peopleEndpoints: string[];
     /** Viewer URL shown to users after a successful deploy. */
@@ -26,6 +33,7 @@ export interface ChainConfig {
 const TESTNET: ChainConfig = {
     assetHubRpc: "wss://asset-hub-paseo-rpc.n.dwellir.com",
     bulletinRpc: "wss://paseo-bulletin-rpc.polkadot.io",
+    bulletinRpcFallbacks: [],
     peopleEndpoints: ["wss://paseo-people-next-rpc.polkadot.io"],
     appViewerOrigin: "https://dot.li",
 };
@@ -36,7 +44,23 @@ export function getChainConfig(env: Env = DEFAULT_ENV): ChainConfig {
             "`--env mainnet` is not yet supported. Use `--env testnet` (default) while mainnet launch is pending.",
         );
     }
-    return TESTNET;
+    const cfg = TESTNET;
+    // CHAOS-test hook: when DOT_BULLETIN_RPC is set, use it as the primary
+    // Bulletin endpoint and retain the built-in URL as a fallback so failover
+    // works. bulletin-deploy's deploy() already applies this pattern internally
+    // (it builds [userRpc, DEFAULT] from options.rpc), so storage.ts consumers
+    // get failover for free. The dedicated WS client in playground.ts reads
+    // bulletinRpcFallbacks explicitly and builds its own endpoint array.
+    // Used by `e2e/cli/chaos.test.ts` to simulate an unreachable primary RPC.
+    const override = process.env.DOT_BULLETIN_RPC;
+    if (override) {
+        return {
+            ...cfg,
+            bulletinRpc: override,
+            bulletinRpcFallbacks: [cfg.bulletinRpc],
+        };
+    }
+    return cfg;
 }
 
 /** Fixed CDM meta-registry contract on Asset Hub. Source: @dotdm/utils REGISTRY_ADDRESS. */

src/utils/deploy/playground.ts

@@ -168,7 +168,7 @@ export async function publishToPlayground(
             const bulletinClient = createClient(
                 withPolkadotSdkCompat(
                     getWsProvider({
-                        endpoints: [cfg.bulletinRpc],
+                        endpoints: [cfg.bulletinRpc, ...cfg.bulletinRpcFallbacks],
                         heartbeatTimeout: BULLETIN_WS_HEARTBEAT_MS,
                     }),
                 ),