@open-kingdom/shared-backend-integration-test-doubles 0.0.2-17 → 0.0.2-18

package/README.md

@@ -37,6 +37,30 @@ const client = new Storage({
 await twin.stop();
 ```
 
+### Using YouTube Twin (Server-Side Interception)
+
+```typescript
+import { YoutubeTwin, NodeInterceptor, RoutingTable, defaultRoutingEntries } from '@open-kingdom/shared-backend-integration-test-doubles';
+
+// Start the twin (default port 9016)
+const twin = new YoutubeTwin();
+await twin.start();
+
+// Install the global fetch interceptor
+const routingTable = new RoutingTable(defaultRoutingEntries);
+const interceptor = new NodeInterceptor(routingTable);
+interceptor.install();
+
+// Call the production YouTube API endpoint (internally routed to twin)
+const res = await fetch('https://www.googleapis.com/youtube/v3/search?q=yoga&key=valid-key');
+const data = await res.json();
+console.log(data.kind); // "youtube#searchListResponse"
+
+// Clean up
+interceptor.uninstall();
+await twin.stop();
+```
+
 ### NestJS Integration
 
 Use the `TwinService` to manage the twin lifecycle within a NestJS application:
@@ -93,6 +117,52 @@ interface BucketConfig {
 }
 ```
 
+### YouTubeTwin & Network Interceptor
+
+#### YouTubeTwin Constructor
+
+```typescript
+constructor(overrides?: Partial<YoutubeTwinConfig>)
+```
+
+- `overrides.port`: Port to run the twin on (default: 9016, or from `YOUTUBE_TWIN_PORT` env var; must be within 9010-9020)
+- `overrides.externalUrl`: External URL for the twin (default: `http://localhost:{port}`)
+
+#### YouTubeTwin Methods
+
+- `start()`: Start the Express server
+- `stop()`: Stop the Express server
+- `reset()`: Reset search fixtures to defaults and clear any active error mode
+- `getEmulatorHost()`: Get the twin URL (e.g., `http://localhost:9016`)
+- `isHealthy()`: Check if the twin is running and responding
+
+#### NodeInterceptor & RoutingTable
+
+- `new NodeInterceptor(routingTable)`: Instantiate interceptor
+- `install()`: Patches `globalThis.fetch` to intercept matching domains
+- `uninstall()`: Restores `globalThis.fetch` to its original reference
+- `isActive()`: Check if interceptor is currently active
+
+#### Browser-Side MSW Interception
+
+Use `getYoutubeMswHandlerConfigs(twinBaseUrl)` to export mock route definitions for browser-side testing frameworks like MSW:
+
+```typescript
+import { http, HttpResponse } from 'msw';
+import { getYoutubeMswHandlerConfigs } from '@open-kingdom/shared-backend-integration-test-doubles';
+
+const configs = getYoutubeMswHandlerConfigs('http://localhost:9016');
+const handlers = configs.map((config) =>
+  http.get(config.url, async () => {
+    const res = await fetch(config.proxyTo);
+    const body = await res.text();
+    return new HttpResponse(body, {
+      headers: { 'Content-Type': config.contentType },
+    });
+  })
+);
+```
+
 ### Exports
 
 ```typescript
@@ -127,7 +197,7 @@ The library reserves ports 9010-9020 for test doubles:
 | GCS             | 9013          |
 | Gmail           | 9014 (future) |
 | Google Auth     | 9015 (future) |
-| YouTube         | 9016 (future) |
+| YouTube         | 9016          |
 | Google Calendar | 9017 (future) |
 | Spotify         | 9018 (future) |
 
@@ -145,14 +215,14 @@ Port validation ensures the value is within the reserved range (9010-9020).
 
 ## Scripts
 
-### Start Twin Manually
+### Start Twins Manually
 
 ```bash
-# Start on default port (9013)
+# Start GCS twin manually on default port (9013)
 npx tsx scripts/start-twin.ts
 
-# Start on specific port
-npx tsx scripts/start-twin.ts 9013
+# Start YouTube twin manually on default port (9016)
+npx nx run integration-test-doubles:start:youtube-twin
 ```
 
 The script outputs the twin URL and sets `GCS_EMULATOR_URL`. Keeps running until Ctrl+C.

package/dist/gcs/gcs-error-mode.d.ts

@@ -0,0 +1,161 @@
+/**
+ * GCS error mode simulation — pure state management and request matching.
+ *
+ * The GcsErrorModeManager knows nothing about HTTP, NestJS, or networking.
+ * It holds the currently active error mode, matches incoming requests against
+ * the mode's criteria, and returns the appropriate GCS-shaped error response.
+ *
+ * Design decisions:
+ * - Single-mode constraint: only one error mode can be active at a time.
+ *   setMode() replaces any existing mode.
+ * - Intermittent-failure uses a deterministic counter (every Nth request fails),
+ *   not random percentage, for reproducible test results.
+ * - reset() and clearMode() clear the mode and counter, ensuring no leakage
+ *   between test runs.
+ */
+/**
+ * The four supported GCS error simulation modes.
+ */
+export type GcsErrorModeType = 'bucket-not-found' | 'quota-exceeded' | 'permission-denied' | 'intermittent-failure';
+/**
+ * Configuration for bucket-not-found mode.
+ * Matches requests targeting a specific bucket name.
+ */
+export interface BucketNotFoundConfig {
+    type: 'bucket-not-found';
+    /** The bucket name that will trigger the 404 response. */
+    bucketName: string;
+}
+/**
+ * Configuration for quota-exceeded mode.
+ * Matches upload/create operations (POST to upload paths).
+ */
+export interface QuotaExceededConfig {
+    type: 'quota-exceeded';
+}
+/**
+ * Configuration for permission-denied mode.
+ * Matches all GCS data operations.
+ */
+export interface PermissionDeniedConfig {
+    type: 'permission-denied';
+}
+/**
+ * Configuration for intermittent-failure mode.
+ * Every Nth request fails with 500, deterministic counter.
+ */
+export interface IntermittentFailureConfig {
+    type: 'intermittent-failure';
+    /** Fail every Nth request. Defaults to 2 (every other request). */
+    every?: number;
+}
+/**
+ * Discriminated union of all error mode configurations.
+ * The `type` field discriminates which kind of mode is active.
+ */
+export type GcsErrorModeConfig = BucketNotFoundConfig | QuotaExceededConfig | PermissionDeniedConfig | IntermittentFailureConfig;
+/**
+ * A GCS-shaped error response that the NestJS interceptor will use
+ * to short-circuit matching requests.
+ */
+export interface GcsErrorSimulationResult {
+    /** HTTP status code to respond with. */
+    status: number;
+    /** GCS-shaped JSON error body. */
+    body: {
+        error: {
+            code: number;
+            message: string;
+            errors: Array<{
+                domain: string;
+                reason: string;
+                message?: string;
+            }>;
+        };
+    };
+}
+/**
+ * Extract the bucket name from a GCS API path.
+ *
+ * Supports both path-style and virtual-hosted-style paths:
+ * - `/storage/v1/b/my-bucket/o` → "my-bucket"
+ * - `/storage/v1/b/my-bucket` → "my-bucket"
+ * - `/upload/storage/v1/b/my-bucket/o` → "my-bucket"
+ * - `/download/storage/v1/b/my-bucket/o` → "my-bucket"
+ * - `/b/my-bucket/o` → "my-bucket"
+ *
+ * Returns undefined if the path doesn't match any known GCS pattern.
+ */
+export declare function extractBucketName(path: string): string | undefined;
+/**
+ * Determine if a request is an upload/create operation.
+ *
+ * Upload operations are POST requests to paths containing "/upload/" or
+ * POST requests to bucket or object creation endpoints.
+ */
+export declare function isUploadOperation(method: string, path: string): boolean;
+/**
+ * Determine if a request is a GCS data operation.
+ *
+ * GCS data operations include CRUD on buckets and objects.
+ * They exclude twin control endpoints (/api/twin/...) and health checks.
+ */
+export declare function isGcsDataOperation(method: string, path: string): boolean;
+/**
+ * Pure state manager for GCS error simulation modes.
+ *
+ * Tracks the active error mode and matches incoming requests against it.
+ * Returns null for pass-through when no mode is active.
+ *
+ * Thread-safety: this class is NOT thread-safe. In NestJS, requests are
+ * handled concurrently, so the counter for intermittent-failure mode must
+ * be managed with atomic operations or a mutex in the interceptor layer.
+ * For now, we use a simple counter since NestJS interceptors run on the
+ * event loop and the matching logic is synchronous.
+ */
+export declare class GcsErrorModeManager {
+    private activeMode;
+    private requestCounter;
+    /**
+     * Activate an error mode. Replaces any existing mode (single-mode constraint).
+     * Resets the request counter for intermittent-failure mode.
+     */
+    setMode(config: GcsErrorModeConfig): void;
+    /**
+     * Deactivate the current error mode. Returns to pass-through.
+     * Resets the request counter.
+     */
+    clearMode(): void;
+    /**
+     * Get the currently active error mode configuration.
+     * Returns null when no mode is active (pass-through).
+     */
+    getMode(): GcsErrorModeConfig | null;
+    /**
+     * Match an incoming request against the active error mode.
+     *
+     * @param method - HTTP method (GET, POST, PUT, DELETE, etc.)
+     * @param path - Request path (e.g., /storage/v1/b/my-bucket/o)
+     * @returns GcsErrorSimulationResult if the request matches, null for pass-through
+     */
+    matchRequest(method: string, path: string): GcsErrorSimulationResult | null;
+    /**
+     * Simulate a sample error for the currently active mode.
+     * This produces the same GcsErrorSimulationResult that the interceptor would
+     * return for a matching request, without mutating the request counter.
+     *
+     * Used by the GET /api/twin/gcs/error-mode endpoint so the frontend can
+     * display the actual error response the backend will produce.
+     */
+    simulateSampleError(): GcsErrorSimulationResult | null;
+    /**
+     * Reset all state: clear the active mode and reset the request counter.
+     * Called by GcsTwin.reset() and GcsTwin.stop() to prevent leakage between tests.
+     */
+    reset(): void;
+    private matchBucketNotFound;
+    private matchQuotaExceeded;
+    private matchPermissionDenied;
+    private matchIntermittentFailure;
+}
+//# sourceMappingURL=gcs-error-mode.d.ts.map

package/dist/gcs/gcs-error-mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gcs-error-mode.d.ts","sourceRoot":"","sources":["../../src/gcs/gcs-error-mode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH;;GAEG;AACH,MAAM,MAAM,gBAAgB,GACxB,kBAAkB,GAClB,gBAAgB,GAChB,mBAAmB,GACnB,sBAAsB,CAAC;AAE3B;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,kBAAkB,CAAC;IACzB,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,gBAAgB,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,mBAAmB,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,sBAAsB,CAAC;IAC7B,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAC1B,oBAAoB,GACpB,mBAAmB,GACnB,sBAAsB,GACtB,yBAAyB,CAAC;AAE9B;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,IAAI,EAAE;QACJ,KAAK,EAAE;YACL,IAAI,EAAE,MAAM,CAAC;YACb,OAAO,EAAE,MAAM,CAAC;YAChB,MAAM,EAAE,KAAK,CAAC;gBACZ,MAAM,EAAE,MAAM,CAAC;gBACf,MAAM,EAAE,MAAM,CAAC;gBACf,OAAO,CAAC,EAAE,MAAM,CAAC;aAClB,CAAC,CAAC;SACJ,CAAC;KACH,CAAC;CACH;AAmCD;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAsClE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAuBvE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CA8BxE;AAMD;;;;;;;;;;;GAWG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,UAAU,CAAmC;IACrD,OAAO,CAAC,cAAc,CAAK;IAE3B;;;OAGG;IACH,OAAO,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI;IAKzC;;;OAGG;IACH,SAAS,IAAI,IAAI;IAKjB;;;OAGG;IACH,OAAO,IAAI,kBAAkB,GAAG,IAAI;IAIpC;;;;;;OAMG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,wBAAwB,GAAG,IAAI;IAe3E;;;;;;;OAOG;IACH,mBAAmB,IAAI,wBAAwB,GAAG,IAAI;IAgBtD;;;OAGG;IACH,KAAK,IAAI,IAAI;IASb,OAAO,CAAC,mBAAmB;IAY3B,OAAO,CAAC,kBAAkB;IAW1B,OAAO,CAAC,qBAAqB;IAW7B,OAAO,CAAC,wBAAwB;CAkBjC"}

package/dist/gcs/gcs-error-mode.js

@@ -0,0 +1,256 @@
+/**
+ * GCS error mode simulation — pure state management and request matching.
+ *
+ * The GcsErrorModeManager knows nothing about HTTP, NestJS, or networking.
+ * It holds the currently active error mode, matches incoming requests against
+ * the mode's criteria, and returns the appropriate GCS-shaped error response.
+ *
+ * Design decisions:
+ * - Single-mode constraint: only one error mode can be active at a time.
+ *   setMode() replaces any existing mode.
+ * - Intermittent-failure uses a deterministic counter (every Nth request fails),
+ *   not random percentage, for reproducible test results.
+ * - reset() and clearMode() clear the mode and counter, ensuring no leakage
+ *   between test runs.
+ */ // ---------------------------------------------------------------------------
+// Type definitions
+// ---------------------------------------------------------------------------
+/**
+ * The four supported GCS error simulation modes.
+ */ // ---------------------------------------------------------------------------
+// GCS error response factory
+// ---------------------------------------------------------------------------
+/** Creates a standard GCS error response shape. */ function gcsError(status, message, reason, detailMessage) {
+    return {
+        status,
+        body: {
+            error: {
+                code: status,
+                message,
+                errors: [
+                    {
+                        domain: 'global',
+                        reason,
+                        message: detailMessage != null ? detailMessage : message
+                    }
+                ]
+            }
+        }
+    };
+}
+// ---------------------------------------------------------------------------
+// Request-matching helpers
+// ---------------------------------------------------------------------------
+/**
+ * Extract the bucket name from a GCS API path.
+ *
+ * Supports both path-style and virtual-hosted-style paths:
+ * - `/storage/v1/b/my-bucket/o` → "my-bucket"
+ * - `/storage/v1/b/my-bucket` → "my-bucket"
+ * - `/upload/storage/v1/b/my-bucket/o` → "my-bucket"
+ * - `/download/storage/v1/b/my-bucket/o` → "my-bucket"
+ * - `/b/my-bucket/o` → "my-bucket"
+ *
+ * Returns undefined if the path doesn't match any known GCS pattern.
+ */ export function extractBucketName(path) {
+    // Strip leading slash for consistent processing
+    const normalized = path.startsWith('/') ? path.slice(1) : path;
+    // Match /api/gcs/files?bucket=<name> (query-string style)
+    const apiGcsBucketMatch = normalized.match(/api\/gcs\/files[?&]bucket=([^&]+)/);
+    if (apiGcsBucketMatch) {
+        return decodeURIComponent(apiGcsBucketMatch[1]);
+    }
+    // Match /api/gcs/files/<bucket>/<name>/... or /api/gcs/files/<bucket>/<name>
+    const apiGcsPathMatch = normalized.match(/api\/gcs\/files\/([^/]+)/);
+    if (apiGcsPathMatch) {
+        return decodeURIComponent(apiGcsPathMatch[1]);
+    }
+    // Match /api/gcs/upload (uses query param or default bucket — derive from body is not possible here)
+    // Uploads via /api/gcs/upload use the bucket in the request body, not URL. Return undefined for now.
+    // Match patterns with optional prefixes (upload/, download/) followed by
+    // the GCS API path structure.
+    const patterns = [
+        // Full v1 API paths: storage/v1/b/{bucket}/... or upload/storage/v1/b/{bucket}/...
+        /(?:upload\/|download\/)?storage\/v1\/b\/([^/]+)/,
+        // Short form: b/{bucket}/...
+        /b\/([^/]+)/
+    ];
+    for (const pattern of patterns){
+        const match = normalized.match(pattern);
+        if (match) {
+            return match[1];
+        }
+    }
+    return undefined;
+}
+/**
+ * Determine if a request is an upload/create operation.
+ *
+ * Upload operations are POST requests to paths containing "/upload/" or
+ * POST requests to bucket or object creation endpoints.
+ */ export function isUploadOperation(method, path) {
+    if (method.toUpperCase() !== 'POST') return false;
+    const normalized = path.toLowerCase();
+    // /api/gcs/upload — the NestJS GCS upload endpoint
+    if (normalized.includes('/api/gcs/upload')) return true;
+    // /api/gcs/files/<bucket>/<name>/delete — treated as a write operation for permission-denied
+    // (not an upload, but this function is specifically for quota-exceeded which targets uploads)
+    // Direct upload path prefix (GCS native)
+    if (normalized.includes('/upload/storage/')) return true;
+    // Object insert via bucket's objects collection
+    // POST /storage/v1/b/{bucket}/o
+    if (normalized.includes('/b/') && normalized.includes('/o')) return true;
+    // Bucket creation
+    // POST /storage/v1/b
+    if (normalized.match(/\/storage\/v1\/b\/?$/)) return true;
+    return false;
+}
+/**
+ * Determine if a request is a GCS data operation.
+ *
+ * GCS data operations include CRUD on buckets and objects.
+ * They exclude twin control endpoints (/api/twin/...) and health checks.
+ */ export function isGcsDataOperation(method, path) {
+    const normalized = path.toLowerCase();
+    // Exclude twin control endpoints
+    if (normalized.startsWith('/api/twin')) return false;
+    // Exclude error-mode control endpoints (control plane, not data plane)
+    if (normalized.startsWith('/api/gcs/error-mode')) return false;
+    // Exclude health checks and non-GCS paths
+    if (normalized === '/' || normalized === '/health' || normalized === '/healthz') {
+        return false;
+    }
+    // NestJS GCS controller routes: /api/gcs/*
+    if (normalized.startsWith('/api/gcs')) return true;
+    // Include known GCS API paths
+    if (normalized.includes('/storage/v1/')) return true;
+    if (normalized.includes('/upload/storage/')) return true;
+    if (normalized.includes('/download/storage/')) return true;
+    // Include paths that match GCS bucket/object patterns
+    if (normalized.match(/\/b\/[^/]+/)) return true;
+    return false;
+}
+// ---------------------------------------------------------------------------
+// GcsErrorModeManager
+// ---------------------------------------------------------------------------
+/**
+ * Pure state manager for GCS error simulation modes.
+ *
+ * Tracks the active error mode and matches incoming requests against it.
+ * Returns null for pass-through when no mode is active.
+ *
+ * Thread-safety: this class is NOT thread-safe. In NestJS, requests are
+ * handled concurrently, so the counter for intermittent-failure mode must
+ * be managed with atomic operations or a mutex in the interceptor layer.
+ * For now, we use a simple counter since NestJS interceptors run on the
+ * event loop and the matching logic is synchronous.
+ */ export class GcsErrorModeManager {
+    /**
+   * Activate an error mode. Replaces any existing mode (single-mode constraint).
+   * Resets the request counter for intermittent-failure mode.
+   */ setMode(config) {
+        this.activeMode = config;
+        this.requestCounter = 0;
+    }
+    /**
+   * Deactivate the current error mode. Returns to pass-through.
+   * Resets the request counter.
+   */ clearMode() {
+        this.activeMode = null;
+        this.requestCounter = 0;
+    }
+    /**
+   * Get the currently active error mode configuration.
+   * Returns null when no mode is active (pass-through).
+   */ getMode() {
+        return this.activeMode;
+    }
+    /**
+   * Match an incoming request against the active error mode.
+   *
+   * @param method - HTTP method (GET, POST, PUT, DELETE, etc.)
+   * @param path - Request path (e.g., /storage/v1/b/my-bucket/o)
+   * @returns GcsErrorSimulationResult if the request matches, null for pass-through
+   */ matchRequest(method, path) {
+        if (!this.activeMode) return null;
+        switch(this.activeMode.type){
+            case 'bucket-not-found':
+                return this.matchBucketNotFound(method, path, this.activeMode);
+            case 'quota-exceeded':
+                return this.matchQuotaExceeded(method, path, this.activeMode);
+            case 'permission-denied':
+                return this.matchPermissionDenied(method, path, this.activeMode);
+            case 'intermittent-failure':
+                return this.matchIntermittentFailure(method, path, this.activeMode);
+        }
+    }
+    /**
+   * Simulate a sample error for the currently active mode.
+   * This produces the same GcsErrorSimulationResult that the interceptor would
+   * return for a matching request, without mutating the request counter.
+   *
+   * Used by the GET /api/twin/gcs/error-mode endpoint so the frontend can
+   * display the actual error response the backend will produce.
+   */ simulateSampleError() {
+        if (!this.activeMode) return null;
+        switch(this.activeMode.type){
+            case 'bucket-not-found':
+                // Representative: a GET to the configured bucket
+                return gcsError(404, 'Not Found', 'notFound');
+            case 'quota-exceeded':
+                return gcsError(403, 'Quota exceeded', 'quotaExceeded');
+            case 'permission-denied':
+                return gcsError(403, 'Forbidden', 'forbidden');
+            case 'intermittent-failure':
+                return gcsError(500, 'Internal Server Error', 'internalError');
+        }
+    }
+    /**
+   * Reset all state: clear the active mode and reset the request counter.
+   * Called by GcsTwin.reset() and GcsTwin.stop() to prevent leakage between tests.
+   */ reset() {
+        this.activeMode = null;
+        this.requestCounter = 0;
+    }
+    // ---------------------------------------------------------------------------
+    // Private matching methods
+    // ---------------------------------------------------------------------------
+    matchBucketNotFound(_method, path, config) {
+        const bucket = extractBucketName(path);
+        if (bucket === config.bucketName) {
+            return gcsError(404, 'Not Found', 'notFound');
+        }
+        return null;
+    }
+    matchQuotaExceeded(method, path, _config) {
+        if (isUploadOperation(method, path)) {
+            return gcsError(403, 'Quota exceeded', 'quotaExceeded');
+        }
+        return null;
+    }
+    matchPermissionDenied(method, path, _config) {
+        if (isGcsDataOperation(method, path)) {
+            return gcsError(403, 'Forbidden', 'forbidden');
+        }
+        return null;
+    }
+    matchIntermittentFailure(method, path, config) {
+        // Only apply to GCS data operations
+        if (!isGcsDataOperation(method, path)) {
+            return null;
+        }
+        this.requestCounter++;
+        var _config_every;
+        const every = (_config_every = config.every) != null ? _config_every : 2;
+        if (this.requestCounter % every === 0) {
+            return gcsError(500, 'Internal Server Error', 'internalError');
+        }
+        return null;
+    }
+    constructor(){
+        this.activeMode = null;
+        this.requestCounter = 0;
+    }
+}
+
+//# sourceMappingURL=gcs-error-mode.js.map

package/dist/gcs/gcs-error-mode.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/gcs/gcs-error-mode.ts"],"sourcesContent":["/**\n * GCS error mode simulation — pure state management and request matching.\n *\n * The GcsErrorModeManager knows nothing about HTTP, NestJS, or networking.\n * It holds the currently active error mode, matches incoming requests against\n * the mode's criteria, and returns the appropriate GCS-shaped error response.\n *\n * Design decisions:\n * - Single-mode constraint: only one error mode can be active at a time.\n *   setMode() replaces any existing mode.\n * - Intermittent-failure uses a deterministic counter (every Nth request fails),\n *   not random percentage, for reproducible test results.\n * - reset() and clearMode() clear the mode and counter, ensuring no leakage\n *   between test runs.\n */\n\n// ---------------------------------------------------------------------------\n// Type definitions\n// ---------------------------------------------------------------------------\n\n/**\n * The four supported GCS error simulation modes.\n */\nexport type GcsErrorModeType =\n  | 'bucket-not-found'\n  | 'quota-exceeded'\n  | 'permission-denied'\n  | 'intermittent-failure';\n\n/**\n * Configuration for bucket-not-found mode.\n * Matches requests targeting a specific bucket name.\n */\nexport interface BucketNotFoundConfig {\n  type: 'bucket-not-found';\n  /** The bucket name that will trigger the 404 response. */\n  bucketName: string;\n}\n\n/**\n * Configuration for quota-exceeded mode.\n * Matches upload/create operations (POST to upload paths).\n */\nexport interface QuotaExceededConfig {\n  type: 'quota-exceeded';\n}\n\n/**\n * Configuration for permission-denied mode.\n * Matches all GCS data operations.\n */\nexport interface PermissionDeniedConfig {\n  type: 'permission-denied';\n}\n\n/**\n * Configuration for intermittent-failure mode.\n * Every Nth request fails with 500, deterministic counter.\n */\nexport interface IntermittentFailureConfig {\n  type: 'intermittent-failure';\n  /** Fail every Nth request. Defaults to 2 (every other request). */\n  every?: number;\n}\n\n/**\n * Discriminated union of all error mode configurations.\n * The `type` field discriminates which kind of mode is active.\n */\nexport type GcsErrorModeConfig =\n  | BucketNotFoundConfig\n  | QuotaExceededConfig\n  | PermissionDeniedConfig\n  | IntermittentFailureConfig;\n\n/**\n * A GCS-shaped error response that the NestJS interceptor will use\n * to short-circuit matching requests.\n */\nexport interface GcsErrorSimulationResult {\n  /** HTTP status code to respond with. */\n  status: number;\n  /** GCS-shaped JSON error body. */\n  body: {\n    error: {\n      code: number;\n      message: string;\n      errors: Array<{\n        domain: string;\n        reason: string;\n        message?: string;\n      }>;\n    };\n  };\n}\n\n// ---------------------------------------------------------------------------\n// GCS error response factory\n// ---------------------------------------------------------------------------\n\n/** Creates a standard GCS error response shape. */\nfunction gcsError(\n  status: number,\n  message: string,\n  reason: string,\n  detailMessage?: string\n): GcsErrorSimulationResult {\n  return {\n    status,\n    body: {\n      error: {\n        code: status,\n        message,\n        errors: [\n          {\n            domain: 'global',\n            reason,\n            message: detailMessage ?? message,\n          },\n        ],\n      },\n    },\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Request-matching helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Extract the bucket name from a GCS API path.\n *\n * Supports both path-style and virtual-hosted-style paths:\n * - `/storage/v1/b/my-bucket/o` → \"my-bucket\"\n * - `/storage/v1/b/my-bucket` → \"my-bucket\"\n * - `/upload/storage/v1/b/my-bucket/o` → \"my-bucket\"\n * - `/download/storage/v1/b/my-bucket/o` → \"my-bucket\"\n * - `/b/my-bucket/o` → \"my-bucket\"\n *\n * Returns undefined if the path doesn't match any known GCS pattern.\n */\nexport function extractBucketName(path: string): string | undefined {\n  // Strip leading slash for consistent processing\n  const normalized = path.startsWith('/') ? path.slice(1) : path;\n\n  // Match /api/gcs/files?bucket=<name> (query-string style)\n  const apiGcsBucketMatch = normalized.match(\n    /api\\/gcs\\/files[?&]bucket=([^&]+)/\n  );\n  if (apiGcsBucketMatch) {\n    return decodeURIComponent(apiGcsBucketMatch[1]);\n  }\n\n  // Match /api/gcs/files/<bucket>/<name>/... or /api/gcs/files/<bucket>/<name>\n  const apiGcsPathMatch = normalized.match(/api\\/gcs\\/files\\/([^/]+)/);\n  if (apiGcsPathMatch) {\n    return decodeURIComponent(apiGcsPathMatch[1]);\n  }\n\n  // Match /api/gcs/upload (uses query param or default bucket — derive from body is not possible here)\n  // Uploads via /api/gcs/upload use the bucket in the request body, not URL. Return undefined for now.\n\n  // Match patterns with optional prefixes (upload/, download/) followed by\n  // the GCS API path structure.\n  const patterns = [\n    // Full v1 API paths: storage/v1/b/{bucket}/... or upload/storage/v1/b/{bucket}/...\n    /(?:upload\\/|download\\/)?storage\\/v1\\/b\\/([^/]+)/,\n    // Short form: b/{bucket}/...\n    /b\\/([^/]+)/,\n  ];\n\n  for (const pattern of patterns) {\n    const match = normalized.match(pattern);\n    if (match) {\n      return match[1];\n    }\n  }\n\n  return undefined;\n}\n\n/**\n * Determine if a request is an upload/create operation.\n *\n * Upload operations are POST requests to paths containing \"/upload/\" or\n * POST requests to bucket or object creation endpoints.\n */\nexport function isUploadOperation(method: string, path: string): boolean {\n  if (method.toUpperCase() !== 'POST') return false;\n\n  const normalized = path.toLowerCase();\n\n  // /api/gcs/upload — the NestJS GCS upload endpoint\n  if (normalized.includes('/api/gcs/upload')) return true;\n\n  // /api/gcs/files/<bucket>/<name>/delete — treated as a write operation for permission-denied\n  // (not an upload, but this function is specifically for quota-exceeded which targets uploads)\n\n  // Direct upload path prefix (GCS native)\n  if (normalized.includes('/upload/storage/')) return true;\n\n  // Object insert via bucket's objects collection\n  // POST /storage/v1/b/{bucket}/o\n  if (normalized.includes('/b/') && normalized.includes('/o')) return true;\n\n  // Bucket creation\n  // POST /storage/v1/b\n  if (normalized.match(/\\/storage\\/v1\\/b\\/?$/)) return true;\n\n  return false;\n}\n\n/**\n * Determine if a request is a GCS data operation.\n *\n * GCS data operations include CRUD on buckets and objects.\n * They exclude twin control endpoints (/api/twin/...) and health checks.\n */\nexport function isGcsDataOperation(method: string, path: string): boolean {\n  const normalized = path.toLowerCase();\n\n  // Exclude twin control endpoints\n  if (normalized.startsWith('/api/twin')) return false;\n\n  // Exclude error-mode control endpoints (control plane, not data plane)\n  if (normalized.startsWith('/api/gcs/error-mode')) return false;\n\n  // Exclude health checks and non-GCS paths\n  if (\n    normalized === '/' ||\n    normalized === '/health' ||\n    normalized === '/healthz'\n  ) {\n    return false;\n  }\n\n  // NestJS GCS controller routes: /api/gcs/*\n  if (normalized.startsWith('/api/gcs')) return true;\n\n  // Include known GCS API paths\n  if (normalized.includes('/storage/v1/')) return true;\n  if (normalized.includes('/upload/storage/')) return true;\n  if (normalized.includes('/download/storage/')) return true;\n\n  // Include paths that match GCS bucket/object patterns\n  if (normalized.match(/\\/b\\/[^/]+/)) return true;\n\n  return false;\n}\n\n// ---------------------------------------------------------------------------\n// GcsErrorModeManager\n// ---------------------------------------------------------------------------\n\n/**\n * Pure state manager for GCS error simulation modes.\n *\n * Tracks the active error mode and matches incoming requests against it.\n * Returns null for pass-through when no mode is active.\n *\n * Thread-safety: this class is NOT thread-safe. In NestJS, requests are\n * handled concurrently, so the counter for intermittent-failure mode must\n * be managed with atomic operations or a mutex in the interceptor layer.\n * For now, we use a simple counter since NestJS interceptors run on the\n * event loop and the matching logic is synchronous.\n */\nexport class GcsErrorModeManager {\n  private activeMode: GcsErrorModeConfig | null = null;\n  private requestCounter = 0;\n\n  /**\n   * Activate an error mode. Replaces any existing mode (single-mode constraint).\n   * Resets the request counter for intermittent-failure mode.\n   */\n  setMode(config: GcsErrorModeConfig): void {\n    this.activeMode = config;\n    this.requestCounter = 0;\n  }\n\n  /**\n   * Deactivate the current error mode. Returns to pass-through.\n   * Resets the request counter.\n   */\n  clearMode(): void {\n    this.activeMode = null;\n    this.requestCounter = 0;\n  }\n\n  /**\n   * Get the currently active error mode configuration.\n   * Returns null when no mode is active (pass-through).\n   */\n  getMode(): GcsErrorModeConfig | null {\n    return this.activeMode;\n  }\n\n  /**\n   * Match an incoming request against the active error mode.\n   *\n   * @param method - HTTP method (GET, POST, PUT, DELETE, etc.)\n   * @param path - Request path (e.g., /storage/v1/b/my-bucket/o)\n   * @returns GcsErrorSimulationResult if the request matches, null for pass-through\n   */\n  matchRequest(method: string, path: string): GcsErrorSimulationResult | null {\n    if (!this.activeMode) return null;\n\n    switch (this.activeMode.type) {\n      case 'bucket-not-found':\n        return this.matchBucketNotFound(method, path, this.activeMode);\n      case 'quota-exceeded':\n        return this.matchQuotaExceeded(method, path, this.activeMode);\n      case 'permission-denied':\n        return this.matchPermissionDenied(method, path, this.activeMode);\n      case 'intermittent-failure':\n        return this.matchIntermittentFailure(method, path, this.activeMode);\n    }\n  }\n\n  /**\n   * Simulate a sample error for the currently active mode.\n   * This produces the same GcsErrorSimulationResult that the interceptor would\n   * return for a matching request, without mutating the request counter.\n   *\n   * Used by the GET /api/twin/gcs/error-mode endpoint so the frontend can\n   * display the actual error response the backend will produce.\n   */\n  simulateSampleError(): GcsErrorSimulationResult | null {\n    if (!this.activeMode) return null;\n\n    switch (this.activeMode.type) {\n      case 'bucket-not-found':\n        // Representative: a GET to the configured bucket\n        return gcsError(404, 'Not Found', 'notFound');\n      case 'quota-exceeded':\n        return gcsError(403, 'Quota exceeded', 'quotaExceeded');\n      case 'permission-denied':\n        return gcsError(403, 'Forbidden', 'forbidden');\n      case 'intermittent-failure':\n        return gcsError(500, 'Internal Server Error', 'internalError');\n    }\n  }\n\n  /**\n   * Reset all state: clear the active mode and reset the request counter.\n   * Called by GcsTwin.reset() and GcsTwin.stop() to prevent leakage between tests.\n   */\n  reset(): void {\n    this.activeMode = null;\n    this.requestCounter = 0;\n  }\n\n  // ---------------------------------------------------------------------------\n  // Private matching methods\n  // ---------------------------------------------------------------------------\n\n  private matchBucketNotFound(\n    _method: string,\n    path: string,\n    config: BucketNotFoundConfig\n  ): GcsErrorSimulationResult | null {\n    const bucket = extractBucketName(path);\n    if (bucket === config.bucketName) {\n      return gcsError(404, 'Not Found', 'notFound');\n    }\n    return null;\n  }\n\n  private matchQuotaExceeded(\n    method: string,\n    path: string,\n    _config: QuotaExceededConfig\n  ): GcsErrorSimulationResult | null {\n    if (isUploadOperation(method, path)) {\n      return gcsError(403, 'Quota exceeded', 'quotaExceeded');\n    }\n    return null;\n  }\n\n  private matchPermissionDenied(\n    method: string,\n    path: string,\n    _config: PermissionDeniedConfig\n  ): GcsErrorSimulationResult | null {\n    if (isGcsDataOperation(method, path)) {\n      return gcsError(403, 'Forbidden', 'forbidden');\n    }\n    return null;\n  }\n\n  private matchIntermittentFailure(\n    method: string,\n    path: string,\n    config: IntermittentFailureConfig\n  ): GcsErrorSimulationResult | null {\n    // Only apply to GCS data operations\n    if (!isGcsDataOperation(method, path)) {\n      return null;\n    }\n\n    this.requestCounter++;\n    const every = config.every ?? 2;\n\n    if (this.requestCounter % every === 0) {\n      return gcsError(500, 'Internal Server Error', 'internalError');\n    }\n    return null;\n  }\n}\n"],"names":["gcsError","status","message","reason","detailMessage","body","error","code","errors","domain","extractBucketName","path","normalized","startsWith","slice","apiGcsBucketMatch","match","decodeURIComponent","apiGcsPathMatch","patterns","pattern","undefined","isUploadOperation","method","toUpperCase","toLowerCase","includes","isGcsDataOperation","GcsErrorModeManager","setMode","config","activeMode","requestCounter","clearMode","getMode","matchRequest","type","matchBucketNotFound","matchQuotaExceeded","matchPermissionDenied","matchIntermittentFailure","simulateSampleError","reset","_method","bucket","bucketName","_config","every"],"rangeMappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;","mappings":"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"}

package/dist/gcs/gcs-error-simulation.interceptor.d.ts

@@ -0,0 +1,21 @@
+import { NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
+import { Observable } from 'rxjs';
+import { GcsErrorModeManager } from './gcs-error-mode.js';
+/**
+ * NestJS interceptor that checks the active GCS error mode and short-circuits
+ * matching requests with GCS-shaped error responses.
+ *
+ * Registered as APP_INTERCEPTOR (global) but exits immediately for non-GCS routes.
+ * The route-prefix check is a cheap string comparison before any mode lookup.
+ *
+ * When an error mode matches, the interceptor throws an HttpException with the
+ * GCS error status code (403, 404, 500) so that the frontend receives a proper
+ * HTTP error response — not a 200 with an error body.
+ */
+export declare class GcsErrorSimulationInterceptor implements NestInterceptor {
+    private readonly errorModeManager;
+    private readonly logger;
+    constructor(errorModeManager: GcsErrorModeManager);
+    intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+}
+//# sourceMappingURL=gcs-error-simulation.interceptor.d.ts.map

package/dist/gcs/gcs-error-simulation.interceptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gcs-error-simulation.interceptor.d.ts","sourceRoot":"","sources":["../../src/gcs/gcs-error-simulation.interceptor.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,eAAe,EACf,gBAAgB,EAChB,WAAW,EAGZ,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAClC,OAAO,EAAE,mBAAmB,EAAsB,MAAM,qBAAqB,CAAC;AAE9E;;;;;;;;;;GAUG;AACH,qBACa,6BAA8B,YAAW,eAAe;IAGvD,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IAF7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkD;gBAE5C,gBAAgB,EAAE,mBAAmB;IAElE,SAAS,CAAC,OAAO,EAAE,gBAAgB,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,CAAC,OAAO,CAAC;CAgC7E"}

package/dist/gcs/gcs-error-simulation.interceptor.js

@@ -0,0 +1,40 @@
+import { _ as _ts_decorate } from "@swc/helpers/_/_ts_decorate";
+import { _ as _ts_metadata } from "@swc/helpers/_/_ts_metadata";
+import { Injectable, Logger, HttpException } from '@nestjs/common';
+import { GcsErrorModeManager, isGcsDataOperation } from './gcs-error-mode.js';
+export class GcsErrorSimulationInterceptor {
+    intercept(context, next) {
+        const request = context.switchToHttp().getRequest();
+        const method = request.method;
+        const path = request.url;
+        // Fast exit: only intercept GCS data operation routes
+        if (!isGcsDataOperation(method, path)) {
+            return next.handle();
+        }
+        const result = this.errorModeManager.matchRequest(method, path);
+        if (result) {
+            this.logger.warn(`Error mode intercepted ${method} ${path} → ${result.status} (${result.body.error.errors[0].reason})`);
+            // Throw with the real HTTP status code so the client gets a proper error response
+            throw new HttpException(result.body, result.status);
+        }
+        // Debug-level log when a mode is active but this request passed through
+        const activeMode = this.errorModeManager.getMode();
+        if (activeMode) {
+            this.logger.debug(`Error mode '${activeMode.type}' active but ${method} ${path} passed through`);
+        }
+        return next.handle();
+    }
+    constructor(errorModeManager){
+        this.errorModeManager = errorModeManager;
+        this.logger = new Logger(GcsErrorSimulationInterceptor.name);
+    }
+}
+GcsErrorSimulationInterceptor = _ts_decorate([
+    Injectable(),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof GcsErrorModeManager === "undefined" ? Object : GcsErrorModeManager
+    ])
+], GcsErrorSimulationInterceptor);
+
+//# sourceMappingURL=gcs-error-simulation.interceptor.js.map

package/dist/gcs/gcs-error-simulation.interceptor.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/gcs/gcs-error-simulation.interceptor.ts"],"sourcesContent":["import {\n  Injectable,\n  NestInterceptor,\n  ExecutionContext,\n  CallHandler,\n  Logger,\n  HttpException,\n} from '@nestjs/common';\nimport { Observable } from 'rxjs';\nimport { GcsErrorModeManager, isGcsDataOperation } from './gcs-error-mode.js';\n\n/**\n * NestJS interceptor that checks the active GCS error mode and short-circuits\n * matching requests with GCS-shaped error responses.\n *\n * Registered as APP_INTERCEPTOR (global) but exits immediately for non-GCS routes.\n * The route-prefix check is a cheap string comparison before any mode lookup.\n *\n * When an error mode matches, the interceptor throws an HttpException with the\n * GCS error status code (403, 404, 500) so that the frontend receives a proper\n * HTTP error response — not a 200 with an error body.\n */\n@Injectable()\nexport class GcsErrorSimulationInterceptor implements NestInterceptor {\n  private readonly logger = new Logger(GcsErrorSimulationInterceptor.name);\n\n  constructor(private readonly errorModeManager: GcsErrorModeManager) {}\n\n  intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {\n    const request = context\n      .switchToHttp()\n      .getRequest<{ method: string; url: string }>();\n    const method: string = request.method;\n    const path: string = request.url;\n\n    // Fast exit: only intercept GCS data operation routes\n    if (!isGcsDataOperation(method, path)) {\n      return next.handle();\n    }\n\n    const result = this.errorModeManager.matchRequest(method, path);\n\n    if (result) {\n      this.logger.warn(\n        `Error mode intercepted ${method} ${path} → ${result.status} (${result.body.error.errors[0].reason})`\n      );\n      // Throw with the real HTTP status code so the client gets a proper error response\n      throw new HttpException(result.body, result.status);\n    }\n\n    // Debug-level log when a mode is active but this request passed through\n    const activeMode = this.errorModeManager.getMode();\n    if (activeMode) {\n      this.logger.debug(\n        `Error mode '${activeMode.type}' active but ${method} ${path} passed through`\n      );\n    }\n\n    return next.handle();\n  }\n}\n"],"names":["Injectable","Logger","HttpException","GcsErrorModeManager","isGcsDataOperation","GcsErrorSimulationInterceptor","intercept","context","next","request","switchToHttp","getRequest","method","path","url","handle","result","errorModeManager","matchRequest","logger","warn","status","body","error","errors","reason","activeMode","getMode","debug","type","constructor","name"],"rangeMappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;","mappings":";;AAAA,SACEA,UAAU,EAIVC,MAAM,EACNC,aAAa,QACR,iBAAiB;AAExB,SAASC,mBAAmB,EAAEC,kBAAkB,QAAQ,sBAAsB;AAc9E,OAAO,MAAMC;IAKXC,UAAUC,OAAyB,EAAEC,IAAiB,EAAuB;QAC3E,MAAMC,UAAUF,QACbG,YAAY,GACZC,UAAU;QACb,MAAMC,SAAiBH,QAAQG,MAAM;QACrC,MAAMC,OAAeJ,QAAQK,GAAG;QAEhC,sDAAsD;QACtD,IAAI,CAACV,mBAAmBQ,QAAQC,OAAO;YACrC,OAAOL,KAAKO,MAAM;QACpB;QAEA,MAAMC,SAAS,IAAI,CAACC,gBAAgB,CAACC,YAAY,CAACN,QAAQC;QAE1D,IAAIG,QAAQ;YACV,IAAI,CAACG,MAAM,CAACC,IAAI,CACd,CAAC,uBAAuB,EAAER,OAAO,CAAC,EAAEC,KAAK,GAAG,EAAEG,OAAOK,MAAM,CAAC,EAAE,EAAEL,OAAOM,IAAI,CAACC,KAAK,CAACC,MAAM,CAAC,EAAE,CAACC,MAAM,CAAC,CAAC,CAAC;YAEvG,kFAAkF;YAClF,MAAM,IAAIvB,cAAcc,OAAOM,IAAI,EAAEN,OAAOK,MAAM;QACpD;QAEA,wEAAwE;QACxE,MAAMK,aAAa,IAAI,CAACT,gBAAgB,CAACU,OAAO;QAChD,IAAID,YAAY;YACd,IAAI,CAACP,MAAM,CAACS,KAAK,CACf,CAAC,YAAY,EAAEF,WAAWG,IAAI,CAAC,aAAa,EAAEjB,OAAO,CAAC,EAAEC,KAAK,eAAe,CAAC;QAEjF;QAEA,OAAOL,KAAKO,MAAM;IACpB;IAjCAe,YAAY,AAAiBb,gBAAqC,CAAE;aAAvCA,mBAAAA;aAFZE,SAAS,IAAIlB,OAAOI,8BAA8B0B,IAAI;IAEF;AAkCvE;AArCa1B;IADZL;;;eAIgD,+CAAA;;GAHpCK"}

package/dist/gcs/gcs-twin.d.ts

@@ -11,6 +11,7 @@ export declare class GcsTwin {
     private readonly docker;
     private container;
     private readonly containerName;
+    private dockerUnavailable;
     /**
      * Create a new GCS twin.
      *