@loutrejs/loutre 0.4.0 → 0.5.0

package/dist/http/definitions.js

@@ -1,5 +1,7 @@
-import { childPipelineOf, protocolGroup } from '../core/index.js';
-import { createHttpDispatchKey, parseHttpPath, } from './path.js';
+import { childPipelineOf } from '../core/index.js';
+import { contractNodeBinding, contractNodeMetadata, protocolNamespaceBuilder, protocolNamespaceType, } from '../core/contract-internal.js';
+import { httpNodeMetadata } from './internal.js';
+import { assertValidHttpMethod, createHttpDispatchKey, parseHttpPath, } from './path.js';
 const controller = Object.freeze({
     kind: 'terminal',
     name: 'http.controller',
@@ -7,6 +9,14 @@ const controller = Object.freeze({
     protocol: 'http',
 });
 function defineHttp(definition) {
+    assertValidHttpMethod(definition.method);
+    for (const response of Object.values(definition.responses)) {
+        if (!Number.isInteger(response.status) ||
+            response.status < 200 ||
+            response.status > 599) {
+            throw new Error(`Invalid HTTP response status: ${response.status}`);
+        }
+    }
     const segments = parseHttpPath(definition.path);
     const paramsSchemas = definition.request?.params;
     if (paramsSchemas) {
@@ -38,7 +48,238 @@ function hasParamsValidation(pipeline) {
             hasParamsValidation(childPipelineOf(item) ?? [])));
 }
 function defineHttpGroup(definitions) {
-    return protocolGroup('http', Object.fromEntries(Object.entries(definitions).map(([name, definition]) => [name, defineHttp(definition)])));
+    const resolution = resolveHttpTree(definitions, {
+        path: '',
+        pipeline: [],
+        responses: {},
+        procedurePrefix: '',
+    });
+    const group = {
+        kind: 'protocol-group',
+        protocol: 'http',
+        procedures: Object.freeze({ ...resolution.procedures }),
+    };
+    Object.defineProperty(group, protocolNamespaceBuilder, {
+        enumerable: false,
+        value: (root) => buildHttpNamespace(resolution.tree, root, []),
+    });
+    return Object.freeze(group);
+}
+const HTTP_LEAF_PROPERTIES = new Set([
+    'method',
+    'path',
+    'summary',
+    'description',
+    'tags',
+    'deprecated',
+    'request',
+    'responses',
+    'pipeline',
+    'interaction',
+]);
+const HTTP_BRANCH_PROPERTIES = new Set([
+    'path',
+    'pipeline',
+    'responses',
+    'routes',
+]);
+function assertHttpRouteTreeObject(definitions) {
+    const prototype = Object.getPrototypeOf(definitions);
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw new Error('HTTP route tree must be a plain object');
+    }
+}
+function assertHttpRouteName(name) {
+    if (name.length === 0 ||
+        name === '__proto__' ||
+        name.includes('.') ||
+        Number.isFinite(Number(name))) {
+        throw new Error(`Invalid HTTP Contract node name: ${JSON.stringify(name)}`);
+    }
+}
+function assertHttpNodeProperties(source) {
+    const allowed = 'method' in source ? HTTP_LEAF_PROPERTIES : HTTP_BRANCH_PROPERTIES;
+    for (const property of Object.keys(source)) {
+        if (!allowed.has(property)) {
+            throw new Error(`Unknown HTTP Contract node property: ${property}`);
+        }
+    }
+}
+function resolveHttpTree(definitions, context) {
+    assertHttpRouteTreeObject(definitions);
+    const procedures = {};
+    const tree = {};
+    for (const [name, candidate] of Object.entries(definitions)) {
+        assertHttpRouteName(name);
+        const metadata = typeof candidate === 'object' &&
+            candidate !== null &&
+            httpNodeMetadata in candidate
+            ? candidate[httpNodeMetadata]
+            : undefined;
+        const source = (metadata?.source ?? candidate);
+        assertHttpNodeProperties(source);
+        const procedureName = context.procedurePrefix === ''
+            ? name
+            : `${context.procedurePrefix}.${name}`;
+        if ('method' in source) {
+            const responses = mergeHttpResponses(context.responses, source.responses);
+            const definition = {
+                ...source,
+                path: joinHttpPath(context.path, source.path),
+                responses,
+                pipeline: [...context.pipeline, ...source.pipeline],
+            };
+            const protocol = defineHttp(definition);
+            procedures[procedureName] = protocol;
+            tree[name] = {
+                kind: 'leaf',
+                source,
+                handlerName: metadata?.kind === 'leaf' && metadata.handlerName
+                    ? metadata.handlerName
+                    : name,
+                protocol,
+            };
+            continue;
+        }
+        assertBranchPipeline(source.pipeline ?? []);
+        const branchResponses = mergeHttpResponses(context.responses, source.responses ?? {});
+        const branch = resolveHttpTree(source.routes, {
+            path: joinHttpPath(context.path, source.path ?? ''),
+            pipeline: [...context.pipeline, ...(source.pipeline ?? [])],
+            responses: branchResponses,
+            procedurePrefix: procedureName,
+        });
+        Object.assign(procedures, branch.procedures);
+        tree[name] = {
+            kind: 'branch',
+            source,
+            children: branch.tree,
+        };
+    }
+    return { procedures, tree: Object.freeze(tree) };
+}
+function joinHttpPath(parent, child) {
+    if (parent === '')
+        return child;
+    if (child === '' || child === '/')
+        return parent;
+    return `${parent}${child}`;
+}
+function mergeHttpResponses(parent, local) {
+    for (const name of Object.keys(local)) {
+        if (Object.hasOwn(parent, name)) {
+            throw new Error(`Duplicate inherited HTTP response variant: ${name}`);
+        }
+    }
+    return Object.freeze({ ...parent, ...local });
+}
+function assertBranchPipeline(pipeline) {
+    for (const item of pipeline) {
+        if (item.kind === 'terminal') {
+            throw new Error('HTTP branch pipeline must not contain a terminal layer');
+        }
+        if (item.kind === 'layer') {
+            const child = childPipelineOf(item);
+            if (child)
+                assertBranchPipeline(child);
+        }
+    }
+}
+function buildHttpNamespace(tree, root, parentPath) {
+    const namespace = {};
+    for (const [name, template] of Object.entries(tree)) {
+        namespace[name] = buildHttpNode(template, root, [...parentPath, name]);
+    }
+    return Object.freeze(namespace);
+}
+function buildHttpNode(template, root, path) {
+    if (template.kind === 'leaf') {
+        const binding = {
+            kind: 'contract',
+            procedures: Object.freeze({
+                [template.handlerName]: Object.freeze({
+                    kind: 'procedure',
+                    protocols: Object.freeze({ http: template.protocol }),
+                }),
+            }),
+        };
+        Object.defineProperty(binding, contractNodeMetadata, {
+            enumerable: false,
+            value: Object.freeze({
+                kind: 'leaf',
+                root,
+                path: Object.freeze(['http', ...path]),
+                procedures: Object.freeze({
+                    [template.handlerName]: path.join('.'),
+                }),
+            }),
+        });
+        Object.freeze(binding);
+        const node = {};
+        Object.defineProperty(node, contractNodeBinding, {
+            enumerable: false,
+            value: binding,
+        });
+        Object.defineProperty(node, httpNodeMetadata, {
+            enumerable: false,
+            value: Object.freeze({
+                kind: 'leaf',
+                root,
+                path: Object.freeze([...path]),
+                source: template.source,
+                handlerName: template.handlerName,
+            }),
+        });
+        return Object.freeze(node);
+    }
+    const children = buildHttpNamespace(template.children, root, path);
+    const procedures = {};
+    collectHttpNodeProcedures(template.children, '', procedures);
+    const binding = {
+        kind: 'contract',
+        procedures: Object.freeze(procedures),
+    };
+    Object.defineProperty(binding, contractNodeMetadata, {
+        enumerable: false,
+        value: Object.freeze({
+            kind: 'branch',
+            root,
+            path: Object.freeze(['http', ...path]),
+            procedures: Object.freeze(Object.fromEntries(Object.keys(procedures).map((procedure) => [
+                procedure,
+                [...path, procedure].join('.'),
+            ]))),
+        }),
+    });
+    Object.freeze(binding);
+    const node = { ...children };
+    Object.defineProperty(node, contractNodeBinding, {
+        enumerable: false,
+        value: binding,
+    });
+    Object.defineProperty(node, httpNodeMetadata, {
+        enumerable: false,
+        value: Object.freeze({
+            kind: 'branch',
+            root,
+            path: Object.freeze([...path]),
+            source: template.source,
+        }),
+    });
+    return Object.freeze(node);
+}
+function collectHttpNodeProcedures(tree, prefix, procedures) {
+    for (const [name, template] of Object.entries(tree)) {
+        const path = prefix === '' ? name : `${prefix}.${name}`;
+        if (template.kind === 'leaf') {
+            procedures[path] = Object.freeze({
+                kind: 'procedure',
+                protocols: Object.freeze({ http: template.protocol }),
+            });
+            continue;
+        }
+        collectHttpNodeProcedures(template.children, path, procedures);
+    }
 }
 export const http = Object.assign(defineHttpGroup, {
     protocol: 'http',

package/dist/http/internal.d.ts

@@ -0,0 +1,8 @@
+export declare const httpNodeMetadata: unique symbol;
+export interface HttpNodeRuntimeMetadata {
+    readonly kind: 'leaf' | 'branch';
+    readonly root: object;
+    readonly path: readonly string[];
+    readonly source: object;
+    readonly handlerName?: string;
+}

package/dist/http/internal.js

@@ -0,0 +1 @@
+export const httpNodeMetadata = Symbol('loutre.http-node-metadata');

package/dist/http/path.d.ts

@@ -3,6 +3,9 @@ type AsciiLetter = AsciiLowercase | Uppercase<AsciiLowercase>;
 type AsciiDigit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
 type ParamNameStart = AsciiLetter | '_';
 type ParamNameContinuation = ParamNameStart | AsciiDigit;
+type HttpMethodTokenCharacter = AsciiLetter | AsciiDigit | '!' | '#' | '$' | '%' | '&' | "'" | '*' | '+' | '-' | '.' | '^' | '_' | '`' | '|' | '~';
+type IsHttpMethodTokenRest<TMethod extends string> = TMethod extends '' ? true : TMethod extends `${HttpMethodTokenCharacter}${infer TRest}` ? IsHttpMethodTokenRest<TRest> : false;
+export type IsValidHttpMethod<TMethod extends string> = string extends TMethod ? false : TMethod extends `${HttpMethodTokenCharacter}${infer TRest}` ? IsHttpMethodTokenRest<TRest> : false;
 type IsParamNameRest<TName extends string> = TName extends '' ? true : TName extends `${ParamNameContinuation}${infer TRest}` ? IsParamNameRest<TRest> : false;
 type IsParamName<TName extends string> = TName extends `${ParamNameStart}${infer TRest}` ? IsParamNameRest<TRest> : false;
 type IsStaticSegment<TSegment extends string> = TSegment extends '' ? false : TSegment extends `${string}{${string}` | `${string}}${string}` ? false : TSegment extends `${string}?${string}` | `${string}#${string}` ? false : true;
@@ -43,6 +46,7 @@ export type HttpPathSegment = {
     readonly kind: 'param';
     readonly name: string;
 };
+export declare function assertValidHttpMethod(method: string): void;
 export declare function parseHttpPath(path: string): readonly HttpPathSegment[];
 export declare function normalizeHttpPath(segments: readonly HttpPathSegment[]): string;
 export declare function createHttpDispatchKey(method: string, segments: readonly HttpPathSegment[]): string;

package/dist/http/path.js

@@ -1,4 +1,10 @@
 const PARAM_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const HTTP_METHOD_PATTERN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+export function assertValidHttpMethod(method) {
+    if (!HTTP_METHOD_PATTERN.test(method)) {
+        throw new Error(`Invalid HTTP method: ${JSON.stringify(method)}`);
+    }
+}
 export function parseHttpPath(path) {
     if (path === '/')
         return Object.freeze([]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loutrejs/loutre",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "license": "MIT",
   "type": "module",
   "files": [