yedra 0.20.11 → 0.20.13

package/dist/src/routing/app.js

@@ -0,0 +1,537 @@
+import { createHash } from 'node:crypto';
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { createServer as createHttpServer } from 'node:http';
+import { createServer as createHttpsServer } from 'node:https';
+import { extname, join } from 'node:path';
+import { URL } from 'node:url';
+import { isUint8Array } from 'node:util/types';
+import { context, propagation, SpanKind, trace } from '@opentelemetry/api';
+import mime from 'mime';
+import { WebSocketServer } from 'ws';
+import { Counter } from '../util/counter.js';
+import { collectLazySchemas } from '../validation/lazy.js';
+import { HttpError } from './errors.js';
+import { Path } from './path.js';
+import { RestEndpoint } from './rest.js';
+import { WsEndpoint } from './websocket.js';
+class Context {
+    constructor(server, wss, counter, docs) {
+        this.server = server;
+        this.wss = wss;
+        this.counter = counter;
+        this.docs = docs;
+    }
+    stop() {
+        return new Promise((resolve) => {
+            // don't accept any new connections
+            this.wss.close();
+            this.server.close();
+            for (const client of this.wss.clients) {
+                // send shutdown message to all WebSocket clients
+                client.close(1000, 'Server Shutdown');
+            }
+            // wait until all connections are done
+            this.counter.wait().then(() => {
+                resolve();
+            });
+        });
+    }
+}
+class BuiltApp {
+    constructor(options) {
+        this.restRoutes = [];
+        this.wsRoutes = [];
+        this.requestData = {};
+        this.serveData = options.serveData;
+        this.docs = options.docs;
+        this.generatedDocs = JSON.stringify(options.docs);
+        this.connectMiddlewares = options.connectMiddlewares;
+        this.quiet = options.quiet;
+        this.restRoutes = options.restRoutes;
+        this.wsRoutes = options.wsRoutes;
+    }
+    static middlewareNext(req, res, middlewares, last) {
+        if (middlewares.length > 0) {
+            // apply the next middleware
+            middlewares[0](req, res, () => BuiltApp.middlewareNext(req, res, middlewares.slice(1), last));
+        }
+        else {
+            // no middlewares left, invoke yedra
+            last();
+        }
+    }
+    handle(req, res) {
+        // first, invoke the middleware chain
+        BuiltApp.middlewareNext(req, res, this.connectMiddlewares, async () => {
+            // this will be called after all middlewares are done
+            const url = new URL(req.url, 'http://localhost');
+            const begin = Date.now();
+            const response = await this.performRequest({
+                method: req.method ?? 'GET',
+                url,
+                body: req,
+                headers: req.headers,
+            });
+            const status = response.status ?? 200;
+            if (response.body instanceof ReadableStream) {
+                res.writeHead(status, response.headers);
+                try {
+                    for await (const chunk of response.body) {
+                        const canContinue = res.write(chunk);
+                        if (!canContinue) {
+                            // Buffer full - wait for drain before continuing
+                            await new Promise((resolve) => res.once('drain', resolve));
+                        }
+                    }
+                }
+                catch (_error) {
+                    res.destroy();
+                }
+            }
+            else if (response.body instanceof Uint8Array) {
+                res.writeHead(status, response.headers);
+                res.write(response.body);
+            }
+            else {
+                res.writeHead(status, {
+                    'content-type': 'application/json',
+                    ...response.headers,
+                });
+                res.write(JSON.stringify(response.body));
+            }
+            res.end();
+            const duration = Date.now() - begin;
+            if (this.quiet !== true) {
+                console.log(`${req.method} ${url.pathname} -> ${status} (${duration}ms)`);
+            }
+            this.track(req.method, status, duration / 1000);
+        });
+    }
+    async performRequest(req) {
+        if (req.method !== 'GET' &&
+            req.method !== 'POST' &&
+            req.method !== 'PUT' &&
+            req.method !== 'PATCH' &&
+            req.method !== 'DELETE') {
+            return BuiltApp.errorResponse(405, `Method \`${req.method}\` not allowed.`);
+        }
+        if (req.method === 'GET' && req.url.pathname === '/openapi.json') {
+            if (this.generatedDocs === undefined) {
+                console.error('Docs were not generated correctly.');
+                return BuiltApp.errorResponse(500, 'Internal Server Error');
+            }
+            return {
+                status: 200,
+                body: Buffer.from(this.generatedDocs ?? '{}', 'utf-8'),
+                headers: {
+                    'content-type': 'application/json',
+                },
+            };
+        }
+        const match = this.matchRestRoute(req.url.pathname, req.method);
+        if (!match.result) {
+            // no matching route found
+            if (req.method === 'GET') {
+                // look for a static file
+                const staticFile = this.serveData.files.get(req.url.pathname) ??
+                    this.serveData.files.get('__fallback');
+                if (staticFile !== undefined) {
+                    const ifNoneMatch = req.headers['if-none-match'];
+                    const clientEtag = Array.isArray(ifNoneMatch)
+                        ? ifNoneMatch[0]
+                        : ifNoneMatch;
+                    if (clientEtag === staticFile.etag) {
+                        return {
+                            status: 304,
+                            body: Buffer.alloc(0),
+                            headers: {
+                                etag: staticFile.etag,
+                                'cache-control': staticFile.cacheControl,
+                            },
+                        };
+                    }
+                    return {
+                        status: 200,
+                        body: staticFile.data,
+                        headers: {
+                            'content-type': staticFile.mime,
+                            etag: staticFile.etag,
+                            'cache-control': staticFile.cacheControl,
+                        },
+                    };
+                }
+                if (this.serveData.fallback !== undefined) {
+                    try {
+                        const response = await this.serveData.fallback({
+                            href: req.url.href,
+                        });
+                        return {
+                            status: response.status ?? 200,
+                            body: isUint8Array(response.body)
+                                ? response.body
+                                : Buffer.from(response.body, 'utf-8'),
+                            headers: response.headers,
+                        };
+                    }
+                    catch (error) {
+                        if (error instanceof HttpError) {
+                            return BuiltApp.errorResponse(error.status, error.message, error.code);
+                        }
+                        console.error(error);
+                        return BuiltApp.errorResponse(500, 'Internal Server Error.');
+                    }
+                }
+            }
+            if (match.invalidMethod) {
+                // we found a route, but it did not match the request method
+                return BuiltApp.errorResponse(405, `Method ${req.method} not allowed for path \`${req.url.pathname}\`.`);
+            }
+            return BuiltApp.errorResponse(404, `Path \`${req.url.pathname}\` not found.`);
+        }
+        try {
+            return await match.result.endpoint.handle({
+                url: req.url.pathname,
+                body: req.body,
+                params: match.result.params,
+                query: Object.fromEntries(req.url.searchParams),
+                headers: Object.fromEntries(Object.entries(req.headers).map(([key, value]) => [
+                    key,
+                    Array.isArray(value) ? value.join(',') : (value ?? ''),
+                ])),
+            });
+        }
+        catch (error) {
+            if (error instanceof HttpError) {
+                return BuiltApp.errorResponse(error.status, error.message, error.code);
+            }
+            console.error(error);
+            return BuiltApp.errorResponse(500, 'Internal Server Error.');
+        }
+    }
+    static errorResponse(status, errorMessage, code) {
+        const defaultCodes = new Map([
+            [400, 'bad_request'],
+            [401, 'unauthorized'],
+            [402, 'payment_required'],
+            [403, 'forbidden'],
+            [404, 'not_found'],
+            [405, 'method_not_allowed'],
+            [409, 'conflict'],
+            [500, 'internal_server_error'],
+        ]);
+        return {
+            status,
+            body: {
+                status,
+                errorMessage,
+                code: code ?? defaultCodes.get(status) ?? 'unknown_error',
+            },
+        };
+    }
+    matchRestRoute(url, method) {
+        let invalidMethod = false;
+        let result;
+        for (const route of this.restRoutes) {
+            const match = route.path.match(url);
+            if (match === undefined) {
+                continue;
+            }
+            const { params, score } = match;
+            if (route.endpoint.method !== method) {
+                invalidMethod = true;
+                continue;
+            }
+            const previous = result?.score;
+            if (previous === undefined || score < previous) {
+                // if there was no previous match or this one is better, use it
+                result = { endpoint: route.endpoint, params, score };
+            }
+        }
+        return { invalidMethod, result };
+    }
+    track(method, status, duration) {
+        const id = `${method}-${status}`;
+        const data = this.requestData[id] ?? { count: 0, duration: 0 };
+        this.requestData[id] = {
+            count: data.count + 1,
+            duration: data.duration + duration,
+        };
+    }
+    metrics() {
+        return Object.entries(this.requestData)
+            .map(([key, data]) => {
+            const [method, status] = key.split('-');
+            return `yedra_requests_total{method="${method}",status="${status}"} ${data?.count}
+yedra_request_duration_sum{method="${method}",status="${status}"} ${data?.duration}
+`;
+        })
+            .join('');
+    }
+    listen(port, options) {
+        const server = options?.tls === undefined
+            ? createHttpServer()
+            : createHttpsServer({
+                key: options.tls.key,
+                cert: options.tls.cert,
+            });
+        const counter = new Counter();
+        server.on('request', (req, res) => {
+            counter.increment();
+            const extractedContext = propagation.extract(context.active(), req.headers);
+            context.with(extractedContext, () => trace.getTracer('yedra').startActiveSpan('incoming_request', {
+                kind: SpanKind.SERVER,
+            }, (span) => {
+                this.handle(req, res);
+                res.on('close', () => {
+                    span.setAttribute('http.method', req.method ?? 'UNKNOWN');
+                    span.setAttribute('http.url', req.url ?? 'UNKNOWN');
+                    span.setAttribute('http.status_code', res.statusCode);
+                    span.end();
+                    counter.decrement();
+                });
+            }));
+        });
+        const wss = new WebSocketServer({ server });
+        wss.on('connection', (ws, req) => {
+            const extractedContext = propagation.extract(context.active(), req.headers);
+            context.with(extractedContext, () => trace.getTracer('yedra').startActiveSpan('incoming_ws_connection', {
+                kind: SpanKind.SERVER,
+            }, async (span) => {
+                span.setAttribute('http.url', req.url ?? 'UNKNOWN');
+                let ended = false;
+                const end = () => {
+                    if (ended) {
+                        return;
+                    }
+                    ended = true;
+                    span.end();
+                };
+                ws.once('close', end);
+                const url = new URL(req.url, 'http://localhost');
+                const { result } = this.matchWsRoute(url.pathname);
+                if (!result) {
+                    ws.close(4404);
+                    end();
+                    return;
+                }
+                try {
+                    const headers = Object.fromEntries(Object.entries(req.headers).map(([key, value]) => [
+                        key,
+                        Array.isArray(value) ? value.join(',') : (value ?? ''),
+                    ]));
+                    await result.endpoint.handle(url, result.params, headers, ws);
+                }
+                catch (error) {
+                    if (error instanceof HttpError) {
+                        ws.close(4000 + error.status, error.message);
+                    }
+                    else {
+                        console.error(error);
+                        ws.close(1011, 'Internal Error');
+                    }
+                }
+            }));
+        });
+        server.listen(port, () => {
+            if (this.quiet !== true) {
+                console.log(`yedra listening on http://localhost:${port}`);
+            }
+        });
+        if (options?.metrics !== undefined) {
+            const metricsEndpoint = options.metrics;
+            const metricsServer = createHttpServer();
+            metricsServer.on('request', async (req, res) => {
+                if (req.method === 'GET' && req.url === metricsEndpoint.path) {
+                    res.writeHead(200, {
+                        'content-type': 'text/plain; version=0.0.4; charset=utf-8; escaping=underscores',
+                    });
+                    res.write(this.metrics());
+                    if (metricsEndpoint.get !== undefined) {
+                        res.write(await metricsEndpoint.get());
+                    }
+                    res.end();
+                }
+                else {
+                    res.writeHead(404);
+                    res.end('Not found');
+                }
+            });
+            metricsServer.listen(metricsEndpoint.port, () => {
+                if (this.quiet !== true) {
+                    console.log(`yedra metrics on http://localhost:${metricsEndpoint.port}${metricsEndpoint.path}`);
+                }
+            });
+        }
+        return new Context(server, wss, counter, this.docs);
+    }
+    matchWsRoute(url) {
+        let result;
+        for (const route of this.wsRoutes) {
+            const match = route.path.match(url);
+            if (match === undefined) {
+                continue;
+            }
+            const { params, score } = match;
+            const previous = result?.score;
+            if (previous === undefined || score < previous) {
+                // if there was no previous match or this one is better, use it
+                result = { endpoint: route.endpoint, params, score };
+            }
+        }
+        return { result };
+    }
+}
+export class Yedra {
+    constructor() {
+        this.restRoutes = [];
+        this.wsRoutes = [];
+    }
+    use(path, endpoint) {
+        if (endpoint instanceof Yedra) {
+            for (const route of endpoint.restRoutes) {
+                const newPath = route.path.withPrefix(path);
+                this.restRoutes.push({
+                    path: newPath,
+                    endpoint: route.endpoint,
+                });
+            }
+            for (const route of endpoint.wsRoutes) {
+                const newPath = route.path.withPrefix(path);
+                this.wsRoutes.push({ path: newPath, endpoint: route.endpoint });
+            }
+        }
+        else if (endpoint instanceof RestEndpoint) {
+            this.restRoutes.push({ path: new Path(path), endpoint });
+        }
+        else if (endpoint instanceof WsEndpoint) {
+            this.wsRoutes.push({ path: new Path(path), endpoint });
+        }
+        else {
+            throw new Error('Invalid endpoint argument.');
+        }
+        return this;
+    }
+    generateDocs(options) {
+        // this set will be filled with the security schemes from all endpoints
+        const securitySchemes = new Set();
+        // Wrap path generation in collectLazySchemas so that any LazySchema
+        // whose documentation() is called will register its full definition.
+        const { result: paths, schemas } = collectLazySchemas(() => {
+            const paths = {};
+            for (const route of this.restRoutes) {
+                if (route.endpoint.isHidden()) {
+                    // do not include hidden endpoints in the documentation
+                    continue;
+                }
+                const path = route.path.toString();
+                const methods = paths[path] ?? {};
+                methods[route.endpoint.method.toLowerCase()] =
+                    route.endpoint.documentation(path, securitySchemes);
+                paths[path] = methods;
+            }
+            return paths;
+        });
+        return {
+            openapi: '3.0.2',
+            info: {
+                title: options?.title ?? 'Yedra API',
+                description: options?.description ??
+                    'This is an OpenAPI documentation generated automatically by Yedra.',
+                version: options?.version ?? '0.1.0',
+            },
+            components: {
+                securitySchemes: Object.fromEntries(securitySchemes
+                    .values()
+                    .map((scheme) => [scheme.name, scheme.scheme])),
+                schemas: Object.fromEntries(schemas),
+            },
+            servers: options?.servers ?? [],
+            paths,
+        };
+    }
+    static async loadServe(config) {
+        if (config === undefined) {
+            return {
+                files: new Map(),
+                fallback: undefined,
+            };
+        }
+        const staticFiles = new Map();
+        let files;
+        try {
+            files = await readdir(config.dir, { recursive: true });
+        }
+        catch (_error) {
+            files = [];
+        }
+        const revalidate = 'public, max-age=0, must-revalidate';
+        await Promise.all(files.map(async (file) => {
+            const absolute = join(config.dir, file);
+            if (!(await stat(absolute)).isFile()) {
+                return;
+            }
+            const data = await readFile(absolute);
+            const urlPath = `/${file}`;
+            const cacheControl = config.immutable !== undefined && config.immutable.pattern.test(file)
+                ? `public, max-age=${config.immutable.maxAge}, immutable`
+                : revalidate;
+            staticFiles.set(urlPath, {
+                data,
+                mime: mime.getType(extname(file)) ?? 'application/octet-stream',
+                etag: `"${createHash('sha1').update(data).digest('hex')}"`,
+                cacheControl,
+            });
+        }));
+        if (config.fallback) {
+            if (typeof config.fallback === 'string') {
+                const data = await readFile(config.fallback);
+                staticFiles.set('__fallback', {
+                    data,
+                    mime: mime.getType(extname(config.fallback)) ??
+                        'application/octet-stream',
+                    etag: `"${createHash('sha1').update(data).digest('hex')}"`,
+                    cacheControl: revalidate,
+                });
+                return {
+                    files: staticFiles,
+                    fallback: undefined,
+                };
+            }
+            return {
+                files: staticFiles,
+                fallback: config.fallback,
+            };
+        }
+        return {
+            files: staticFiles,
+            fallback: undefined,
+        };
+    }
+    async build(options) {
+        const serveData = await Yedra.loadServe(options?.serve);
+        const docs = this.generateDocs(options?.docs);
+        return new BuiltApp({
+            serveData,
+            docs,
+            connectMiddlewares: options?.connectMiddlewares ?? [],
+            quiet: options?.quiet ?? false,
+            restRoutes: this.restRoutes,
+            wsRoutes: this.wsRoutes,
+        });
+    }
+    async listen(port, options) {
+        const app = await this.build({
+            docs: options?.docs,
+            serve: options?.serve,
+            quiet: options?.quiet,
+            connectMiddlewares: options?.connectMiddlewares,
+        });
+        return app.listen(port, options);
+    }
+}
+/**
+ * TODO: how do we add OpenTelemetry instrumentation here?
+ * We need two things:
+ * 1. Start active span for each incoming request, and end after response is sent.
+ * 2. Extract context from incoming requests to propagate traces.
+ */

package/dist/src/routing/env.d.ts

@@ -0,0 +1,4 @@
+import type { Typeof } from '../validation/body.js';
+import { type ObjectSchema } from '../validation/object.js';
+import type { Schema } from '../validation/schema.js';
+export declare const parseEnv: <T extends Record<string, Schema<unknown>>>(shape: T) => Typeof<ObjectSchema<T>>;

package/dist/src/routing/env.js

@@ -0,0 +1,13 @@
+import { ValidationError } from '../validation/error.js';
+import { laxObject } from '../validation/object.js';
+export const parseEnv = (shape) => {
+    try {
+        return laxObject(shape).parse(process.env);
+    }
+    catch (error) {
+        if (error instanceof ValidationError) {
+            console.error(`error: env validation failed: ${error.format()}`);
+        }
+        process.exit(1);
+    }
+};

package/dist/src/routing/errors.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Base class for errors that will be handled as HTTP status codes.
+ */
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly code: string | undefined;
+    constructor(status: number, message: string, code?: string);
+}
+/**
+ * Indicates a malformed request.
+ * Corresponds to HTTP status code 400 Bad Request.
+ */
+export declare class BadRequestError extends HttpError {
+    constructor(message: string, code?: string);
+}
+/**
+ * Indicates missing or invalid credentials.
+ * Corresponds to HTTP status code 401 Unauthorized.
+ */
+export declare class UnauthorizedError extends HttpError {
+    constructor(message: string, code?: string);
+}
+/**
+ * Indicates that some kind of payment is required.
+ * Corresponds to HTTP status code 402 Payment Required.
+ */
+export declare class PaymentRequiredError extends HttpError {
+    constructor(message: string, code?: string);
+}
+/**
+ * Indicates that the user is not allowed to do something.
+ * Corresponds to HTTP status code 403 Forbidden.
+ */
+export declare class ForbiddenError extends HttpError {
+    constructor(message: string, code?: string);
+}
+/**
+ * Indicates that the requested resource does not exist.
+ * Corresponds to HTTP status code 404 Not Found.
+ */
+export declare class NotFoundError extends HttpError {
+    constructor(message: string, code?: string);
+}
+/**
+ * Indicates that the action conflicts with the current state.
+ * Corresponds to HTTP status code 409 Conflict.
+ */
+export declare class ConflictError extends HttpError {
+    constructor(message: string, code?: string);
+}

package/dist/src/routing/errors.js

@@ -0,0 +1,64 @@
+/**
+ * Base class for errors that will be handled as HTTP status codes.
+ */
+export class HttpError extends Error {
+    constructor(status, message, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+/**
+ * Indicates a malformed request.
+ * Corresponds to HTTP status code 400 Bad Request.
+ */
+export class BadRequestError extends HttpError {
+    constructor(message, code) {
+        super(400, message, code);
+    }
+}
+/**
+ * Indicates missing or invalid credentials.
+ * Corresponds to HTTP status code 401 Unauthorized.
+ */
+export class UnauthorizedError extends HttpError {
+    constructor(message, code) {
+        super(401, message, code);
+    }
+}
+/**
+ * Indicates that some kind of payment is required.
+ * Corresponds to HTTP status code 402 Payment Required.
+ */
+export class PaymentRequiredError extends HttpError {
+    constructor(message, code) {
+        super(402, message, code);
+    }
+}
+/**
+ * Indicates that the user is not allowed to do something.
+ * Corresponds to HTTP status code 403 Forbidden.
+ */
+export class ForbiddenError extends HttpError {
+    constructor(message, code) {
+        super(403, message, code);
+    }
+}
+/**
+ * Indicates that the requested resource does not exist.
+ * Corresponds to HTTP status code 404 Not Found.
+ */
+export class NotFoundError extends HttpError {
+    constructor(message, code) {
+        super(404, message, code);
+    }
+}
+/**
+ * Indicates that the action conflicts with the current state.
+ * Corresponds to HTTP status code 409 Conflict.
+ */
+export class ConflictError extends HttpError {
+    constructor(message, code) {
+        super(409, message, code);
+    }
+}

package/dist/src/routing/log.d.ts

@@ -0,0 +1,22 @@
+export declare class Log {
+    /**
+     * Output a debug message.
+     * @param args - The message.
+     */
+    debug(...args: unknown[]): void;
+    /**
+     * Output an informational message.
+     * @param args - The message.
+     */
+    info(...args: unknown[]): void;
+    /**
+     * Output a warning message.
+     * @param args - The message.
+     */
+    warning(...args: unknown[]): void;
+    /**
+     * Output an error message.
+     * @param args - The message.
+     */
+    error(...args: unknown[]): void;
+}