@concavejs/runtime-cf-base 0.0.1-alpha.8 → 0.0.1-alpha.9

package/dist/http/http-api.d.ts

@@ -1,7 +1,38 @@
+import type { SerializedKeyRange } from "@concavejs/core/queryengine";
 /** Minimal Env shape needed by the HTTP API handler */
 interface Env {
     CONCAVE_DO: DurableObjectNamespace;
     SYNC_DO: DurableObjectNamespace;
+    SYNC_NOTIFY_QUEUE?: QueueLike;
 }
-export declare function handleHttpApiRequest(request: Request, env: Env, ctx: ExecutionContext, instance?: string): Promise<Response>;
+type QueueLike = {
+    send(message: unknown): Promise<void>;
+};
+export interface HttpApiRoutingTargets {
+    /** Physical ConcaveDO name for execution traffic. Defaults to the logical `instance`. */
+    concaveDoName?: string;
+    /** Alias for non-DO runtimes to describe the write execution target identifier. */
+    concaveTargetName?: string;
+    /**
+     * Physical SyncDO names to notify after writes.
+     * Defaults to `[instance]`.
+     */
+    syncDoNames?: string[];
+    /** Alias for non-DO runtimes to describe sync invalidation targets. */
+    syncTargetNames?: string[];
+    /**
+     * Optional custom write dispatcher.
+     * When set, it is responsible for fanning out invalidations (queue, stream, etc.).
+     */
+    dispatchSyncWrites?: (payload: SyncWriteDispatchPayload) => Promise<void>;
+}
+export interface SyncWriteDispatchPayload {
+    logicalInstance: string;
+    projectId?: string;
+    syncTargets: string[];
+    writtenRanges?: SerializedKeyRange[];
+    writtenTables?: string[];
+    commitTimestamp?: string;
+}
+export declare function handleHttpApiRequest(request: Request, env: Env, ctx: ExecutionContext, instance?: string, routingTargets?: HttpApiRoutingTargets): Promise<Response>;
 export {};

package/dist/http/http-api.js

@@ -60,7 +60,7 @@ function base64ToArrayBuffer(base64) {
  * Create a storage adapter that routes through the ConcaveDO's storage syscall handler.
  * This ensures storage operations are properly isolated within the DO.
  */
-function createStorageAdapter(concaveDO, _instance) {
+function createStorageAdapter(concaveDO) {
     return {
         store: async (blob) => {
             const buffer = await blob.arrayBuffer();
@@ -106,26 +106,66 @@ function createStorageAdapter(concaveDO, _instance) {
         },
     };
 }
-function createNotifyWrites(env, instance, ctx) {
+function createNotifyWrites(env, syncDoNames, ctx, logicalInstance, projectId, dispatchSyncWrites) {
     return async (writtenRanges, writtenTables, commitTimestamp) => {
         if (!writtenRanges?.length && !writtenTables?.length) {
             return;
         }
-        const syncDoId = env.SYNC_DO.idFromName(instance);
-        const syncDo = env.SYNC_DO.get(syncDoId);
         const payload = {
+            logicalInstance,
+            projectId,
+            syncTargets: syncDoNames,
             writtenRanges,
             writtenTables: writtenTables ?? writtenTablesFromRanges(writtenRanges),
             commitTimestamp: commitTimestamp ? commitTimestamp.toString() : undefined,
         };
-        ctx.waitUntil(syncDo.fetch("http://do/notify", {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify(payload),
-        }));
+        if (dispatchSyncWrites) {
+            ctx.waitUntil(dispatchSyncWrites(payload).catch((error) => {
+                console.warn("[notifyWrites] Custom sync write dispatch failed", error);
+            }));
+            return;
+        }
+        if (isQueueLike(env.SYNC_NOTIFY_QUEUE)) {
+            ctx.waitUntil(env.SYNC_NOTIFY_QUEUE.send(payload).catch((error) => {
+                console.warn("[notifyWrites] Queue-based sync write dispatch failed", error);
+            }));
+            return;
+        }
+        const doPayload = {
+            writtenRanges,
+            writtenTables: writtenTables ?? writtenTablesFromRanges(writtenRanges),
+            commitTimestamp: commitTimestamp ? commitTimestamp.toString() : undefined,
+        };
+        for (const syncDoName of syncDoNames) {
+            const syncDoId = env.SYNC_DO.idFromName(syncDoName);
+            const syncDo = env.SYNC_DO.get(syncDoId);
+            const headers = {
+                "Content-Type": "application/json",
+                "X-Concave-Instance": logicalInstance,
+            };
+            if (projectId) {
+                headers["X-Concave-Project-Id"] = projectId;
+            }
+            ctx.waitUntil(syncDo
+                .fetch("http://do/notify", {
+                method: "POST",
+                headers,
+                body: JSON.stringify(doPayload),
+            })
+                .catch((error) => {
+                console.warn("[notifyWrites] Direct SyncDO notify failed", error);
+            }));
+        }
     };
 }
-export async function handleHttpApiRequest(request, env, ctx, instance = "singleton") {
+function isQueueLike(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const candidate = value;
+    return typeof candidate.send === "function";
+}
+export async function handleHttpApiRequest(request, env, ctx, instance = "singleton", routingTargets) {
     const corsHeaders = computeCorsHeaders(request);
     const apply = (response) => applyCors(response, corsHeaders);
     const url = new URL(request.url);
@@ -133,14 +173,19 @@ export async function handleHttpApiRequest(request, env, ctx, instance = "single
     if (pathParts[0] !== "api") {
         return apply(new Response("Not found", { status: 404 }));
     }
-    console.log(`[handleHttpApiRequest] instance=${instance}`);
-    const concaveId = env.CONCAVE_DO.idFromName(instance);
-    const concave = env.CONCAVE_DO.get(concaveId);
+    const logicalInstance = instance;
+    const concaveDoName = normalizeDoName(routingTargets?.concaveDoName ?? routingTargets?.concaveTargetName, logicalInstance);
+    const syncDoNames = normalizeSyncDoNames(routingTargets?.syncDoNames ?? routingTargets?.syncTargetNames, logicalInstance);
+    const projectId = request.headers.get("X-Concave-Project-Id") ?? undefined;
+    console.log(`[handleHttpApiRequest] logicalInstance=${logicalInstance} concaveDo=${concaveDoName} syncTargets=${syncDoNames.join(",")}`);
+    const concaveId = env.CONCAVE_DO.idFromName(concaveDoName);
+    const concaveRaw = env.CONCAVE_DO.get(concaveId);
+    const concave = wrapConcaveStub(concaveRaw, logicalInstance, projectId);
     const executor = new ConcaveStubExecutor(concave);
     const adapter = createClientAdapter(executor);
-    const notifyWrites = createNotifyWrites(env, instance, ctx);
+    const notifyWrites = createNotifyWrites(env, syncDoNames, ctx, logicalInstance, projectId, routingTargets?.dispatchSyncWrites);
     // Route storage operations through the DO's storage syscall handler
-    const storageAdapter = createStorageAdapter(concave, instance);
+    const storageAdapter = createStorageAdapter(concave);
     const authHeader = request.headers.get("Authorization");
     const headerToken = authHeader?.replace(/^Bearer\s+/i, "").trim() || undefined;
     let headerIdentity;
@@ -294,3 +339,38 @@ export async function handleHttpApiRequest(request, env, ctx, instance = "single
     }
     return apply(new Response("Not found", { status: 404 }));
 }
+function wrapConcaveStub(stub, logicalInstance, projectId) {
+    return {
+        fetch: async (input, init) => {
+            const headers = new Headers(init?.headers);
+            headers.set("X-Concave-Instance", logicalInstance);
+            if (projectId) {
+                headers.set("X-Concave-Project-Id", projectId);
+            }
+            return stub.fetch(input, {
+                ...init,
+                headers,
+            });
+        },
+    };
+}
+function normalizeDoName(target, fallback) {
+    const trimmed = target?.trim();
+    return trimmed && trimmed.length > 0 ? trimmed : fallback;
+}
+function normalizeSyncDoNames(targets, fallback) {
+    if (targets === undefined) {
+        return [fallback];
+    }
+    if (targets.length === 0) {
+        return [];
+    }
+    const deduped = new Set();
+    for (const target of targets) {
+        const trimmed = target.trim();
+        if (trimmed.length > 0) {
+            deduped.add(trimmed);
+        }
+    }
+    return Array.from(deduped);
+}

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 export * from "@concavejs/core";
 export type { ConcaveEnv, ConcaveStorageEnv, ConcaveD1Env } from "./env";
 export { UdfExecutorRpc } from "./worker/udf-worker";
-export { createConcaveWorker, resolveNamespaceBinding, createScopedNamespace, type ConcaveWorkerOptions, type ConcaveWorkerBindings, type ConcaveWorker, } from "./worker/create-concave-worker";
+export { createConcaveWorker, resolveNamespaceBinding, createScopedNamespace, type ConcaveWorkerOptions, type ConcaveWorkerBindings, type ConcaveWorker, type ConcaveWorkerRouteContext, type ConcaveWorkerRouteTargets, } from "./worker/create-concave-worker";
 export { DEFAULT_INSTANCE_KEY, DEFAULT_INSTANCE_VALUE, DEFAULT_INSTANCE_COOKIE_PATH, resolveInstanceFromRequest, maybeAttachInstanceCookie, readCookieValue, buildInstanceCookie, type InstanceResolution, type InstanceResolutionOptions, type InstanceCookieOptions, } from "./routing/instance";
+export { createCfSyncTopologyRuntime, buildPooledInstanceName as buildSyncPooledInstanceName, parseNodeIds as parseSyncNodeIds, parseNodeIdsByRegion as parseSyncNodeIdsByRegion, normalizeTargetList as normalizeSyncTargetList, type CfSyncTopologyConfig, type BuildShardMapFromReportsOptions as SyncBuildShardMapFromReportsOptions, type ResolveSyncFanoutDoNamesAsyncOptions, type CreateCfSyncTopologyRuntimeOptions, type CfSyncTopologyRuntime, } from "./routing/sync-topology";
 export { UdfExecInline } from "./udf/executor/inline-executor";
 export { UdfExecIsolated } from "./udf/executor/isolated-executor";
 export { ConcaveDOBase, type ConcaveDOConfig, type ConcaveDOAdapterContext, type ConcaveDOExecutorContext, } from "./durable-objects/concave-do-base";

package/dist/index.js

@@ -5,6 +5,7 @@ export { UdfExecutorRpc } from "./worker/udf-worker";
 export { createConcaveWorker, resolveNamespaceBinding, createScopedNamespace, } from "./worker/create-concave-worker";
 // Export instance routing helpers
 export { DEFAULT_INSTANCE_KEY, DEFAULT_INSTANCE_VALUE, DEFAULT_INSTANCE_COOKIE_PATH, resolveInstanceFromRequest, maybeAttachInstanceCookie, readCookieValue, buildInstanceCookie, } from "./routing/instance";
+export { createCfSyncTopologyRuntime, buildPooledInstanceName as buildSyncPooledInstanceName, parseNodeIds as parseSyncNodeIds, parseNodeIdsByRegion as parseSyncNodeIdsByRegion, normalizeTargetList as normalizeSyncTargetList, } from "./routing/sync-topology";
 // Export UDF executors
 export { UdfExecInline } from "./udf/executor/inline-executor";
 export { UdfExecIsolated } from "./udf/executor/isolated-executor";

package/dist/routing/sync-topology.d.ts

@@ -0,0 +1,40 @@
+import type { ConcaveWorkerRouteContext, ConcaveWorkerRouteTargets } from "../worker/create-concave-worker";
+import { type BuildShardMapFromReportsOptions as SharedBuildShardMapFromReportsOptions, type SyncShardMap, type SyncTopologyConfig } from "@concavejs/runtime-base";
+export interface CfSyncTopologyConfig extends SyncTopologyConfig {
+    syncAffinityKey: string;
+    regionKey: string;
+    regionByColo: Record<string, string>;
+    useColoAsRegion: boolean;
+}
+export interface BuildShardMapFromReportsOptions extends Omit<SharedBuildShardMapFromReportsOptions, "config"> {
+    logicalInstance: string;
+    env: Record<string, unknown>;
+}
+export interface ResolveSyncFanoutDoNamesAsyncOptions {
+    request?: Request;
+    projectId?: string;
+}
+export interface CreateCfSyncTopologyRuntimeOptions {
+    logPrefix?: string;
+    projectHeaderName?: string;
+    coordinatorBindingName?: string;
+    shardMapKvBindingName?: string;
+    resolveProjectId?: (request: Request, env: Record<string, unknown>) => string | undefined;
+    buildCoordinatorDoName: (logicalInstance: string, projectId?: string) => string;
+    buildShardMapKvKey: (logicalInstance: string, projectId?: string) => string;
+    buildShardMapCacheKey?: (logicalInstance: string, projectId?: string) => string;
+}
+export interface CfSyncTopologyRuntime {
+    resolveRouteTargets(context: ConcaveWorkerRouteContext): Promise<ConcaveWorkerRouteTargets>;
+    resolveSyncFanoutDoNames(logicalInstance: string, env: Record<string, unknown>): string[];
+    resolveSyncFanoutDoNamesAsync(logicalInstance: string, env: Record<string, unknown>, options?: ResolveSyncFanoutDoNamesAsyncOptions): Promise<string[]>;
+    resolveStaticSyncShardMap(logicalInstance: string, env: Record<string, unknown>, nowMs?: number): SyncShardMap;
+    buildShardMapFromReports(options: BuildShardMapFromReportsOptions): SyncShardMap;
+    resolveTopologyConfig(env: Record<string, unknown>): CfSyncTopologyConfig;
+    resolveRequestRegion(request: Request, env: Record<string, unknown>): string;
+}
+export declare function createCfSyncTopologyRuntime(options: CreateCfSyncTopologyRuntimeOptions): CfSyncTopologyRuntime;
+export declare function buildPooledInstanceName(logicalInstance: string, poolKind: "sync" | "udf", nodeId: string): string;
+export declare function parseNodeIds(raw: unknown): string[];
+export declare function parseNodeIdsByRegion(raw: unknown): Record<string, string[]>;
+export declare function normalizeTargetList(targets: string[] | undefined): string[];

package/dist/routing/sync-topology.js

@@ -0,0 +1,669 @@
+import { buildPooledInstanceName as buildSharedPooledInstanceName, buildShardMapFromReports as buildSharedShardMapFromReports, isValidSyncShardMap, normalizeTargetList as normalizeSharedTargetList, parseNodeIds as parseSharedNodeIds, parseNodeIdsByRegion as parseSharedNodeIdsByRegion, resolveBootstrapSyncShardCandidates, resolveStaticSyncShardMap as resolveSharedStaticShardMap, } from "@concavejs/runtime-base";
+const DEFAULT_SYNC_NODE_IDS_ENV = "CONCAVE_SYNC_NODE_IDS";
+const DEFAULT_SYNC_NODE_IDS_BY_REGION_ENV = "CONCAVE_SYNC_NODE_IDS_BY_REGION";
+const DEFAULT_SYNC_AFFINITY_KEY_ENV = "CONCAVE_SYNC_AFFINITY_KEY";
+const DEFAULT_SYNC_REGION_KEY_ENV = "CONCAVE_SYNC_REGION_KEY";
+const DEFAULT_SYNC_DEFAULT_REGION_ENV = "CONCAVE_SYNC_DEFAULT_REGION";
+const DEFAULT_SYNC_REGION_MAP_ENV = "CONCAVE_SYNC_REGION_MAP";
+const DEFAULT_SYNC_USE_COLO_AS_REGION_ENV = "CONCAVE_SYNC_USE_COLO_AS_REGION";
+const DEFAULT_SYNC_SHARD_MAP_CACHE_MS_ENV = "CONCAVE_SYNC_SHARD_MAP_CACHE_MS";
+const DEFAULT_SYNC_NODE_STALE_MS_ENV = "CONCAVE_SYNC_NODE_STALE_MS";
+const DEFAULT_SYNC_MIN_SHARDS_ENV = "CONCAVE_SYNC_MIN_SHARDS_PER_REGION";
+const DEFAULT_SYNC_MAX_SHARDS_ENV = "CONCAVE_SYNC_MAX_SHARDS_PER_REGION";
+const DEFAULT_SYNC_TARGET_SESSIONS_ENV = "CONCAVE_SYNC_TARGET_SESSIONS_PER_SHARD";
+const DEFAULT_SYNC_TARGET_MESSAGE_RATE_ENV = "CONCAVE_SYNC_TARGET_MESSAGE_RATE_PER_SHARD";
+const DEFAULT_SYNC_TARGET_NOTIFY_RATE_ENV = "CONCAVE_SYNC_TARGET_NOTIFY_RATE_PER_SHARD";
+const DEFAULT_SYNC_TARGET_CPU_UTILIZATION_ENV = "CONCAVE_SYNC_TARGET_CPU_UTILIZATION";
+const DEFAULT_SYNC_TARGET_MEMORY_UTILIZATION_ENV = "CONCAVE_SYNC_TARGET_MEMORY_UTILIZATION";
+const DEFAULT_SYNC_AUTO_SHARDS_ENV = "CONCAVE_SYNC_AUTO_SHARDS_PER_REGION";
+const DEFAULT_SYNC_AUTO_SHARD_PREFIX_ENV = "CONCAVE_SYNC_AUTO_SHARD_PREFIX";
+const DEFAULT_SYNC_SCALE_TO_ZERO_ENV = "CONCAVE_SYNC_SCALE_TO_ZERO";
+const DEFAULT_SYNC_AUTOSCALE_PROFILE_ENV = "CONCAVE_SYNC_AUTOSCALE_PROFILE";
+const DEFAULT_SYNC_SCALE_UP_COOLDOWN_MS_ENV = "CONCAVE_SYNC_SCALE_UP_COOLDOWN_MS";
+const DEFAULT_SYNC_SCALE_DOWN_COOLDOWN_MS_ENV = "CONCAVE_SYNC_SCALE_DOWN_COOLDOWN_MS";
+const DEFAULT_SYNC_SCALE_UP_HYSTERESIS_RATIO_ENV = "CONCAVE_SYNC_SCALE_UP_HYSTERESIS_RATIO";
+const DEFAULT_SYNC_SCALE_DOWN_HYSTERESIS_RATIO_ENV = "CONCAVE_SYNC_SCALE_DOWN_HYSTERESIS_RATIO";
+const DEFAULT_SYNC_MAX_SCALE_UP_STEP_ENV = "CONCAVE_SYNC_MAX_SCALE_UP_STEP";
+const DEFAULT_SYNC_MAX_SCALE_DOWN_STEP_ENV = "CONCAVE_SYNC_MAX_SCALE_DOWN_STEP";
+const DEFAULT_PROJECT_HEADER = "X-Concave-Project-Id";
+const DEFAULT_SYNC_COORDINATOR_BINDING = "SYNC_COORDINATOR_DO";
+const DEFAULT_SYNC_SHARD_MAP_KV_BINDING = "SYNC_SHARD_MAP_KV";
+const DEFAULT_SYNC_AFFINITY_KEY = "x-concave-sync-affinity";
+const DEFAULT_SYNC_REGION_KEY = "x-concave-region";
+const DEFAULT_SYNC_DEFAULT_REGION = "global";
+const DEFAULT_SHARD_MAP_CACHE_MS = 5_000;
+const DEFAULT_NODE_STALE_MS = 90_000;
+const DEFAULT_MIN_SHARDS = 1;
+const DEFAULT_TARGET_SESSIONS_PER_SHARD = 500;
+const DEFAULT_TARGET_CPU_UTILIZATION = 0.75;
+const DEFAULT_TARGET_MEMORY_UTILIZATION = 0.8;
+const DEFAULT_AUTO_SHARD_PREFIX = "auto";
+const DEFAULT_SYNC_AUTOSCALE_PROFILE = "advanced";
+const DEFAULT_SCALE_UP_COOLDOWN_MS = 15_000;
+const DEFAULT_SCALE_DOWN_COOLDOWN_MS = 45_000;
+const DEFAULT_SCALE_UP_HYSTERESIS_RATIO = 1.05;
+const DEFAULT_SCALE_DOWN_HYSTERESIS_RATIO = 0.95;
+const DEFAULT_MAX_SCALE_UP_STEP = 2;
+const DEFAULT_MAX_SCALE_DOWN_STEP = 1;
+export function createCfSyncTopologyRuntime(options) {
+    const logPrefix = options.logPrefix ?? "[sync-topology]";
+    const projectHeaderName = options.projectHeaderName ?? DEFAULT_PROJECT_HEADER;
+    const coordinatorBindingName = options.coordinatorBindingName ?? DEFAULT_SYNC_COORDINATOR_BINDING;
+    const shardMapKvBindingName = options.shardMapKvBindingName ?? DEFAULT_SYNC_SHARD_MAP_KV_BINDING;
+    const resolveProjectId = options.resolveProjectId ?? (() => undefined);
+    const buildShardMapCacheKey = options.buildShardMapCacheKey ??
+        ((logicalInstance, projectId) => {
+            const normalizedProject = projectId?.trim() ?? "default";
+            return `${normalizedProject}:${logicalInstance}`;
+        });
+    const shardMapCache = new Map();
+    const shardMapInFlight = new Map();
+    async function resolveRouteTargets(context) {
+        const env = context.env;
+        const config = resolveTopologyConfig(env);
+        const projectId = resolveProjectId(context.request, env);
+        const region = resolveRequestRegion(context.request, env);
+        const shardMap = await resolveSyncShardMap({
+            request: context.request,
+            env,
+            logicalInstance: context.instance,
+            projectId,
+            region,
+            config,
+        });
+        const regionCandidates = resolveRegionShardCandidates(shardMap, region, config.defaultRegion);
+        const bootstrapCandidates = regionCandidates.length > 0
+            ? regionCandidates
+            : resolveBootstrapShardCandidates(context.instance, region, config);
+        const syncDoName = selectDoName(context.request, context.instance, bootstrapCandidates, config.syncAffinityKey);
+        return {
+            syncDoName,
+            concaveDoName: context.instance,
+            syncNotifyDoNames: normalizeTargetList(shardMap.notifyShards),
+        };
+    }
+    function resolveSyncFanoutDoNames(logicalInstance, env) {
+        const staticMap = resolveStaticSyncShardMap(logicalInstance, env);
+        return normalizeTargetList(staticMap.notifyShards);
+    }
+    async function resolveSyncFanoutDoNamesAsync(logicalInstance, env, optionsInput) {
+        const config = resolveTopologyConfig(env);
+        const request = optionsInput?.request ?? new Request("https://concave.invalid/sync");
+        const projectId = optionsInput?.projectId ?? resolveProjectId(request, env);
+        const region = resolveRequestRegion(request, env);
+        const shardMap = await resolveSyncShardMap({
+            request,
+            env,
+            logicalInstance,
+            projectId,
+            region,
+            config,
+        });
+        return normalizeTargetList(shardMap.notifyShards);
+    }
+    function resolveStaticSyncShardMap(logicalInstance, env, nowMs = Date.now()) {
+        const config = resolveTopologyConfig(env);
+        return resolveSharedStaticShardMap(logicalInstance, config, nowMs);
+    }
+    function buildShardMapFromReports(optionsInput) {
+        return buildSharedShardMapFromReports({
+            ...optionsInput,
+            config: resolveTopologyConfig(optionsInput.env),
+        });
+    }
+    function resolveTopologyConfig(env) {
+        const syncNodes = parseNodeIds(env[DEFAULT_SYNC_NODE_IDS_ENV]);
+        const syncNodesByRegion = parseNodeIdsByRegion(env[DEFAULT_SYNC_NODE_IDS_BY_REGION_ENV]);
+        const syncAffinityKey = resolveHeaderLikeKey(env[DEFAULT_SYNC_AFFINITY_KEY_ENV], DEFAULT_SYNC_AFFINITY_KEY);
+        const regionKey = resolveHeaderLikeKey(env[DEFAULT_SYNC_REGION_KEY_ENV], DEFAULT_SYNC_REGION_KEY);
+        const defaultRegion = normalizeRegionName(env[DEFAULT_SYNC_DEFAULT_REGION_ENV], DEFAULT_SYNC_DEFAULT_REGION);
+        const regionByColo = parseRegionByColoMap(env[DEFAULT_SYNC_REGION_MAP_ENV]);
+        const useColoAsRegion = parseBoolean(env[DEFAULT_SYNC_USE_COLO_AS_REGION_ENV], false);
+        const scaleProfile = parseScaleProfile(env[DEFAULT_SYNC_AUTOSCALE_PROFILE_ENV], DEFAULT_SYNC_AUTOSCALE_PROFILE);
+        const allowScaleToZeroRequested = parseBoolean(env[DEFAULT_SYNC_SCALE_TO_ZERO_ENV], false);
+        const allowScaleToZero = allowScaleToZeroRequested && asDurableObjectNamespace(env[coordinatorBindingName]) !== undefined;
+        const shardMapCacheMs = parseIntWithMin(env[DEFAULT_SYNC_SHARD_MAP_CACHE_MS_ENV], DEFAULT_SHARD_MAP_CACHE_MS, 500);
+        const nodeStaleMs = parseIntWithMin(env[DEFAULT_SYNC_NODE_STALE_MS_ENV], DEFAULT_NODE_STALE_MS, 1_000);
+        const minShardFloor = allowScaleToZero ? 0 : 1;
+        const minShardsPerRegion = parseIntWithMin(env[DEFAULT_SYNC_MIN_SHARDS_ENV], allowScaleToZero ? 0 : DEFAULT_MIN_SHARDS, minShardFloor);
+        const maxShardsPerRegion = parseOptionalIntWithMin(env[DEFAULT_SYNC_MAX_SHARDS_ENV], minShardsPerRegion);
+        const targetSessionsPerShard = parseIntWithMin(env[DEFAULT_SYNC_TARGET_SESSIONS_ENV], DEFAULT_TARGET_SESSIONS_PER_SHARD, 1);
+        const targetMessageRatePerShard = parseOptionalIntWithMin(env[DEFAULT_SYNC_TARGET_MESSAGE_RATE_ENV], 1);
+        const targetNotifyRatePerShard = parseOptionalIntWithMin(env[DEFAULT_SYNC_TARGET_NOTIFY_RATE_ENV], 1);
+        const targetCpuUtilizationRaw = parseOptionalFloatWithRange(env[DEFAULT_SYNC_TARGET_CPU_UTILIZATION_ENV], 0.01, 1.5);
+        const targetMemoryUtilizationRaw = parseOptionalFloatWithRange(env[DEFAULT_SYNC_TARGET_MEMORY_UTILIZATION_ENV], 0.01, 1.5);
+        const targetCpuUtilization = targetCpuUtilizationRaw ?? (scaleProfile === "minimal" ? undefined : DEFAULT_TARGET_CPU_UTILIZATION);
+        const targetMemoryUtilization = targetMemoryUtilizationRaw ?? (scaleProfile === "minimal" ? undefined : DEFAULT_TARGET_MEMORY_UTILIZATION);
+        const autoShardsPerRegion = parseIntWithMin(env[DEFAULT_SYNC_AUTO_SHARDS_ENV], maxShardsPerRegion ?? minShardsPerRegion, 1);
+        const autoShardPrefix = resolveShardPrefix(env[DEFAULT_SYNC_AUTO_SHARD_PREFIX_ENV], DEFAULT_AUTO_SHARD_PREFIX);
+        const scaleUpCooldownMs = parseIntWithMin(env[DEFAULT_SYNC_SCALE_UP_COOLDOWN_MS_ENV], DEFAULT_SCALE_UP_COOLDOWN_MS, 0);
+        const scaleDownCooldownMs = parseIntWithMin(env[DEFAULT_SYNC_SCALE_DOWN_COOLDOWN_MS_ENV], DEFAULT_SCALE_DOWN_COOLDOWN_MS, 0);
+        const scaleUpHysteresisRatio = parseFloatWithRange(env[DEFAULT_SYNC_SCALE_UP_HYSTERESIS_RATIO_ENV], DEFAULT_SCALE_UP_HYSTERESIS_RATIO, 1, 3);
+        const scaleDownHysteresisRatio = parseFloatWithRange(env[DEFAULT_SYNC_SCALE_DOWN_HYSTERESIS_RATIO_ENV], DEFAULT_SCALE_DOWN_HYSTERESIS_RATIO, 0, 1);
+        const maxScaleUpStep = parseIntWithMin(env[DEFAULT_SYNC_MAX_SCALE_UP_STEP_ENV], DEFAULT_MAX_SCALE_UP_STEP, 1);
+        const maxScaleDownStep = parseIntWithMin(env[DEFAULT_SYNC_MAX_SCALE_DOWN_STEP_ENV], DEFAULT_MAX_SCALE_DOWN_STEP, 1);
+        return {
+            syncNodes,
+            syncNodesByRegion,
+            syncAffinityKey,
+            regionKey,
+            defaultRegion,
+            regionByColo,
+            useColoAsRegion,
+            shardMapCacheMs,
+            nodeStaleMs,
+            minShardsPerRegion,
+            maxShardsPerRegion,
+            targetSessionsPerShard,
+            targetMessageRatePerShard,
+            targetNotifyRatePerShard,
+            targetCpuUtilization,
+            targetMemoryUtilization,
+            autoShardsPerRegion,
+            autoShardPrefix,
+            allowScaleToZero,
+            scaleProfile,
+            scaleUpCooldownMs,
+            scaleDownCooldownMs,
+            scaleUpHysteresisRatio,
+            scaleDownHysteresisRatio,
+            maxScaleUpStep,
+            maxScaleDownStep,
+        };
+    }
+    function resolveRequestRegion(request, env) {
+        const config = resolveTopologyConfig(env);
+        const regionFromRequest = resolveHeaderQueryOrCookieValue(request, config.regionKey);
+        if (regionFromRequest && regionFromRequest.length > 0) {
+            return normalizeRegionName(regionFromRequest, config.defaultRegion);
+        }
+        const requestWithCf = request;
+        const colo = requestWithCf.cf?.colo?.trim();
+        if (colo && colo.length > 0) {
+            const mapped = config.regionByColo[colo.toUpperCase()];
+            if (mapped) {
+                return mapped;
+            }
+            if (config.useColoAsRegion) {
+                return normalizeRegionName(colo, config.defaultRegion);
+            }
+        }
+        return config.defaultRegion;
+    }
+    async function resolveSyncShardMap(context) {
+        const cacheKey = buildShardMapCacheKey(context.logicalInstance, context.projectId);
+        const nowMs = Date.now();
+        const cached = shardMapCache.get(cacheKey);
+        if (cached && cached.expiresAtMs > nowMs) {
+            return cached.value;
+        }
+        const inFlight = shardMapInFlight.get(cacheKey);
+        if (inFlight) {
+            return inFlight;
+        }
+        const resolution = resolveSyncShardMapUncached(context).then((resolved) => {
+            const ttlMs = parseIntWithMin(resolved.ttlMs, context.config.shardMapCacheMs, 500);
+            const normalized = {
+                ...resolved,
+                ttlMs,
+            };
+            shardMapCache.set(cacheKey, {
+                expiresAtMs: Date.now() + ttlMs,
+                value: normalized,
+            });
+            return normalized;
+        });
+        shardMapInFlight.set(cacheKey, resolution);
+        try {
+            return await resolution;
+        }
+        finally {
+            shardMapInFlight.delete(cacheKey);
+        }
+    }
+    async function resolveSyncShardMapUncached(context) {
+        const fromKv = await tryReadShardMapFromKv(context);
+        if (fromKv) {
+            return fromKv;
+        }
+        const fromCoordinator = await tryReadShardMapFromCoordinator(context);
+        if (fromCoordinator) {
+            return fromCoordinator;
+        }
+        return resolveStaticSyncShardMap(context.logicalInstance, context.env);
+    }
+    async function tryReadShardMapFromKv(context) {
+        const kv = asKvNamespace(context.env[shardMapKvBindingName]);
+        if (!kv) {
+            return undefined;
+        }
+        try {
+            const key = options.buildShardMapKvKey(context.logicalInstance, context.projectId);
+            const raw = await kv.get(key, { type: "json" });
+            const parsed = parseShardMap(raw, context.logicalInstance);
+            if (!parsed) {
+                return undefined;
+            }
+            return { ...parsed, source: "kv" };
+        }
+        catch (error) {
+            console.warn(`${logPrefix} Failed to read sync shard map from KV`, error);
+            return undefined;
+        }
+    }
+    async function tryReadShardMapFromCoordinator(context) {
+        const coordinatorNamespace = asDurableObjectNamespace(context.env[coordinatorBindingName]);
+        if (!coordinatorNamespace) {
+            return undefined;
+        }
+        try {
+            const coordinatorName = options.buildCoordinatorDoName(context.logicalInstance, context.projectId);
+            const coordinatorId = coordinatorNamespace.idFromName(coordinatorName);
+            const coordinatorStub = coordinatorNamespace.get(coordinatorId);
+            const headers = new Headers({
+                "X-Concave-Instance": context.logicalInstance,
+                "X-Concave-Region": context.region,
+            });
+            if (context.projectId) {
+                headers.set(projectHeaderName, context.projectId);
+            }
+            const response = await coordinatorStub.fetch(`http://do/shard-map?region=${encodeURIComponent(context.region)}`, {
+                method: "GET",
+                headers,
+            });
+            if (!response.ok) {
+                return undefined;
+            }
+            const body = (await response.json());
+            const parsed = parseShardMap(body, context.logicalInstance);
+            if (!parsed) {
+                return undefined;
+            }
+            return { ...parsed, source: "coordinator" };
+        }
+        catch (error) {
+            console.warn(`${logPrefix} Failed to read sync shard map from coordinator`, error);
+            return undefined;
+        }
+    }
+    return {
+        resolveRouteTargets,
+        resolveSyncFanoutDoNames,
+        resolveSyncFanoutDoNamesAsync,
+        resolveStaticSyncShardMap,
+        buildShardMapFromReports,
+        resolveTopologyConfig,
+        resolveRequestRegion,
+    };
+}
+export function buildPooledInstanceName(logicalInstance, poolKind, nodeId) {
+    return buildSharedPooledInstanceName(logicalInstance, poolKind, nodeId);
+}
+export function parseNodeIds(raw) {
+    return parseSharedNodeIds(raw);
+}
+export function parseNodeIdsByRegion(raw) {
+    return parseSharedNodeIdsByRegion(raw);
+}
+export function normalizeTargetList(targets) {
+    return normalizeSharedTargetList(targets);
+}
+function parseShardMap(raw, fallbackInstance) {
+    if (isValidSyncShardMap(raw)) {
+        return normalizeParsedShardMap(raw, fallbackInstance);
+    }
+    const data = parseRecordLike(raw);
+    if (!data) {
+        return undefined;
+    }
+    const regionsRaw = parseRecordLike(data.regions);
+    const regions = {};
+    if (regionsRaw) {
+        for (const [region, value] of Object.entries(regionsRaw)) {
+            const normalizedRegion = normalizeRegionName(region, "");
+            if (!normalizedRegion) {
+                continue;
+            }
+            const targets = parseNodeIds(value);
+            if (targets.length > 0 || isExplicitEmptyNodeList(value)) {
+                regions[normalizedRegion] = targets;
+            }
+        }
+    }
+    const notifySource = data.notifyShards ?? data.notify;
+    const notifyShards = normalizeTargetList(parseNodeIds(notifySource));
+    if (Object.keys(regions).length === 0) {
+        regions[DEFAULT_SYNC_DEFAULT_REGION] = [fallbackInstance];
+    }
+    const ttlMs = parseIntWithMin(data.ttlMs, DEFAULT_SHARD_MAP_CACHE_MS, 500);
+    const generatedAtMs = parseIntWithMin(data.generatedAtMs, Date.now(), 0);
+    return normalizeParsedShardMap({
+        generatedAtMs,
+        ttlMs,
+        regions,
+        notifyShards,
+    }, fallbackInstance);
+}
+function normalizeParsedShardMap(shardMap, fallbackInstance) {
+    const regions = {};
+    for (const [region, targets] of Object.entries(shardMap.regions)) {
+        const normalizedRegion = normalizeRegionName(region, "");
+        if (!normalizedRegion) {
+            continue;
+        }
+        regions[normalizedRegion] = normalizeTargetList(targets);
+    }
+    if (Object.keys(regions).length === 0) {
+        regions[DEFAULT_SYNC_DEFAULT_REGION] = [fallbackInstance];
+    }
+    return {
+        ...shardMap,
+        generatedAtMs: parseIntWithMin(shardMap.generatedAtMs, Date.now(), 0),
+        ttlMs: parseIntWithMin(shardMap.ttlMs, DEFAULT_SHARD_MAP_CACHE_MS, 500),
+        regions,
+        notifyShards: normalizeTargetList(shardMap.notifyShards),
+    };
+}
+function parseRegionByColoMap(raw) {
+    const parsed = parseRecordLike(raw);
+    if (!parsed) {
+        return {};
+    }
+    const result = {};
+    for (const [colo, regionValue] of Object.entries(parsed)) {
+        if (typeof regionValue !== "string") {
+            continue;
+        }
+        const normalizedRegion = normalizeRegionName(regionValue, "");
+        if (!normalizedRegion) {
+            continue;
+        }
+        result[colo.trim().toUpperCase()] = normalizedRegion;
+    }
+    return result;
+}
+function parseRecordLike(raw) {
+    if (typeof raw === "object" && raw !== null && !Array.isArray(raw)) {
+        return raw;
+    }
+    if (typeof raw !== "string") {
+        return undefined;
+    }
+    const trimmed = raw.trim();
+    if (trimmed.length === 0) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return undefined;
+    }
+    catch {
+        const result = {};
+        for (const token of trimmed.split(";")) {
+            const normalizedToken = token.trim();
+            if (!normalizedToken) {
+                continue;
+            }
+            const equalsIndex = normalizedToken.indexOf("=");
+            const colonIndex = normalizedToken.indexOf(":");
+            const separatorIndex = equalsIndex === -1 ? colonIndex : equalsIndex;
+            if (separatorIndex === -1) {
+                continue;
+            }
+            const key = normalizedToken.slice(0, separatorIndex).trim();
+            const value = normalizedToken.slice(separatorIndex + 1).trim();
+            if (!key || !value) {
+                continue;
+            }
+            result[key] = value;
+        }
+        return result;
+    }
+}
+function isExplicitEmptyNodeList(raw) {
+    if (Array.isArray(raw)) {
+        return raw.length === 0;
+    }
+    if (typeof raw !== "string") {
+        return false;
+    }
+    return raw.trim() === "[]";
+}
+function resolveRegionShardCandidates(shardMap, region, defaultRegion) {
+    const normalizedRegion = normalizeRegionName(region, defaultRegion);
+    const directMatch = shardMap.regions[normalizedRegion];
+    if (directMatch) {
+        return normalizeTargetList(directMatch);
+    }
+    const defaultMatch = shardMap.regions[defaultRegion];
+    if (defaultMatch) {
+        return normalizeTargetList(defaultMatch);
+    }
+    const firstRegion = Object.values(shardMap.regions).find((targets) => targets.length > 0);
+    return normalizeTargetList(firstRegion);
+}
+function selectDoName(request, fallbackInstance, targets, affinityKey) {
+    const candidates = normalizeTargets(targets, fallbackInstance);
+    if (candidates.length <= 1) {
+        return candidates[0] ?? fallbackInstance;
+    }
+    const affinity = resolveAffinityValue(request, affinityKey, fallbackInstance);
+    return pickNodeByRendezvousHash(affinity, candidates);
+}
+function resolveAffinityValue(request, affinityKey, fallback) {
+    const affinity = resolveHeaderQueryOrCookieValue(request, affinityKey);
+    if (affinity && affinity.length > 0) {
+        return affinity;
+    }
+    const authHeader = request.headers.get("Authorization");
+    if (authHeader && authHeader.length > 0) {
+        return authHeader;
+    }
+    const clientIp = request.headers.get("CF-Connecting-IP") ?? request.headers.get("X-Forwarded-For");
+    if (clientIp && clientIp.length > 0) {
+        return clientIp;
+    }
+    const userAgent = request.headers.get("User-Agent");
+    if (userAgent && userAgent.length > 0) {
+        return userAgent;
+    }
+    return fallback;
+}
+function resolveHeaderQueryOrCookieValue(request, key) {
+    const url = new URL(request.url);
+    const queryValue = url.searchParams.get(key);
+    if (queryValue && queryValue.length > 0) {
+        return queryValue;
+    }
+    const headerValue = request.headers.get(key);
+    if (headerValue && headerValue.length > 0) {
+        return headerValue;
+    }
+    const cookieValue = readCookieValue(request.headers.get("Cookie"), key);
+    if (cookieValue && cookieValue.length > 0) {
+        return cookieValue;
+    }
+    return undefined;
+}
+function readCookieValue(cookieHeader, name) {
+    if (!cookieHeader) {
+        return undefined;
+    }
+    const target = name.toLowerCase();
+    const entries = cookieHeader.split(";").map((part) => part.trim());
+    for (const entry of entries) {
+        if (!entry) {
+            continue;
+        }
+        const equals = entry.indexOf("=");
+        if (equals === -1) {
+            continue;
+        }
+        const key = entry.slice(0, equals).trim().toLowerCase();
+        if (key !== target) {
+            continue;
+        }
+        return decodeURIComponent(entry.slice(equals + 1).trim());
+    }
+    return undefined;
+}
+function resolveBootstrapShardCandidates(logicalInstance, region, config) {
+    return resolveBootstrapSyncShardCandidates(logicalInstance, region, config);
+}
+function normalizeTargets(targets, fallback) {
+    const normalized = normalizeTargetList(targets);
+    return normalized.length > 0 ? normalized : [fallback];
+}
+function normalizeRegionName(raw, fallback) {
+    if (typeof raw !== "string") {
+        return fallback;
+    }
+    const normalized = raw.trim().toLowerCase();
+    return normalized.length > 0 ? normalized : fallback;
+}
+function asDurableObjectNamespace(raw) {
+    if (!raw || typeof raw !== "object") {
+        return undefined;
+    }
+    const candidate = raw;
+    if (typeof candidate.idFromName !== "function" || typeof candidate.get !== "function") {
+        return undefined;
+    }
+    return candidate;
+}
+function asKvNamespace(raw) {
+    if (!raw || typeof raw !== "object") {
+        return undefined;
+    }
+    const candidate = raw;
+    if (typeof candidate.get !== "function") {
+        return undefined;
+    }
+    return candidate;
+}
+function resolveHeaderLikeKey(raw, fallback) {
+    if (typeof raw !== "string") {
+        return fallback;
+    }
+    const trimmed = raw.trim().toLowerCase();
+    return trimmed.length > 0 ? trimmed : fallback;
+}
+function parseBoolean(raw, fallback) {
+    if (typeof raw === "boolean") {
+        return raw;
+    }
+    if (typeof raw !== "string") {
+        return fallback;
+    }
+    const normalized = raw.trim().toLowerCase();
+    if (normalized === "1" || normalized === "true" || normalized === "yes") {
+        return true;
+    }
+    if (normalized === "0" || normalized === "false" || normalized === "no") {
+        return false;
+    }
+    return fallback;
+}
+function resolveShardPrefix(raw, fallback) {
+    if (typeof raw !== "string") {
+        return fallback;
+    }
+    const normalized = raw
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+    return normalized.length > 0 ? normalized : fallback;
+}
+function parseIntWithMin(raw, fallback, minimum) {
+    const value = parseNumber(raw);
+    if (value === undefined) {
+        return Math.max(minimum, fallback);
+    }
+    return Math.max(minimum, value);
+}
+function parseOptionalIntWithMin(raw, minimum) {
+    const value = parseNumber(raw);
+    if (value === undefined) {
+        return undefined;
+    }
+    return Math.max(minimum, value);
+}
+function parseOptionalFloatWithRange(raw, minimum, maximum) {
+    const value = parseFloatNumber(raw);
+    if (value === undefined) {
+        return undefined;
+    }
+    return clampNumber(value, minimum, maximum);
+}
+function parseFloatWithRange(raw, fallback, minimum, maximum) {
+    const value = parseFloatNumber(raw);
+    if (value === undefined) {
+        return clampNumber(fallback, minimum, maximum);
+    }
+    return clampNumber(value, minimum, maximum);
+}
+function parseNumber(raw) {
+    if (typeof raw === "number" && Number.isFinite(raw)) {
+        return Math.floor(raw);
+    }
+    if (typeof raw !== "string") {
+        return undefined;
+    }
+    const trimmed = raw.trim();
+    if (!/^\d+$/.test(trimmed)) {
+        return undefined;
+    }
+    return Number(trimmed);
+}
+function parseFloatNumber(raw) {
+    if (typeof raw === "number" && Number.isFinite(raw)) {
+        return raw;
+    }
+    if (typeof raw !== "string") {
+        return undefined;
+    }
+    const trimmed = raw.trim();
+    if (!/^\d+(?:\.\d+)?$/.test(trimmed)) {
+        return undefined;
+    }
+    const parsed = Number(trimmed);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+function parseScaleProfile(raw, fallback) {
+    if (typeof raw !== "string") {
+        return fallback;
+    }
+    const normalized = raw.trim().toLowerCase();
+    if (normalized === "minimal" || normalized === "advanced" || normalized === "custom") {
+        return normalized;
+    }
+    return fallback;
+}
+function clampNumber(value, minimum, maximum) {
+    return Math.max(minimum, Math.min(maximum, value));
+}
+function pickNodeByRendezvousHash(affinity, nodes) {
+    let selected = nodes[0];
+    let bestScore = -1;
+    for (const nodeId of nodes) {
+        const score = fnv1a32(`${affinity}:${nodeId}`);
+        if (score > bestScore || (score === bestScore && nodeId > selected)) {
+            bestScore = score;
+            selected = nodeId;
+        }
+    }
+    return selected;
+}
+function fnv1a32(input) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < input.length; i += 1) {
+        hash ^= input.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return hash >>> 0;
+}

package/dist/worker/create-concave-worker.d.ts

@@ -1,5 +1,6 @@
 import type { DurableObjectNamespace, ExecutionContext } from "@cloudflare/workers-types";
 import { handleHttpApiRequest } from "../http/http-api";
+import type { SyncWriteDispatchPayload } from "../http/http-api";
 import { type ModuleLoader, type ModuleRegistry } from "@concavejs/core/udf";
 export interface ConcaveWorkerBindings {
     getConcaveNamespace: (env: any, ctx: ExecutionContext) => DurableObjectNamespace | undefined;
@@ -25,6 +26,50 @@ export interface ConcaveWorkerOptions {
     configureModuleLoaders?: (registry: ModuleRegistry) => void;
     /** Pre-loaded dashboard HTML (avoids bundling dashboard-local) */
     dashboardHtml?: string;
+    /**
+     * Optional per-request routing overrides for selecting physical DO targets.
+     *
+     * `instance` remains the logical tenant/app instance used for auth/data scoping.
+     * Route targets can point at a pooled DO name for scaling.
+     */
+    resolveRouteTargets?: (context: ConcaveWorkerRouteContext) => ConcaveWorkerRouteTargets | Promise<ConcaveWorkerRouteTargets | undefined> | undefined;
+}
+export interface ConcaveWorkerRouteContext<Env = any> {
+    request: Request;
+    env: Env;
+    ctx: ExecutionContext;
+    /** Logical instance selected via query/header/cookie routing. */
+    instance: string;
+}
+export interface ConcaveWorkerRouteTargets {
+    /** Physical ConcaveDO name to route /api and /udf requests to. */
+    concaveDoName?: string;
+    /** Physical SyncDO name to route /sync websocket connections to. */
+    syncDoName?: string;
+    /**
+     * Physical SyncDO names that should receive mutation write notifications.
+     * Defaults to `[syncDoName]`.
+     */
+    syncNotifyDoNames?: string[];
+    /**
+     * Structured target descriptor for runtime adapters.
+     * `targetName` maps to ConcaveDO in Cloudflare runtime.
+     */
+    concave?: {
+        targetName?: string;
+    };
+    /**
+     * Structured sync target descriptor for runtime adapters.
+     * `targetName` maps to SyncDO, and `notifyTargetNames` maps to fanout targets.
+     */
+    sync?: {
+        targetName?: string;
+        notifyTargetNames?: string[];
+    };
+    /**
+     * Optional write-dispatch override (queue/stream fanout) for API mutations.
+     */
+    dispatchSyncWrites?: (payload: SyncWriteDispatchPayload) => Promise<void>;
 }
 export declare function resolveNamespaceBinding(env: any, ctx: ExecutionContext, bindingName: string, exportName: string): DurableObjectNamespace | undefined;
 export declare function createScopedNamespace(ns: DurableObjectNamespace, prefix: string): DurableObjectNamespace;

package/dist/worker/create-concave-worker.js

@@ -22,7 +22,7 @@ export function createScopedNamespace(ns, prefix) {
     };
 }
 export function createConcaveWorker(options) {
-    const { bindings, instanceKey = DEFAULT_INSTANCE_KEY, cors = true, apiPrefix = "/api", udfPrefix = "/udf", syncPathMatcher = DEFAULT_SYNC_PATH_MATCHER, handleHttpApiRequest: apiHandler = handleHttpApiRequest, moduleLoader, moduleLoaders, configureModuleLoaders, dashboardHtml: injectedDashboardHtml, } = options;
+    const { bindings, instanceKey = DEFAULT_INSTANCE_KEY, cors = true, apiPrefix = "/api", udfPrefix = "/udf", syncPathMatcher = DEFAULT_SYNC_PATH_MATCHER, handleHttpApiRequest: apiHandler = handleHttpApiRequest, moduleLoader, moduleLoaders, configureModuleLoaders, dashboardHtml: injectedDashboardHtml, resolveRouteTargets, } = options;
     let cachedDashboardHtml = injectedDashboardHtml;
     const explicitLoaders = collectModuleLoaders(moduleLoader, moduleLoaders);
     if (explicitLoaders.length > 0) {
@@ -49,6 +49,10 @@ export function createConcaveWorker(options) {
             });
             const instance = instanceResolution.value;
             const forwardUrl = new URL(url.toString());
+            const routeTargets = (await resolveRouteTargets?.({ request, env, ctx, instance })) ?? {};
+            const concaveDoName = normalizeRouteTargetName(routeTargets.concaveDoName ?? routeTargets.concave?.targetName, instance);
+            const syncDoName = normalizeRouteTargetName(routeTargets.syncDoName ?? routeTargets.sync?.targetName, instance);
+            const syncNotifyDoNames = normalizeSyncNotifyTargets(routeTargets.syncNotifyDoNames ?? routeTargets.sync?.notifyTargetNames, syncDoName);
             if (cors && request.method === "OPTIONS") {
                 return new Response("OK", {
                     headers: buildCorsHeaders(request),
@@ -63,10 +67,11 @@ export function createConcaveWorker(options) {
                     console.error("[ConcaveWorker] Sync Durable Object namespace is not configured");
                     throw new Error("Sync Durable Object namespace is not configured");
                 }
-                const id = namespace.idFromName(instance);
+                const id = namespace.idFromName(syncDoName);
                 const stub = namespace.get(id);
-                console.log(`[ConcaveWorker] Forwarding to SyncDO: ${instance} (${id.toString()})`);
+                console.log(`[ConcaveWorker] Forwarding to SyncDO: logical=${instance} physical=${syncDoName} (${id.toString()})`);
                 const forwardedRequest = new Request(forwardUrl.toString(), request);
+                forwardedRequest.headers.set("X-Concave-Instance", instance);
                 if (request.headers.get("Upgrade")) {
                     forwardedRequest.headers.set("Upgrade", request.headers.get("Upgrade"));
                 }
@@ -85,7 +90,12 @@ export function createConcaveWorker(options) {
             }
             if (pathname.startsWith(apiPrefix)) {
                 const forwardedRequest = new Request(forwardUrl.toString(), request);
-                const response = await apiHandler(forwardedRequest, env, ctx, instance);
+                forwardedRequest.headers.set("X-Concave-Instance", instance);
+                const response = await apiHandler(forwardedRequest, env, ctx, instance, {
+                    concaveDoName,
+                    syncDoNames: syncNotifyDoNames,
+                    dispatchSyncWrites: routeTargets.dispatchSyncWrites,
+                });
                 return maybeAttachInstanceCookie(response, request, instanceResolution, { instanceKey });
             }
             if (pathname.startsWith(udfPrefix)) {
@@ -93,9 +103,10 @@ export function createConcaveWorker(options) {
                 if (!namespace) {
                     throw new Error("Concave Durable Object namespace is not configured");
                 }
-                const id = namespace.idFromName(instance);
+                const id = namespace.idFromName(concaveDoName);
                 const stub = namespace.get(id);
                 const forwardedRequest = new Request(forwardUrl.toString(), request);
+                forwardedRequest.headers.set("X-Concave-Instance", instance);
                 const response = await stub.fetch(forwardedRequest);
                 return maybeAttachInstanceCookie(response, request, instanceResolution, { instanceKey });
             }
@@ -160,3 +171,23 @@ function collectModuleLoaders(primary, additional) {
 function isDashboardPath(pathname) {
     return pathname === "/_dashboard" || pathname.startsWith("/_dashboard/");
 }
+function normalizeRouteTargetName(target, fallback) {
+    const trimmed = target?.trim();
+    return trimmed && trimmed.length > 0 ? trimmed : fallback;
+}
+function normalizeSyncNotifyTargets(targets, fallback) {
+    if (targets === undefined) {
+        return [fallback];
+    }
+    if (targets.length === 0) {
+        return [];
+    }
+    const deduped = new Set();
+    for (const target of targets) {
+        const trimmed = target.trim();
+        if (trimmed.length > 0) {
+            deduped.add(trimmed);
+        }
+    }
+    return Array.from(deduped);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@concavejs/runtime-cf-base",
-  "version": "0.0.1-alpha.8",
+  "version": "0.0.1-alpha.9",
   "license": "FSL-1.1-Apache-2.0",
   "publishConfig": {
     "access": "public"
@@ -68,6 +68,10 @@
 "types": "./dist/worker/udf-worker.d.ts",
 "default": "./dist/worker/udf-worker.js"
 },
+"./routing/sync-topology": {
+"types": "./dist/routing/sync-topology.d.ts",
+"default": "./dist/routing/sync-topology.js"
+},
 "./sync": {
 "types": "./dist/sync/index.d.ts",
 "default": "./dist/sync/index.js"