npm - @gcoredev/fastedge-test - Versions diffs - 0.1.6 → 0.1.7 - Mend

@gcoredev/fastedge-test 0.1.6 → 0.1.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (22) hide show

package/dist/frontend/assets/{index-BpdzhbRl.js → index-BCXfEMSq.js} +18 -18
package/dist/frontend/index.html +1 -1
package/dist/lib/index.cjs +34 -4
package/dist/lib/index.js +34 -4
package/dist/lib/runner/HttpWasmRunner.d.ts +9 -1
package/dist/lib/runner/IWasmRunner.d.ts +25 -1
package/dist/lib/runner/PortManager.d.ts +4 -1
package/dist/lib/schemas/api.d.ts +2 -0
package/dist/lib/schemas/config.d.ts +2 -0
package/dist/lib/test-framework/index.cjs +41 -4
package/dist/lib/test-framework/index.js +41 -4
package/dist/lib/test-framework/suite-runner.d.ts +16 -0
package/dist/server.js +13 -13
package/docs/API.md +29 -5
package/docs/DEBUGGER.md +1 -1
package/docs/RUNNER.md +69 -32
package/docs/TEST_CONFIG.md +73 -21
package/docs/TEST_FRAMEWORK.md +42 -18
package/package.json +1 -1
package/schemas/api-config.schema.json +5 -0
package/schemas/api-load.schema.json +5 -0
package/schemas/fastedge-config.test.schema.json +5 -0

package/dist/frontend/index.html CHANGED Viewed

@@ -4,7 +4,7 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Proxy Runner</title>
-    <script type="module" crossorigin src="/assets/index-BpdzhbRl.js"></script>
+    <script type="module" crossorigin src="/assets/index-BCXfEMSq.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-DdlINQc_.css">
   </head>
   <body>

package/dist/lib/index.cjs CHANGED Viewed

@@ -2861,6 +2861,8 @@ var HttpWasmRunner = class {
     this.stateManager = null;
     this.dotenvEnabled = true;
     this.dotenvPath = null;
+    /** Pinned ports bypass PortManager allocation and must not be released back to it. */
+    this.isPinnedPort = false;
     /** @deprecated Legacy sync support — remove when #[fastedge::http] is retired */
     this.isLegacySync = false;
     this.portManager = portManager;
@@ -2887,7 +2889,19 @@ var HttpWasmRunner = class {
       this.tempWasmPath = wasmPath;
     }
     this.isLegacySync = await isLegacySyncWasm(bufferOrPath);
-    this.port = await this.portManager.allocate();
+    if (config?.httpPort !== void 0) {
+      const pinned = config.httpPort;
+      if (!await this.portManager.isPortFree(pinned)) {
+        throw new Error(
+          `fastedge-run port ${pinned} is not available \u2014 release it or choose a different httpPort in fastedge-config.test.json`
+        );
+      }
+      this.port = pinned;
+      this.isPinnedPort = true;
+    } else {
+      this.port = await this.portManager.allocate();
+      this.isPinnedPort = false;
+    }
     const wasi_http = !this.isLegacySync;
     const args = [
       "http",
@@ -2919,7 +2933,13 @@ var HttpWasmRunner = class {
     await this.waitForServerReady(this.port, timeout);
   }
   /**
-   * Execute an HTTP request through the WASM module
+   * Execute an HTTP request through the WASM module.
+   *
+   * Redirects are surfaced verbatim — `fetch` is called with
+   * `redirect: "manual"` so 3xx responses (status + `Location`) reach the
+   * caller intact. This matches FastEdge edge behaviour, which returns
+   * redirects to the client rather than following them server-side. See
+   * `IWasmRunner.execute` for the public contract.
    */
   async execute(request) {
     if (!this.port || !this.process) {
@@ -2932,8 +2952,12 @@ var HttpWasmRunner = class {
         method: request.method,
         headers: request.headers,
         body: request.body || void 0,
-        signal: AbortSignal.timeout(3e4)
+        signal: AbortSignal.timeout(3e4),
         // 30 second timeout
+        // Surface 3xx responses verbatim so tests can assert on status/Location.
+        // A FastEdge edge returns redirects to the client rather than following
+        // them server-side; production parity requires the same here.
+        redirect: "manual"
       });
       const arrayBuffer = await response.arrayBuffer();
       const bodyBuffer = Buffer.from(arrayBuffer);
@@ -3024,8 +3048,11 @@ var HttpWasmRunner = class {
       this.process = null;
     }
     if (this.port !== null) {
-      this.portManager.release(this.port);
+      if (!this.isPinnedPort) {
+        this.portManager.release(this.port);
+      }
       this.port = null;
+      this.isPinnedPort = false;
     }
     if (this.tempWasmPath) {
       await removeTempWasmFile(this.tempWasmPath);
@@ -3242,6 +3269,9 @@ var PortManager = class {
    * This is necessary when multiple server processes run simultaneously —
    * each has its own PortManager with independent in-memory state, so
    * in-memory tracking alone is not enough to prevent cross-process conflicts.
+   *
+   * Public so pinned-port callers (HttpWasmRunner with RunnerConfig.httpPort)
+   * can reuse the same OS-level check without going through allocate().
    */
   isPortFree(port) {
     return new Promise((resolve) => {

package/dist/lib/index.js CHANGED Viewed

@@ -2817,6 +2817,8 @@ var HttpWasmRunner = class {
     this.stateManager = null;
     this.dotenvEnabled = true;
     this.dotenvPath = null;
+    /** Pinned ports bypass PortManager allocation and must not be released back to it. */
+    this.isPinnedPort = false;
     /** @deprecated Legacy sync support — remove when #[fastedge::http] is retired */
     this.isLegacySync = false;
     this.portManager = portManager;
@@ -2843,7 +2845,19 @@ var HttpWasmRunner = class {
       this.tempWasmPath = wasmPath;
     }
     this.isLegacySync = await isLegacySyncWasm(bufferOrPath);
-    this.port = await this.portManager.allocate();
+    if (config?.httpPort !== void 0) {
+      const pinned = config.httpPort;
+      if (!await this.portManager.isPortFree(pinned)) {
+        throw new Error(
+          `fastedge-run port ${pinned} is not available \u2014 release it or choose a different httpPort in fastedge-config.test.json`
+        );
+      }
+      this.port = pinned;
+      this.isPinnedPort = true;
+    } else {
+      this.port = await this.portManager.allocate();
+      this.isPinnedPort = false;
+    }
     const wasi_http = !this.isLegacySync;
     const args = [
       "http",
@@ -2875,7 +2889,13 @@ var HttpWasmRunner = class {
     await this.waitForServerReady(this.port, timeout);
   }
   /**
-   * Execute an HTTP request through the WASM module
+   * Execute an HTTP request through the WASM module.
+   *
+   * Redirects are surfaced verbatim — `fetch` is called with
+   * `redirect: "manual"` so 3xx responses (status + `Location`) reach the
+   * caller intact. This matches FastEdge edge behaviour, which returns
+   * redirects to the client rather than following them server-side. See
+   * `IWasmRunner.execute` for the public contract.
    */
   async execute(request) {
     if (!this.port || !this.process) {
@@ -2888,8 +2908,12 @@ var HttpWasmRunner = class {
         method: request.method,
         headers: request.headers,
         body: request.body || void 0,
-        signal: AbortSignal.timeout(3e4)
+        signal: AbortSignal.timeout(3e4),
         // 30 second timeout
+        // Surface 3xx responses verbatim so tests can assert on status/Location.
+        // A FastEdge edge returns redirects to the client rather than following
+        // them server-side; production parity requires the same here.
+        redirect: "manual"
       });
       const arrayBuffer = await response.arrayBuffer();
       const bodyBuffer = Buffer.from(arrayBuffer);
@@ -2980,8 +3004,11 @@ var HttpWasmRunner = class {
       this.process = null;
     }
     if (this.port !== null) {
-      this.portManager.release(this.port);
+      if (!this.isPinnedPort) {
+        this.portManager.release(this.port);
+      }
       this.port = null;
+      this.isPinnedPort = false;
     }
     if (this.tempWasmPath) {
       await removeTempWasmFile(this.tempWasmPath);
@@ -3198,6 +3225,9 @@ var PortManager = class {
    * This is necessary when multiple server processes run simultaneously —
    * each has its own PortManager with independent in-memory state, so
    * in-memory tracking alone is not enough to prevent cross-process conflicts.
+   *
+   * Public so pinned-port callers (HttpWasmRunner with RunnerConfig.httpPort)
+   * can reuse the same OS-level check without going through allocate().
    */
   isPortFree(port) {
     return new Promise((resolve) => {

package/dist/lib/runner/HttpWasmRunner.d.ts CHANGED Viewed

@@ -24,6 +24,8 @@ export declare class HttpWasmRunner implements IWasmRunner {
     private portManager;
     private dotenvEnabled;
     private dotenvPath;
+    /** Pinned ports bypass PortManager allocation and must not be released back to it. */
+    private isPinnedPort;
     /** @deprecated Legacy sync support — remove when #[fastedge::http] is retired */
     private isLegacySync;
     constructor(portManager: PortManager, dotenvEnabled?: boolean);
@@ -32,7 +34,13 @@ export declare class HttpWasmRunner implements IWasmRunner {
      */
     load(bufferOrPath: Buffer | string, config?: RunnerConfig): Promise<void>;
     /**
-     * Execute an HTTP request through the WASM module
+     * Execute an HTTP request through the WASM module.
+     *
+     * Redirects are surfaced verbatim — `fetch` is called with
+     * `redirect: "manual"` so 3xx responses (status + `Location`) reach the
+     * caller intact. This matches FastEdge edge behaviour, which returns
+     * redirects to the client rather than following them server-side. See
+     * `IWasmRunner.execute` for the public contract.
      */
     execute(request: HttpRequest): Promise<HttpResponse>;
     /**

package/dist/lib/runner/IWasmRunner.d.ts CHANGED Viewed

@@ -18,6 +18,15 @@ export interface RunnerConfig {
     enforceProductionPropertyRules?: boolean;
     /** Override automatic WASM type detection. Use when detection produces wrong results. */
     runnerType?: WasmType;
+    /**
+     * HTTP-WASM only. Pin the spawned `fastedge-run` HTTP server to a specific
+     * port instead of allocating from the dynamic pool (8100-8199). Intended for
+     * Codespaces/Docker port-forwarding setups, stable live-preview URLs, or any
+     * external tooling that requires a fixed target. `load()` throws if the port
+     * is already in use — there is no fallback to dynamic allocation. Ignored
+     * for proxy-wasm runners.
+     */
+    httpPort?: number;
 }
 /**
  * HTTP Request type for HTTP WASM runner
@@ -54,7 +63,22 @@ export interface IWasmRunner {
      */
     load(bufferOrPath: Buffer | string, config?: RunnerConfig): Promise<void>;
     /**
-     * Execute a request through the WASM module (HTTP WASM only)
+     * Execute a request through the WASM module (HTTP WASM only).
+     *
+     * Redirects are surfaced verbatim — the underlying fetch uses
+     * `redirect: "manual"` so tests can assert on 3xx status and the `Location`
+     * header. This matches how a FastEdge edge deployment returns redirects to
+     * the client rather than following them server-side.
+     *
+     * `execute` only hits the WASM app under test — `request.path` is a path on
+     * the spawned `fastedge-run` server, not a full URL. To follow a redirect
+     * the caller must inspect `response.headers.location`:
+     * - Relative Location (`/foo`) — reuse as `request.path` directly.
+     * - Absolute same-host Location — extract `pathname + search` via `new URL()`
+     *   and re-issue with that path.
+     * - Absolute cross-host Location — cannot be followed through the runner;
+     *   the 302 is the terminal state for the test.
+     *
      * @param request The HTTP request to execute
      * @returns The HTTP response
      */

package/dist/lib/runner/PortManager.d.ts CHANGED Viewed

@@ -18,8 +18,11 @@ export declare class PortManager {
      * This is necessary when multiple server processes run simultaneously —
      * each has its own PortManager with independent in-memory state, so
      * in-memory tracking alone is not enough to prevent cross-process conflicts.
+     *
+     * Public so pinned-port callers (HttpWasmRunner with RunnerConfig.httpPort)
+     * can reuse the same OS-level check without going through allocate().
      */
-    private isPortFree;
+    isPortFree(port: number): Promise<boolean>;
     /**
      * Allocate an available port from the pool.
      * Combines in-memory tracking (avoids TCP TIME_WAIT reuse within this process)

package/dist/lib/schemas/api.d.ts CHANGED Viewed

@@ -6,6 +6,7 @@ export declare const ApiLoadBodySchema: z.ZodObject<{
         enabled: z.ZodOptional<z.ZodBoolean>;
         path: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
+    httpPort: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export declare const ApiSendBodySchema: z.ZodObject<{
     url: z.ZodUnion<readonly [z.ZodLiteral<"built-in">, z.ZodString]>;
@@ -52,6 +53,7 @@ export declare const ApiConfigBodySchema: z.ZodObject<{
             path: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
         appType: z.ZodLiteral<"http-wasm">;
+        httpPort: z.ZodOptional<z.ZodNumber>;
         request: z.ZodObject<{
             method: z.ZodDefault<z.ZodString>;
             path: z.ZodString;

package/dist/lib/schemas/config.d.ts CHANGED Viewed

@@ -56,6 +56,7 @@ declare const HttpConfigSchema: z.ZodObject<{
         path: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     appType: z.ZodLiteral<"http-wasm">;
+    httpPort: z.ZodOptional<z.ZodNumber>;
     request: z.ZodObject<{
         method: z.ZodDefault<z.ZodString>;
         path: z.ZodString;
@@ -76,6 +77,7 @@ export declare const TestConfigSchema: z.ZodUnion<readonly [z.ZodObject<{
         path: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     appType: z.ZodLiteral<"http-wasm">;
+    httpPort: z.ZodOptional<z.ZodNumber>;
     request: z.ZodObject<{
         method: z.ZodDefault<z.ZodString>;
         path: z.ZodString;

package/dist/lib/test-framework/index.cjs CHANGED Viewed

@@ -2888,6 +2888,8 @@ var HttpWasmRunner = class {
     this.stateManager = null;
     this.dotenvEnabled = true;
     this.dotenvPath = null;
+    /** Pinned ports bypass PortManager allocation and must not be released back to it. */
+    this.isPinnedPort = false;
     /** @deprecated Legacy sync support — remove when #[fastedge::http] is retired */
     this.isLegacySync = false;
     this.portManager = portManager;
@@ -2914,7 +2916,19 @@ var HttpWasmRunner = class {
       this.tempWasmPath = wasmPath;
     }
     this.isLegacySync = await isLegacySyncWasm(bufferOrPath);
-    this.port = await this.portManager.allocate();
+    if (config?.httpPort !== void 0) {
+      const pinned = config.httpPort;
+      if (!await this.portManager.isPortFree(pinned)) {
+        throw new Error(
+          `fastedge-run port ${pinned} is not available \u2014 release it or choose a different httpPort in fastedge-config.test.json`
+        );
+      }
+      this.port = pinned;
+      this.isPinnedPort = true;
+    } else {
+      this.port = await this.portManager.allocate();
+      this.isPinnedPort = false;
+    }
     const wasi_http = !this.isLegacySync;
     const args = [
       "http",
@@ -2946,7 +2960,13 @@ var HttpWasmRunner = class {
     await this.waitForServerReady(this.port, timeout);
   }
   /**
-   * Execute an HTTP request through the WASM module
+   * Execute an HTTP request through the WASM module.
+   *
+   * Redirects are surfaced verbatim — `fetch` is called with
+   * `redirect: "manual"` so 3xx responses (status + `Location`) reach the
+   * caller intact. This matches FastEdge edge behaviour, which returns
+   * redirects to the client rather than following them server-side. See
+   * `IWasmRunner.execute` for the public contract.
    */
   async execute(request) {
     if (!this.port || !this.process) {
@@ -2959,8 +2979,12 @@ var HttpWasmRunner = class {
         method: request.method,
         headers: request.headers,
         body: request.body || void 0,
-        signal: AbortSignal.timeout(3e4)
+        signal: AbortSignal.timeout(3e4),
         // 30 second timeout
+        // Surface 3xx responses verbatim so tests can assert on status/Location.
+        // A FastEdge edge returns redirects to the client rather than following
+        // them server-side; production parity requires the same here.
+        redirect: "manual"
       });
       const arrayBuffer = await response.arrayBuffer();
       const bodyBuffer = Buffer.from(arrayBuffer);
@@ -3051,8 +3075,11 @@ var HttpWasmRunner = class {
       this.process = null;
     }
     if (this.port !== null) {
-      this.portManager.release(this.port);
+      if (!this.isPinnedPort) {
+        this.portManager.release(this.port);
+      }
       this.port = null;
+      this.isPinnedPort = false;
     }
     if (this.tempWasmPath) {
       await removeTempWasmFile(this.tempWasmPath);
@@ -3269,6 +3296,9 @@ var PortManager = class {
    * This is necessary when multiple server processes run simultaneously —
    * each has its own PortManager with independent in-memory state, so
    * in-memory tracking alone is not enough to prevent cross-process conflicts.
+   *
+   * Public so pinned-port callers (HttpWasmRunner with RunnerConfig.httpPort)
+   * can reuse the same OS-level check without going through allocate().
    */
   isPortFree(port) {
     return new Promise((resolve) => {
@@ -3412,6 +3442,13 @@ var CdnConfigSchema = BaseConfigSchema.extend({
 });
 var HttpConfigSchema = BaseConfigSchema.extend({
   appType: import_zod.z.literal("http-wasm"),
+  /**
+   * Pin the fastedge-run subprocess to a specific port instead of allocating
+   * from the dynamic pool (8100-8199). Use for Codespaces/Docker port-forwarding,
+   * stable live-preview URLs, or tooling that needs a fixed target. Load fails
+   * fast if the port is already in use.
+   */
+  httpPort: import_zod.z.number().int().min(1024).max(65535).optional(),
   request: HttpRequestConfigSchema
 });
 var TestConfigSchema = import_zod.z.union([HttpConfigSchema, CdnConfigSchema]);

package/dist/lib/test-framework/index.js CHANGED Viewed

@@ -2824,6 +2824,8 @@ var HttpWasmRunner = class {
     this.stateManager = null;
     this.dotenvEnabled = true;
     this.dotenvPath = null;
+    /** Pinned ports bypass PortManager allocation and must not be released back to it. */
+    this.isPinnedPort = false;
     /** @deprecated Legacy sync support — remove when #[fastedge::http] is retired */
     this.isLegacySync = false;
     this.portManager = portManager;
@@ -2850,7 +2852,19 @@ var HttpWasmRunner = class {
       this.tempWasmPath = wasmPath;
     }
     this.isLegacySync = await isLegacySyncWasm(bufferOrPath);
-    this.port = await this.portManager.allocate();
+    if (config?.httpPort !== void 0) {
+      const pinned = config.httpPort;
+      if (!await this.portManager.isPortFree(pinned)) {
+        throw new Error(
+          `fastedge-run port ${pinned} is not available \u2014 release it or choose a different httpPort in fastedge-config.test.json`
+        );
+      }
+      this.port = pinned;
+      this.isPinnedPort = true;
+    } else {
+      this.port = await this.portManager.allocate();
+      this.isPinnedPort = false;
+    }
     const wasi_http = !this.isLegacySync;
     const args = [
       "http",
@@ -2882,7 +2896,13 @@ var HttpWasmRunner = class {
     await this.waitForServerReady(this.port, timeout);
   }
   /**
-   * Execute an HTTP request through the WASM module
+   * Execute an HTTP request through the WASM module.
+   *
+   * Redirects are surfaced verbatim — `fetch` is called with
+   * `redirect: "manual"` so 3xx responses (status + `Location`) reach the
+   * caller intact. This matches FastEdge edge behaviour, which returns
+   * redirects to the client rather than following them server-side. See
+   * `IWasmRunner.execute` for the public contract.
    */
   async execute(request) {
     if (!this.port || !this.process) {
@@ -2895,8 +2915,12 @@ var HttpWasmRunner = class {
         method: request.method,
         headers: request.headers,
         body: request.body || void 0,
-        signal: AbortSignal.timeout(3e4)
+        signal: AbortSignal.timeout(3e4),
         // 30 second timeout
+        // Surface 3xx responses verbatim so tests can assert on status/Location.
+        // A FastEdge edge returns redirects to the client rather than following
+        // them server-side; production parity requires the same here.
+        redirect: "manual"
       });
       const arrayBuffer = await response.arrayBuffer();
       const bodyBuffer = Buffer.from(arrayBuffer);
@@ -2987,8 +3011,11 @@ var HttpWasmRunner = class {
       this.process = null;
     }
     if (this.port !== null) {
-      this.portManager.release(this.port);
+      if (!this.isPinnedPort) {
+        this.portManager.release(this.port);
+      }
       this.port = null;
+      this.isPinnedPort = false;
     }
     if (this.tempWasmPath) {
       await removeTempWasmFile(this.tempWasmPath);
@@ -3205,6 +3232,9 @@ var PortManager = class {
    * This is necessary when multiple server processes run simultaneously —
    * each has its own PortManager with independent in-memory state, so
    * in-memory tracking alone is not enough to prevent cross-process conflicts.
+   *
+   * Public so pinned-port callers (HttpWasmRunner with RunnerConfig.httpPort)
+   * can reuse the same OS-level check without going through allocate().
    */
   isPortFree(port) {
     return new Promise((resolve) => {
@@ -3348,6 +3378,13 @@ var CdnConfigSchema = BaseConfigSchema.extend({
 });
 var HttpConfigSchema = BaseConfigSchema.extend({
   appType: z.literal("http-wasm"),
+  /**
+   * Pin the fastedge-run subprocess to a specific port instead of allocating
+   * from the dynamic pool (8100-8199). Use for Codespaces/Docker port-forwarding,
+   * stable live-preview URLs, or tooling that needs a fixed target. Load fails
+   * fast if the port is already in use.
+   */
+  httpPort: z.number().int().min(1024).max(65535).optional(),
   request: HttpRequestConfigSchema
 });
 var TestConfigSchema = z.union([HttpConfigSchema, CdnConfigSchema]);

package/dist/lib/test-framework/suite-runner.d.ts CHANGED Viewed

@@ -36,6 +36,22 @@ export declare function runFlow(runner: IWasmRunner, options: FlowOptions): Prom
  * - method defaults to "GET"
  * - headers defaults to {}
  * - body defaults to ""
+ *
+ * Redirects are surfaced verbatim — a 302 from the WASM is returned to the
+ * caller with its `Location` header preserved, matching FastEdge edge
+ * behaviour.
+ *
+ * `runHttpRequest` targets the WASM app under test only (`options.path` is a
+ * path on the local `fastedge-run` server, not a full URL). Following a
+ * redirect therefore depends on the shape of `response.headers.location`:
+ *
+ * - Relative (e.g. `/auth/complete`) — pass it directly as `path` in a second
+ *   `runHttpRequest` call.
+ * - Absolute with the app's own host — parse with `new URL(...)`, then
+ *   re-issue against `url.pathname + url.search`.
+ * - Absolute with an external host — cannot be followed through the runner;
+ *   that redirect is the end of the test, assert on status + Location and
+ *   stop there.
  */
 export declare function runHttpRequest(runner: IWasmRunner, options: HttpRequestOptions): Promise<HttpResponse>;
 /**