@concavejs/runtime-cf-base 0.0.1-alpha.10

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/rpc/blobstore-proxy.d.ts

@@ -0,0 +1,11 @@
+import type { BlobStore } from "@concavejs/core/abstractions";
+/**
+ * Wraps a DO stub as a BlobStore.
+ * Blobstore methods are prefixed with "blobstore" on the DO to avoid collisions.
+ */
+export declare function createBlobStoreProxy(stub: any): BlobStore;
+/**
+ * Wraps a SyscallGateway service binding as a BlobStore.
+ * Prepends projectId and instance to each call for multi-tenant routing.
+ */
+export declare function createGatewayBlobStoreProxy(gateway: any, projectId: string, instance: string): BlobStore;