yedra 0.20.10 → 0.20.12

package/dist/routing/app.d.ts

@@ -15,6 +15,8 @@ declare class Context {
 type ServeFile = {
     data: Buffer;
     mime: string;
+    etag: string;
+    cacheControl: string;
 };
 type ServeResponse = {
     status?: number;
@@ -27,6 +29,16 @@ type ServeFallback = (req: {
 type ServeConfig = {
     dir: string;
     fallback?: string | ServeFallback;
+    /**
+     * Files matching `pattern` are served with `Cache-Control: public,
+     * max-age=<maxAge>, immutable`. Intended for content-addressed assets
+     * (e.g. `app.abc12345.js`) whose URL changes when the content changes.
+     * Never matches the fallback file.
+     */
+    immutable?: {
+        pattern: RegExp;
+        maxAge: number;
+    };
 };
 type ServeData = {
     files: Map<string, ServeFile>;

package/dist/routing/app.js

@@ -1,3 +1,4 @@
+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';
@@ -135,11 +136,27 @@ class BuiltApp {
                 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,
                         },
                     };
                 }
@@ -275,29 +292,45 @@ yedra_request_duration_sum{method="${method}",status="${status}"} ${data?.durati
             }));
         });
         const wss = new WebSocketServer({ server });
-        wss.on('connection', async (ws, req) => {
-            const url = new URL(req.url, 'http://localhost');
-            const { result } = this.matchWsRoute(url.pathname);
-            if (!result) {
-                ws.close(4404);
-                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);
+        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;
                 }
-                else {
-                    console.error(error);
-                    ws.close(1011, 'Internal Error');
+                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) {
@@ -431,15 +464,22 @@ export class Yedra {
         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);
-            staticFiles.set(`/${file}`, {
+            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) {
@@ -449,6 +489,8 @@ export class Yedra {
                     data,
                     mime: mime.getType(extname(config.fallback)) ??
                         'application/octet-stream',
+                    etag: `"${createHash('sha1').update(data).digest('hex')}"`,
+                    cacheControl: revalidate,
                 });
                 return {
                     files: staticFiles,

package/dist/routing/rest.d.ts

@@ -6,9 +6,11 @@ import { type ObjectSchema } from '../validation/object.js';
 import type { Schema } from '../validation/schema.js';
 type ReqObject<Params, Query, Headers, Body> = {
     url: string;
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
     params: Params;
     query: Query;
     headers: Headers;
+    rawHeaders: Record<string, string>;
     body: Body;
 };
 type ResObject<Body> = Promise<{

package/dist/routing/rest.js

@@ -84,12 +84,14 @@ class ConcreteRestEndpoint extends RestEndpoint {
         }
         return await this.options.do({
             url: req.url,
+            method: this._method,
             // biome-ignore lint/style/noNonNullAssertion: this is required to convince TypeScript that this is initialized
             params: parsedParams,
             // biome-ignore lint/style/noNonNullAssertion: this is required to convince TypeScript that this is initialized
             query: parsedQuery,
             // biome-ignore lint/style/noNonNullAssertion: this is required to convince TypeScript that this is initialized
             headers: parsedHeaders,
+            rawHeaders: req.headers,
             // biome-ignore lint/style/noNonNullAssertion: this is required to convince TypeScript that this is initialized
             body: parsedBody,
         });

package/dist/src/index.d.ts

@@ -0,0 +1,9 @@
+import * as y from './lib.js';
+export { y };
+export type { ConnectMiddleware } from './routing/app.js';
+export { Yedra } from './routing/app.js';
+export { BadRequestError, ConflictError, ForbiddenError, HttpError, NotFoundError, PaymentRequiredError, UnauthorizedError, } from './routing/errors.js';
+export { Delete, Get, Patch, Post, Put } from './routing/rest.js';
+export type { YedraWebSocket } from './routing/websocket.js';
+export { Ws } from './routing/websocket.js';
+export { SecurityScheme } from './util/security.js';

package/dist/src/index.js

@@ -0,0 +1,7 @@
+import * as y from './lib.js';
+export { y };
+export { Yedra } from './routing/app.js';
+export { BadRequestError, ConflictError, ForbiddenError, HttpError, NotFoundError, PaymentRequiredError, UnauthorizedError, } from './routing/errors.js';
+export { Delete, Get, Patch, Post, Put } from './routing/rest.js';
+export { Ws } from './routing/websocket.js';
+export { SecurityScheme } from './util/security.js';

package/dist/src/lib.d.ts

@@ -0,0 +1,10 @@
+export { BadRequestError, ConflictError, ForbiddenError, HttpError, NotFoundError, PaymentRequiredError, UnauthorizedError, } from './routing/errors.js';
+export { Log } from './routing/log.js';
+export * from './schema-lib.js';
+export declare const validatePath: (path: string) => void;
+export { parseEnv } from './routing/env.js';
+export { SecurityScheme } from './util/security.js';
+export { either } from './validation/either.js';
+export { json } from './validation/json.js';
+export { raw } from './validation/raw.js';
+export { stream } from './validation/stream.js';

package/dist/src/lib.js

@@ -0,0 +1,16 @@
+import { Path } from './routing/path.js';
+// routing
+export { BadRequestError, ConflictError, ForbiddenError, HttpError, NotFoundError, PaymentRequiredError, UnauthorizedError, } from './routing/errors.js';
+export { Log } from './routing/log.js';
+// validation (browser-safe, shared with yedra/schema)
+export * from './schema-lib.js';
+export const validatePath = (path) => {
+    new Path(path);
+};
+export { parseEnv } from './routing/env.js';
+export { SecurityScheme } from './util/security.js';
+// Node-only body types
+export { either } from './validation/either.js';
+export { json } from './validation/json.js';
+export { raw } from './validation/raw.js';
+export { stream } from './validation/stream.js';

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

@@ -0,0 +1,165 @@
+import type { IncomingMessage, Server, ServerResponse } from 'node:http';
+import { WebSocketServer } from 'ws';
+import { Counter } from '../util/counter.js';
+import { Path } from './path.js';
+import { RestEndpoint } from './rest.js';
+import { WsEndpoint } from './websocket.js';
+declare class Context {
+    private readonly server;
+    private readonly wss;
+    private readonly counter;
+    readonly docs: object;
+    constructor(server: Server, wss: WebSocketServer, counter: Counter, docs: object);
+    stop(): Promise<void>;
+}
+type ServeFile = {
+    data: Buffer;
+    mime: string;
+    etag: string;
+    cacheControl: string;
+};
+type ServeResponse = {
+    status?: number;
+    body: Uint8Array | string;
+    headers?: Record<string, string>;
+};
+type ServeFallback = (req: {
+    href: string;
+}) => ServeResponse | Promise<ServeResponse>;
+type ServeConfig = {
+    dir: string;
+    fallback?: string | ServeFallback;
+    /**
+     * Files matching `pattern` are served with `Cache-Control: public,
+     * max-age=<maxAge>, immutable`. Intended for content-addressed assets
+     * (e.g. `app.abc12345.js`) whose URL changes when the content changes.
+     * Never matches the fallback file.
+     */
+    immutable?: {
+        pattern: RegExp;
+        maxAge: number;
+    };
+};
+type ServeData = {
+    files: Map<string, ServeFile>;
+    fallback: ServeFallback | undefined;
+};
+type DocsData = {
+    /**
+     * The title of your API.
+     */
+    title: string;
+    /**
+     * The description of your API.
+     */
+    description: string;
+    /**
+     * The current version of your API.
+     */
+    version: string;
+    /**
+     * The list of servers your API is reachable under.
+     */
+    servers?: {
+        description: string;
+        url: string;
+    }[];
+};
+export type ConnectMiddleware = (req: IncomingMessage, res: ServerResponse, next: () => void) => void;
+type RestRoute = {
+    path: Path;
+    endpoint: RestEndpoint;
+};
+type WsRoute = {
+    path: Path;
+    endpoint: WsEndpoint;
+};
+declare class BuiltApp {
+    private serveData;
+    private docs;
+    private generatedDocs;
+    private connectMiddlewares;
+    private quiet;
+    private restRoutes;
+    private wsRoutes;
+    private requestData;
+    constructor(options: {
+        serveData: ServeData;
+        docs: object;
+        connectMiddlewares: ConnectMiddleware[];
+        quiet: boolean;
+        restRoutes: RestRoute[];
+        wsRoutes: WsRoute[];
+    });
+    private static middlewareNext;
+    handle(req: IncomingMessage, res: ServerResponse): void;
+    private performRequest;
+    private static errorResponse;
+    private matchRestRoute;
+    private track;
+    metrics(): string;
+    listen(port: number, options?: {
+        tls?: {
+            key: string;
+            cert: string;
+        };
+        metrics?: {
+            port: number;
+            path: string;
+            get?: () => Promise<string> | string;
+        };
+    }): Context;
+    private matchWsRoute;
+}
+export declare class Yedra {
+    private restRoutes;
+    private wsRoutes;
+    use(path: string, endpoint: RestEndpoint | WsEndpoint | Yedra): Yedra;
+    private generateDocs;
+    private static loadServe;
+    build(options?: {
+        /**
+         * Configuration for the `/openapi.json` endpoint, which generates
+         * OpenAPI documentation.
+         */
+        docs?: DocsData;
+        quiet?: boolean;
+        serve?: ServeConfig;
+        /**
+         * Add Express/Connect compatible middleware.
+         */
+        connectMiddlewares?: ConnectMiddleware[];
+    }): Promise<BuiltApp>;
+    listen(port: number, options?: {
+        tls?: {
+            key: string;
+            cert: string;
+        };
+        metrics?: {
+            port: number;
+            path: string;
+            get?: () => Promise<string> | string;
+        };
+        /**
+         * Configuration for the `/openapi.json` endpoint, which generates
+         * OpenAPI documentation.
+         */
+        docs?: DocsData;
+        serve?: ServeConfig;
+        /**
+         * Prevents all normal output from Yedra. Mostly useful for tests.
+         */
+        quiet?: boolean;
+        /**
+         * Add Express/Connect compatible middleware.
+         */
+        connectMiddlewares?: ConnectMiddleware[];
+    }): Promise<Context>;
+}
+export {};
+/**
+ * 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.
+ */