import { createHash } from "node:crypto"; import { resourceEnvironmentKeys, resourceToken, validateDevFnConfig, type DevFnConfig, type ResourceKind, type ResourceSpec, type ResourceTargetSpec } from "@devfn/config"; import { composeProjectName, type ComposeServiceDnsNames } from "@devfn/compose"; import { DevFnError, type LifecyclePlan } from "./types.js"; /** Where a planned value came from; values never include credentials. */ export type ResourceValueSource = "manifest" | "lease" | "compose" | "host-gateway" | "namespace"; export interface ResourceValue { value: string; source: ResourceValueSource; field: string } export interface UnreachableResourceValue { unreachable: string } export interface PlannedResource { kind: ResourceKind; target?: { name: string; location: "local" | "remote"; selectedBy: "profile" | "defaultTarget"; field: string }; provider?: { node: string; kind: "process" | "service"; port: string }; /** Credential-free remote URL; validation rejects userinfo, queries and fragments. */ remote?: { url: string }; consumers: string[]; namespace?: { sharing: "isolated" | "shared"; prefix: string; field: string }; /** Host environment variable names consumers receive through their secret channel. Values are never read. */ secrets: Array<{ name: string; env: string; field: string; present?: boolean }>; /** Values for host-side consumers: native processes, readiness commands and environment outputs. */ values: Record; /** * What each selected Compose service receives of every key, or why it * receives none (serviceValues): consumers their container-side endpoint, * a Compose provider the addresses it advertises, every service the * namespace values. */ services: Record>; } /** A redacted, side-effect-free resource topology for one profile and runtime owner. */ export interface ResourcePlan { profile: string; /** Opaque digest of the lifecycle owner the plan was made for. */ owner: string; /** Opaque digest of the lifecycle owner and runtime identity that isolates namespaces. */ ownerToken: string; containerHostGateway?: { host: string; field: string }; resources: Record; } export interface ResourcePlanInput { config: DevFnConfig; plan: LifecyclePlan; /** Opaque lifecycle owner, as passed to the endpoint resolver. */ ownerId: string; /** * Random identity of the runtime (its DevFn state directory). Owner ids * derive from checkout paths, which separate machines, devcontainers and CI * runners can share; with it, their isolated namespaces differ. */ runtimeId?: string; /** Leased ports by name; preflight callers pass placeholders and set provisionalPorts. */ ports: Readonly>; /** * The ports are preflight placeholders, not leases: an exact port is its * declared number, and any other port names no loopback listener yet. */ provisionalPorts?: boolean; /** Effective Compose networks by selected service, as passed to the endpoint resolver. */ composeNetworks?: Readonly>; /** * Other Docker DNS names of each selected service, read with its effective * networks: container_name and network aliases, and the names its own * links and extra_hosts map. Without them only service names are known. */ composeNames?: Readonly>; /** * The Compose networks are provisional placeholders, not effective * networks: which listener a Compose service name reaches is unknown, so * collisions on such listeners are left to a pass with effective networks. */ provisionalNetworks?: boolean; /** * Host name containers use to reach host loopback listeners. Defaults to * host.docker.internal on macOS and Windows (Docker Desktop) and to none on * Linux, where Compose consumers of host listeners fail instead. */ containerHostGateway?: string | null; platform?: NodeJS.Platform; /** Host environment, read only for secret presence; values are never copied. */ environment?: Readonly>; } function invalid(message: string): never { throw new DevFnError("DEVFN_RESOURCE_INVALID", message); } /** An own entry of a manifest map: names such as constructor never reach Object.prototype. */ function own(map: Readonly> | undefined, name: string): T | undefined { return map && Object.hasOwn(map, name) ? map[name] : undefined; } /** The manifest entry of a lifecycle node, by its kind. */ function nodeSpec(config: DevFnConfig, node: { name: string; kind: string }) { return node.kind === "process" ? own(config.processes, node.name) : own(config.services, node.name); } /** The target a profile selects for a resource, or undefined when it selects none. */ export function selectedResourceTarget(config: DevFnConfig, profile: string, resource: string): { name: string; selectedBy: "profile" | "defaultTarget" } | undefined { const selected = own(own(config.profiles, profile)?.resources, resource); if (selected !== undefined) return { name: selected, selectedBy: "profile" }; const fallback = own(config.resources, resource)?.defaultTarget; return fallback === undefined ? undefined : { name: fallback, selectedBy: "defaultTarget" }; } function localProvider(config: DevFnConfig, profile: string, resource: string, consumer?: string): string | undefined { const spec = own(config.resources, resource); if (!spec || spec.kind === "browser") return undefined; const selection = selectedResourceTarget(config, profile, resource); if (!selection) { invalid(`${consumer ? `${consumer} consumes resource ${resource}, but profile` : "Profile"} ${profile} selects no target for it and it declares no defaultTarget.`); } const target = own(spec.targets, selection.name)!; return "node" in target ? target.node : undefined; } /** Lifecycle nodes that provide the local targets a node's consumed resources select. */ export function resourceProviders(config: DevFnConfig, profile: string, node: string): string[] { const consumed = own(config.processes, node)?.resources ?? own(config.services, node)?.resources ?? []; return consumed.flatMap((resource) => localProvider(config, profile, resource, node) ?? []); } /** Lifecycle nodes that provide the local targets a profile selects explicitly. */ export function profileResourceProviders(config: DevFnConfig, profile: string): string[] { return Object.keys(own(config.profiles, profile)?.resources ?? {}).flatMap((resource) => localProvider(config, profile, resource) ?? []); } interface Endpoint { scheme?: string; host: string; port: string; path: string } const DEFAULT_PORTS: Record = { "http:": "80", "https:": "443", "ws:": "80", "wss:": "443" }; /** * A host as the host resolver sees it, whatever the URL scheme: IPv4 * shorthand, IPv6 and case are normalized by WHATWG host parsing, which * non-special schemes (postgres:, redis:) otherwise skip, and a trailing * root dot is dropped. */ function canonicalHost(host: string): string { let canonical = host.toLowerCase(); try { canonical = new URL(`http://${host}/`).hostname; } catch { /* an opaque host is compared as written */ } // A linear scan: a regular expression backtracks on long runs of dots. let end = canonical.length; while (end > 0 && canonical[end - 1] === ".") end -= 1; return canonical.slice(0, end); } /** * How a host reaches this machine's loopback: "address" for loopback and * unspecified addresses (127/8, 0/8, [::1], [::] and their IPv4-mapped or * -compatible forms) and plain localhost; "name" for *.localhost names, whose * listeners (such as the DevFn proxy) may route by that name. */ function loopbackHost(host: string): "address" | "name" | undefined { const canonical = canonicalHost(host); if (canonical === "localhost") return "address"; if (canonical.endsWith(".localhost")) return "name"; if (/^(?:127|0)\.\d+\.\d+\.\d+$/.test(canonical)) return "address"; const ipv6 = /^\[([0-9a-f:.]+)\]$/.exec(canonical)?.[1]; if (!ipv6) return undefined; if (ipv6 === "::1" || ipv6 === "::") return "address"; const embedded = /^::(?:ffff:(?:0:)?)?([0-9a-f]{1,4}):[0-9a-f]{1,4}$/.exec(ipv6); const firstOctet = embedded ? Number.parseInt(embedded[1], 16) >> 8 : -1; return firstOctet === 127 || firstOctet === 0 ? "address" : undefined; } /** A URL in the form clients and Origin headers use: a scheme's default port is omitted. */ function endpointUrl(endpoint: Endpoint): string { const port = DEFAULT_PORTS[`${endpoint.scheme}:`] === endpoint.port ? "" : `:${endpoint.port}`; return `${endpoint.scheme}://${endpoint.host}${port}${endpoint.path}`; } function endpointValues(prefix: string, endpoint: Endpoint, source: ResourceValueSource, field: string): Record { const value = (text: string): ResourceValue => ({ value: text, source, field }); const authority = `${endpoint.host}:${endpoint.port}`; return { [`${prefix}HOST`]: value(endpoint.host), [`${prefix}PORT`]: value(endpoint.port), [`${prefix}ENDPOINT`]: value(authority), ...(endpoint.scheme ? { [`${prefix}URL`]: value(endpointUrl(endpoint)) } : {}), }; } interface NamespaceValues { prefix: string; values: Record; database?: string; schema?: string; members: string[]; scope?: string[] } /** * The key segments a URL path names, without empty or "." segments and with * ".." applied; target URLs cannot be percent-encoded. Folding spellings an * object store may distinguish can only report an overlap, never hide one. */ function pathSegments(raw: string): string[] { const segments: string[] = []; for (const segment of raw.split("/")) { if (segment === "" || segment === ".") continue; if (segment === "..") segments.pop(); else segments.push(segment); } return segments; } function namespaceValues(name: string, spec: ResourceSpec, token: string, prefix: string): NamespaceValues { const isolated = spec.namespace?.sharing !== "shared"; const base = spec.namespace?.base ?? (spec.kind === "database" ? name.replaceAll("-", "_") : name); const owned = (separator: string) => isolated ? `${base}${separator}${token}` : base; switch (spec.kind) { case "database": { const namespace = owned("_"); const schemaLevel = spec.namespace?.level === "schema"; const database = schemaLevel ? spec.namespace!.database! : namespace; return { prefix: namespace, database, ...(schemaLevel ? { schema: namespace } : {}), members: [], values: { [`${prefix}NAMESPACE`]: namespace, [`${prefix}DATABASE`]: database, ...(schemaLevel ? { [`${prefix}SCHEMA`]: namespace } : {}) } }; } case "cache": case "object-store": { const separator = spec.kind === "cache" ? ":" : "/"; const namespace = `${owned(separator)}${separator}`; return { prefix: namespace, members: [], values: { [`${prefix}NAMESPACE`]: owned(separator), [`${prefix}PREFIX`]: namespace } }; } case "broker": { // Topics and the consumer group share one namespace: an isolated runtime // never joins another runtime's group or reads its topics by accident. const namespace = owned("."); const topics = Object.fromEntries(spec.topics!.map((topic) => [`${prefix}TOPIC_${resourceToken(topic)}`, `${namespace}.${topic}`])); const group = spec.consumerGroup ? `${namespace}.${spec.consumerGroup}` : namespace; return { prefix: namespace, members: [...Object.values(topics), `group:${group}`], values: { [`${prefix}NAMESPACE`]: namespace, ...topics, [`${prefix}CONSUMER_GROUP`]: group } }; } case "browser": { const namespace = owned("_"); const cookies = Object.fromEntries((spec.cookies ?? []).map((cookie) => [`${prefix}COOKIE_${resourceToken(cookie)}`, `${namespace}_${cookie}`])); const storage = Object.fromEntries((spec.storageKeys ?? []).map((key) => [`${prefix}STORAGE_${resourceToken(key)}`, `${namespace}:${key}`])); return { prefix: namespace, members: [...Object.values(cookies).map((cookie) => `cookie:${cookie}`), ...Object.values(storage).map((key) => `storage:${key}`)], values: { [`${prefix}NAMESPACE`]: namespace, ...cookies, ...storage } }; } default: return { prefix: "", members: [], values: {} }; } } /** * Whether a consumer reaches a Compose provider by its service name, under the * endpoint resolver's sibling URL rule: same project and a shared effective * network. Listener identity instead follows Docker DNS, which also resolves * the name across projects on a shared network (containerListeners). */ function sharesComposeNetwork(input: ResourcePlanInput, producer: string, consumer: string): boolean { const { config, ownerId } = input; const project = (name: string) => composeProjectName(own(config.services, name)!.projectName ?? "devfn", ownerId); if (project(producer) !== project(consumer)) return false; const consumerNetworks = own(input.composeNetworks, consumer) ?? []; return (own(input.composeNetworks, producer) ?? []).some((network) => consumerNetworks.includes(network)); } interface TargetContext { input: ResourcePlanInput; name: string; spec: ResourceSpec; targetName: string; target: ResourceTargetSpec; database?: string; gateway?: { host: string; field: string }; } /** The number a port has before reservation, when the manifest fixes it. */ function exactPort(input: ResourcePlanInput, port: string): number | undefined { const spec = own(input.config.ports, port); return spec?.exact ? spec.preferred : undefined; } /** A leased port's number, or undefined while it is a preflight placeholder. */ function knownPort(input: ResourcePlanInput, port: string): number | undefined { return input.provisionalPorts ? exactPort(input, port) : own(input.ports, port); } function localEndpoint(context: TargetContext, target: Extract): { host: Endpoint; provider: PlannedResource["provider"] } { const { input, name } = context; const provider = input.plan.nodes.find((node) => node.name === target.node); if (!provider) invalid(`Resource ${name} selects local target ${context.targetName}, but profile ${input.plan.profile} does not start ${target.node}.`); // Containers dial a Compose provider by its service name; a loopback name // would reach each consumer, and the provider's advertised address, itself. const service = provider.kind === "service" ? own(input.config.services, target.node)!.service : undefined; if (service !== undefined && loopbackHost(service)) { invalid(`Resource ${name} target ${context.targetName} is provided by Compose service ${service}, a loopback name that containers resolve to themselves; rename the Compose service.`); } const leased = knownPort(input, target.port) ?? own(input.ports, target.port); if (leased === undefined || !Number.isInteger(leased) || leased < 1 || leased > 65535) invalid(`Resource ${name} target ${context.targetName} requires a leased ${target.port} port.`); const path = context.database !== undefined ? `/${context.database}` : target.path ?? ""; return { host: { ...(target.scheme ? { scheme: target.scheme } : {}), host: "127.0.0.1", port: String(leased), path }, provider: { node: target.node, kind: provider.kind, port: target.port } }; } function remoteEndpoint(context: TargetContext, raw: string): Endpoint { const url = new URL(raw); const path = context.database !== undefined ? `/${context.database}` : url.pathname === "/" ? "" : url.pathname; return { scheme: url.protocol.slice(0, -1), host: url.hostname, port: url.port || DEFAULT_PORTS[url.protocol], path }; } /** Container-side endpoint of a selected target for one Compose service, or why it is unreachable. */ function containerEndpoint(context: TargetContext, host: Endpoint, service: string): { endpoint: Endpoint; source: ResourceValueSource; field: string } | { unreachable: string } { const { input, target, gateway } = context; if ("node" in target) { const producer = own(input.config.services, target.node); if (producer && input.plan.nodes.some((node) => node.name === target.node && node.kind === "service") && sharesComposeNetwork(input, target.node, service)) { return { endpoint: { ...host, host: producer.service, port: String(own(producer.ports, target.port)) }, source: "compose", field: `services.${target.node}.ports.${target.port}` }; } } else { const loopback = loopbackHost(host.host); if (!loopback) return { endpoint: host, source: "manifest", field: `resources.${context.name}.targets.${context.targetName}.url` }; // Rewriting a *.localhost name to the gateway would drop the name its // listener routes by, so it is never rewritten. if (loopback === "name") { return { unreachable: `Resource ${context.name} target ${context.targetName} uses loopback name ${host.host}, which Compose service ${service} cannot reach and DevFn cannot rewrite to a container host gateway without changing the name its listener routes by; select a target reachable from containers.` }; } } // Host loopback inside a container is the container itself. Only a // platform host gateway reaches the host's loopback listeners. if (gateway) return { endpoint: { ...host, host: gateway.host }, source: "host-gateway", field: gateway.field }; return { unreachable: `Resource ${context.name} target ${context.targetName} listens on host loopback, which Compose service ${service} cannot reach on this platform without a container host gateway; provide it from a Compose service on a shared network or select a remote target.` }; } const HOST_LABEL = /^[a-z0-9_](?:[a-z0-9_-]{0,61}[a-z0-9_])?$/i; /** * A bare hostname, IPv4 literal or bracketed IPv6 literal: the value becomes * the host of every gateway-reached endpoint, so userinfo, a scheme, a port, a * path or whitespace would corrupt those URLs or put credentials in the plan. */ function bareHost(host: string): boolean { if (host.startsWith("[")) { if (!/^\[[0-9a-f:.]+\]$/i.test(host)) return false; try { return new URL(`http://${host}/`).hostname !== ""; } catch { return false; } } if (host.length > 253) return false; const labels = host.split("."); if (labels.every((label) => /^\d+$/.test(label))) return labels.length === 4 && labels.every((octet) => Number(octet) <= 255); return labels.every((label) => HOST_LABEL.test(label)); } function defaultGateway(input: ResourcePlanInput): { host: string; field: string } | undefined { const platform = input.platform ?? process.platform; if (input.containerHostGateway === null) return undefined; if (input.containerHostGateway !== undefined) { // The rejected value is not echoed: it may carry credentials. if (typeof input.containerHostGateway !== "string" || !bareHost(input.containerHostGateway)) { invalid("containerHostGateway must be a bare hostname, IPv4 address or bracketed IPv6 address without userinfo, scheme, port, path or whitespace."); } if (loopbackHost(input.containerHostGateway)) invalid(`containerHostGateway ${input.containerHostGateway} is a loopback name, which a container resolves to itself.`); return { host: input.containerHostGateway, field: "option:containerHostGateway" }; } return platform === "darwin" || platform === "win32" ? { host: "host.docker.internal", field: `platform:${platform}` } : undefined; } function consumersOf(input: ResourcePlanInput, resource: string): string[] { const { config, plan } = input; return plan.nodes.filter((node) => nodeSpec(config, node)?.resources?.includes(resource)) .map((node) => node.name); } function plannedSecrets(input: ResourcePlanInput, name: string, context: TargetContext | undefined, consumers: readonly string[]): PlannedResource["secrets"] { if (!context) return []; const field = `resources.${name}.targets.${context.targetName}.secrets`; const secrets = Object.entries(context.target.secrets ?? {}).map(([secret, env]) => ({ name: secret, env, field: `${field}.${secret}`, ...(input.environment ? { present: own(input.environment, env) !== undefined } : {}) })); for (const consumer of consumers) { const spec = nodeSpec(input.config, input.plan.nodes.find((node) => node.name === consumer)!); for (const secret of secrets) { if (!spec?.envAllowlist?.includes(secret.env) || !spec.secretEnv?.includes(secret.env)) { invalid(`${consumer} consumes resource ${name}, whose target ${context.targetName} needs secret ${secret.env}; add it to the consumer's envAllowlist and secretEnv.`); } } } return secrets; } /** From the host, any loopback spelling is the loopback port; another host is its canonical name. */ function hostListener(endpoint: Endpoint): string { return loopbackHost(endpoint.host) ? `loopback:${endpoint.port}` : `dns:${canonicalHost(endpoint.host)}:${endpoint.port}`; } /** A selected Compose service's container port, whichever network or name reaches it. */ function containerListener(input: ResourcePlanInput, node: string, port: string | number): string { const spec = own(input.config.services, node)!; return `container:${composeProjectName(spec.projectName ?? "devfn", input.ownerId)}:${spec.service}:${port}`; } /** * Where an endpoint leads from inside one Compose consumer, decided once from * its source and the consumer's own mappings, for listener identity and * endpoint ambiguity: "gateway" for the host's loopback ports, otherwise the * selected services that answer it (reachedServices). The consumer's own * links, external_links and extra_hosts resolve a name ahead of Docker DNS, * so a name it maps has no listener DevFn can establish, except a name mapped * only to Docker's host-gateway address, which is the host gateway. A * selected provider's service name is never the gateway: a consumer mapping * of it, or a gateway name of the same spelling, sends the consumer away from * the provider. An unmapped gateway name that a selected service also answers * is ambiguous. Mapped addresses are never echoed. */ function containerRoute(context: TargetContext, endpoint: Endpoint, source: ResourceValueSource, consumer: string): "gateway" | string[] | undefined { const { input, name, gateway } = context; const host = canonicalHost(endpoint.host); const isGateway = gateway !== undefined && host === canonicalHost(gateway.host); const mapped = own(input.composeNames, consumer)?.overrides.filter((entry) => canonicalHost(entry.name) === host) ?? []; if (source === "compose") { const provider = `${endpoint.host}:${endpoint.port} is the service name of its selected provider ${(context.target as { node: string }).node}`; if (mapped.length) { invalid(`Compose service ${consumer} consumes resource ${name}, whose endpoint ${provider}, which its own links, external_links or extra_hosts map elsewhere; remove that mapping.`); } if (isGateway) { invalid(`Compose service ${consumer} consumes resource ${name}, whose endpoint ${provider}, but that name is also the container host gateway, which may reach the host instead; rename the Compose service.`); } return reachedServices(input, host, consumer); } // The configured gateway name unless mapped elsewhere, or any name mapped only to host-gateway. const toGateway = (isGateway || mapped.length > 0) && mapped.every((entry) => entry.address === "host-gateway"); if (mapped.length && !toGateway) { const reason = isGateway ? "the container host gateway, which its own links, external_links or extra_hosts map to an address other than host-gateway" : "a name its own links, external_links or extra_hosts map"; invalid(`Compose service ${consumer} consumes resource ${name}, whose endpoint ${endpoint.host}:${endpoint.port} is ${reason}; remove that mapping or select a target it does not map.`); } if (!toGateway) return reachedServices(input, host, consumer); // Its extra_hosts entry resolves ahead of Docker DNS, which a selected service would otherwise answer first. const shadowing = mapped.length ? [] : reachedServices(input, host, consumer) ?? []; if (shadowing.length) { invalid(`Compose service ${consumer} consumes resource ${name}, whose endpoint ${endpoint.host}:${endpoint.port} is the container host gateway, but Docker DNS also answers that name with ` + `${shadowing.join(", ")} on the networks ${consumer} joins; rename them or map the gateway to host-gateway in its extra_hosts.`); } return "gateway"; } /** * The listeners an endpoint reaches from inside one Compose consumer. The * host gateway is the host's loopback port. Docker DNS resolves a service * name on every network the consumer joins, whichever project owns the * service, so a name is the container port of each selected service of that * name on the consumer's networks, and a name no selected service has is its * canonical name. Which services a name reaches depends on effective * networks; with provisional networks it is left to a later pass. */ function containerListeners(context: TargetContext, endpoint: Endpoint, source: ResourceValueSource, consumer: string): string[] { const { input } = context; const route = containerRoute(context, endpoint, source, consumer); if (route === "gateway") return [`loopback:${endpoint.port}`]; if (!route) return []; return route.length ? route.map((node) => containerListener(input, node, endpoint.port)) : [`dns:${canonicalHost(endpoint.host)}:${endpoint.port}`]; } /** * The selected Compose services a host name reaches by Docker DNS from inside * one consumer: on a network both join, the service's name, its * container_name or an alias it has on that network. Undefined while networks * are provisional and a selected service has that name. */ function reachedServices(input: ResourcePlanInput, host: string, consumer: string): string[] | undefined { const services = input.plan.nodes.filter((node) => node.kind === "service"); if (input.provisionalNetworks) return services.some((node) => canonicalHost(own(input.config.services, node.name)!.service) === host) ? undefined : []; const joined = new Set(own(input.composeNetworks, consumer) ?? []); const answers = (node: string, network: string) => [own(input.config.services, node)!.service, ...own(own(input.composeNames, node)?.networks, network) ?? []].some((name) => canonicalHost(name) === host); return services.filter((node) => (own(input.composeNetworks, node.name) ?? []).some((network) => joined.has(network) && answers(node.name, network))) .map((node) => node.name); } /** * A consumer's container-side endpoint must name one listener: the selected * Compose provider of a local target, or at most one selected Compose service * for a remote host. Docker DNS answers a name that several reached services * share with any of them, so the consumer could dial a provider it did not * select. Decided on effective networks, before state or leases. */ function rejectAmbiguousContainerEndpoint(context: TargetContext, endpoint: Endpoint, source: ResourceValueSource, consumer: string): void { const { input, name, target } = context; const reached = containerRoute(context, endpoint, source, consumer); if (!reached || reached === "gateway") return; const selected = source === "compose" && "node" in target ? containerListener(input, target.node, endpoint.port) : undefined; const listeners = new Set(reached.map((node) => containerListener(input, node, endpoint.port))); const competing = reached.filter((node) => containerListener(input, node, endpoint.port) !== selected); if (selected ? competing.length === 0 : listeners.size <= 1) return; const reach = selected ? `which selects provider ${(target as { node: string }).node}, but its endpoint ${endpoint.host}:${endpoint.port} also names ${competing.join(", ")}` : `whose endpoint ${endpoint.host}:${endpoint.port} names ${competing.join(", ")}`; invalid(`Compose service ${consumer} consumes resource ${name}, ${reach} on the networks ${consumer} joins, and Docker DNS may answer with any of them; ` + "give those services distinct service names or networks."); } /** * The listeners a selected target reaches in every context that receives its * endpoint values: the host side (native processes, readiness and environment * outputs) always, and each Compose service that consumes it, since only * consumers receive container-side endpoints. Each consumer's endpoint is * resolved as that container resolves it, for local and remote targets alike: * a service name can reach a same-named service of another project on a * shared network. A local provider is also its port, its leased loopback port * and, for a Compose provider, its container port, which every pass knows * whatever networks reach it. */ function targetListeners(context: TargetContext, host: Endpoint, containers: ReadonlyMap): string[] { const { input, target } = context; const reached = [...containers].flatMap(([consumer, { endpoint, source }]) => containerListeners(context, endpoint, source, consumer)); if (!("node" in target)) return [hostListener(host), ...reached]; // Before reservation only a manifest-fixed port names a loopback listener, // whether the host dials it or a consumer reaches it through the gateway. const leased = knownPort(input, target.port) !== undefined; const listeners = [`port:${target.port}`, ...(leased ? [`loopback:${host.port}`] : [])]; const provider = input.plan.nodes.find((node) => node.name === target.node); if (provider?.kind === "service") listeners.push(containerListener(input, target.node, own(own(input.config.services, target.node)!.ports, target.port)!)); return [...listeners, ...reached.filter((listener) => leased || !listener.startsWith("loopback:"))]; } function planTarget(context: TargetContext, prefix: string, consumers: readonly string[]): Pick & { listeners: string[]; path: string } { const { input, name, targetName, target } = context; const selection = selectedResourceTarget(input.config, input.plan.profile, name)!; const targetField = `resources.${name}.targets.${targetName}`; const local = "node" in target ? localEndpoint(context, target) : undefined; const host = local?.host ?? remoteEndpoint(context, (target as { url: string }).url); const values = endpointValues(prefix, host, local ? "lease" : "manifest", local ? `ports.${(target as { port: string }).port}` : `${targetField}.url`); if (local) { values[`${prefix}HOST_ENDPOINT`] = { value: `127.0.0.1:${host.port}`, source: "lease", field: `ports.${local.provider!.port}` }; const producer = own(input.config.services, local.provider!.node); if (producer && local.provider!.kind === "service") { values[`${prefix}INTERNAL_ENDPOINT`] = { value: `${producer.service}:${own(producer.ports, local.provider!.port)}`, source: "compose", field: `services.${local.provider!.node}.ports.${local.provider!.port}` }; } } // Only consumers receive container-side endpoints (serviceValues). // Keyed by manifest service names, which may spell __proto__. const services: PlannedResource["services"] = Object.create(null); const containers = new Map(); for (const node of input.plan.nodes) { if (node.kind !== "service" || !consumers.includes(node.name)) continue; const located = containerEndpoint(context, host, node.name); if ("unreachable" in located) invalid(located.unreachable); rejectAmbiguousContainerEndpoint(context, located.endpoint, located.source, node.name); containers.set(node.name, located); services[node.name] = endpointValues(prefix, located.endpoint, located.source, located.field); } return { target: { name: targetName, location: local ? "local" : "remote", selectedBy: selection.selectedBy, field: selection.selectedBy === "profile" ? `profiles.${input.plan.profile}.resources.${name}` : `resources.${name}.defaultTarget` }, ...(local ? { provider: local.provider } : { remote: { url: endpointUrl(host) } }), values, services, listeners: targetListeners(context, host, containers), path: host.path, }; } /** Whether a node is a transitive dependency of another. */ function startsBefore(plan: LifecyclePlan, node: string, dependent: string): boolean { const seen = new Set(); const pending = [dependent]; while (pending.length) { const current = pending.pop(); for (const dependency of plan.nodes.find((candidate) => candidate.name === current)?.dependencies ?? []) { if (!seen.has(dependency)) { seen.add(dependency); pending.push(dependency); } } } return seen.has(node); } /** * What each selected Compose service receives of a resource, decided in one * place. Namespace values name state, not a listener, and are the same in * every context, so every service receives them. Endpoint values depend on * the receiving container's networks: a consumer receives its planned * container-side endpoint, and other services none, because only consumer * views are checked for collisions. The Compose provider of a selected local * target receives the addresses it advertises, _HOST_ENDPOINT (its published * loopback port as host clients dial it) and _INTERNAL_ENDPOINT (its service * name and container port), without consuming itself. No consumer receives * those: a container cannot dial host loopback, and its own endpoint already * names the provider as it reaches it. */ function serviceValues(input: ResourcePlanInput, name: string, prefix: string, planned: Pick, namespaceKeys: ReadonlySet, consumers: readonly string[]): void { const advertised = new Set([`${prefix}HOST_ENDPOINT`, `${prefix}INTERNAL_ENDPOINT`]); const provider = planned.provider?.kind === "service" ? planned.provider.node : undefined; for (const node of input.plan.nodes) { if (node.kind !== "service") continue; const consumer = consumers.includes(node.name); const view: PlannedResource["services"][string] = {}; for (const [key, value] of Object.entries(planned.values)) { if (namespaceKeys.has(key)) view[key] = value; else if (consumer) { view[key] = Object.hasOwn(planned.services[node.name], key) ? planned.services[node.name][key] : { unreachable: `${key} is an address provider ${planned.provider?.node} advertises; Compose service ${node.name} reaches resource ${name} through ${prefix}ENDPOINT.` }; } else if (node.name === provider) { view[key] = advertised.has(key) ? value : { unreachable: `Compose service ${node.name} provides resource ${name}; it receives ${prefix}INTERNAL_ENDPOINT and ${prefix}HOST_ENDPOINT, and only consumers receive ${key}.` }; } else { // A service the provider starts after cannot consume it without a cycle. const consume = planned.provider && startsBefore(input.plan, node.name, planned.provider.node) ? "" : `add ${name} to services.${node.name}.resources, or `; view[key] = { unreachable: `Compose service ${node.name} does not consume resource ${name}; ${consume}reference ${key} only where a consumer receives it.` }; } } planned.services[node.name] = view; } } function namespacesOverlap(kind: ResourceKind, left: NamespaceValues, right: NamespaceValues): boolean { if (kind === "database") return left.database === right.database && (left.schema === undefined || right.schema === undefined || left.schema === right.schema); if (kind === "broker" || kind === "browser") return left.members.some((member) => right.members.includes(member)); if (left.scope && right.scope) { // Object keys nest by path segment below the target path, so /bucket/a/ // and the prefix b/ of /bucket/a/b/ overlap while /bucket and /bucket2 do not. const [shorter, longer] = left.scope.length <= right.scope.length ? [left.scope, right.scope] : [right.scope, left.scope]; return shorter.every((segment, index) => longer[index] === segment); } return left.prefix.startsWith(right.prefix) || right.prefix.startsWith(left.prefix); } /** * Two selected resources must not mix data in one namespace of the same * listener. Before reservation, a collision that depends on a port DevFn has * not leased yet is unknown; the locked pass detects it and releases the lease. */ function rejectNamespaceCollisions(planned: Record, namespaces: ReadonlyMap, listeners: ReadonlyMap): void { const names = Object.keys(planned).filter((name) => namespaces.has(name)); for (const [index, left] of names.entries()) { for (const right of names.slice(index + 1)) { if (planned[left].kind !== planned[right].kind || !listeners.get(left)!.some((listener) => listeners.get(right)!.includes(listener))) continue; if (namespacesOverlap(planned[left].kind, namespaces.get(left)!, namespaces.get(right)!)) { const namespace = (name: string) => namespaces.get(name)!.scope ? `/${namespaces.get(name)!.scope!.join("/")}/` : namespaces.get(name)!.prefix; const shared = namespace(left) === namespace(right) ? `share namespace ${namespace(left)}` : `share namespaces ${namespace(left)} and ${namespace(right)}, one inside the other,`; invalid(`Resources ${left} and ${right} ${shared} on the same ${planned[left].kind} target; declare distinct namespace bases.`); } } } } function selectedResourceNames(config: DevFnConfig, plan: LifecyclePlan): string[] { const consumed = plan.nodes.flatMap((node) => nodeSpec(config, node)?.resources ?? []); // Code-unit order, as a plain sort() gives: plan order is part of its fingerprint. return [...new Set([...Object.keys(own(config.profiles, plan.profile)?.resources ?? {}), ...consumed])] .sort((left, right) => (left < right ? -1 : Number(left > right))); } /** * Select each resource target the profile uses, derive its namespaces and * endpoint values with provenance, and validate the topology. Pure: no lease, * file, process or service is touched, and no secret value is read. */ export function planResources(input: ResourcePlanInput): ResourcePlan { const config = validateDevFnConfig(input.config); if (!input.ownerId || input.ownerId.includes("\0")) invalid("ownerId must be a non-empty opaque value without NUL."); const context = { ...input, config }; if (input.runtimeId !== undefined && !/^[0-9a-f]{32}$/.test(input.runtimeId)) invalid("runtimeId must be 32 lowercase hexadecimal digits."); const owner = resourceOwner(input.ownerId); const ownerToken = input.runtimeId === undefined ? owner : resourceOwner(`${input.ownerId}\0${input.runtimeId}`); const gateway = defaultGateway(input); const resources: Record = Object.create(null); const namespaces = new Map(); const listeners = new Map(); for (const name of selectedResourceNames(config, input.plan)) { const spec = own(config.resources, name)!; const prefix = `DEVFN_RESOURCE_${resourceToken(name)}_`; const consumers = consumersOf(context, name); const namespace = namespaceValues(name, spec, ownerToken, prefix); const namespaceField = spec.namespace ? `resources.${name}.namespace` : `resources.${name}`; const selection = spec.kind === "browser" ? undefined : selectedResourceTarget(config, input.plan.profile, name); if (spec.kind !== "browser" && !selection) invalid(`Profile ${input.plan.profile} selects no target for resource ${name} and it declares no defaultTarget.`); const targetContext: TargetContext | undefined = selection ? { input: context, name, spec, targetName: selection.name, target: own(spec.targets, selection.name)!, ...(namespace.database !== undefined ? { database: namespace.database } : {}), ...(gateway ? { gateway } : {}) } : undefined; const { listeners: reached, path: targetPath, ...target } = targetContext ? planTarget(targetContext, prefix, consumers) : // Every browser resource names state in the same local browser profile. { values: {} as PlannedResource["values"], services: Object.create(null) as PlannedResource["services"], listeners: ["browser"], path: "" }; listeners.set(name, reached); // An object store's keys live below its target path; the prefix names keys there. if (spec.kind === "object-store") namespace.scope = [...pathSegments(targetPath), ...pathSegments(namespace.prefix)]; for (const [key, value] of Object.entries(namespace.values)) { target.values[key] = { value, source: "namespace", field: key === `${prefix}DATABASE` && spec.namespace?.level === "schema" ? `${namespaceField}.database` : namespaceField }; } const emitted = new Set(resourceEnvironmentKeys(name, spec)); for (const key of Object.keys(target.values)) if (!emitted.has(key)) invalid(`Resource ${name} produced undeclared key ${key}.`); serviceValues(context, name, prefix, target, new Set(Object.keys(namespace.values)), consumers); resources[name] = { kind: spec.kind, ...target, consumers, ...(spec.kind === "service" ? {} : { namespace: { sharing: spec.namespace?.sharing ?? "isolated", prefix: namespace.prefix, field: namespaceField } }), secrets: plannedSecrets(context, name, targetContext, consumers), }; if (spec.kind !== "service") namespaces.set(name, namespace); } rejectNamespaceCollisions(resources, namespaces, listeners); return { profile: input.plan.profile, owner, ownerToken, ...(gateway ? { containerHostGateway: gateway } : {}), resources }; } /** The opaque digest of a lifecycle owner a resource plan records. */ export function resourceOwner(ownerId: string): string { return `o${createHash("sha256").update(ownerId).digest("hex").slice(0, 12)}`; } /** * A credential-free digest of the selected targets, namespaces and values a * lifecycle was started with. Only secret presence (secrets[].present) is * excluded; secret values are never part of a plan. */ export function resourcePlanFingerprint(plan: ResourcePlan | undefined): string | undefined { if (!plan) return undefined; const resources = Object.entries(plan.resources).map(([name, resource]) => [name, { ...resource, secrets: resource.secrets.map(({ present: _present, ...secret }) => secret) }]); return createHash("sha256").update(JSON.stringify({ ...plan, resources })).digest("hex"); } /** Host-side generated values of a plan, for the endpoint resolver. */ export function resourceEnvironment(plan: ResourcePlan | undefined): Record { const environment: Record = Object.create(null); for (const resource of Object.values(plan?.resources ?? {})) { for (const [key, value] of Object.entries(resource.values)) environment[key] = value.value; } return environment; } /** Container-side values of a plan for one Compose service, or the reason a key is unreachable there. */ export function resourceServiceEnvironment(plan: ResourcePlan | undefined, service: string): Map { const environment = new Map(); for (const resource of Object.values(plan?.resources ?? {})) { for (const [key, value] of Object.entries(own(resource.services, service) ?? {})) environment.set(key, "unreachable" in value ? value : { value: value.value }); } return environment; } /** * Whether a selected Compose service provides, consumes or references a * selected resource, so its effective networks are read before any state. */ export function resourcesNeedComposeNetworks(config: DevFnConfig, plan: LifecyclePlan): boolean { if (!config.resources) return false; const services = new Set(plan.nodes.filter((node) => node.kind === "service").map((node) => node.name)); return JSON.stringify(config).includes("{{env.DEVFN_RESOURCE_") || [...services].some((node) => (own(config.services, node)?.resources?.length ?? 0) > 0) || selectedResourceNames(config, plan).some((name) => services.has(localProvider(config, plan.profile, name) ?? "")); }