@scalar/mock-server 0.11.0 → 0.12.0

package/dist/utils/resolve-channels.js

@@ -0,0 +1,100 @@
+import { ASYNCAPI_WEBSOCKET_PROTOCOLS, getAllChannelMessages, getAsyncApiServers, getChannelOperations, resolveChannel, } from '@scalar/workspace-store/channel-example';
+import { getNameFromRef } from '@scalar/workspace-store/helpers/get-name-from-ref';
+import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
+import { honoRouteFromPath } from '../utils/hono-route-from-path.js';
+/** Extract a plain JSON Schema from a message `payload`, unwrapping the Multi Format Schema Object. */
+function extractPayloadSchema(payload) {
+    const resolved = getResolvedRef(payload);
+    if (!resolved || typeof resolved !== 'object') {
+        return undefined;
+    }
+    // Multi Format Schema Object: `{ schemaFormat, schema }`. The actual schema lives under `schema`.
+    if ('schemaFormat' in resolved && 'schema' in resolved) {
+        return getResolvedRef(resolved.schema);
+    }
+    return resolved;
+}
+/**
+ * Adapt a resolved AsyncAPI message into the transport-facing {@link ResolvedMessage} shape: a plain
+ * payload schema (ready for `getExampleFromSchema`), any defined examples, and the content type.
+ *
+ * @param key - The message's key in `channel.messages` (what operation `$ref`s point at).
+ * @param message - The dereferenced AsyncAPI message object.
+ */
+function toResolvedMessage(key, message, defaultContentType) {
+    const resolved = message;
+    const examples = Array.isArray(resolved.examples)
+        ? resolved.examples
+            .map((example) => getResolvedRef(example))
+            .filter((example) => example?.payload !== undefined)
+            .map((example) => example.payload)
+        : [];
+    return {
+        id: resolved.name ?? key,
+        payload: extractPayloadSchema(resolved.payload),
+        examples,
+        contentType: resolved.contentType ?? defaultContentType,
+    };
+}
+/**
+ * Collect the connection protocols (lower-cased) advertised for a channel. Server protocols come
+ * from the shared workspace-store resolver (the same one the API client uses), so the mock and the
+ * client classify a document identically. A WebSocket binding is an additional reliable hint when
+ * the channel declares no servers.
+ */
+function resolveProtocols(document, channel) {
+    const protocols = new Set();
+    for (const server of getAsyncApiServers(document, { channel: channel, webSocketOnly: false })) {
+        if (server.protocol) {
+            protocols.add(server.protocol);
+        }
+    }
+    const bindings = getResolvedRef(channel.bindings);
+    if (bindings?.ws) {
+        protocols.add(ASYNCAPI_WEBSOCKET_PROTOCOLS[0]);
+    }
+    return [...protocols];
+}
+/**
+ * Normalize an AsyncAPI 3.1 document into a flat list of {@link ResolvedChannel}s a transport can
+ * serve. Channel, message, operation, and server resolution are delegated to
+ * `@scalar/workspace-store/channel-example` — the same layer the API client uses to connect to
+ * channels — so the mock and the client agree on how a document maps to channels and operations
+ * (including operation traits). This function only adapts that output into the transport types.
+ */
+export function resolveChannels(document) {
+    const channelNames = Object.keys(document.channels ?? {});
+    return channelNames.flatMap((channelName) => {
+        const resolved = resolveChannel(document, channelName);
+        if (!resolved) {
+            return [];
+        }
+        const { channel, channelAddress } = resolved;
+        const messageEntries = getAllChannelMessages(document, channel);
+        const messages = messageEntries.map(({ name, message }) => toResolvedMessage(name, message, document.defaultContentType));
+        // Keyed by the `channels.*.messages` key (what operation `$ref`s point at), which can differ
+        // from a message's resolved `id` when the message declares a `name`.
+        const messagesByKey = new Map(messageEntries.map(({ name }, index) => [name, messages[index]]));
+        const operations = getChannelOperations(document, channelName).map(({ operationName, operation, action }) => {
+            // An operation may scope itself to a subset of the channel's messages; otherwise use all.
+            const operationMessages = Array.isArray(operation.messages)
+                ? operation.messages
+                    .map((message) => message?.['$ref'])
+                    .filter((ref) => typeof ref === 'string')
+                    .map((ref) => messagesByKey.get(getNameFromRef(ref, ['channels', channelName, 'messages']) ?? ''))
+                    .filter((message) => message !== undefined)
+                : messages;
+            return { id: operationName, action, messages: operationMessages };
+        });
+        return [
+            {
+                id: channelName,
+                address: channelAddress,
+                route: honoRouteFromPath(`/${channelAddress.replace(/^\//, '')}`),
+                protocols: resolveProtocols(document, channel),
+                operations,
+                messages,
+            },
+        ];
+    });
+}

package/dist/utils/validate-request.d.ts

@@ -7,8 +7,8 @@ import type { MiddlewareHandler } from 'hono';
  * violation the middleware short-circuits with a `422` and a `application/problem+json` body;
  * otherwise it calls `next()` and the normal mock handler runs.
  *
- * TODO: Parity follow-ups, intentionally deferred in this slice — response validation,
- * header/cookie parameter validation, non-JSON body validation, and validation proxy mode.
+ * TODO: Parity follow-ups, intentionally deferred — response validation, non-JSON body validation,
+ * and validation proxy mode.
  */
 export declare const validateRequest: (operation: OpenAPIV3_1.OperationObject, pathItemParameters?: OpenAPIV3_1.PathItemObject["parameters"]) => MiddlewareHandler;
 //# sourceMappingURL=validate-request.d.ts.map

package/dist/utils/validate-request.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-request.d.ts","sourceRoot":"","sources":["../../src/utils/validate-request.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAMxD,OAAO,KAAK,EAAW,iBAAiB,EAAE,MAAM,MAAM,CAAA;AAmLtD;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,GAC1B,WAAW,WAAW,CAAC,eAAe,EACtC,qBAAqB,WAAW,CAAC,cAAc,CAAC,YAAY,CAAC,KAC5D,iBAyDF,CAAA"}
+{"version":3,"file":"validate-request.d.ts","sourceRoot":"","sources":["../../src/utils/validate-request.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAMxD,OAAO,KAAK,EAAW,iBAAiB,EAAE,MAAM,MAAM,CAAA;AAuRtD;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,GAC1B,WAAW,WAAW,CAAC,eAAe,EACtC,qBAAqB,WAAW,CAAC,cAAc,CAAC,YAAY,CAAC,KAC5D,iBAkKF,CAAA"}

package/dist/utils/validate-request.js

@@ -2,22 +2,66 @@ import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref
 import { getResolvedRefDeep } from '@scalar/workspace-store/helpers/get-resolved-ref-deep';
 import Ajv2020 from 'ajv/dist/2020.js';
 import addFormats from 'ajv-formats';
+import { getCookie } from 'hono/cookie';
+import { deserializeArrayParameter, deserializeObjectParameter, getObjectPropertyNames, isArraySchema, isObjectSchema, resolveSerialization, } from './deserialize-parameter.js';
 /**
- * Build a JSON Schema object for the parameters declared `in` the given location.
+ * Header parameters named `Accept`, `Content-Type`, or `Authorization` are defined elsewhere in
+ * OpenAPI (through `content` and `security`), so the spec says such parameter definitions SHALL be
+ * ignored. We compare case-insensitively because header names are case-insensitive.
+ */
+const IGNORED_HEADER_PARAMETERS = new Set(['accept', 'content-type', 'authorization']);
+/**
+ * Collapse a `key -> string[]` map (as returned by Hono's `c.req.queries()`) into a `key -> string |
+ * string[]` map: a single value becomes a plain string, while repeated keys keep their array so
+ * array-valued object properties are not silently truncated to the first value.
+ */
+const mapRepeatedValues = (values) => {
+    const map = {};
+    for (const [key, list] of Object.entries(values)) {
+        map[key] = list.length > 1 ? list : (list[0] ?? '');
+    }
+    return map;
+};
+/**
+ * Build a JSON Schema object for the parameters declared `in` the given location, alongside a
+ * descriptor for each declared parameter.
  *
  * Parameters arrive as strings, so the caller compiles these with `coerceTypes: true` to let
- * `type: integer`/`boolean` validate correctly. Returns `null` when there is nothing to validate.
+ * `type: integer`/`boolean` validate correctly. The descriptors let the middleware gather only
+ * declared values and deserialize array parameters by their `style`/`explode`. Returns `null` when
+ * there is nothing to validate.
  */
 const buildParameterSchema = (parameters, location) => {
     const properties = {};
     const required = [];
+    const descriptors = [];
     for (const parameterOrRef of parameters ?? []) {
         const parameter = getResolvedRef(parameterOrRef);
         if (parameter?.in !== location) {
             continue;
         }
-        if (parameter.schema) {
-            properties[parameter.name] = getResolvedRefDeep(parameter.schema);
+        // Per the OpenAPI spec, these header parameters are defined elsewhere and ignored as parameters.
+        if (location === 'header' && IGNORED_HEADER_PARAMETERS.has(parameter.name.toLowerCase())) {
+            continue;
+        }
+        const resolvedSchema = parameter.schema
+            ? getResolvedRefDeep(parameter.schema)
+            : undefined;
+        const { style, explode } = resolveSerialization(location, parameter.style, parameter.explode);
+        // Property names let exploded `form` objects be gathered from matching top-level query keys. They
+        // are collected through any `anyOf`/`oneOf`/`allOf` composition so a composed object schema does not
+        // fall back to free-form gathering and claim unrelated keys.
+        const propertyNames = getObjectPropertyNames(resolvedSchema);
+        descriptors.push({
+            name: parameter.name,
+            style,
+            explode,
+            isArray: isArraySchema(resolvedSchema),
+            isObject: isObjectSchema(resolvedSchema),
+            propertyNames,
+        });
+        if (resolvedSchema) {
+            properties[parameter.name] = resolvedSchema;
         }
         if (parameter.required) {
             required.push(parameter.name);
@@ -27,7 +71,7 @@ const buildParameterSchema = (parameters, location) => {
         return null;
     }
     // Allow undeclared parameters to pass through; we only enforce what the operation declares.
-    return { type: 'object', properties, required, additionalProperties: true };
+    return { schema: { type: 'object', properties, required, additionalProperties: true }, parameters: descriptors };
 };
 /**
  * Merge path-item-level parameters with operation-level parameters.
@@ -81,6 +125,10 @@ const compileValidators = (operation, pathItemParameters) => {
     addFormats(bodyAjv);
     // Path-item parameters apply to every operation, so fold them in before building the schemas.
     const parameters = mergeParameters(pathItemParameters, operation.parameters);
+    const pathParameters = buildParameterSchema(parameters, 'path');
+    const queryParameters = buildParameterSchema(parameters, 'query');
+    const headerParameters = buildParameterSchema(parameters, 'header');
+    const cookieParameters = buildParameterSchema(parameters, 'cookie');
     const requestBody = getResolvedRef(operation.requestBody);
     // Build the body schema defensively; resolving a malformed `$ref` should not crash setup.
     let bodySchema = null;
@@ -92,22 +140,35 @@ const compileValidators = (operation, pathItemParameters) => {
         console.error('Error resolving request body schema, skipping body validation:', error);
     }
     return {
-        path: compileSchema(parameterAjv, buildParameterSchema(parameters, 'path'), 'path parameter'),
-        query: compileSchema(parameterAjv, buildParameterSchema(parameters, 'query'), 'query parameter'),
+        path: compileSchema(parameterAjv, pathParameters?.schema ?? null, 'path parameter'),
+        query: compileSchema(parameterAjv, queryParameters?.schema ?? null, 'query parameter'),
+        header: compileSchema(parameterAjv, headerParameters?.schema ?? null, 'header parameter'),
+        cookie: compileSchema(parameterAjv, cookieParameters?.schema ?? null, 'cookie parameter'),
+        pathParameters: pathParameters?.parameters ?? [],
+        queryParameters: queryParameters?.parameters ?? [],
+        headerParameters: headerParameters?.parameters ?? [],
+        cookieParameters: cookieParameters?.parameters ?? [],
         body: compileSchema(bodyAjv, bodySchema, 'request body'),
         // Required-body enforcement is independent of whether the body schema compiles.
         bodyRequired: requestBody?.required === true,
     };
 };
 /**
- * Map Ajv errors into our violation shape. For path/query parameters the offending parameter name
- * is prepended to the message so the response is readable without cross-referencing the pointer.
+ * Map Ajv errors into our violation shape. For non-body parameters (path, query, header, cookie) the
+ * offending parameter name is prepended to the message so the response is readable without
+ * cross-referencing the pointer.
  */
 const mapErrors = (errors, location) => (errors ?? []).map((error) => {
     const missingProperty = typeof error.params === 'object' && error.params && 'missingProperty' in error.params
         ? String(error.params.missingProperty)
         : '';
     const path = error.instancePath || (missingProperty ? `/${missingProperty}` : '');
+    // A missing parameter surfaces as a top-level `required` error whose `missingProperty` is the
+    // parameter name. Phrase it as "<name> is required" instead of the confusing, self-referential
+    // "<name> must have required property '<name>'" that Ajv produces against the synthetic wrapper.
+    if (location !== 'body' && missingProperty && !error.instancePath) {
+        return { location, path, message: `${missingProperty} is required` };
+    }
     const name = error.instancePath.replace(/^\//, '') || missingProperty;
     const message = location !== 'body' && name ? `${name} ${error.message ?? ''}`.trim() : (error.message ?? '');
     return { location, path, message };
@@ -129,25 +190,115 @@ const isJsonRequest = (c) => {
  * violation the middleware short-circuits with a `422` and a `application/problem+json` body;
  * otherwise it calls `next()` and the normal mock handler runs.
  *
- * TODO: Parity follow-ups, intentionally deferred in this slice — response validation,
- * header/cookie parameter validation, non-JSON body validation, and validation proxy mode.
+ * TODO: Parity follow-ups, intentionally deferred — response validation, non-JSON body validation,
+ * and validation proxy mode.
  */
 export const validateRequest = (operation, pathItemParameters) => {
     const validators = compileValidators(operation, pathItemParameters);
     return async (c, next) => {
         const violations = [];
-        // Path parameters (coerced from strings)
-        if (validators.path) {
-            const data = { ...c.req.param() };
-            if (!validators.path(data)) {
-                violations.push(...mapErrors(validators.path.errors, 'path'));
+        /**
+         * Gather declared parameter values for one location into a plain object for validation. Array and
+         * object parameters are deserialized by their `style`/`explode`; everything else is read as a
+         * single string. Values are looked up by declared name (rather than dumping every request value)
+         * so header names match case-insensitively and only declared parameters are enforced.
+         *
+         * `getValues` (repeated query keys) is only supplied for the query location, where exploded arrays
+         * need it. `getMap` returns the full key/value map for the location and is supplied for query and
+         * cookie, where exploded-`form` objects (and query `deepObject`) spread properties across keys —
+         * for cookies each object property is its own cookie (`Cookie: r=100; g=200`).
+         */
+        const gather = (descriptors, getValue, getValues, getMap) => {
+            // Names of every declared parameter in this location, so a free-form exploded object does not
+            // swallow a sibling parameter's key (e.g. a required free-form object satisfied by `?limit=5`).
+            const declaredNames = new Set(descriptors.map((descriptor) => descriptor.name));
+            const readAsObject = (descriptor) => deserializeObjectParameter({
+                style: descriptor.style,
+                explode: descriptor.explode,
+                single: getValue(descriptor.name),
+                map: getMap?.(),
+                name: descriptor.name,
+                propertyNames: descriptor.propertyNames,
+                reservedKeys: declaredNames,
+            });
+            const readAsArray = (descriptor) => deserializeArrayParameter({
+                style: descriptor.style,
+                explode: descriptor.explode,
+                single: getValue(descriptor.name),
+                multi: getValues?.(descriptor.name),
+            });
+            const data = {};
+            for (const descriptor of descriptors) {
+                let value;
+                if (descriptor.isArray && descriptor.isObject) {
+                    // A schema composed with `anyOf`/`oneOf`/`allOf` can look like both an array and an object, and
+                    // form encoding cannot say which the client meant. Prefer a non-empty array — that only happens
+                    // when the request carries the parameter's own (possibly repeated) key — and fall back to the
+                    // object reading otherwise. This parses array-style input (`?filter=1&filter=2`) as an array while
+                    // still letting object-style input (properties spread across other keys) be gathered as an object.
+                    // A lone empty value (`?filter=`) deserializes to `[]`, which is not array-shaped input, so it must
+                    // not short-circuit the object fallback; the empty array is only kept when no object value is found.
+                    const asArray = readAsArray(descriptor);
+                    value = Array.isArray(asArray) && asArray.length > 0 ? asArray : (readAsObject(descriptor) ?? asArray);
+                }
+                else if (descriptor.isObject) {
+                    value = readAsObject(descriptor);
+                }
+                else if (descriptor.isArray) {
+                    value = readAsArray(descriptor);
+                }
+                else {
+                    value = getValue(descriptor.name);
+                }
+                if (value !== undefined) {
+                    data[descriptor.name] = value;
+                }
             }
-        }
-        // Query parameters (coerced from strings)
-        if (validators.query) {
-            const data = { ...c.req.query() };
-            if (!validators.query(data)) {
-                violations.push(...mapErrors(validators.query.errors, 'query'));
+            return data;
+        };
+        // Validate each parameter location with its own request accessors. Values are coerced from strings.
+        // The differences between locations are only the accessors:
+        //  - query supplies `getValues` (repeated keys feed exploded arrays) and a `getMap` that keeps
+        //    repeated keys as arrays, so an array-valued object property (`filter[tags]=a&filter[tags]=b`)
+        //    survives deserialization;
+        //  - cookie supplies a `getMap` (each exploded `form` object property is its own cookie);
+        //  - header names are matched case-insensitively by Hono's `c.req.header`.
+        const parameterLocations = [
+            {
+                validator: validators.path,
+                descriptors: validators.pathParameters,
+                location: 'path',
+                getValue: (name) => c.req.param(name),
+            },
+            {
+                validator: validators.query,
+                descriptors: validators.queryParameters,
+                location: 'query',
+                getValue: (name) => c.req.query(name),
+                getValues: (name) => c.req.queries(name),
+                getMap: () => mapRepeatedValues(c.req.queries()),
+            },
+            {
+                validator: validators.header,
+                descriptors: validators.headerParameters,
+                location: 'header',
+                getValue: (name) => c.req.header(name),
+            },
+            {
+                validator: validators.cookie,
+                descriptors: validators.cookieParameters,
+                location: 'cookie',
+                getValue: (name) => getCookie(c, name),
+                getMap: () => getCookie(c),
+            },
+        ];
+        for (const { validator, descriptors, location, getValue, getValues, getMap } of parameterLocations) {
+            if (!validator) {
+                continue;
+            }
+            const data = gather(descriptors, getValue, getValues, getMap);
+            if (!validator(data)) {
+                violations.push(...mapErrors(validator.errors, location));
             }
         }
         // Request body — only `application/json` in this slice

package/package.json

@@ -16,7 +16,7 @@
     "swagger",
     "cli"
   ],
-  "version": "0.11.0",
+  "version": "0.12.0",
   "engines": {
     "node": ">=22"
   },
@@ -52,15 +52,17 @@
   },
   "dependencies": {
     "@faker-js/faker": "10.4.0",
+    "@hono/node-ws": "^1.2.0",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "hono": "^4.12.7",
     "yaml": "^2.8.3",
     "@scalar/helpers": "0.8.2",
+    "@scalar/openapi-upgrader": "0.2.9",
     "@scalar/json-magic": "0.12.16",
     "@scalar/openapi-types": "0.9.1",
-    "@scalar/openapi-upgrader": "0.2.9",
-    "@scalar/workspace-store": "0.54.3"
+    "@scalar/workspace-store": "0.54.5",
+    "@scalar/types": "0.15.0"
   },
   "devDependencies": {
     "@types/node": "^24.1.0",