@znight/websocket 0.0.0 → 0.6.1

package/dist/compiler.mjs

@@ -0,0 +1,864 @@
+import { readRouteMeta, requiredRouteGroups } from "@znight/http/compiler";
+import { checkRoutePath, normalizePath, parseRoutePath } from "@znight/http/path";
+// src/compiler/constants.ts
+/** Name of the extension, also the key of `metadata.extensions.websocket`. */
+const EXTENSION_NAME = "websocket";
+/** Module the generated code imports its helpers and types from. */
+const RUNTIME_MODULE = "@znight/websocket";
+/** Canonical identities of the decorators owned by the extension. */
+const WsDecorator = Object.freeze({
+	Gateway: "@znight/websocket#Gateway",
+	OnConnect: "@znight/websocket#OnConnect",
+	OnMessage: "@znight/websocket#OnMessage",
+	OnDisconnect: "@znight/websocket#OnDisconnect",
+	Payload: "@znight/websocket#Payload",
+	Conn: "@znight/websocket#Conn",
+	Ctx: "@znight/websocket#Ctx",
+	UseHandshakeGuard: "@znight/websocket#UseHandshakeGuard",
+	UseMessageGuard: "@znight/websocket#UseMessageGuard"
+});
+/** Decorators giving a method a role. */
+const ROLE_DECORATORS = /* @__PURE__ */ new Set([
+	WsDecorator.OnConnect,
+	WsDecorator.OnMessage,
+	WsDecorator.OnDisconnect
+]);
+/** Decorators applied to methods (roles and message guards). */
+const METHOD_DECORATORS = /* @__PURE__ */ new Set([...ROLE_DECORATORS, WsDecorator.UseMessageGuard]);
+/** Decorators applied to handler parameters. */
+const PARAMETER_DECORATORS = /* @__PURE__ */ new Set([
+	WsDecorator.Payload,
+	WsDecorator.Conn,
+	WsDecorator.Ctx
+]);
+/** ZNIGHT005: invalid decorator usage. */
+const INVALID_DECORATOR = "ZNIGHT005";
+/** ZNIGHT007: invalid or conflicting gateway path. */
+const INVALID_ROUTE = "ZNIGHT007";
+/** ZNIGHT017: non-primitive `@Payload()` without schema. */
+const UNVALIDATED_INPUT = "ZNIGHT017";
+/** ZNIGHT023: a gateway without a decision of a required route decorator group (RFC 0001). */
+const MISSING_ROUTE_DECISION = "ZNIGHT023";
+/** ZNIGHT050: invalid gateway. */
+const INVALID_GATEWAY = "ZNIGHT050";
+/** Event names of the `events` protocol (the runtime `EVENT_NAME`, checked by the tests). */
+const EVENT_NAME = /^[A-Za-z][\w.:/-]{0,127}$/;
+/** RFC 7230 token: subprotocol names. */
+const SUBPROTOCOL = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+/** Deterministic string comparison (never `localeCompare`). */
+function compareStrings(a, b) {
+	if (a === b) return 0;
+	return a < b ? -1 : 1;
+}
+const UNITS = {
+	b: 1,
+	k: 1024,
+	kb: 1024,
+	kib: 1024,
+	m: 1024 ** 2,
+	mb: 1024 ** 2,
+	mib: 1024 ** 2,
+	g: 1024 ** 3,
+	gb: 1024 ** 3,
+	gib: 1024 ** 3
+};
+const SIZE = /^(\d+(?:\.\d+)?|\.\d+)\s*([a-z]*)$/i;
+/** A positive byte size (`'64kb'`, `65536`), the grammar of `ByteSize`; `undefined` otherwise. */
+function parseSize(value) {
+	if (typeof value === "number") return Number.isSafeInteger(value) && value > 0 ? value : void 0;
+	if (typeof value !== "string") return void 0;
+	const match = SIZE.exec(value.trim());
+	if (match === null) return void 0;
+	const unit = match[2].toLowerCase();
+	const multiplier = unit === "" ? 1 : UNITS[unit];
+	if (multiplier === void 0) return void 0;
+	const bytes = Math.floor(Number(match[1]) * multiplier);
+	return Number.isSafeInteger(bytes) && bytes > 0 ? bytes : void 0;
+}
+// src/compiler/analyze.ts
+/** Types a `@Payload()` without schema may have (RFC 0003 §5.5). */
+const BINARY_TYPES = /* @__PURE__ */ new Set([
+	"globalThis#Uint8Array",
+	"globalThis#ArrayBuffer",
+	"globalThis#Buffer",
+	"node:buffer#Buffer",
+	"buffer#Buffer"
+]);
+const OPTION_KEYS = /* @__PURE__ */ new Set([
+	"path",
+	"scope",
+	"protocol",
+	"protocols",
+	"maxPayload",
+	"concurrency",
+	"rateLimit",
+	"backpressure"
+]);
+/** Maximum depth of the base class chain walked for inherited handlers. */
+const MAX_CHAIN = 32;
+/** Analyses a class carrying at least one decorator of the extension. */
+function analyzeWebSocketClass(cls, ctx) {
+	const gateways = cls.decorators.filter((decorator) => decorator.identity === WsDecorator.Gateway);
+	const gateway = gateways[0];
+	if (gateway === void 0) {
+		analyzeMembers(cls, ctx);
+		const decorators = [...cls.decorators.filter(isOwnClassDecorator), ...cls.methods.flatMap((method) => method.decorators.filter(isOwnMethodDecorator))].map((decorator) => ({
+			name: decorator.name,
+			location: decorator.location
+		}));
+		if (decorators.length > 0) ctx.store({
+			kind: "members",
+			identity: cls.identity,
+			displayName: cls.displayName,
+			abstract: cls.abstract,
+			decorators
+		});
+		return;
+	}
+	for (const duplicate of gateways.slice(1)) report(ctx, INVALID_DECORATOR, duplicate.location, `@Gateway is applied several times on ${cls.displayName}`, ["Keep a single @Gateway: a class serves one path"]);
+	const read = readGatewayOptions(gateway, cls, ctx);
+	const token = ctx.registerProvider(cls, { scope: read.scope });
+	const chain = classChain(cls, ctx);
+	const merged = /* @__PURE__ */ new Map();
+	for (let index = chain.length - 1; index >= 0; index--) {
+		const owner = chain[index];
+		for (const [name, member] of analyzeMembers(owner, ctx, index === 0 ? void 0 : cls)) merged.set(name, member);
+	}
+	const members = [...merged.values()];
+	const handlers = members.flatMap((member) => member.handlers);
+	const onConnect = single(ctx, cls, members, "onConnect", "@OnConnect");
+	const onDisconnect = single(ctx, cls, members, "onDisconnect", "@OnDisconnect");
+	checkHandlers(cls, read.options.protocol, handlers, ctx);
+	if (!members.some((member) => member.role)) report(ctx, INVALID_GATEWAY, gateway.location, `@Gateway ${cls.displayName} has no handler`, ["Decorate a public method with @OnMessage(\"event\"), @OnConnect() or @OnDisconnect()"], "warning");
+	ctx.store({
+		kind: "gateway",
+		token,
+		identity: cls.identity,
+		displayName: cls.displayName,
+		path: read.path,
+		options: read.options,
+		meta: readRouteMeta(ctx, cls),
+		handshakeGuards: guardRefs(ctx, cls, cls.decorators, WsDecorator.UseHandshakeGuard),
+		messageGuards: guardRefs(ctx, cls, cls.decorators, WsDecorator.UseMessageGuard),
+		onConnect,
+		onDisconnect,
+		handlers,
+		chain: chain.map((owner) => owner.identity),
+		location: gateway.location
+	});
+}
+function isOwnClassDecorator(decorator) {
+	return decorator.identity === WsDecorator.UseHandshakeGuard || decorator.identity === WsDecorator.UseMessageGuard;
+}
+function isOwnMethodDecorator(decorator) {
+	return decorator.identity !== void 0 && METHOD_DECORATORS.has(decorator.identity);
+}
+function report(ctx, code, location, message, hints, severity = "error", related) {
+	ctx.report({
+		code,
+		severity,
+		message,
+		location,
+		...hints === void 0 ? {} : { hints },
+		...related === void 0 ? {} : { related }
+	});
+}
+function isRecord(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+function describe(value) {
+	if (value === void 0) return "undefined";
+	if (value === null) return "null";
+	if (typeof value === "string") return JSON.stringify(value);
+	if (typeof value !== "object") return String(value);
+	if (Array.isArray(value)) return "an array";
+	return isRecord(value) ? "an object" : "a reference";
+}
+function isPositiveInteger(value) {
+	return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+/** `@Gateway()`, `@Gateway('/chat')` or `@Gateway({ path, scope, protocol, ... })`. */
+function readGatewayOptions(decorator, cls, ctx) {
+	const prefix = `@Gateway ${cls.displayName}`;
+	const fallback = {
+		path: void 0,
+		scope: "singleton",
+		options: { protocol: "events" }
+	};
+	const arg = decorator.args[0];
+	if (!decorator.called) return fallback;
+	if (arg === void 0) return {
+		...fallback,
+		path: "/"
+	};
+	if (!arg.evaluated) return fallback;
+	const value = arg.value;
+	if (typeof value === "string") return {
+		...fallback,
+		path: checkPath(ctx, prefix, value, arg.location)
+	};
+	if (value === void 0) return {
+		...fallback,
+		path: "/"
+	};
+	if (!isRecord(value)) {
+		report(ctx, INVALID_DECORATOR, arg.location, `${prefix}: expected a path or an options object, got ${describe(value)}`, ["Write @Gateway('/chat') or @Gateway({ path: '/chat', protocol: 'raw' })"]);
+		return fallback;
+	}
+	const fail = (message, hints) => {
+		report(ctx, INVALID_GATEWAY, arg.location, `${prefix}: ${message}`, hints);
+	};
+	for (const key of Object.keys(value)) if (!OPTION_KEYS.has(key)) fail(`unknown option "${key}"`, [`Known options: ${[...OPTION_KEYS].join(", ")}`]);
+	let path = "/";
+	const rawPath = value["path"];
+	if (rawPath !== void 0) {
+		if (typeof rawPath === "string") path = checkPath(ctx, prefix, rawPath, arg.location);
+		else {
+			fail(`"path" must be a string, got ${describe(rawPath)}`);
+			path = void 0;
+		}
+	}
+	let scope = "singleton";
+	const rawScope = value["scope"];
+	if (rawScope === "request") scope = "request";
+	else if (rawScope === "transient") fail("a gateway cannot be 'transient'", ["Use scope: 'request' for one instance per connection, or the default singleton"]);
+	else if (rawScope !== void 0 && rawScope !== "singleton") fail(`"scope" must be 'singleton' or 'request', got ${describe(rawScope)}`);
+	let protocol = "events";
+	const rawProtocol = value["protocol"];
+	if (rawProtocol === "raw") protocol = "raw";
+	else if (rawProtocol !== void 0 && rawProtocol !== "events") fail(`"protocol" must be 'events' or 'raw', got ${describe(rawProtocol)}`);
+	const options = { protocol };
+	const protocols = value["protocols"];
+	if (protocols !== void 0) {
+		if (!Array.isArray(protocols) || protocols.length === 0 || !protocols.every((item) => typeof item === "string" && SUBPROTOCOL.test(item)) || new Set(protocols).size !== protocols.length) fail(`"protocols" must be a non-empty list of distinct subprotocol tokens, got ${describe(protocols)}`, ["protocols: ['chat.v1']"]);
+		else options.protocols = protocols;
+	}
+	const maxPayload = value["maxPayload"];
+	if (maxPayload !== void 0) {
+		const bytes = parseSize(maxPayload);
+		if (bytes === void 0) fail(`"maxPayload" must be a positive byte size ('64kb', 65536), got ${describe(maxPayload)}`);
+		else options.maxPayload = bytes;
+	}
+	const concurrency = value["concurrency"];
+	if (concurrency !== void 0) {
+		if (isPositiveInteger(concurrency)) options.concurrency = concurrency;
+		else fail(`"concurrency" must be a positive integer, got ${describe(concurrency)}`);
+	}
+	const rateLimit = value["rateLimit"];
+	if (rateLimit !== void 0) {
+		const onLimit = isRecord(rateLimit) ? rateLimit["onLimit"] ?? "reject" : void 0;
+		if (!isRecord(rateLimit) || !isPositiveInteger(rateLimit["messages"]) || !isPositiveInteger(rateLimit["intervalMs"]) || onLimit !== "reject" && onLimit !== "close" || Object.keys(rateLimit).some((key) => key !== "messages" && key !== "intervalMs" && key !== "onLimit")) fail(`"rateLimit" must be { messages, intervalMs, onLimit?: 'reject' | 'close' }, got ${describe(rateLimit)}`, ["rateLimit: { messages: 30, intervalMs: 1000 }"]);
+		else options.rateLimit = {
+			messages: rateLimit["messages"],
+			intervalMs: rateLimit["intervalMs"],
+			onLimit
+		};
+	}
+	const backpressure = value["backpressure"];
+	if (backpressure !== void 0) {
+		const limit = isRecord(backpressure) ? backpressure["limit"] : void 0;
+		const onLimit = isRecord(backpressure) ? backpressure["onLimit"] : void 0;
+		const bytes = limit === void 0 ? void 0 : parseSize(limit);
+		if (!isRecord(backpressure) || limit !== void 0 && bytes === void 0 || onLimit !== void 0 && onLimit !== "close" && onLimit !== "drop" || Object.keys(backpressure).some((key) => key !== "limit" && key !== "onLimit")) fail(`"backpressure" must be { limit?: ByteSize, onLimit?: 'close' | 'drop' }, got ${describe(backpressure)}`);
+		else options.backpressure = {
+			...bytes === void 0 ? {} : { limit: bytes },
+			...onLimit === void 0 ? {} : { onLimit }
+		};
+	}
+	return {
+		path,
+		scope,
+		options
+	};
+}
+/** The normalised path, or `undefined` when it breaks the route grammar (ZNIGHT007). */
+function checkPath(ctx, prefix, raw, location) {
+	const path = normalizePath(raw);
+	const issue = checkRoutePath(path);
+	if (issue === void 0) return path;
+	report(ctx, INVALID_ROUTE, location, `${prefix}: invalid path "${raw}": ${issue.message}`, ["Gateway paths use the route grammar: '/chat', '/docs/:docId', '/feeds/*'"]);
+}
+/** The class and its analysable base classes (nearest first). */
+function classChain(cls, ctx) {
+	const chain = [cls];
+	const seen = /* @__PURE__ */ new Set([cls.identity]);
+	let current = cls;
+	while (current.superClass !== void 0 && chain.length < MAX_CHAIN) {
+		const base = ctx.classInfo(current.superClass.identity);
+		if (base === void 0 || seen.has(base.identity)) break;
+		chain.push(base);
+		seen.add(base.identity);
+		current = base;
+	}
+	return chain;
+}
+/** `@UseHandshakeGuard` / `@UseMessageGuard` arguments, bound with a gateway → guard edge. */
+function guardRefs(ctx, from, decorators, identity) {
+	const refs = [];
+	for (const decorator of decorators) {
+		if (decorator.identity !== identity) continue;
+		if (decorator.called && decorator.args.length === 0) report(ctx, INVALID_DECORATOR, decorator.location, `@${decorator.name} requires at least one guard`, [`@${decorator.name}(MyGuard)`]);
+		for (const arg of decorator.args) {
+			const ref = ctx.resolveClassRef(arg, {
+				from,
+				role: "guard"
+			});
+			if (ref) refs.push(ref);
+		}
+	}
+	return refs;
+}
+/** The single `@OnConnect` / `@OnDisconnect` of a gateway (ZNIGHT050 for several). */
+function single(ctx, cls, members, key, name) {
+	const found = members.flatMap((member) => member[key] === void 0 ? [] : [member[key]]);
+	const first = found[0];
+	for (const extra of found.slice(1)) report(ctx, INVALID_GATEWAY, extra.location, `${cls.displayName} has several ${name} methods: ${found.map((item) => `${item.declaredBy}.${item.method}`).join(", ")}`, [`Keep a single ${name} method per gateway`], "error", [{
+		message: `First ${name} method`,
+		location: first.location
+	}]);
+	return first;
+}
+/** Events handled twice, several default handlers, events on raw gateways (ZNIGHT050). */
+function checkHandlers(cls, protocol, handlers, ctx) {
+	const label = (handler) => `${handler.declaredBy}.${handler.method}`;
+	if (protocol === "raw") {
+		for (const handler of handlers) {
+			if (handler.event === void 0) continue;
+			report(ctx, INVALID_GATEWAY, handler.location, `@OnMessage("${handler.event}") on the raw gateway ${cls.displayName}`, ["A raw gateway has no events: use @OnMessage() for its single handler, or protocol: \"events\""]);
+		}
+		const first = handlers[0];
+		for (const extra of handlers.slice(1)) report(ctx, INVALID_GATEWAY, extra.location, `The raw gateway ${cls.displayName} has several handlers: ${handlers.map(label).join(", ")}`, ["A raw gateway has a single @OnMessage() handler receiving every frame"], "error", [{
+			message: "First handler",
+			location: first.location
+		}]);
+		return;
+	}
+	let fallback;
+	const byEvent = /* @__PURE__ */ new Map();
+	for (const handler of handlers) {
+		if (handler.event === void 0) {
+			if (fallback === void 0) {
+				fallback = handler;
+				continue;
+			}
+			report(ctx, INVALID_GATEWAY, handler.location, `${cls.displayName} has several default handlers: ${label(fallback)} and ${label(handler)}`, ["Give one of them an event: @OnMessage(\"message.send\")"], "error", [{
+				message: "First default handler",
+				location: fallback.location
+			}]);
+			continue;
+		}
+		const first = byEvent.get(handler.event);
+		if (first === void 0) {
+			byEvent.set(handler.event, handler);
+			continue;
+		}
+		report(ctx, INVALID_GATEWAY, handler.location, `${cls.displayName} handles "${handler.event}" twice: ${label(first)} and ${label(handler)}`, ["An event has a single handler per gateway: merge the methods, or rename one of the events"], "error", [{
+			message: "first handled here",
+			location: first.location
+		}]);
+	}
+}
+/**
+* Websocket methods declared by `cls` itself, by name. `host` is the gateway when `cls` is one of
+* its bases (its methods were already reported when the base was analysed: no second report).
+*/
+function analyzeMembers(cls, ctx, host) {
+	const members = /* @__PURE__ */ new Map();
+	const quiet = host === void 0 ? ctx : silenced(ctx);
+	for (const method of cls.methods) {
+		const member = analyzeMethod(cls, method, quiet, host ?? cls);
+		if (member !== void 0) members.set(method.name, member);
+	}
+	return members;
+}
+/** The context without reports (a base class analysed again for a gateway). */
+function silenced(ctx) {
+	return new Proxy(ctx, { get(target, key, receiver) {
+		if (key === "report") return () => void 0;
+		const value = Reflect.get(target, key, receiver);
+		return typeof value === "function" ? value.bind(target) : value;
+	} });
+}
+function analyzeMethod(cls, method, ctx, host) {
+	const onConnect = method.decorators.filter((decorator) => decorator.identity === WsDecorator.OnConnect);
+	const onDisconnect = method.decorators.filter((decorator) => decorator.identity === WsDecorator.OnDisconnect);
+	const onMessage = method.decorators.filter((decorator) => decorator.identity === WsDecorator.OnMessage);
+	const guards = method.decorators.filter((decorator) => decorator.identity === WsDecorator.UseMessageGuard);
+	const decoratedParams = method.params.some((param) => param.decorators.some(isParameterDecorator));
+	if (onConnect.length + onDisconnect.length + onMessage.length + guards.length === 0 && !decoratedParams) return;
+	const where = `${cls.displayName}.${method.name}`;
+	const roles = [
+		onConnect[0],
+		onDisconnect[0],
+		onMessage[0]
+	].filter((item) => item !== void 0);
+	const primary = roles[0];
+	if (primary === void 0) {
+		for (const guard of guards) report(ctx, INVALID_DECORATOR, guard.location, `@UseMessageGuard has no effect on ${where}: it is not an @OnMessage handler`, ["Add @OnMessage(\"event\") to the method, or put the guard on the gateway class"]);
+		reportStrayParameters(method, where, ctx);
+		return {
+			method: method.name,
+			declaredBy: cls.displayName,
+			onConnect: void 0,
+			onDisconnect: void 0,
+			handlers: [],
+			role: false
+		};
+	}
+	checkMethodShape(method, primary, where, ctx);
+	if (roles.length > 1) report(ctx, INVALID_GATEWAY, roles[1].location, `${where} has several roles (${roles.map((role) => `@${role.name}`).join(", ")})`, ["A method is either @OnConnect, @OnDisconnect or an @OnMessage handler: split it"]);
+	for (const duplicate of [...onConnect.slice(1), ...onDisconnect.slice(1)]) report(ctx, INVALID_DECORATOR, duplicate.location, `@${duplicate.name} is applied several times on ${where}`, [`Keep a single @${duplicate.name}`]);
+	const location = primary.location;
+	if (onMessage.length === 0) {
+		for (const guard of guards) report(ctx, INVALID_DECORATOR, guard.location, `@UseMessageGuard has no effect on ${where}: it is not an @OnMessage handler`, ["Message guards run before @OnMessage handlers; guard the handshake with @UseHandshakeGuard on the class"]);
+		const lifecycle = {
+			method: method.name,
+			params: analyzeParams(method, where, "lifecycle", ctx),
+			declaredBy: cls.displayName,
+			location
+		};
+		return {
+			method: method.name,
+			declaredBy: cls.displayName,
+			onConnect: onConnect.length > 0 ? lifecycle : void 0,
+			onDisconnect: onConnect.length === 0 ? lifecycle : void 0,
+			handlers: [],
+			role: true
+		};
+	}
+	const params = analyzeParams(method, where, "message", ctx);
+	const meta = readRouteMeta(ctx, cls, method);
+	const methodGuards = guardRefs(ctx, host, method.decorators, WsDecorator.UseMessageGuard);
+	const handlers = onMessage.flatMap((decorator) => {
+		const event = eventOf(decorator, where, ctx);
+		if (event === false) return [];
+		return [Object.freeze({
+			method: method.name,
+			event,
+			meta,
+			guards: methodGuards,
+			params,
+			declaredBy: cls.displayName,
+			location: decorator.location
+		})];
+	});
+	return {
+		method: method.name,
+		declaredBy: cls.displayName,
+		onConnect: void 0,
+		onDisconnect: void 0,
+		handlers,
+		role: true
+	};
+}
+/** The event of `@OnMessage(event?)`: a string, `undefined` (default handler) or `false` (invalid). */
+function eventOf(decorator, where, ctx) {
+	const arg = decorator.args[0];
+	if (arg === void 0 || arg.evaluated && arg.value === void 0) return void 0;
+	if (!arg.evaluated) return false;
+	const value = arg.value;
+	if (typeof value !== "string") {
+		report(ctx, INVALID_DECORATOR, arg.location, `@OnMessage on ${where} expects an event name (a string), got ${describe(value)}`, ["Use @OnMessage() for the default handler"]);
+		return false;
+	}
+	if (value.startsWith("$")) {
+		report(ctx, INVALID_GATEWAY, arg.location, `Event name "${value}" is reserved (${where})`, [`Names starting with "$" are protocol events${value === "$ping" ? "; \"$ping\" is answered by Znight itself" : ""}`]);
+		return false;
+	}
+	if (!EVENT_NAME.test(value)) {
+		report(ctx, INVALID_GATEWAY, arg.location, `Invalid event name "${value}" (${where})`, ["An event name starts with a letter, then up to 127 letters, digits or _ . : / -"]);
+		return false;
+	}
+	return value;
+}
+/** Handlers are called by the generated code: `gateway.method(...)`. */
+function checkMethodShape(method, decorator, where, ctx) {
+	const name = `@${decorator.name}`;
+	let problem;
+	if (method.kind !== "method") problem = [`${name} cannot be applied to the accessor ${where}`, "Use a regular method"];
+	else if (method.static) problem = [`${name} cannot be applied to the static method ${where}`, "Remove `static`"];
+	else if (method.privateName) problem = [`${name} cannot be applied to the #private method ${where}`, "Use a public method"];
+	else if (method.visibility !== "public") problem = [`${where} must be public: ${name} methods are called by the generated code`, `Remove the '${method.visibility}' modifier`];
+	else if (method.computed) problem = [`${name} cannot be applied to ${where}: computed names are not supported`, "Use a plain method name"];
+	else if (method.generator) problem = [`${name} cannot be applied to the generator method ${where}`, "Use a regular (or async) method"];
+	if (problem !== void 0) report(ctx, INVALID_DECORATOR, decorator.location, problem[0], [problem[1]]);
+}
+function analyzeParams(method, where, role, ctx) {
+	let payload;
+	return Object.freeze(method.params.map((param) => {
+		const data = analyzeParam(param, where, role, ctx);
+		if (data.kind === "payload" || data.kind === "validated") {
+			const decorator = parameterDecorators(param)[0];
+			if (payload !== void 0) report(ctx, INVALID_GATEWAY, decorator.location, `${where} has two @Payload parameters`, ["A message has one payload: keep a single @Payload()"]);
+			payload ??= decorator;
+		}
+		return data;
+	}));
+}
+function analyzeParam(param, where, role, ctx) {
+	const absent = {
+		kind: "undefined",
+		optional: param.optional || param.hasDefault
+	};
+	const decorators = parameterDecorators(param);
+	const decorator = decorators[0];
+	if (decorator === void 0) {
+		const foreign = foreignParameterDecorator(param);
+		if (foreign !== void 0) {
+			report(ctx, INVALID_DECORATOR, foreign.decorator.location, `@${foreign.decorator.name} on parameter '${param.name}' of ${where} is imported from '${foreign.module}': gateway handlers use ${foreign.name} from '${RUNTIME_MODULE}'`, [`Import it from '${RUNTIME_MODULE}': import { ${foreign.name} } from '${RUNTIME_MODULE}'`]);
+			return absent;
+		}
+		if (param.optional || param.hasDefault || param.rest) return absent;
+		report(ctx, INVALID_GATEWAY, param.location, `Parameter '${param.name}' of ${where} has no @Payload(), @Conn() or @Ctx() decorator`, [role === "message" ? "Every handler parameter is extracted from the message: @Payload(schema?), @Conn() or @Ctx()" : "@OnConnect and @OnDisconnect methods receive the connection: @Conn()"]);
+		return absent;
+	}
+	if (decorators.length > 1) report(ctx, INVALID_DECORATOR, decorators[1].location, `Parameter '${param.name}' of ${where} has several websocket decorators`, ["Keep a single one"]);
+	if (param.rest) {
+		report(ctx, INVALID_DECORATOR, decorator.location, `@${decorator.name} cannot be applied to the rest parameter '...${param.name}' of ${where}`);
+		return absent;
+	}
+	if (decorator.identity === WsDecorator.Conn) return { kind: "connection" };
+	if (role === "lifecycle") {
+		report(ctx, INVALID_GATEWAY, decorator.location, `@${decorator.name} on ${where}: only @OnMessage handlers receive a message`, ["@OnConnect and @OnDisconnect methods take @Conn() only"]);
+		return absent;
+	}
+	if (decorator.identity === WsDecorator.Ctx) return { kind: "context" };
+	return payloadParam(param, decorator, where, ctx);
+}
+/** `@Payload()` / `@Payload(schema)`. */
+function payloadParam(param, decorator, where, ctx) {
+	const arg = decorator.args[0];
+	if (arg === void 0 || arg.evaluated && arg.value === void 0) {
+		checkUnvalidated(param, decorator, where, ctx);
+		return { kind: "payload" };
+	}
+	if (arg.ref !== void 0) {
+		if (isClassReference(arg.ref)) {
+			report(ctx, INVALID_DECORATOR, arg.location, `@Payload(${arg.text}) on ${where}: '${arg.ref.name}' is a class, not a Standard Schema`, ["Pass a Standard Schema (Zod, Valibot, ArkType...): export const SendMessage = z.object({ ... })"]);
+			return {
+				kind: "undefined",
+				optional: false
+			};
+		}
+		return {
+			kind: "validated",
+			schema: arg.ref
+		};
+	}
+	if (!arg.evaluated) return {
+		kind: "undefined",
+		optional: false
+	};
+	report(ctx, INVALID_DECORATOR, arg.location, `@Payload on ${where} expects a Standard Schema (Zod, Valibot, ArkType...), got ${describe(arg.value)}`, ["Declare the schema with `export const SendMessage = z.object({ ... })` and pass it: @Payload(SendMessage)"]);
+	return {
+		kind: "undefined",
+		optional: false
+	};
+}
+/** ZNIGHT017: a structured payload injected without schema is trusted blindly. */
+function checkUnvalidated(param, decorator, where, ctx) {
+	const { type } = ctx.types.stripNullish(param.type);
+	if (isSafePayloadType(type)) return;
+	const typed = type.kind === "opaque" && type.reason === "missing-annotation" ? "has no type annotation" : `is typed '${ctx.types.format(param.type)}'`;
+	ctx.report({
+		code: UNVALIDATED_INPUT,
+		severity: ctx.options.strictValidation ? "error" : "warning",
+		message: `Unvalidated message payload: parameter '${param.name}' of ${where} ${typed} but @Payload() has no schema`,
+		location: decorator.location,
+		hints: ["Validate it with a Standard Schema (Zod, Valibot, ArkType...): @Payload(SendMessage)", "Or declare the parameter as 'unknown' (or 'string | Uint8Array') and check it in the handler"]
+	});
+}
+/** Parameter decorators of a method that has no websocket role. */
+function reportStrayParameters(method, where, ctx) {
+	for (const param of method.params) for (const decorator of parameterDecorators(param)) report(ctx, INVALID_DECORATOR, decorator.location, `@${decorator.name} has no effect on parameter '${param.name}' of ${where}: it is not a gateway handler`, ["Add @OnMessage(\"event\"), @OnConnect() or @OnDisconnect() to the method, or remove the decorator"]);
+}
+/** A parameter decorator named like a websocket one (`Ctx`, `Payload`) imported from another package. */
+function foreignParameterDecorator(param) {
+	for (const decorator of param.decorators) {
+		const identity = decorator.identity;
+		const separator = identity?.lastIndexOf("#") ?? -1;
+		if (identity === void 0 || separator <= 0) continue;
+		const module = identity.slice(0, separator);
+		const name = identity.slice(separator + 1);
+		if (module === "@znight/websocket" || !module.startsWith("@znight/")) continue;
+		if (PARAMETER_DECORATORS.has(`@znight/websocket#${name}`)) return {
+			decorator,
+			module,
+			name
+		};
+	}
+}
+/** Websocket decorators of a parameter, de-duplicated by position. */
+function parameterDecorators(param) {
+	const seen = /* @__PURE__ */ new Set();
+	return param.decorators.filter((decorator) => {
+		if (!isParameterDecorator(decorator) || seen.has(decorator.location.start)) return false;
+		seen.add(decorator.location.start);
+		return true;
+	});
+}
+function isParameterDecorator(decorator) {
+	return decorator.identity !== void 0 && PARAMETER_DECORATORS.has(decorator.identity);
+}
+function isClassReference(ref) {
+	const symbol = ref.symbol;
+	return symbol.kind === "declaration" && symbol.declaration.kind === "class";
+}
+/** `string`, `Uint8Array`, `string | Uint8Array`, literals and `unknown` need no schema. */
+function isSafePayloadType(type) {
+	switch (type.kind) {
+		case "primitive": return type.name !== "any" && type.name !== "object";
+		case "literal": return true;
+		case "union": return type.types.every(isSafePayloadType);
+		case "reference": return BINARY_TYPES.has(type.identity);
+		default: return false;
+	}
+}
+// src/compiler/generate.ts
+/** Builds the websocket section; `undefined` (no section) without gateways. */
+function generateWebSocket(ctx) {
+	const gateways = ctx.stored.filter((data) => data.kind === "gateway").sort((a, b) => compareStrings(a.token, b.token));
+	if (gateways.length === 0) return void 0;
+	const helpers = lazyHelpers(ctx);
+	const entries = [["gateways", ctx.arr(gateways.map((gateway) => gatewayNode(ctx, gateway, helpers)))]];
+	const groups = groupsNode(ctx, gateways);
+	if (groups !== void 0) entries.push(["groups", groups]);
+	return ctx.obj(entries);
+}
+function gatewayNode(ctx, gateway, helpers) {
+	let classType;
+	const gatewayType = () => {
+		classType ??= ctx.importType(gateway.identity);
+		return classType;
+	};
+	const options = gateway.options;
+	const entries = [
+		["token", gateway.token],
+		["path", gateway.path ?? "/"],
+		["protocol", options.protocol]
+	];
+	if (options.protocols !== void 0) entries.push(["protocols", ctx.lit([...options.protocols])]);
+	if (options.maxPayload !== void 0) entries.push(["maxPayload", options.maxPayload]);
+	if (options.concurrency !== void 0) entries.push(["concurrency", options.concurrency]);
+	if (options.rateLimit !== void 0) entries.push(["rateLimit", ctx.lit({ ...options.rateLimit })]);
+	if (options.backpressure !== void 0) entries.push(["backpressure", ctx.lit({ ...options.backpressure })]);
+	entries.push(["meta", metaNode(ctx, gateway.meta)], ["handshakeGuards", tokens(ctx, gateway.handshakeGuards)], ["messageGuards", tokens(ctx, gateway.messageGuards)]);
+	if (gateway.onConnect !== void 0) entries.push(["onConnect", lifecycleNode(ctx, gateway.onConnect, gatewayType, helpers)]);
+	if (gateway.onDisconnect !== void 0) entries.push(["onDisconnect", lifecycleNode(ctx, gateway.onDisconnect, gatewayType, helpers)]);
+	entries.push(["handlers", ctx.arr(gateway.handlers.map((handler) => handlerNode(ctx, handler, gatewayType, helpers)))]);
+	return ctx.obj(entries);
+}
+function metaNode(ctx, meta) {
+	return ctx.obj(meta.map((entry) => [entry.key, ctx.lit(entry.value)]));
+}
+function tokens(ctx, refs) {
+	return ctx.arr(refs.map((ref) => ctx.tokenOf(ref) ?? ref.token));
+}
+/** Trailing parameters left `undefined` are not passed. */
+function trimmed(params) {
+	const list = [...params];
+	while (list.length > 0 && list[list.length - 1]?.kind === "undefined") list.pop();
+	return list;
+}
+/** `{ method, invoke: (g: Gateway, c: WsConnection) => g.method(c as never) }`. */
+function lifecycleNode(ctx, lifecycle, gatewayType, helpers) {
+	const params = trimmed(lifecycle.params);
+	const invoke = params.length === 0 ? ctx.arrow([["g", gatewayType()]], (g) => ctx.call(ctx.member(g, lifecycle.method))) : ctx.arrow([["g", gatewayType()], ["c", helpers.connection()]], (g, c) => ctx.call(ctx.member(g, lifecycle.method), params.map((param) => param.kind === "connection" ? ctx.code`${c} as never` : ctx.lit(void 0))));
+	return ctx.obj([["method", lifecycle.method], ["invoke", invoke]]);
+}
+function handlerNode(ctx, handler, gatewayType, helpers) {
+	const entries = [["method", handler.method]];
+	if (handler.event !== void 0) entries.push(["event", handler.event]);
+	entries.push(["meta", metaNode(ctx, handler.meta)], ["guards", tokens(ctx, handler.guards)], ["params", ctx.arr(handler.params.flatMap((param, index) => paramNode(ctx, param, index)))], ["invoke", invokeNode(ctx, handler, gatewayType, helpers)]);
+	return ctx.obj(entries);
+}
+/** The informational `params` entry of a parameter (none for a parameter left `undefined`). */
+function paramNode(ctx, param, index) {
+	switch (param.kind) {
+		case "payload": return [ctx.obj([["index", index], ["source", "payload"]])];
+		case "validated": return [ctx.obj([
+			["index", index],
+			["source", "payload"],
+			["schema", true]
+		])];
+		case "connection": return [ctx.obj([["index", index], ["source", "connection"]])];
+		case "context": return [ctx.obj([["index", index], ["source", "context"]])];
+		case "undefined": return [];
+	}
+}
+/** `(g: Gateway, m: WsMessageContext) => g.method(...args)`, `async` when a payload is validated. */
+function invokeNode(ctx, handler, gatewayType, helpers) {
+	const params = trimmed(handler.params);
+	if (params.length === 0) return ctx.arrow([["g", gatewayType()]], (g) => ctx.call(ctx.member(g, handler.method)));
+	return ctx.arrow([["g", gatewayType()], ["m", helpers.messageContext()]], (g, m) => ctx.call(ctx.member(g, handler.method), params.map((param) => argumentNode(ctx, param, m, helpers))), { async: params.some((param) => param.kind === "validated") });
+}
+function argumentNode(ctx, param, m, helpers) {
+	switch (param.kind) {
+		case "payload": return ctx.code`${ctx.member(m, "data")} as never`;
+		case "validated": return ctx.code`await ${ctx.call(helpers.validatePayload(), [ctx.importValue(param.schema), ctx.member(m, "data")])}`;
+		case "connection": return ctx.code`${ctx.member(m, "connection")} as never`;
+		case "context": return m;
+		case "undefined": return ctx.lit(void 0);
+	}
+}
+/**
+* `groups`: the route decorator groups the runtime needs (required, holding several keys, or named
+* differently from their key), sorted; `undefined` when there is none (as `extensions.http`).
+*/
+function groupsNode(ctx, gateways) {
+	const groups = /* @__PURE__ */ new Map();
+	const visit = (entries) => {
+		for (const entry of entries) {
+			const group = groups.get(entry.group);
+			if (group === void 0) groups.set(entry.group, {
+				keys: /* @__PURE__ */ new Set([entry.key]),
+				required: entry.required
+			});
+			else {
+				group.keys.add(entry.key);
+				group.required ||= entry.required;
+			}
+		}
+	};
+	for (const gateway of gateways) {
+		visit(gateway.meta);
+		for (const handler of gateway.handlers) visit(handler.meta);
+	}
+	const needed = [...groups].filter(([name, group]) => group.required || group.keys.size > 1 || !group.keys.has(name)).sort(([a], [b]) => compareStrings(a, b));
+	if (needed.length === 0) return void 0;
+	return ctx.obj(needed.map(([name, group]) => [name, ctx.obj([["keys", ctx.lit([...group.keys].sort(compareStrings))], ["required", group.required]])]));
+}
+function lazyHelpers(ctx) {
+	const cache = /* @__PURE__ */ new Map();
+	const get = (name, type) => {
+		let node = cache.get(name);
+		if (node === void 0) {
+			node = ctx.importFrom(RUNTIME_MODULE, name, type ? { type: true } : {});
+			cache.set(name, node);
+		}
+		return node;
+	};
+	return {
+		connection: () => get("WsConnection", true),
+		messageContext: () => get("WsMessageContext", true),
+		validatePayload: () => get("validatePayload", false)
+	};
+}
+// src/compiler/validate.ts
+/** Validates the gateways of the application. */
+function validateWebSocket(ctx) {
+	const gateways = ctx.stored.filter((data) => data.kind === "gateway").sort((a, b) => compareStrings(a.token, b.token));
+	const byShape = /* @__PURE__ */ new Map();
+	for (const gateway of gateways) {
+		if (gateway.path === void 0) continue;
+		const shape = parseRoutePath(gateway.path).shape;
+		const first = byShape.get(shape);
+		if (first === void 0) {
+			byShape.set(shape, gateway);
+			continue;
+		}
+		ctx.report({
+			code: INVALID_ROUTE,
+			severity: "error",
+			message: `${first.displayName} (${first.path}) and ${gateway.displayName} (${gateway.path}) serve the same path`,
+			location: gateway.location,
+			hints: ["Two gateways cannot match the same handshake: change one of the paths"],
+			related: [{
+				message: `${first.displayName} serves ${first.path}`,
+				location: first.location
+			}]
+		});
+	}
+	const bases = new Set(gateways.flatMap((gateway) => gateway.chain));
+	for (const data of ctx.stored) {
+		if (data.kind !== "members" || data.abstract || bases.has(data.identity)) continue;
+		for (const decorator of data.decorators) ctx.report({
+			code: INVALID_DECORATOR,
+			severity: "error",
+			message: `@${decorator.name} has no effect: ${data.displayName} is not a @Gateway`,
+			location: decorator.location,
+			hints: [`Add @Gateway('/path') to ${data.displayName}, or extend it from a @Gateway class`, "Base classes holding shared handlers should be abstract"]
+		});
+	}
+	const applied = [];
+	for (const gateway of gateways) {
+		applied.push(...gateway.meta);
+		for (const handler of gateway.handlers) applied.push(...handler.meta);
+	}
+	const required = requiredRouteGroups(ctx, applied);
+	if (required.length === 0) return;
+	for (const gateway of gateways) {
+		const decided = new Set(gateway.meta.map((entry) => entry.group));
+		for (const group of required) {
+			if (decided.has(group.group)) continue;
+			const definition = group.decorators[0];
+			ctx.report({
+				code: MISSING_ROUTE_DECISION,
+				severity: "error",
+				message: `Gateway ${gateway.displayName} (${gateway.path ?? "?"}) has no "${group.group}" decision`,
+				location: gateway.location,
+				hints: [`Add ${group.suggestion} to ${gateway.displayName}: the handshake is an HTTP request`],
+				...definition?.definition === void 0 ? {} : { related: [{
+					message: `The "${group.group}" group is required`,
+					location: definition.definition
+				}] }
+			});
+		}
+	}
+}
+// src/compiler/index.ts
+/** Decorators owned by the extension (static / value arguments, spec §4.6). */
+const decorators = Object.freeze({
+	[WsDecorator.Gateway]: {
+		targets: ["class"],
+		params: ["static"]
+	},
+	[WsDecorator.OnConnect]: {
+		targets: ["method"],
+		params: []
+	},
+	[WsDecorator.OnDisconnect]: {
+		targets: ["method"],
+		params: []
+	},
+	[WsDecorator.OnMessage]: {
+		targets: ["method"],
+		params: ["static"]
+	},
+	[WsDecorator.Payload]: {
+		targets: ["parameter"],
+		params: ["value"]
+	},
+	[WsDecorator.Conn]: {
+		targets: ["parameter"],
+		params: []
+	},
+	[WsDecorator.Ctx]: {
+		targets: ["parameter"],
+		params: []
+	},
+	[WsDecorator.UseHandshakeGuard]: {
+		targets: ["class"],
+		params: [],
+		rest: "value"
+	},
+	[WsDecorator.UseMessageGuard]: {
+		targets: ["class", "method"],
+		params: [],
+		rest: "value"
+	}
+});
+/** The `@znight/websocket` compiler extension. */
+const webSocketCompilerExtension = Object.freeze({
+	apiVersion: 1,
+	name: EXTENSION_NAME,
+	decorators,
+	analyzeClass: analyzeWebSocketClass,
+	validate: validateWebSocket,
+	generate: generateWebSocket
+});
+export { webSocketCompilerExtension as default, webSocketCompilerExtension };
+
+//# sourceMappingURL=compiler.mjs.map