@go-to-k/cdkd 0.136.0 → 0.137.1

package/dist/cli.js

@@ -65,6 +65,7 @@ import { createServer } from "node:net";
 import { promisify } from "node:util";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import { readFile } from "fs/promises";
+import { WebSocketServer } from "ws";
 import { createServer as createServer$1 } from "node:http";
 import { createServer as createServer$2 } from "node:https";
 import * as chokidar from "chokidar";
@@ -38712,6 +38713,7 @@ async function runDetached(opts) {
 	if (opts.name) args.push("--name", opts.name);
 	if (opts.network) args.push("--network", opts.network);
 	if (opts.platform) args.push("--platform", opts.platform);
+	if (opts.extraHosts) for (const entry of opts.extraHosts) args.push("--add-host", `${entry.host}:${entry.ip}`);
 	const host = opts.host ?? "127.0.0.1";
 	args.push("-p", `${host}:${opts.hostPort}:8080`);
 	if (opts.debugPort !== void 0) args.push("-p", `${host}:${opts.debugPort}:${opts.debugPort}`);
@@ -40361,13 +40363,13 @@ function discoverRestV1Method(logicalId, resource, template, stackName) {
 	const integration = props["Integration"];
 	if (!integration) throw new Error(`${stackName}/${logicalId} (AWS::ApiGateway::Method): missing Integration property`);
 	const restApiId = props["RestApiId"];
-	const restApiLogicalId = pickRefLogicalId$2(restApiId);
+	const restApiLogicalId = pickRefLogicalId$3(restApiId);
 	if (!restApiLogicalId) throw new Error(`${stackName}/${logicalId} (AWS::ApiGateway::Method): RestApiId must be a { Ref: '...' } reference (got ${shortJson$1(restApiId)}).`);
 	const resourceId = props["ResourceId"];
 	const path = buildRestV1Path(resourceId, restApiLogicalId, template, stackName, logicalId);
 	const httpMethod = stringifyValue(props["HttpMethod"] ?? "ANY");
 	const stage = pickRestV1Stage(restApiLogicalId, template);
-	const restApiCdkPath = readApiCdkPath(restApiLogicalId, template);
+	const restApiCdkPath = readApiCdkPath$1(restApiLogicalId, template);
 	const baseRoute = {
 		source: "rest-v1",
 		apiVersion: "v1",
@@ -40721,7 +40723,7 @@ function buildRestV1Path(resourceIdIntrinsic, restApiLogicalId, template, stackN
 			if (Array.isArray(arg) && arg.length === 2 && arg[1] === "RootResourceId") return "/";
 		}
 	}
-	const resourceLogicalId = pickRefLogicalId$2(resourceIdIntrinsic);
+	const resourceLogicalId = pickRefLogicalId$3(resourceIdIntrinsic);
 	if (!resourceLogicalId) throw new Error(`${stackName}/${methodLogicalId}: ResourceId must be { Ref: '...' } or { 'Fn::GetAtt': [..., 'RootResourceId'] } (got ${shortJson$1(resourceIdIntrinsic)}).`);
 	const segments = [];
 	const visited = /* @__PURE__ */ new Set();
@@ -40741,7 +40743,7 @@ function buildRestV1Path(resourceIdIntrinsic, restApiLogicalId, template, stackN
 			const arg = parentId["Fn::GetAtt"];
 			if (Array.isArray(arg) && arg[1] === "RootResourceId") break;
 		}
-		cursor = pickRefLogicalId$2(parentId) ?? void 0;
+		cursor = pickRefLogicalId$3(parentId) ?? void 0;
 	}
 	return "/" + segments.join("/");
 }
@@ -40756,7 +40758,7 @@ function pickRestV1Stage(restApiLogicalId, template) {
 	for (const [, resource] of Object.entries(resources)) {
 		if (resource.Type !== "AWS::ApiGateway::Stage") continue;
 		const props = resource.Properties ?? {};
-		if (pickRefLogicalId$2(props["RestApiId"]) === restApiLogicalId) {
+		if (pickRefLogicalId$3(props["RestApiId"]) === restApiLogicalId) {
 			const stageName = props["StageName"];
 			if (typeof stageName === "string") return stageName;
 		}
@@ -40775,26 +40777,14 @@ function pickRestV1Stage(restApiLogicalId, template) {
 function discoverHttpApiRoute(logicalId, resource, template, stackName) {
 	const props = resource.Properties ?? {};
 	const apiId = props["ApiId"];
-	const apiLogicalId = pickRefLogicalId$2(apiId);
+	const apiLogicalId = pickRefLogicalId$3(apiId);
 	if (!apiLogicalId) throw new Error(`${stackName}/${logicalId} (AWS::ApiGatewayV2::Route): ApiId must be { Ref: '...' } (got ${shortJson$1(apiId)}).`);
 	const routeKey = props["RouteKey"];
 	if (typeof routeKey !== "string" || routeKey.length === 0) throw new Error(`${stackName}/${logicalId} (AWS::ApiGatewayV2::Route): RouteKey must be a string`);
-	const apiCdkPath = readApiCdkPath(apiLogicalId, template);
+	const apiCdkPath = readApiCdkPath$1(apiLogicalId, template);
 	const apiResource = template.Resources?.[apiLogicalId];
 	if (apiResource?.Type === "AWS::ApiGatewayV2::Api") {
-		if ((apiResource.Properties ?? {})["ProtocolType"] === "WEBSOCKET") return [{
-			method: "ANY",
-			pathPattern: routeKey,
-			lambdaLogicalId: "",
-			source: "http-api",
-			apiVersion: "v2",
-			stage: "$default",
-			apiLogicalId,
-			apiStackName: stackName,
-			...apiCdkPath !== void 0 && { apiCdkPath },
-			declaredAt: `${stackName}/${logicalId}`,
-			unsupported: { reason: `${stackName}/${logicalId}: WebSocket APIs are not supported in cdkd local start-api.` }
-		}];
+		if ((apiResource.Properties ?? {})["ProtocolType"] === "WEBSOCKET") return [];
 	}
 	const { method, pathPattern } = parseRouteKey(routeKey);
 	const baseRoute = {
@@ -40896,7 +40886,7 @@ function discoverFunctionUrl(logicalId, resource, template, stackName) {
 	const arnOutcome = resolveLambdaArnOutcome(targetArn);
 	if (arnOutcome.kind === "unsupported") throw new Error(`${stackName}/${logicalId}.TargetFunctionArn: ${arnOutcome.detail} (got ${shortJson$1(targetArn)}).`);
 	const lambdaLogicalId = arnOutcome.logicalId;
-	const lambdaCdkPath = readApiCdkPath(lambdaLogicalId, template);
+	const lambdaCdkPath = readApiCdkPath$1(lambdaLogicalId, template);
 	const baseRoute = {
 		method: "ANY",
 		pathPattern: "/{proxy+}",
@@ -40933,7 +40923,7 @@ function discoverFunctionUrl(logicalId, resource, template, stackName) {
 * metadata isn't set. Hides the "may be missing for a hand-rolled
 * `cfn.Resource`" branch from every call site.
 */
-function readApiCdkPath(logicalId, template) {
+function readApiCdkPath$1(logicalId, template) {
 	const resource = template.Resources?.[logicalId];
 	if (!resource) return void 0;
 	return readCdkPath(resource) || void 0;
@@ -41000,11 +40990,11 @@ function parseHttpApiTargetIntegration(target, location) {
 			const sep = join[0];
 			const parts = join[1];
 			if (sep === "/" && parts.length === 2 && parts[0] === "integrations") {
-				const ref = pickRefLogicalId$2(parts[1]);
+				const ref = pickRefLogicalId$3(parts[1]);
 				if (ref) return ref;
 			}
 			if (sep === "" && parts.length === 2 && parts[0] === "integrations/") {
-				const ref = pickRefLogicalId$2(parts[1]);
+				const ref = pickRefLogicalId$3(parts[1]);
 				if (ref) return ref;
 			}
 		}
@@ -41024,7 +41014,7 @@ function parseHttpApiTargetIntegration(target, location) {
 				if (m) {
 					const bound = bindings[m[1]];
 					if (bound !== void 0) {
-						const ref = pickRefLogicalId$2(bound);
+						const ref = pickRefLogicalId$3(bound);
 						if (ref) return ref;
 					}
 				}
@@ -41053,7 +41043,7 @@ function parseRouteKey(routeKey) {
 * If `value` is a `{ Ref: <string> }` intrinsic, return the referenced
 * logical ID. Otherwise return `null`.
 */
-function pickRefLogicalId$2(value) {
+function pickRefLogicalId$3(value) {
 	if (value && typeof value === "object" && !Array.isArray(value)) {
 		const ref = value["Ref"];
 		if (typeof ref === "string") return ref;
@@ -41073,6 +41063,1017 @@ function shortJson$1(value) {
 	}
 }
 
+//#endregion
+//#region src/local/websocket-route-discovery.ts
+const DEFAULT_ROUTE_SELECTION_EXPRESSION = "$request.body.action";
+const DEFAULT_STAGE = "local";
+/**
+* Walk every synthesized stack and produce one {@link DiscoveredWebSocketApi}
+* per WebSocket API found. Errors per API are aggregated and surfaced
+* as a single {@link RouteDiscoveryError} (matches the HTTP-side
+* discovery behavior — a single malformed API shouldn't abort the
+* server boot for sibling APIs).
+*
+* Resolution chain:
+*   1. Find each `AWS::ApiGatewayV2::Api` with `ProtocolType: WEBSOCKET`.
+*   2. Validate `RouteSelectionExpression` (only `$request.body.<key>`
+*      forms supported in v1).
+*   3. Resolve attached Stage (first Stage referencing this API).
+*   4. Walk every `AWS::ApiGatewayV2::Route` referencing this API,
+*      resolve each route's Target → Integration → IntegrationUri →
+*      Lambda logical ID via the shared `resolveLambdaArnIntrinsic`
+*      helper (handles every CFn intrinsic shape CDK emits).
+*/
+function discoverWebSocketApis(stacks) {
+	const apis = [];
+	const errors = [];
+	for (const stack of stacks) {
+		const template = stack.template;
+		const resources = template.Resources ?? {};
+		for (const [logicalId, resource] of Object.entries(resources)) {
+			if (resource.Type !== "AWS::ApiGatewayV2::Api") continue;
+			if ((resource.Properties ?? {})["ProtocolType"] !== "WEBSOCKET") continue;
+			try {
+				apis.push(discoverOneApi(logicalId, resource, template, stack.stackName));
+			} catch (err) {
+				errors.push(err instanceof Error ? err.message : String(err));
+			}
+		}
+	}
+	return {
+		apis,
+		errors
+	};
+}
+function discoverOneApi(logicalId, resource, template, stackName) {
+	const props = resource.Properties ?? {};
+	const declaredAt = `${stackName}/${logicalId}`;
+	const rawSelection = props["RouteSelectionExpression"];
+	const routeSelectionExpression = typeof rawSelection === "string" && rawSelection.length > 0 ? rawSelection : DEFAULT_ROUTE_SELECTION_EXPRESSION;
+	assertSupportedSelectionExpression(routeSelectionExpression, declaredAt);
+	const stage = pickStage$1(logicalId, template);
+	const apiCdkPath = readApiCdkPath(logicalId, template);
+	const routes = collectRoutesForApi(logicalId, template, stackName);
+	if (routes.length === 0) throw new Error(`${declaredAt}: WebSocket API has no AWS::ApiGatewayV2::Route children — at least one route (typically '$connect') is required to dispatch.`);
+	const authRoutes = collectAuthRoutesForApi(logicalId, template, stackName);
+	const unsupported = authRoutes.length > 0 ? { reason: `WebSocket API requires authorizer support, which cdkd v1 does not emulate. Affected route(s): ${authRoutes.map((r) => `${r.routeKey} [AuthorizationType=${r.authorizationType}]`).join(", ")}. The API will be discovered but no upgrade requests will be accepted on this server.` } : void 0;
+	return {
+		apiLogicalId: logicalId,
+		apiStackName: stackName,
+		declaredAt,
+		...apiCdkPath !== "" && { apiCdkPath },
+		routeSelectionExpression,
+		stage,
+		routes,
+		...unsupported !== void 0 && { unsupported }
+	};
+}
+/**
+* Scan the synthesized template for every `AWS::ApiGatewayV2::Route`
+* referencing the given WebSocket API, returning the subset whose
+* `AuthorizationType` is set to anything other than `NONE` (the
+* AWS-default when omitted). Used by {@link discoverOneApi} to tag
+* the parent API as unsupported when v1's no-authorizer emulation
+* gap would otherwise let unauthenticated clients through.
+*/
+function collectAuthRoutesForApi(apiLogicalId, template, _stackName) {
+	const resources = template.Resources ?? {};
+	const result = [];
+	for (const [, resource] of Object.entries(resources)) {
+		if (resource.Type !== "AWS::ApiGatewayV2::Route") continue;
+		const props = resource.Properties ?? {};
+		if (pickRefLogicalId$2(props["ApiId"]) !== apiLogicalId) continue;
+		const authType = props["AuthorizationType"];
+		if (authType === void 0) continue;
+		const routeKey = props["RouteKey"];
+		const routeKeyForReport = typeof routeKey === "string" ? routeKey : "<unknown>";
+		if (typeof authType !== "string" || authType.length === 0) {
+			result.push({
+				routeKey: routeKeyForReport,
+				authorizationType: "<intrinsic-or-malformed>"
+			});
+			continue;
+		}
+		if (authType === "NONE") continue;
+		result.push({
+			routeKey: routeKeyForReport,
+			authorizationType: authType
+		});
+	}
+	return result;
+}
+/**
+* `$request.body.<key>` is the AWS-canonical shape and the only one
+* v1 supports. Allow nested dot access (`$request.body.action.subKey`)
+* — real CDK chat apps sometimes use this for protocol versioning.
+*
+* Reject array-index access (`$request.body.items[0]`), filter
+* expressions, header / context selections — these would require a
+* fuller JSONPath / VTL evaluator and are out of scope for v1.
+*/
+function assertSupportedSelectionExpression(expr, declaredAt) {
+	if (!/^\$request\.body(?:\.[A-Za-z_][A-Za-z0-9_]*)+$/.test(expr)) throw new Error(`${declaredAt}: RouteSelectionExpression '${expr}' is not supported in cdkd local start-api v1 — only '$request.body.<key>' shapes (optionally nested via dots) are recognized. File a follow-up issue if you need '$request.header.X' / '$context.X' / array-index access.`);
+}
+/**
+* Parse a `$request.body.x.y` selection expression into the JSON-path
+* tokens after `$request.body`. Returns `['x', 'y']` for the example
+* above. Used at message-dispatch time to walk the parsed message body.
+*/
+function parseSelectionExpressionPath(expr) {
+	const m = /^\$request\.body\.(.+)$/.exec(expr);
+	if (!m) return [];
+	return m[1].split(".");
+}
+/**
+* Pick the first `AWS::ApiGatewayV2::Stage` referencing the API. CDK's
+* `apigatewayv2.WebSocketStage` always emits one; the fallback to
+* `'local'` handles hand-rolled templates without a Stage.
+*/
+function pickStage$1(apiLogicalId, template) {
+	const resources = template.Resources ?? {};
+	for (const [, resource] of Object.entries(resources)) {
+		if (resource.Type !== "AWS::ApiGatewayV2::Stage") continue;
+		const props = resource.Properties ?? {};
+		if (pickRefLogicalId$2(props["ApiId"]) === apiLogicalId) {
+			const stageName = props["StageName"];
+			if (typeof stageName === "string" && stageName.length > 0) return stageName;
+		}
+	}
+	return DEFAULT_STAGE;
+}
+/**
+* Walk every `AWS::ApiGatewayV2::Route` and resolve each one whose
+* parent `ApiId` Ref matches the WebSocket API. Per-route failures
+* abort the API's discovery (a partial route map would silently
+* disable some routes — better to fail fast and let the user fix the
+* template).
+*/
+function collectRoutesForApi(apiLogicalId, template, stackName) {
+	const resources = template.Resources ?? {};
+	const result = [];
+	const seenKeys = /* @__PURE__ */ new Set();
+	for (const [routeLogicalId, resource] of Object.entries(resources)) {
+		if (resource.Type !== "AWS::ApiGatewayV2::Route") continue;
+		const props = resource.Properties ?? {};
+		if (pickRefLogicalId$2(props["ApiId"]) !== apiLogicalId) continue;
+		const declaredAt = `${stackName}/${routeLogicalId}`;
+		const routeKey = props["RouteKey"];
+		if (typeof routeKey !== "string" || routeKey.length === 0) throw new Error(`${declaredAt}: RouteKey must be a non-empty string.`);
+		if (seenKeys.has(routeKey)) throw new Error(`${declaredAt}: WebSocket API has duplicate RouteKey '${routeKey}' — each RouteKey may appear at most once per API.`);
+		seenKeys.add(routeKey);
+		const targetLogicalId = parseRouteTarget(props["Target"], declaredAt);
+		const integration = resources[targetLogicalId];
+		if (!integration || integration.Type !== "AWS::ApiGatewayV2::Integration") throw new Error(`${declaredAt}: Target points at '${targetLogicalId}' which is not an AWS::ApiGatewayV2::Integration.`);
+		const integrationProps = integration.Properties ?? {};
+		const integrationType = integrationProps["IntegrationType"];
+		if (integrationType !== "AWS_PROXY") throw new Error(`${declaredAt}: WebSocket route IntegrationType '${String(integrationType)}' is not supported in cdkd local start-api v1 — only AWS_PROXY (Lambda) integrations are emulated.`);
+		const arnOutcome = resolveLambdaArnIntrinsic(integrationProps["IntegrationUri"]);
+		if (arnOutcome.kind === "unsupported") throw new Error(`${stackName}/${targetLogicalId}.IntegrationUri: ${arnOutcome.detail} — WebSocket routes must point at a same-template Lambda.`);
+		result.push({
+			routeKey,
+			targetLambdaLogicalId: arnOutcome.logicalId,
+			lambdaStackName: stackName,
+			declaredAt
+		});
+	}
+	return result;
+}
+/**
+* WebSocket Routes use the same `Target: 'integrations/<id>'` shape as
+* HTTP API v2 Routes. We accept the same five forms documented in
+* `route-discovery.ts:parseHttpApiTargetIntegration` — literal string,
+* two `Fn::Join` shapes, two `Fn::Sub` shapes.
+*
+* Implementation note: we intentionally duplicate the parser rather
+* than reach into `route-discovery.ts` because that module is in flux
+* (`unsupported` / `mockCors` shapes; HTTP-specific). When the two
+* parsers grow apart, the WebSocket one only needs to track the AWS
+* WebSocket-side shape — which has been stable since 2018.
+*/
+function parseRouteTarget(target, location) {
+	if (typeof target === "string") {
+		const m = /^integrations\/(.+)$/.exec(target);
+		if (m) return m[1];
+		throw new Error(`${location}: literal Target '${target}' must start with 'integrations/'.`);
+	}
+	if (target && typeof target === "object" && !Array.isArray(target)) {
+		const obj = target;
+		const join = obj["Fn::Join"];
+		if (Array.isArray(join) && join.length === 2 && Array.isArray(join[1])) {
+			const sep = join[0];
+			const parts = join[1];
+			if (sep === "/" && parts.length === 2 && parts[0] === "integrations") {
+				const ref = pickRefLogicalId$2(parts[1]);
+				if (ref) return ref;
+			}
+			if (sep === "" && parts.length === 2 && parts[0] === "integrations/") {
+				const ref = pickRefLogicalId$2(parts[1]);
+				if (ref) return ref;
+			}
+		}
+		if ("Fn::Sub" in obj) {
+			const sub = obj["Fn::Sub"];
+			const prefix = "integrations/";
+			if (typeof sub === "string") {
+				const m = new RegExp(`^${prefix}\\$\\{([^}]+)\\}$`).exec(sub);
+				if (m) {
+					const placeholder = m[1];
+					if (!placeholder.includes(".")) return placeholder;
+				}
+			}
+			if (Array.isArray(sub) && sub.length === 2 && typeof sub[0] === "string" && sub[1] !== null && typeof sub[1] === "object" && !Array.isArray(sub[1])) {
+				const template = sub[0];
+				const bindings = sub[1];
+				const m = new RegExp(`^${prefix}\\$\\{([^}]+)\\}$`).exec(template);
+				if (m) {
+					const bound = bindings[m[1]];
+					if (bound !== void 0) {
+						const ref = pickRefLogicalId$2(bound);
+						if (ref) return ref;
+					}
+				}
+			}
+		}
+	}
+	throw new Error(`${location}: Target must be 'integrations/<id>' literal, Fn::Join with the documented shapes, or Fn::Sub with an 'integrations/\${...}' template.`);
+}
+function pickRefLogicalId$2(value) {
+	if (value && typeof value === "object" && !Array.isArray(value)) {
+		const ref = value["Ref"];
+		if (typeof ref === "string") return ref;
+	}
+	return null;
+}
+function readApiCdkPath(logicalId, template) {
+	const resource = template.Resources?.[logicalId];
+	if (!resource) return "";
+	return readCdkPath(resource);
+}
+
+//#endregion
+//#region src/local/websocket-event.ts
+const MOCK_DOMAIN_NAME$1 = "localhost";
+const MOCK_API_ID$1 = "local";
+/**
+* Build a request-context block shared across all three event types.
+* `eventType` / `routeKey` are passed in by the per-event caller; the
+* shared block produces fresh `requestId` / `extendedRequestId` per
+* event (matching AWS-deployed behavior — these are NOT stable across
+* events on the same connection).
+*/
+function buildRequestContext(routeKey, eventType, connectionId, connectedAt, stage, snapshot) {
+	const now = Date.now();
+	return {
+		routeKey,
+		eventType,
+		connectionId,
+		extendedRequestId: randomUUID(),
+		requestTime: formatRequestTime$1(now),
+		requestTimeEpoch: now,
+		messageDirection: "IN",
+		stage,
+		connectedAt,
+		requestId: randomUUID(),
+		domainName: MOCK_DOMAIN_NAME$1,
+		apiId: MOCK_API_ID$1,
+		authorizer: null,
+		identity: {
+			sourceIp: snapshot.sourceIp ?? "127.0.0.1",
+			userAgent: snapshot.userAgent ?? ""
+		}
+	};
+}
+/**
+* Build the `$connect` event. AWS WebSocket APIs fire `$connect` ONCE
+* per client connection. Handler returns `{statusCode: 200}` to allow
+* the connection, anything else (or throws) to deny — cdkd matches the
+* deployed behavior by checking the response in the caller.
+*/
+function buildConnectEvent(opts) {
+	const headers = normalizeHeaders(opts.snapshot.headers);
+	const multiValueHeaders = lowercaseMultiValueHeaders(opts.snapshot.headers);
+	return {
+		...headers !== void 0 && { headers },
+		...multiValueHeaders !== void 0 && { multiValueHeaders },
+		queryStringParameters: opts.snapshot.queryStringParameters ?? null,
+		multiValueQueryStringParameters: opts.snapshot.multiValueQueryStringParameters ?? null,
+		requestContext: { ...buildRequestContext("$connect", "CONNECT", opts.connectionId, opts.connectedAt, opts.stage, opts.snapshot) },
+		isBase64Encoded: false,
+		body: ""
+	};
+}
+/**
+* Build a MESSAGE event. Fires for every frame the client sends. The
+* route the API dispatches to is resolved upstream by the route
+* selection-expression layer; the resolved `routeKey` (`$default` or
+* a custom string) lands on `requestContext.routeKey`.
+*/
+function buildMessageEvent(opts) {
+	return {
+		requestContext: {
+			...buildRequestContext(opts.routeKey, "MESSAGE", opts.connectionId, opts.connectedAt, opts.stage, opts.snapshot),
+			messageId: randomUUID()
+		},
+		isBase64Encoded: opts.isBase64Encoded,
+		body: opts.body
+	};
+}
+/**
+* Build the `$disconnect` event. Fires when the WebSocket closes from
+* either side (client / server / abnormal). The Lambda's response is
+* ignored (the socket is already gone); AWS still invokes the handler
+* for cleanup / logging side effects.
+*
+* `disconnectStatusCode` / `disconnectReason` are taken from the
+* WebSocket close frame (RFC 6455 §7.1.5 — close codes such as 1000
+* normal / 1001 going-away / 1008 policy-violation).
+*/
+function buildDisconnectEvent(opts) {
+	return {
+		requestContext: {
+			...buildRequestContext("$disconnect", "DISCONNECT", opts.connectionId, opts.connectedAt, opts.stage, opts.snapshot),
+			...opts.disconnectStatusCode !== void 0 && { disconnectStatusCode: opts.disconnectStatusCode },
+			...opts.disconnectReason !== void 0 && { disconnectReason: opts.disconnectReason }
+		},
+		isBase64Encoded: false,
+		body: ""
+	};
+}
+/**
+* Format a timestamp in the AWS-canonical `dd/MMM/yyyy:HH:mm:ss +0000`
+* shape that AWS API Gateway emits on `requestContext.requestTime`.
+* Always UTC (matches AWS-deployed behavior, which is region-independent).
+*/
+function formatRequestTime$1(epochMs) {
+	const d = new Date(epochMs);
+	return `${String(d.getUTCDate()).padStart(2, "0")}/${[
+		"Jan",
+		"Feb",
+		"Mar",
+		"Apr",
+		"May",
+		"Jun",
+		"Jul",
+		"Aug",
+		"Sep",
+		"Oct",
+		"Nov",
+		"Dec"
+	][d.getUTCMonth()]}/${d.getUTCFullYear()}:${String(d.getUTCHours()).padStart(2, "0")}:${String(d.getUTCMinutes()).padStart(2, "0")}:${String(d.getUTCSeconds()).padStart(2, "0")} +0000`;
+}
+/**
+* Lowercase header keys, comma-join duplicates per AWS spec.
+*/
+function normalizeHeaders(headers) {
+	const out = {};
+	let any = false;
+	for (const [name, values] of Object.entries(headers)) {
+		if (values.length === 0) continue;
+		out[name.toLowerCase()] = values.join(",");
+		any = true;
+	}
+	return any ? out : void 0;
+}
+/**
+* Lowercase header keys, preserve multi-value array shape.
+*/
+function lowercaseMultiValueHeaders(headers) {
+	const out = {};
+	let any = false;
+	for (const [name, values] of Object.entries(headers)) {
+		if (values.length === 0) continue;
+		out[name.toLowerCase()] = [...values];
+		any = true;
+	}
+	return any ? out : void 0;
+}
+
+//#endregion
+//#region src/local/websocket-mgmt-api.ts
+/**
+* `Map<connectionId, ConnectionRegistryEntry>` wrapper with type-safe
+* accessors. Lookups by connectionId stay O(1).
+*/
+var ConnectionRegistry = class {
+	entries = /* @__PURE__ */ new Map();
+	register(entry) {
+		this.entries.set(entry.connectionId, entry);
+	}
+	unregister(connectionId) {
+		const entry = this.entries.get(connectionId);
+		if (entry) this.entries.delete(connectionId);
+		return entry;
+	}
+	get(connectionId) {
+		return this.entries.get(connectionId);
+	}
+	size() {
+		return this.entries.size;
+	}
+	/**
+	* Snapshot the live entries (for diagnostics / shutdown drain).
+	* Returns a fresh array so the caller can iterate without ownership
+	* concerns over the underlying Map.
+	*/
+	list() {
+		return Array.from(this.entries.values());
+	}
+	clear() {
+		this.entries.clear();
+	}
+};
+/**
+* Match the request URL against the `@connections` endpoint family.
+* Returns the parsed connectionId on match, `null` otherwise.
+*
+* AWS reserves `$` / `@` for control planes so the path prefix
+* `/@connections/` can never collide with user-declared routes.
+*
+* Accepted shapes:
+*   - `/@connections/<id>` (AWS-deployed historical form — supported
+*     for backward compatibility with handlers that construct URLs
+*     manually).
+*   - `/<stage>/@connections/<id>` (AWS-docs-canonical form — the
+*     deployed apigatewaymanagementapi endpoint URL is
+*     `https://<api-id>.execute-api.<region>.amazonaws.com/<stage>`,
+*     so SDK-built clients call `POST /<stage>/@connections/<id>`).
+*
+* The optional `<stage>` segment matches AWS's deployed URL exactly —
+* any non-slash sequence preceding `/@connections/`. The stage value
+* itself is intentionally NOT validated against the per-API configured
+* stage name: cdkd is a local-dev tool, not a security boundary, and
+* an aggressive stage check would just trip on misconfigured handlers
+* without adding any real protection.
+*/
+function parseConnectionsPath(url) {
+	const pathOnly = url.split("?", 1)[0];
+	const m = /^\/(?:[^/]+\/)?@connections\/([^/]+)\/?$/.exec(pathOnly);
+	if (!m) return null;
+	const decoded = safeDecodeURIComponent(m[1]);
+	if (decoded === null) return null;
+	return { connectionId: decoded };
+}
+/**
+* Build the per-Lambda env-var URL the cdkd local server injects as
+* `AWS_ENDPOINT_URL_APIGATEWAYMANAGEMENTAPI`. The URL MUST include the
+* `/<stage>` segment to mirror the AWS-deployed apigatewaymanagementapi
+* endpoint `https://<api-id>.execute-api.<region>.amazonaws.com/<stage>`:
+* SDK clients built from `domainName + stage` produce
+* `POST /<stage>/@connections/<id>`, and the local `parseConnectionsPath`
+* regex above requires the matching prefix. Without `/<stage>` the
+* deployed-shape SDK call hits a 404 against the local parser
+* (BLOCKER B1, #526).
+*
+* Lives next to `parseConnectionsPath` so the producer + consumer of
+* the URL shape stay in lockstep — change one, the other's tests fail.
+* Issue #537 item 7.
+*/
+function buildMgmtEndpointEnvUrl(host, port, stage) {
+	return `http://${host}:${port}/${stage}`;
+}
+/**
+* `decodeURIComponent` throws `URIError` on malformed input
+* (`%`-escape with non-hex tail). We treat that as a not-found rather
+* than a server error — symmetric with AWS-deployed behavior, which
+* returns `GoneException` (HTTP 410) for any connection id it can't
+* look up.
+*/
+function safeDecodeURIComponent(s) {
+	try {
+		return decodeURIComponent(s);
+	} catch {
+		return null;
+	}
+}
+/**
+* Read the full request body into a Buffer. Mirrors `node:http`'s
+* `IncomingMessage` consume pattern — collect chunks, resolve on `end`.
+*
+* The body is what the user's handler passed to
+* `apigatewaymanagementapi.PostToConnection({Data: <bytes>})`. AWS docs
+* say the body is raw bytes (treated as opaque by the API plane); we
+* forward the buffer through to `WebSocket.send` so binary frames work
+* end to end.
+*/
+function readRequestBody(req) {
+	return new Promise((resolve, reject) => {
+		const chunks = [];
+		req.on("data", (chunk) => {
+			if (Buffer.isBuffer(chunk)) chunks.push(chunk);
+			else chunks.push(Buffer.from(chunk, "utf-8"));
+		});
+		req.on("end", () => {
+			resolve(Buffer.concat(chunks));
+		});
+		req.on("error", reject);
+	});
+}
+/**
+* Handle a `@connections/<id>` HTTP request. Dispatches by method:
+*   - `POST`   → push the request body to the matching open WebSocket.
+*   - `DELETE` → force-close the WebSocket (1000 normal close).
+*   - `GET`    → return synthetic metadata for the connection.
+*   - anything else → 405.
+*
+* Returns `true` when the request was handled (caller short-circuits),
+* `false` when the URL didn't match (caller continues normal HTTP
+* route dispatch).
+*
+* AWS-correct status codes:
+*   - Connection not in registry → `410 Gone` (matches AWS's
+*     `GoneException` for closed connections).
+*   - Send succeeded → `200 OK` (body empty).
+*   - Send failed (socket not OPEN) → `410 Gone` — the connection has
+*     started closing on the WebSocket side but the registry entry
+*     hasn't been removed yet (the `close` event clean-up is async).
+*
+* NOTE: The body buffer can include arbitrary binary; `ws.send` handles
+* both string and Buffer inputs (the recipient receives the same bytes
+* the sender wrote).
+*/
+async function handleConnectionsRequest(opts) {
+	const { req, res, registry } = opts;
+	const parsed = parseConnectionsPath(req.url ?? "");
+	if (!parsed) {
+		writeJson(res, 404, { message: "Not Found" });
+		return;
+	}
+	const { connectionId } = parsed;
+	const entry = registry.get(connectionId);
+	const method = (req.method ?? "").toUpperCase();
+	if (!entry) {
+		writeJson(res, 410, { message: "GoneException" });
+		return;
+	}
+	if (method === "POST") {
+		let body;
+		try {
+			body = await readRequestBody(req);
+		} catch (err) {
+			writeJson(res, 500, { message: `Failed to read request body: ${err instanceof Error ? err.message : String(err)}` });
+			return;
+		}
+		if (entry.socket.readyState !== entry.socket.OPEN) {
+			writeJson(res, 410, { message: "GoneException" });
+			return;
+		}
+		try {
+			entry.socket.send(body);
+		} catch (err) {
+			writeJson(res, 500, { message: `Failed to deliver to socket: ${err instanceof Error ? err.message : String(err)}` });
+			return;
+		}
+		res.writeHead(200);
+		res.end();
+		return;
+	}
+	if (method === "DELETE") {
+		try {
+			entry.socket.close(1e3, "DeleteConnection");
+		} catch (err) {
+			writeJson(res, 500, { message: `Failed to close socket: ${err instanceof Error ? err.message : String(err)}` });
+			return;
+		}
+		res.writeHead(204);
+		res.end();
+		return;
+	}
+	if (method === "GET") {
+		writeJson(res, 200, {
+			ConnectedAt: new Date(entry.connectedAt).toISOString(),
+			Identity: { SourceIp: "127.0.0.1" },
+			LastActiveAt: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		return;
+	}
+	res.setHeader("Allow", "POST, GET, DELETE");
+	writeJson(res, 405, { message: "MethodNotAllowedException" });
+}
+function writeJson(res, status, body) {
+	const json = JSON.stringify(body);
+	res.writeHead(status, {
+		"Content-Type": "application/json",
+		"Content-Length": Buffer.byteLength(json)
+	});
+	res.end(json);
+}
+
+//#endregion
+//#region src/local/websocket-body.ts
+/**
+* Convert a ws-emitted message buffer into the AWS-canonical event
+* body + `isBase64Encoded` discriminator. Text frames (opcode 0x1) pass
+* through as UTF-8 with `isBase64Encoded: false`; binary frames
+* (opcode 0x2) are base64-encoded with `isBase64Encoded: true`. Matches
+* AWS-deployed WebSocket API event shape exactly — handlers decode via
+* `Buffer.from(event.body, event.isBase64Encoded ? 'base64' : 'utf8')`.
+*
+* Closes the data-integrity bug where every byte > 0x7F on a binary
+* frame was silently corrupted by handlers that trusted the previously
+* hardcoded `isBase64Encoded: false` flag and UTF-8-decoded the
+* base64-encoded body.
+*
+* Lives in its own module so the B4 regression test can install a
+* `vi.fn()` spy that intercepts EVERY call — same-module references in
+* `websocket-server.ts` would bypass the export-binding spy. See
+* Issue #537 item 6.
+*/
+function bufferToBody(raw, isBinary) {
+	const buf = Array.isArray(raw) ? Buffer.concat(raw) : Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
+	if (isBinary) return {
+		body: buf.toString("base64"),
+		isBase64Encoded: true
+	};
+	return {
+		body: buf.toString("utf-8"),
+		isBase64Encoded: false
+	};
+}
+
+//#endregion
+//#region src/local/websocket-server.ts
+/**
+* Wire a WebSocket API into a long-lived `node:http`'s `upgrade`
+* pipeline. The same server already serves HTTP API v2 / REST v1 /
+* Function URL routes via the `request` listener; this module adds a
+* sibling `upgrade` listener that handles WebSocket handshakes.
+*
+* Architecture (mirrors design doc §2 / §8):
+*   - One {@link WebSocketServer} per cdkd local-start-api server.
+*   - `noServer: true` mode — cdkd owns the upgrade-event dispatch.
+*   - Per-connection lifecycle: handshake -> $connect Lambda ->
+*     (allow/deny) -> message loop -> close -> $disconnect Lambda.
+*   - Outbound `@connections/<id>` POST from a handler-side AWS SDK
+*     call routes to the WebSocket via the shared
+*     {@link ConnectionRegistry}.
+*
+* The container pool is the SAME instance the HTTP-side server uses for
+* REST/HTTP API/Function URL routes — WebSocket dispatch is just
+* another consumer; per-Lambda concurrency caps still apply.
+*/
+const DEFAULT_INVOKE_TIMEOUT_MS = 6e4;
+/**
+* Attach a WebSocket server to the parent HTTP listener. Returns an
+* {@link AttachedWebSocketServer} the CLI uses for graceful shutdown +
+* to expose the connection registry to the management-API
+* pre-pass.
+*
+* Implementation:
+*   - One shared {@link ws.WebSocketServer} in `noServer` mode.
+*   - One `upgrade` listener that routes by `req.url`'s pathname; an
+*     unrecognized upgrade target is destroyed (RFC 6455 §4.3.2 —
+*     server SHOULD respond with HTTP 404 or 426).
+*   - Per-connection state held in a {@link ConnectionRegistry} the
+*     `@connections` HTTP handler reads to push messages back.
+*
+* Returns synchronously — the underlying ws server is fully bound by
+* the time this function returns.
+*/
+function attachWebSocketServer(opts) {
+	const logger = getLogger().child("start-api/ws");
+	const rieTimeoutMs = opts.rieTimeoutMs ?? DEFAULT_INVOKE_TIMEOUT_MS;
+	const registry = new ConnectionRegistry();
+	const wss = new WebSocketServer({ noServer: true });
+	const apisByPath = /* @__PURE__ */ new Map();
+	const apiPaths = [];
+	for (const cfg of opts.apis) {
+		apisByPath.set(cfg.apiPath, cfg);
+		apiPaths.push(cfg.apiPath);
+	}
+	const upgradeListener = (req, socket, head) => {
+		const pathOnly = (req.url ?? "/").split("?", 1)[0];
+		const cfg = apisByPath.get(pathOnly);
+		if (!cfg) {
+			socket.write("HTTP/1.1 404 Not Found\r\nConnection: close\r\n\r\n");
+			socket.destroy();
+			return;
+		}
+		wss.handleUpgrade(req, socket, head, (ws) => {
+			onConnect(ws, req, cfg).catch((err) => {
+				logger.error(`WebSocket $connect dispatch failed: ${err instanceof Error ? err.stack ?? err.message : String(err)}`);
+				try {
+					ws.close(1011, "internal error");
+				} catch {}
+			});
+		});
+	};
+	opts.httpServer.on("upgrade", upgradeListener);
+	const MAX_PRE_VERDICT_FRAMES = 100;
+	const onConnect = async (ws, req, cfg) => {
+		const connectionId = randomUUID();
+		const connectedAt = Date.now();
+		const handshakeSnapshot = buildHandshakeSnapshot(req);
+		const connectEvent = buildConnectEvent({
+			connectionId,
+			connectedAt,
+			stage: cfg.api.stage,
+			snapshot: handshakeSnapshot
+		});
+		const preVerdictFrames = [];
+		let preVerdictOverflow = false;
+		let preVerdictClosed = false;
+		const preListener = (raw, isBinary) => {
+			if (preVerdictClosed) return;
+			if (preVerdictFrames.length >= MAX_PRE_VERDICT_FRAMES) {
+				if (!preVerdictOverflow) {
+					preVerdictOverflow = true;
+					logger.warn(`WebSocket connection ${connectionId}: pre-verdict message buffer overflowed (>${MAX_PRE_VERDICT_FRAMES} frames). Excess frames dropped — client is sending faster than the $connect handler can resolve. (api=${cfg.api.declaredAt})`);
+				}
+				return;
+			}
+			preVerdictFrames.push({
+				raw,
+				isBinary
+			});
+		};
+		ws.on("message", preListener);
+		const connectRoute = cfg.api.routes.find((r) => r.routeKey === "$connect");
+		if (connectRoute) {
+			if (!await invokeRouteAndDecideAuth(connectRoute.targetLambdaLogicalId, connectEvent, opts.pool, rieTimeoutMs)) {
+				preVerdictClosed = true;
+				preVerdictFrames.length = 0;
+				ws.off("message", preListener);
+				try {
+					ws.close(1008, "Forbidden");
+				} catch {}
+				logger.debug(`WebSocket $connect denied for connection ${connectionId} on ${cfg.api.declaredAt}`);
+				return;
+			}
+		}
+		preVerdictClosed = true;
+		ws.off("message", preListener);
+		if (ws.readyState !== ws.OPEN) {
+			preVerdictFrames.length = 0;
+			logger.debug(`WebSocket connection ${connectionId} closed during $connect await (readyState=${ws.readyState}) — skipping registration`);
+			return;
+		}
+		const entry = {
+			connectionId,
+			socket: ws,
+			connectedAt,
+			apiLogicalId: cfg.api.apiLogicalId,
+			stage: cfg.api.stage
+		};
+		registry.register(entry);
+		logger.debug(`WebSocket connected: ${connectionId} (${cfg.api.declaredAt}, stage=${cfg.api.stage})`);
+		ws.on("message", (raw, isBinary) => {
+			const { body, isBase64Encoded } = bufferToBody(raw, isBinary);
+			logger.debug(`WebSocket message received for connection ${connectionId}: ${body.slice(0, 200)}`);
+			dispatchMessage(connectionId, cfg, body, isBase64Encoded, handshakeSnapshot).catch((err) => {
+				logger.error(`WebSocket message dispatch failed (connection ${connectionId}): ${err instanceof Error ? err.stack ?? err.message : String(err)}`);
+				try {
+					ws.send(JSON.stringify({
+						message: "Internal server error",
+						connectionId,
+						requestId: randomUUID()
+					}));
+				} catch {}
+			});
+		});
+		ws.on("close", (code, reason) => {
+			onDisconnect(connectionId, cfg, handshakeSnapshot, code, reason.toString("utf-8")).catch((err) => {
+				logger.warn(`WebSocket $disconnect dispatch failed (connection ${connectionId}): ${err instanceof Error ? err.message : String(err)}`);
+			});
+		});
+		ws.on("error", (err) => {
+			logger.debug(`WebSocket error for connection ${connectionId}: ${err instanceof Error ? err.message : String(err)}`);
+		});
+		for (const frame of preVerdictFrames) {
+			const { body, isBase64Encoded } = bufferToBody(frame.raw, frame.isBinary);
+			dispatchMessage(connectionId, cfg, body, isBase64Encoded, handshakeSnapshot).catch((err) => {
+				logger.error(`WebSocket buffered-message dispatch failed (connection ${connectionId}): ${err instanceof Error ? err.stack ?? err.message : String(err)}`);
+			});
+		}
+		preVerdictFrames.length = 0;
+	};
+	const dispatchMessage = async (connectionId, cfg, body, isBase64Encoded, snapshot) => {
+		const entry = registry.get(connectionId);
+		if (!entry) return;
+		const routeKey = selectRouteKey(cfg.api, body);
+		const route = cfg.api.routes.find((r) => r.routeKey === routeKey);
+		if (!route) {
+			try {
+				entry.socket.send(JSON.stringify({
+					message: "Internal server error",
+					connectionId,
+					requestId: randomUUID()
+				}));
+			} catch {}
+			return;
+		}
+		const event = buildMessageEvent({
+			connectionId,
+			connectedAt: entry.connectedAt,
+			stage: entry.stage,
+			snapshot,
+			routeKey,
+			body,
+			isBase64Encoded
+		});
+		await invokeRoute(route.targetLambdaLogicalId, event, opts.pool, rieTimeoutMs);
+	};
+	const onDisconnect = async (connectionId, cfg, snapshot, code, reason) => {
+		const entry = registry.unregister(connectionId);
+		if (!entry) return;
+		logger.debug(`WebSocket disconnected: ${connectionId} (code=${code}, reason=${reason || "<none>"})`);
+		const disconnectRoute = cfg.api.routes.find((r) => r.routeKey === "$disconnect");
+		if (!disconnectRoute) return;
+		const event = buildDisconnectEvent({
+			connectionId,
+			connectedAt: entry.connectedAt,
+			stage: entry.stage,
+			snapshot,
+			disconnectStatusCode: code,
+			disconnectReason: reason
+		});
+		await invokeRoute(disconnectRoute.targetLambdaLogicalId, event, opts.pool, rieTimeoutMs);
+	};
+	let closed = false;
+	return {
+		registry,
+		apiPaths,
+		close: async () => {
+			if (closed) return;
+			closed = true;
+			opts.httpServer.off("upgrade", upgradeListener);
+			const closes = Array.from(wss.clients).map((ws) => new Promise((resolve) => {
+				const onClose = () => resolve();
+				ws.once("close", onClose);
+				try {
+					ws.close(1001, "going away");
+				} catch {
+					resolve();
+				}
+				setTimeout(() => {
+					ws.off("close", onClose);
+					resolve();
+				}, 5e3).unref();
+			}));
+			await Promise.all(closes);
+			await new Promise((resolve) => {
+				wss.close(() => resolve());
+			});
+		}
+	};
+}
+/**
+* Pre-pass for the HTTP `request` listener: intercept `POST/GET/DELETE
+* /@connections/<id>` calls and route them to the connection registry.
+*
+* Returns `true` when the request was handled (caller short-circuits
+* the normal HTTP dispatch path), `false` when the URL didn't match.
+*
+* The CLI installs this BEFORE the existing http-server pipeline so a
+* Lambda inside a container can call
+* `apigatewaymanagementapi:PostToConnection` and have cdkd deliver the
+* message back to the open WebSocket without the request hitting the
+* route table.
+*/
+async function handleManagementRequest(req, res, registry) {
+	if (parseConnectionsPath(req.url ?? "") === null) return false;
+	await handleConnectionsRequest({
+		req,
+		res,
+		registry
+	});
+	return true;
+}
+/**
+* Select the route the client message dispatches to.
+*
+* Algorithm (matches AWS docs §"Selection expressions"):
+*   1. Try to parse the body as JSON. Non-JSON → `$default`.
+*   2. Walk the selection-expression's JSON-path tokens against the
+*      parsed body. Missing intermediate keys → `$default`.
+*   3. The final value's `String()` representation is the route key.
+*   4. When that key has no matching route, fall back to `$default`.
+*
+* v1's selection-expression grammar is `$request.body.<key>` (with
+* optional nested dot access). Other shapes were rejected upstream at
+* discovery time.
+*/
+function selectRouteKey(api, body) {
+	let parsed;
+	try {
+		parsed = JSON.parse(body);
+	} catch {
+		return "$default";
+	}
+	const tokens = parseSelectionExpressionPath(api.routeSelectionExpression);
+	let cursor = parsed;
+	for (const token of tokens) {
+		if (cursor === null || typeof cursor !== "object") return "$default";
+		cursor = cursor[token];
+		if (cursor === void 0) return "$default";
+	}
+	const candidate = String(cursor);
+	if (api.routes.some((r) => r.routeKey === candidate)) return candidate;
+	return "$default";
+}
+/**
+* Invoke a route's Lambda for side effects only (MESSAGE / DISCONNECT
+* paths). The Lambda's response is intentionally discarded — AWS-deployed
+* WebSocket APIs do the same; handlers reply via `PostToConnection`.
+*/
+async function invokeRoute(lambdaLogicalId, event, pool, rieTimeoutMs) {
+	const handle = await pool.acquire(lambdaLogicalId);
+	try {
+		await invokeRie(handle.containerHost, handle.hostPort, event, rieTimeoutMs);
+	} finally {
+		pool.release(handle);
+	}
+}
+/**
+* Invoke the `$connect` Lambda and decide whether to accept the
+* connection. AWS-deployed behavior: handler returns `{statusCode:
+* 200}` (or any 2xx) → allow; anything else (non-2xx, error envelope,
+* throw, timeout) → deny.
+*/
+async function invokeRouteAndDecideAuth(lambdaLogicalId, event, pool, rieTimeoutMs) {
+	let result;
+	try {
+		const handle = await pool.acquire(lambdaLogicalId);
+		try {
+			result = await invokeRie(handle.containerHost, handle.hostPort, event, rieTimeoutMs);
+		} finally {
+			pool.release(handle);
+		}
+	} catch {
+		return false;
+	}
+	if (result.payload && typeof result.payload === "object") {
+		const obj = result.payload;
+		if (typeof obj["errorMessage"] === "string" && typeof obj["statusCode"] !== "number") return false;
+		const status = obj["statusCode"];
+		if (typeof status === "number") return status >= 200 && status < 300;
+	}
+	return true;
+}
+/**
+* Snapshot the upgrade-request data the event-builders need. We capture
+* this ONCE at `$connect` and reuse it for every event on the same
+* connection — `requestContext.identity.sourceIp` etc. must stay
+* consistent across CONNECT / MESSAGE / DISCONNECT (matches AWS).
+*/
+function buildHandshakeSnapshot(req) {
+	const headers = {};
+	for (const [name, value] of Object.entries(req.headers)) {
+		if (value === void 0) continue;
+		headers[name] = Array.isArray(value) ? [...value] : [value];
+	}
+	const url = req.url ?? "/";
+	const queryIdx = url.indexOf("?");
+	const rawQueryString = queryIdx >= 0 ? url.slice(queryIdx + 1) : "";
+	const { single, multi } = parseQueryString(rawQueryString);
+	const userAgent = typeof req.headers["user-agent"] === "string" ? req.headers["user-agent"] : void 0;
+	const sourceIp = req.socket.remoteAddress;
+	return {
+		headers,
+		rawQueryString,
+		...Object.keys(single).length > 0 && { queryStringParameters: single },
+		...Object.keys(multi).length > 0 && { multiValueQueryStringParameters: multi },
+		...sourceIp !== void 0 && { sourceIp },
+		...userAgent !== void 0 && { userAgent }
+	};
+}
+/**
+* Parse a raw query string into single-value (last-wins per AWS) and
+* multi-value maps. Mirrors `route-discovery.ts:parseQueryStringSingular`'s
+* convention — duplicated locally rather than reaching across modules
+* because the WebSocket path is a thin slice that does not need the
+* full HTTP-API parser.
+*/
+function parseQueryString(qs) {
+	const single = {};
+	const multi = {};
+	if (qs.length === 0) return {
+		single,
+		multi
+	};
+	for (const pair of qs.split("&")) {
+		if (pair.length === 0) continue;
+		const eq = pair.indexOf("=");
+		const rawKey = eq >= 0 ? pair.slice(0, eq) : pair;
+		const rawVal = eq >= 0 ? pair.slice(eq + 1) : "";
+		const key = safeDecode$1(rawKey);
+		const val = safeDecode$1(rawVal);
+		if (key === null) continue;
+		single[key] = val ?? "";
+		(multi[key] ??= []).push(val ?? "");
+	}
+	return {
+		single,
+		multi
+	};
+}
+function safeDecode$1(s) {
+	try {
+		return decodeURIComponent(s.replace(/\+/g, " "));
+	} catch {
+		return null;
+	}
+}
+
 //#endregion
 //#region src/local/vtl-engine.ts
 /** Error thrown when a template references an unsupported VTL feature. */
@@ -42610,7 +43611,8 @@ function createContainerPool(specs, options) {
 				host: spec.containerHost,
 				name,
 				...spec.debugPort !== void 0 && { debugPort: spec.debugPort },
-				...spec.tmpfs !== void 0 && { tmpfs: spec.tmpfs }
+				...spec.tmpfs !== void 0 && { tmpfs: spec.tmpfs },
+				...spec.extraHosts !== void 0 && { extraHosts: spec.extraHosts }
 			});
 		} else containerId = await runDetached({
 			image: spec.image,
@@ -42624,7 +43626,8 @@ function createContainerPool(specs, options) {
 			...spec.entryPoint !== void 0 && { entryPoint: spec.entryPoint },
 			...spec.workingDir !== void 0 && { workingDir: spec.workingDir },
 			...spec.debugPort !== void 0 && { debugPort: spec.debugPort },
-			...spec.tmpfs !== void 0 && { tmpfs: spec.tmpfs }
+			...spec.tmpfs !== void 0 && { tmpfs: spec.tmpfs },
+			...spec.extraHosts !== void 0 && { extraHosts: spec.extraHosts }
 		});
 		const stopLogStream = streamingEnabled ? streamLogs(containerId) : () => void 0;
 		try {
@@ -45480,6 +46483,13 @@ async function startApiServer(opts) {
 */
 async function handleRequest(req, res, state, opts) {
 	const logger = getLogger().child("start-api");
+	if (opts.preDispatch) try {
+		if (await opts.preDispatch(req, res)) return;
+	} catch (err) {
+		logger.error(`preDispatch hook threw: ${err instanceof Error ? err.stack ?? err.message : String(err)}`);
+		if (!res.headersSent) writeError(res, 502);
+		return;
+	}
 	const bodyBuf = await readBody(req);
 	const rawUrl = req.url ?? "/";
 	const method = (req.method ?? "GET").toUpperCase();
@@ -46873,7 +47883,10 @@ async function localStartApiCommand(target, options) {
 		const targetStacks = pickTargetStacks(stacks, options.stack);
 		if (targetStacks.length === 0) throw new Error("No stacks matched. Pass --stack <name> or run from a single-stack app.");
 		const routes = discoverRoutes(targetStacks);
-		if (routes.length === 0) throw new Error("No supported API routes were discovered. cdkd local start-api supports AWS::ApiGateway::* (REST v1), AWS::ApiGatewayV2::* (HTTP), and AWS::Lambda::Url (Function URL) with AWS_PROXY integrations only.");
+		const wsDiscovery = discoverWebSocketApis(targetStacks);
+		if (wsDiscovery.errors.length > 0) for (const e of wsDiscovery.errors) logger.warn(`WebSocket discovery: ${e}`);
+		const webSocketApis = wsDiscovery.apis;
+		if (routes.length === 0 && webSocketApis.length === 0) throw new Error("No supported API routes were discovered. cdkd local start-api supports AWS::ApiGateway::* (REST v1), AWS::ApiGatewayV2::* (HTTP + WebSocket), and AWS::Lambda::Url (Function URL) with AWS_PROXY integrations only.");
 		const stageMap = /* @__PURE__ */ new Map();
 		for (const stack of targetStacks) {
 			const m = buildStageMap(stack.template, options.stage);
@@ -46904,7 +47917,7 @@ async function localStartApiCommand(target, options) {
 			for (const [k, v] of m) corsConfigByApiId.set(k, v);
 		}
 		const stateByStack = options.fromState ? await loadStateForRoutedStacks(targetStacks, routes, routesWithAuth, options) : /* @__PURE__ */ new Map();
-		const lambdaIds = uniqueLambdaIds(routes, routesWithAuth);
+		const lambdaIds = uniqueLambdaIds(routes, routesWithAuth, webSocketApis);
 		const specs = /* @__PURE__ */ new Map();
 		for (let i = 0; i < lambdaIds.length; i++) {
 			const logicalId = lambdaIds[i];
@@ -46931,6 +47944,7 @@ async function localStartApiCommand(target, options) {
 			routes: routesWithAuth,
 			specs,
 			corsConfigByApiId,
+			webSocketApis,
 			stacks: targetStacks
 		};
 	};
@@ -47024,12 +48038,88 @@ async function localStartApiCommand(target, options) {
 		});
 		if (basePort !== 0) nextPort += 1;
 	}
+	const wsServers = [];
+	const initialWsApis = initialMaterial.webSocketApis ?? [];
+	warnUnsupportedWebSocketApis(initialWsApis, logger);
+	for (const api of initialWsApis) {
+		if (api.unsupported) continue;
+		const wsLambdaIds = new Set(api.routes.map((r) => r.targetLambdaLogicalId));
+		const wsSpecs = /* @__PURE__ */ new Map();
+		for (const id of wsLambdaIds) {
+			const spec = initialMaterial.specs.get(id);
+			if (spec) wsSpecs.set(id, spec);
+		}
+		if (wsSpecs.size === 0) {
+			logger.warn(`WebSocket API ${api.declaredAt}: no resolvable Lambda backing routes; skipping.`);
+			continue;
+		}
+		const wsPool = buildPool(wsSpecs);
+		const wsState = {
+			routes: [],
+			pool: wsPool,
+			corsConfigByApiId: /* @__PURE__ */ new Map()
+		};
+		const wsApiPath = `/${api.stage}`;
+		let registryRef;
+		const started = await startApiServer({
+			state: wsState,
+			rieTimeoutMs,
+			host: options.host,
+			port: basePort === 0 ? 0 : nextPort,
+			authorizerCache,
+			jwksCache,
+			jwksWarnedUrls,
+			sigV4WarnedForeignIds,
+			sigV4AllowUnverified: options.allowUnverifiedSigv4 === true,
+			preDispatch: async (req, res) => {
+				if (!registryRef) return false;
+				return handleManagementRequest(req, res, registryRef.registry);
+			}
+		});
+		const attached = attachWebSocketServer({
+			httpServer: started.server,
+			pool: wsPool,
+			rieTimeoutMs,
+			apis: [{
+				api,
+				apiPath: wsApiPath
+			}]
+		});
+		registryRef = attached;
+		const mgmtEndpoint = buildMgmtEndpointEnvUrl("host.docker.internal", started.port, api.stage);
+		const hostGatewayMapping = [{
+			host: "host.docker.internal",
+			ip: "host-gateway"
+		}];
+		for (const id of wsLambdaIds) {
+			const spec = initialMaterial.specs.get(id);
+			if (!spec) continue;
+			spec.env["AWS_ENDPOINT_URL_APIGATEWAYMANAGEMENTAPI"] = mgmtEndpoint;
+			if (!spec.env["AWS_ACCESS_KEY_ID"]) {
+				spec.env["AWS_ACCESS_KEY_ID"] = "AKIAIOSFODNN7EXAMPLE";
+				spec.env["AWS_SECRET_ACCESS_KEY"] = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY";
+			}
+			if (!spec.env["AWS_REGION"]) spec.env["AWS_REGION"] = options.region ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"] ?? "us-east-1";
+			spec.extraHosts = [...spec.extraHosts ?? [], ...hostGatewayMapping];
+		}
+		wsServers.push({
+			api,
+			server: started,
+			attached,
+			apiPath: wsApiPath
+		});
+		if (basePort !== 0) nextPort += 1;
+	}
 	printPerServerRouteTables(servers);
 	const allRoutes = servers.flatMap((s) => s.group.routes.map((r) => r.route));
 	warnUnsupportedRoutes(allRoutes, logger);
 	warnSsrfRiskyIntegrations(allRoutes, logger);
 	logger.info(`Per-Lambda concurrency: ${perLambdaConcurrency} (override with --per-lambda-concurrency)`);
 	for (const { group, server } of servers) process.stdout.write(`Server listening on ${server.scheme}://${server.host}:${server.port}  (${group.displayName})\n`);
+	for (const ws of wsServers) {
+		const scheme = ws.server.scheme === "https" ? "wss" : "ws";
+		process.stdout.write(`Server listening on ${scheme}://${ws.server.host}:${ws.server.port}${ws.apiPath}  (${ws.api.apiLogicalId} (WebSocket API))\n`);
+	}
 	process.stdout.write("^C to stop and clean up containers.\n");
 	let watcher;
 	let reloadChain = Promise.resolve();
@@ -47063,6 +48153,13 @@ async function localStartApiCommand(target, options) {
 		} catch (err) {
 			logger.warn(`watcher.close() failed: ${err instanceof Error ? err.message : String(err)}`);
 		}
+		await Promise.allSettled(wsServers.map(async (ws) => {
+			try {
+				await ws.attached.close();
+			} catch (err) {
+				logger.warn(`WebSocket close() failed for ${ws.api.apiLogicalId}: ${err instanceof Error ? err.message : String(err)}`);
+			}
+		}));
 		await Promise.allSettled(servers.map(async ({ server, group }) => {
 			try {
 				await server.close();
@@ -47070,6 +48167,13 @@ async function localStartApiCommand(target, options) {
 				logger.warn(`server.close() failed for ${group.displayName}: ${err instanceof Error ? err.message : String(err)}`);
 			}
 		}));
+		await Promise.allSettled(wsServers.map(async (ws) => {
+			try {
+				await ws.server.close();
+			} catch (err) {
+				logger.warn(`WebSocket server.close() failed for ${ws.api.apiLogicalId}: ${err instanceof Error ? err.message : String(err)}`);
+			}
+		}));
 		await Promise.allSettled(servers.map(async ({ server, group }) => {
 			try {
 				await server.getServerState().pool.dispose();
@@ -47077,6 +48181,13 @@ async function localStartApiCommand(target, options) {
 				logger.warn(`pool.dispose() failed for ${group.displayName}: ${err instanceof Error ? err.message : String(err)}`);
 			}
 		}));
+		await Promise.allSettled(wsServers.map(async (ws) => {
+			try {
+				await ws.server.getServerState().pool.dispose();
+			} catch (err) {
+				logger.warn(`WebSocket pool.dispose() failed for ${ws.api.apiLogicalId}: ${err instanceof Error ? err.message : String(err)}`);
+			}
+		}));
 		for (const dir of inlineTmpDirs) try {
 			rmSync(dir, {
 				recursive: true,
@@ -47143,7 +48254,7 @@ function pickTargetStacks(stacks, pattern) {
 * list, then any newly-introduced authorizer Lambdas, which keeps the
 * route-table output deterministic.
 */
-function uniqueLambdaIds(routes, routesWithAuth) {
+function uniqueLambdaIds(routes, routesWithAuth, webSocketApis = []) {
 	const seen = /* @__PURE__ */ new Set();
 	const out = [];
 	for (const r of routes) {
@@ -47165,6 +48276,10 @@ function uniqueLambdaIds(routes, routesWithAuth) {
 			}
 		}
 	}
+	for (const api of webSocketApis) for (const r of api.routes) if (!seen.has(r.targetLambdaLogicalId)) {
+		seen.add(r.targetLambdaLogicalId);
+		out.push(r.targetLambdaLogicalId);
+	}
 	return out;
 }
 /**
@@ -47728,6 +48843,24 @@ function warnUnsupportedRoutes(routes, logger) {
 	return unsupported.length;
 }
 /**
+* Surface every WebSocket API tagged as unsupported at discovery as a
+* startup warn. The boot loop above skips attaching the server for
+* these APIs, so no upgrade requests are ever accepted on them —
+* mirrors `warnUnsupportedRoutes`'s shape but for the WebSocket axis.
+* Typical trigger: a Route declaring `AuthorizationType !== 'NONE'` on
+* `$connect` (cdkd v1 does not emulate WebSocket authorizers; closing
+* this gap structurally rather than silently admitting
+* unauthenticated clients matches the security-by-default precedent
+* PR #514 set for HTTP API v2 service integrations).
+*/
+function warnUnsupportedWebSocketApis(apis, logger) {
+	const unsupported = apis.filter((api) => api.unsupported);
+	if (unsupported.length === 0) return 0;
+	logger.warn(`${unsupported.length} WebSocket API(s) will NOT accept upgrade requests (boot continued):`);
+	for (const api of unsupported) logger.warn(`  - ${api.declaredAt}: ${api.unsupported.reason}`);
+	return unsupported.length;
+}
+/**
 * Surface a one-line warn per HTTP / HTTP_PROXY integration whose
 * `Integration.Uri` points at a well-known internal address space
 * (AWS IMDS, loopback, link-local, RFC1918). PR #505 / issue #457
@@ -52882,7 +54015,7 @@ function reorderArgs(argv) {
 */
 async function main() {
 	const program = new Command();
-	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.136.0");
+	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.137.1");
 	program.addCommand(createBootstrapCommand());
 	program.addCommand(createSynthCommand());
 	program.addCommand(createListCommand());