feat(theia): fail loudly on bridge failure when DATA_BRIDGE_ENABLED is set

Predixx · Predixx · commit a389e2ff2705 · 2026-05-04T13:26:37.000+02:00
readEnvVarsViaDataBridge now returns a discriminated union instead of
`Record | undefined`:
  - 'no-bridge'  : DATA_BRIDGE_ENABLED unset (genuine Desktop)
  - 'success'    : all keys delivered
  - 'failure'    : bridge expected but unreachable (command-missing /
                   timeout / invalid-response)

detectTheiaEnvironment dispatches on this union: 'failure' surfaces
showErrorMessage and falls back to Desktop so the diagnostic command
remains accessible. Previously every non-success collapsed to silent
Desktop, which booted EduIDE pods with Cookie auth (wrong scheme
against an EduIDE Artemis) when the bridge was slow or absent.

Adds 11 unit tests covering all four return shapes plus the
fail-loud branches in the detector. No behaviour change for
genuine Desktop boots.
diff --git a/extension/src/extension/theia/dataBridgeReader.ts b/extension/src/extension/theia/dataBridgeReader.ts
@@ -26,6 +26,20 @@ export const KNOWN_BRIDGE_KEYS = [
 
 type KnownBridgeKey = (typeof KNOWN_BRIDGE_KEYS)[number];
 
+/**
+ * Outcome of a {@link readEnvVarsViaDataBridge} call.
+ *
+ * The discriminator distinguishes two situations that both used to be encoded
+ * as `undefined`: a genuine Desktop boot (`no-bridge`) and an EduIDE boot where
+ * the bridge was expected but unreachable (`failure`). Conflating them lets a
+ * broken EduIDE pod silently boot in Desktop-Cookie mode, which is the wrong
+ * failure mode (auth would attempt the wrong scheme; auto-clone would not run).
+ */
+export type ReadEnvResult<T extends string> =
+    | { kind: 'no-bridge' }
+    | { kind: 'success'; env: Record<T, string | undefined> }
+    | { kind: 'failure'; reason: 'command-missing' | 'timeout' | 'invalid-response'; details?: string };
+
 /**
  * Reads environment variables via the EduIDE data-bridge companion extension.
  *
@@ -40,66 +54,77 @@ type KnownBridgeKey = (typeof KNOWN_BRIDGE_KEYS)[number];
  * data, which would cause a 10s blocking poll on every startup.
  *
  * Polls every 500ms until all requested keys are present, with a 10s timeout.
- * Returns `undefined` if data-bridge is unavailable or times out — the caller
- * treats this as "not running in Theia/EduIDE" and falls back to the
- * non-Theia default environment.
+ *
+ * Return semantics:
+ *  - `no-bridge`: `DATA_BRIDGE_ENABLED` is not set → genuinely Desktop.
+ *  - `failure`: bridge was expected (`DATA_BRIDGE_ENABLED=1`) but the command
+ *    is missing or did not deliver values within the timeout → caller MUST
+ *    surface this loudly; silently degrading to Desktop produces broken auth.
+ *  - `success`: all requested keys delivered.
  *
  * Pattern adapted from Scorpio's DataBridgeStrategy (env-strategy.ts).
  */
 export async function readEnvVarsViaDataBridge<T extends string>(
     names: readonly T[],
-): Promise<Record<T, string | undefined> | undefined> {
+): Promise<ReadEnvResult<T>> {
     // DATA_BRIDGE_ENABLED is a container-boot config var, available in process.env
     // from container startup — unlike the credentials (ARTEMIS_TOKEN etc.) which are
     // injected later via the data-bridge HTTP server. This is why process.env is
     // reliable here even though it's unreliable for late-arriving credentials.
     // Without this guard, polling would block for 10s with no data arriving.
     const bridgeEnabled = process.env.DATA_BRIDGE_ENABLED;
     if (bridgeEnabled !== '1' && bridgeEnabled !== 'true') {
-        return undefined;
+        return { kind: 'no-bridge' };
     }
 
     const commands = await vscode.commands.getCommands(true);
     if (!commands.includes(DATA_BRIDGE_COMMAND)) {
-        return undefined;
+        return { kind: 'failure', reason: 'command-missing' };
     }
 
     logger.info('DataBridge enabled, polling for environment variables...', LogCategory.GENERAL);
     const deadline = Date.now() + POLL_TIMEOUT_MS;
+    let lastInvalidResponse: string | undefined;
 
     while (Date.now() < deadline) {
         try {
             // The data-bridge `getEnv` command requires a `string[]` argument
             // (validated server-side via arktype). Calling without args makes
             // the command return its error summary as a plain string, not a
             // record — which silently masquerades as an empty result.
-            const envMap = await vscode.commands.executeCommand<Record<string, string>>(
+            const envMap = await vscode.commands.executeCommand<Record<string, string> | string>(
                 DATA_BRIDGE_COMMAND,
                 [...names],
             );
 
             if (envMap && typeof envMap === 'object') {
-                if (names.every((name) => !!envMap[name])) {
+                if (names.every((name) => !!(envMap as Record<string, string>)[name])) {
                     logger.info('DataBridge: all environment variables received', LogCategory.GENERAL);
                     const result = {} as Record<T, string | undefined>;
                     for (const name of names) {
-                        result[name] = envMap[name] || undefined;
+                        result[name] = (envMap as Record<string, string>)[name] || undefined;
                     }
-                    return result;
+                    return { kind: 'success', env: result };
                 }
+            } else if (typeof envMap === 'string') {
+                // Bridge returned its error summary string — keep the latest
+                // for diagnostics if the deadline runs out before recovery.
+                lastInvalidResponse = envMap;
             }
-        } catch {
-            // data-bridge may not be ready yet — keep polling
+        } catch (e) {
+            // data-bridge may not be ready yet — keep polling. Capture the
+            // most recent error to surface if the deadline elapses.
+            lastInvalidResponse = e instanceof Error ? e.message : String(e);
         }
 
         await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
     }
 
     logger.warn(
-        'DataBridge: timeout waiting for environment variables, treating session as non-Theia',
+        'DataBridge: timeout waiting for environment variables',
         LogCategory.GENERAL,
     );
-    return undefined;
+    return { kind: 'failure', reason: 'timeout', details: lastInvalidResponse };
 }
 
 interface DataBridgeProbeResult {
diff --git a/extension/src/extension/theia/theiaEnvironment.ts b/extension/src/extension/theia/theiaEnvironment.ts
@@ -1,4 +1,6 @@
+import * as vscode from 'vscode';
 import { readEnvVarsViaDataBridge } from './dataBridgeReader';
+import { logger, LogCategory } from '../services/loggingService';
 import { VSCODE_ENVIRONMENT, type TheiaEnvironment } from './types';
 
 /**
@@ -43,17 +45,56 @@ export function getTheiaEnvironment(): TheiaEnvironment {
  * Detects whether the extension is running inside a Theia-based IDE
  * and reads all relevant environment variables.
  *
- * The data-bridge is the sole source of truth: in EduIDE deployments the
- * orchestrator POSTs credentials into the bridge after pod boot, and the
- * bridge command is only registered when its activation gate
- * (`DATA_BRIDGE_ENABLED=1`) is set. On regular VS Code Desktop neither is
- * true, so the call returns undefined and detection cleanly resolves to
- * the non-Theia default.
+ * The data-bridge is the sole source of truth. The reader distinguishes three
+ * outcomes; each maps to a different boot path here:
+ *  - `no-bridge`: `DATA_BRIDGE_ENABLED` not set → genuinely Desktop. Return
+ *    the non-Theia default; Cookie auth and interactive login are correct.
+ *  - `failure`: bridge was expected but unreachable. Surface a hard error so
+ *    the operator and the student see why authentication will not work,
+ *    instead of silently booting in Desktop-Cookie mode against an EduIDE
+ *    Artemis (which would then attempt the wrong auth scheme and fail with
+ *    a confusing 401). The extension still loads so the diagnostic command
+ *    remains accessible.
+ *  - `success`: bridge delivered all keys → Theia-managed environment.
  */
 async function detectTheiaEnvironment(): Promise<TheiaEnvironment> {
-    const env = await readEnvVarsViaDataBridge(THEIA_ENV_VARS);
+    const result = await readEnvVarsViaDataBridge(THEIA_ENV_VARS);
 
-    if (!env || !(env.ARTEMIS_TOKEN || env.ARTEMIS_URL)) {
+    if (result.kind === 'no-bridge') {
+        return VSCODE_ENVIRONMENT;
+    }
+
+    if (result.kind === 'failure') {
+        const reasonText =
+            result.reason === 'command-missing'
+                ? 'data-bridge extension not registered'
+                : result.reason === 'timeout'
+                    ? 'timed out waiting for credentials'
+                    : 'invalid response';
+        const detailsSuffix = result.details ? ` (${result.details})` : '';
+        logger.error(
+            `EduIDE bridge unavailable: ${reasonText}${detailsSuffix}`,
+            LogCategory.GENERAL,
+        );
+        void vscode.window.showErrorMessage(
+            `Iris: EduIDE bridge unavailable (${reasonText}). Authentication and auto-clone will not work. ` +
+                'Restart your EduIDE pod or contact support.',
+        );
+        return VSCODE_ENVIRONMENT;
+    }
+
+    const env = result.env;
+    if (!env.ARTEMIS_TOKEN || !env.ARTEMIS_URL) {
+        // Bridge responded but did not deliver the auth pair — same hard
+        // failure as `failure` from the caller's perspective.
+        logger.error(
+            'EduIDE bridge response missing ARTEMIS_URL or ARTEMIS_TOKEN',
+            LogCategory.GENERAL,
+        );
+        void vscode.window.showErrorMessage(
+            'Iris: EduIDE bridge returned an incomplete credential set. Authentication will not work. ' +
+                'Restart your EduIDE pod or contact support.',
+        );
         return VSCODE_ENVIRONMENT;
     }
 
diff --git a/extension/test/unit/theia/dataBridgeReader.test.ts b/extension/test/unit/theia/dataBridgeReader.test.ts
@@ -0,0 +1,133 @@
+/**
+ * Unit tests for readEnvVarsViaDataBridge.
+ *
+ * Verifies the discriminated-union return contract:
+ *  - DATA_BRIDGE_ENABLED unset → 'no-bridge'
+ *  - DATA_BRIDGE_ENABLED=1 + command not registered → 'failure: command-missing'
+ *  - DATA_BRIDGE_ENABLED=1 + command never delivers → 'failure: timeout'
+ *  - DATA_BRIDGE_ENABLED=1 + command returns full record → 'success'
+ *  - DATA_BRIDGE_ENABLED=1 + command returns partial record → eventually
+ *    'failure: timeout' (waits for all keys)
+ */
+
+import * as assert from 'assert';
+import * as sinon from 'sinon';
+import * as vscode from 'vscode';
+import { readEnvVarsViaDataBridge } from '../../../src/extension/theia/dataBridgeReader';
+
+const KEYS = ['ARTEMIS_URL', 'ARTEMIS_TOKEN'] as const;
+
+suite('readEnvVarsViaDataBridge', () => {
+    let sandbox: sinon.SinonSandbox;
+    let originalDataBridgeEnabled: string | undefined;
+
+    setup(() => {
+        sandbox = sinon.createSandbox();
+        originalDataBridgeEnabled = process.env.DATA_BRIDGE_ENABLED;
+    });
+
+    teardown(() => {
+        sandbox.restore();
+        if (originalDataBridgeEnabled === undefined) {
+            delete process.env.DATA_BRIDGE_ENABLED;
+        } else {
+            process.env.DATA_BRIDGE_ENABLED = originalDataBridgeEnabled;
+        }
+    });
+
+    test('returns no-bridge when DATA_BRIDGE_ENABLED is unset', async () => {
+        delete process.env.DATA_BRIDGE_ENABLED;
+
+        const result = await readEnvVarsViaDataBridge(KEYS);
+
+        assert.strictEqual(result.kind, 'no-bridge');
+    });
+
+    test('returns no-bridge when DATA_BRIDGE_ENABLED is "false"', async () => {
+        process.env.DATA_BRIDGE_ENABLED = 'false';
+
+        const result = await readEnvVarsViaDataBridge(KEYS);
+
+        assert.strictEqual(result.kind, 'no-bridge');
+    });
+
+    test('returns failure with reason=command-missing when bridge command is not registered', async () => {
+        process.env.DATA_BRIDGE_ENABLED = '1';
+        sandbox.stub(vscode.commands, 'getCommands').resolves(['some.other.command']);
+
+        const result = await readEnvVarsViaDataBridge(KEYS);
+
+        assert.strictEqual(result.kind, 'failure');
+        if (result.kind === 'failure') {
+            assert.strictEqual(result.reason, 'command-missing');
+        }
+    });
+
+    test('returns failure with reason=timeout when bridge command never delivers values', async () => {
+        process.env.DATA_BRIDGE_ENABLED = '1';
+        sandbox.stub(vscode.commands, 'getCommands').resolves(['dataBridge.getEnv']);
+        sandbox.stub(vscode.commands, 'executeCommand').resolves({});  // empty record forever
+
+        // Drive timeout deterministically by stubbing Date.now to leap past the 10s deadline.
+        const startTime = 1_000_000_000;
+        let nowOffset = 0;
+        sandbox.stub(Date, 'now').callsFake(() => startTime + nowOffset);
+        // First poll attempt sees deadline = start + 10000. Bump offset past that on the
+        // second call so the while-loop exits via deadline check.
+        const setTimeoutStub = sandbox.stub(global, 'setTimeout').callsFake((fn: TimerHandler) => {
+            nowOffset += 11_000;  // jump past deadline before the next iteration runs
+            if (typeof fn === 'function') { (fn as () => void)(); }
+            return 0 as unknown as NodeJS.Timeout;
+        });
+
+        const result = await readEnvVarsViaDataBridge(KEYS);
+
+        assert.strictEqual(result.kind, 'failure');
+        if (result.kind === 'failure') {
+            assert.strictEqual(result.reason, 'timeout');
+        }
+        // Polling happened at least once
+        assert.ok(setTimeoutStub.callCount >= 1);
+    });
+
+    test('returns failure with reason=timeout and details when bridge returns its error string', async () => {
+        process.env.DATA_BRIDGE_ENABLED = '1';
+        sandbox.stub(vscode.commands, 'getCommands').resolves(['dataBridge.getEnv']);
+        sandbox.stub(vscode.commands, 'executeCommand').resolves('arktype validation error: expected string[]');
+
+        const startTime = 1_000_000_000;
+        let nowOffset = 0;
+        sandbox.stub(Date, 'now').callsFake(() => startTime + nowOffset);
+        sandbox.stub(global, 'setTimeout').callsFake((fn: TimerHandler) => {
+            nowOffset += 11_000;
+            if (typeof fn === 'function') { (fn as () => void)(); }
+            return 0 as unknown as NodeJS.Timeout;
+        });
+
+        const result = await readEnvVarsViaDataBridge(KEYS);
+
+        assert.strictEqual(result.kind, 'failure');
+        if (result.kind === 'failure') {
+            assert.strictEqual(result.reason, 'timeout');
+            assert.ok(result.details && result.details.includes('arktype'),
+                `expected details to include the bridge error string, got: ${result.details}`);
+        }
+    });
+
+    test('returns success with all requested keys when bridge delivers them', async () => {
+        process.env.DATA_BRIDGE_ENABLED = '1';
+        sandbox.stub(vscode.commands, 'getCommands').resolves(['dataBridge.getEnv']);
+        sandbox.stub(vscode.commands, 'executeCommand').resolves({
+            ARTEMIS_URL: 'https://artemis.test',
+            ARTEMIS_TOKEN: 'jwt-abc',
+        });
+
+        const result = await readEnvVarsViaDataBridge(KEYS);
+
+        assert.strictEqual(result.kind, 'success');
+        if (result.kind === 'success') {
+            assert.strictEqual(result.env.ARTEMIS_URL, 'https://artemis.test');
+            assert.strictEqual(result.env.ARTEMIS_TOKEN, 'jwt-abc');
+        }
+    });
+});
diff --git a/extension/test/unit/theia/theiaEnvironment.test.ts b/extension/test/unit/theia/theiaEnvironment.test.ts
