feat: add configurable base url to embedded world

packages/core/src/runtime/world.ts

@@ -41,6 +41,7 @@ export const createWorld = (): World => {
     return createEmbeddedWorld({
       dataDir: process.env.WORKFLOW_EMBEDDED_DATA_DIR,
       port: process.env.PORT ? Number(process.env.PORT) : undefined,
+      baseUrl: process.env.WORKFLOW_BASE_URL,
     });
   }
 

packages/world-local/src/config.ts

@@ -6,6 +6,33 @@ const getDataDirFromEnv = () => {
 
 export const DEFAULT_RESOLVE_DATA_OPTION = 'all';
 
+export const normalizeBaseUrl = (
+  value: string,
+  sourceLabel = 'baseUrl' // NOTE: Should I keep this? This helps us throw errors like Invalid baseUrl: … or WORKFLOW_BASE_URL cannot be empty
+) => {
+  const candidate = value.trim();
+  if (candidate.length === 0) {
+    throw new Error(`${sourceLabel} cannot be empty`);
+  }
+
+  try {
+    const url = new URL(candidate);
+    // Preserve any path segments (for reverse proxies) but trim trailing slashes to avoid duplicates.
+    return url.href.replace(/\/+$/, '');
+  } catch {
+    throw new Error(`Invalid ${sourceLabel}: ${value}`);
+  }
+};
+
+const getBaseUrlFromEnv = () => {
+  const baseUrl = process.env.WORKFLOW_BASE_URL;
+  if (!baseUrl) {
+    return null;
+  }
+
+  return normalizeBaseUrl(baseUrl, 'WORKFLOW_BASE_URL');
+};
+
 const getPortFromEnv = () => {
   const port = process.env.PORT;
   if (port) {
@@ -18,6 +45,7 @@ const getPortFromEnv = () => {
 export const config = once(() => {
   const dataDir = getDataDirFromEnv();
   const port = getPortFromEnv();
+  const baseUrl = getBaseUrlFromEnv();
 
-  return { dataDir, port };
+  return { dataDir, port, baseUrl };
 });

packages/world-local/src/index.ts

@@ -1,5 +1,5 @@
 import type { World } from '@workflow/world';
-import { config } from './config.js';
+import { config, normalizeBaseUrl } from './config.js';
 import { createQueue } from './queue.js';
 import { createStorage } from './storage.js';
 import { createStreamer } from './streamer.js';
@@ -9,18 +9,33 @@ import { createStreamer } from './streamer.js';
  *
  * @param dataDir - The directory to use for storage. If not provided, the default data dir will be used.
  * @param port - The port to use for the queue. If not provided, the default port will be used.
+ * @param baseUrl - The base URL to use for the queue. Takes priority over port if provided.
  */
 export function createEmbeddedWorld({
   dataDir,
   port,
+  baseUrl,
 }: {
   dataDir?: string;
   port?: number;
+  baseUrl?: string;
 }): World {
   const dir = dataDir ?? config.value.dataDir;
-  const queuePort = port ?? config.value.port;
+
+  const overrideBaseUrl =
+    typeof baseUrl === 'string' ? normalizeBaseUrl(baseUrl, 'baseUrl') : null;
+
+  // TODO: confirm with Gal on priority. Current Priority - baseUrl parameter > config baseUrl > port parameter > config port > default 3000
+  const queueBaseUrl =
+    overrideBaseUrl ?? config.value.baseUrl ?? port ?? config.value.port;
+
+  const finalUrl =
+    typeof queueBaseUrl === 'string'
+      ? queueBaseUrl
+      : `http://localhost:${queueBaseUrl}`;
+
   return {
-    ...createQueue(queuePort),
+    ...createQueue(finalUrl),
     ...createStorage(dir),
     ...createStreamer(dir),
   };

packages/world-local/src/queue.ts

@@ -16,10 +16,15 @@ const httpAgent = new Agent({
   headersTimeout: 0,
 });
 
-export function createQueue(port?: number): Queue {
+export function createQueue(portOrBaseUrl?: number | string): Queue {
   const transport = new JsonTransport();
   const generateId = monotonicFactory();
 
+  const baseUrl =
+    typeof portOrBaseUrl === 'string'
+      ? portOrBaseUrl
+      : `http://localhost:${portOrBaseUrl ?? 3000}`; // NOTE: nullish coalescing keeps port 0 working for ephemeral bindings.
+
   /**
    * holds inflight messages by idempotency key to ensure
    * that we don't queue the same message multiple times
@@ -61,7 +66,7 @@ export function createQueue(port?: number): Queue {
         defaultRetriesLeft--;
 
         const response = await fetch(
-          `http://localhost:${port}/.well-known/workflow/v1/${pathname}`,
+          `${baseUrl}/.well-known/workflow/v1/${pathname}`,
           {
             method: 'POST',
             duplex: 'half',