barehttp 1.0.0 → 2.1.0

package/README.md

@@ -49,22 +49,29 @@ yarn add barehttp
 ```typescript
 import { BareHttp, logMe } from 'barehttp';
 
-const app = new BareHttp({ logging: false });
+const app = new BareHttp();
 
 app.route.get({
   route: '/route',
-  handler: function routeV1(flow) {
-    flow.json({ everythings: 'OK' });
+  handler: function routeGet(flow) {
+    flow.json({ everything: 'OK' });
   })
 });
 
 
-app.route.post({
-  route: '/route',
-  handler: async function routeV1(flow) {
-    return 'JUST MESSAGE';
-  },
-});
+// you can chain the routes
+app.route
+  .post({
+    route: '/route',
+    handler: async function routePost(flow) {
+      return 'RESPONSE POST';
+    },
+  })
+  .route.patch({
+    route: '/route',
+    handler: async function routePatch(flow) {
+      return 'RESPONSE PATCH';
+  })
 
 // Define a middleware
 app.use((flow) => {
@@ -81,16 +88,19 @@ app.start((address) => {
 ```typescript
 import { BareHttp, logMe } from 'barehttp';
 
-const app = new BareHttp({ logging: false });
+const app = new BareHttp({ logging: true });
 
-app.route.get('/route', async function routeV1() {
-  return { promised: 'data' };
+ app.route.get({
+  route:'/route',
+  handler: async function routeV1() {
+    return { promised: 'data' };
+  })
 });
 
 // Define a middleware
 app.use(async (flow) => {
   logMe.info('my middleware');
-  await someAuthentication();
+  await someAuthenticationFlow();
 });
 
 app.start((address) => {
@@ -108,7 +118,7 @@ An instance of the application
 
 Options submitted to the server at initialization
 
-#### `middlewares?` (Array<(flow: BareRequest) => Promise<void> | void>):
+#### `middlewares?` (Array<(flow: BareRequest) => Promise<void> | void>)
 
 If provided, this will apply an array of middlewares to each incoming request.
 The order of the array is the order of middlewares to apply
@@ -137,11 +147,21 @@ Default `false`
 
 Enable request/response logging, format varies from `production` or `development` environments, though to change use e.g. `NODE_ENV=production`
 
+#### `ws?` (Boolean)
+
+Default `false`
+
+Enable WebSocket support through `ws` package.
+
+#### `wsOptions?` (Object)
+
+Refer to [ws](https://github.com/websockets/ws) documentation.
+
 #### `errorHandlerMiddleware?` ((err: any, flow: BareRequest) => void)
 
 If provided, will set a custom error handler to catch the bubbled errors from the handlers
 
-#### `errorHandlerMiddleware?` (String: 's' | 'ms')
+#### `requestTimeFormat?` (String: 's' | 'ms')
 
 Default `'s'` - seconds
 
@@ -160,26 +180,30 @@ To set options for the cookies decoding/encoding
 If enabled, and also with `logging: true`, will try to log the resolved reverse DNS of the first hop for remote ip of the client (first proxy).
 Logs follow an [Apache Common Log Format](https://httpd.apache.org/docs/2.4/logs.html)
 
-#### `statisticReport?` (Boolean)
+#### `statisticsReport?` (Boolean)
 
 Default `false`
 
 Exposes a basic report with the routes usage under `GET /_report` route
 
-### `BareServer.use` ((flow: BareRequest) => Promise<void> | void)
+---
+
+## `BareServer.use` ((flow: BareRequest) => Promise<void> | void)
 
 Attach a middleware `after` the middlewares optional array.
 The order of the middlewares is followed by code declarations order.
 
-### `BareServer.route` (Object)
+---
+
+## `BareServer.route.get | post | patch | put | delete | options | head | declare` (Function)
 
 To set a route for `get | post | patch | put | delete | options | head` with following parameters:
 
 - `route` (String) - should follow a format of `/your_route`, including params as `/your_route/:param`
 - `options` (Object) - `RouteOptions`
 - `handler` (Function) - A function with the signature `(flow: BareRequest) => Promise<any> | any`
-
-Example
+- `method` (Array) - if the method is `declare` you have to indicate an array of methods to declare the route e.g. `['get', 'post']`
+  Example
 
 ```ts
 app.route.get({
@@ -189,6 +213,36 @@ app.route.get({
     return 'My route response';
   },
 });
+
+app.route.declare({
+  route: '/declared_route',
+  handler: () => {
+    return 'My declared route response';
+  },
+  methods: ['post', 'patch'],
+});
+```
+
+## `BareServer.runtimeRoute.get | post | patch | put | delete | options | head | declare` (Function)
+
+Same as the above routes API, but you can only declare them when the server is `listening`
+
+```ts
+app.runtimeRoute
+  .get({
+    route: '/route',
+    options: { timeout: 2000 },
+    handler: async (flow) => {
+      return 'My route response';
+    },
+  })
+  .declare({
+    route: '/declared_runtime_route',
+    handler: () => {
+      return 'My declared runtime route response';
+    },
+    methods: ['post', 'patch'],
+  });
 ```
 
 #### `RouteOptions` (Object)
@@ -201,16 +255,76 @@ Disables all cache headers for the response. This overrides any other cache sett
 
 ##### `cache?` (CacheOptions)
 
-If set, provides a granular cache handling per route.
+If set, provides a granular cache headers handling per route.
 
 ##### `timeout?` (Number)
 
 Request timeout value in `ms`. This will cancel the request _only_ for this route if time expired
 
+---
+
+## `BareServer.ws?` (WebSocketServer)
+
+Based on `ws` package, for internals please refer to [external WebSocketServer](https://github.com/websockets/ws#external-https-server) for documentation.
+
+This particular implementation works out easily for WebSockets interaction for pushing data to server from the clients and waiting for some answer in async.
+
+Also exposes an way to keep pushing messages to the Client from the Server on server handle through internal clients list. (WIP optimizing this)
+
+### `WebSocketServer.declareReceiver` ((Data, UserClient, WSClient, MessageEvent) => Promise\<M> | M)
+
+This is the main 'handler' function for any kind of Client request. If there's a response to that push from the client the return should contain it, otherwise if the response is `void` there will be no answer to the client side.
+
+- `Data`: is the data received from the client for this exact `Type`
+- `UserClient`: is an optional client defined on the stage of `Upgrade` to provide some closured client data to be able to know what Client is exactly making the request to the Server
+- `WSClient`: raw instance of `ws.Client & { userClient: UC }`
+- `MessageEvent`: raw instance of `ws.MessageClient`
+
+Code Example:
+
+```ts
+app.ws?.declareReceiver<{ ok: string }>({
+  type: 'BASE_TYPE',
+  handler: async (data, client) => {
+    // do your async or sync operations here
+    // return the response if you need to send an answer
+    return { cool: 'some answer', client };
+  },
+});
+```
+
+### `WebSocketServer.defineUpgrade` ((IncomingRequest) => Promise\<M> | M)
+
+To de able to handle authorization or any other previous operation before opening and upgrading an incoming client's request.
+**If this function is not initialized with the callback, all incoming connections will be accepted by default**
+
+```ts
+app.ws?.defineUpgrade(async (req) => {
+  // you can do some async or sync operation here
+  // the returning of this function will be
+  // defined as the `UserClient` and attached to the `ws.Client` instance
+  return { access: true, client: {...properties of the client} };
+});
+```
+
+---
+
 ## `BareRequest` (Class)
 
 An instance of the request passed through to middlewares and handlers
 
+### `cm?` (CookiesManager)
+
+Access to the CookiesManager instance attached to the request.
+
+#### `CookiesManager` (Class)
+
+Internal methods to work with cookies
+
+##### `setCookie` (Function)
+
+##### `clearCookie` (Function)
+
 ### `getHeader` (Function)
 
 Get an exact header stored to return with this request to the client
@@ -231,21 +345,29 @@ Imperatively disables cache, does the same as `disableCache: true` in `RouteOpti
 
 Imperatively sets the cache, does the same as `cache: CacheOptions` in `RouteOptions`
 
+### `addHeader` (Function)
+
+Adds a header outgoing header string as a (key, value) `addHeader(header, value)`. Can **not** overwrite.
+
+### `addHeaders` (Function)
+
+Adds outgoing headers in a "batch", merges provided headers object `{ [header: string]: value }` to already existing headers. Can **not** overwrite.
+
 ### `setHeader` (Function)
 
-Set outgoing header as a (key, value) arguments `setHeader(header, value)`. Can overwrite
+Does the same as `addHeader` but overrides the value.
 
 ### `setHeaders` (Function)
 
-Set outgoing headers in a "batch", merges provided headers object `{ [header: string]: value }` to already existing headers. Can overwrite
+Does the same as `addHeaders` but overrides the value.
 
 ### `status` (Function)
 
-Set a status for the outgoing request
+Set a status for the response
 
 ### `sendStatus` (Function)
 
-Set a status for the outgoing request and send it (end the request)
+Set a status for the response and send it (end the request)
 
 ### `stream` (Function)
 
@@ -265,19 +387,54 @@ Some of the features are in progress.
 
 - [x] Request wide context storage and incorporated tracing (ready for cloud)
 - [x] UID (adopted or generated)
+- [x] WebSocket server exposure
+- [x] handy WebSocket interaction tools, for authorization, etc.
 - [x] Request-Processing-Time header and value
 - [x] Promised or conventional middlewares
 - [x] Logging and serialized with `pino`
 - [x] Routes usage report and endpoint
 - [x] Cache headers handy handling, per route
 - [x] Cookies creation/parsing
+- [x] CORS middleware options
 - [x] Request execution cancellation by timeout
-- [ ] Streaming of chunked multipart response
-- [ ] Safe and fast serialization-deserialization of JSON
+- [x] Bulk/chaining routes declaration
+- [x] Runtime routes hot swapping
+- [x] runtime validation schema generation per route response types (on project compile/on launch)
+- [ ] middlewares per route
+- [ ] swagger OpenAPI 3.0 on `/docs` endpoint
+- [ ] swagger OpenAPI 3.0 scheme on `/docs_raw` endpoint
+- [ ] optional export of generated schema to a location (yaml, json)
+- [ ] streaming/receiving of chunked multipart
+- [ ] runtime route params or query validation upon declared types (on project compile/on launch)
+
+## Runtime schema validation on response (EXPERIMENTAL)
+
+This feature enables a runtime check for the returned value for a route,
+for now it only works for `return` statements of the routes declared in handlers.
+
+Please write your `return` statements with plain response objects within the `handler` or `controller` function.
+
+To enable this feature you need to set up the following:
+
+- On `BareHttp` settings set: `enableSchemaValidation: true`
+- On `BareHttp` settings set: `declaredRoutesPaths: [...array of paths to routes]`,
+- On `route.<method>` declaration set: `options: { builtInRuntime: { output: true } }`
 
 ## Benchmarks
 
-WIP
+Done on MacBook Pro with M1 Pro processor. No logs enabled. `NODE_ENV=production` is set. All settings set to default.
+
+### BareHttp
+
+![BareHttp](./docs/barehttp.png)
+
+### Express
+
+![Express](./docs/express.png)
+
+### Fastify
+
+![Fastify](./docs/fastify.png)
 
 ## Support
 

package/lib/context/execution.d.ts

@@ -0,0 +1,7 @@
+export declare class Execution {
+    id: string;
+    type: string;
+    store: Map<string, string | number>;
+    headers: Map<string, string | number>;
+    constructor(type: string);
+}

package/lib/context/execution.js

@@ -0,0 +1,14 @@
+import hyperid from 'hyperid';
+const generateId = hyperid();
+export class Execution {
+    id;
+    type;
+    store;
+    headers;
+    constructor(type) {
+        this.id = generateId();
+        this.type = type;
+        this.store = new Map();
+        this.headers = new Map();
+    }
+}

package/lib/context/index.d.ts

@@ -0,0 +1,10 @@
+import { Execution } from './execution.js';
+import asyncHooks from 'async_hooks';
+type Context = {
+    current?: Execution;
+    enabled: boolean;
+};
+declare const newContext: (type: string) => void;
+declare const context: Context;
+declare const enableContext: () => asyncHooks.AsyncHook;
+export { context, newContext, enableContext };

package/lib/context/index.js

@@ -0,0 +1,46 @@
+import { Execution } from './execution.js';
+import asyncHooks from 'async_hooks';
+const running = new Map();
+const previous = new Map();
+const newContext = (type) => {
+    if (!context.enabled)
+        return;
+    context.current = new Execution(type);
+    running.set(asyncHooks.executionAsyncId(), context.current);
+};
+const context = {
+    enabled: false,
+};
+function init(asyncId, _type, triggerAsyncId) {
+    if (running.get(triggerAsyncId)) {
+        running.set(asyncId, running.get(triggerAsyncId));
+    }
+}
+function before(asyncId) {
+    if (!running.get(asyncId))
+        return;
+    previous.set(asyncId, context.current);
+    context.current = running.get(asyncId);
+}
+function after(asyncId) {
+    if (!running.get(asyncId))
+        return;
+    context.current = previous.get(asyncId);
+}
+function destroy(asyncId) {
+    if (running.get(asyncId)) {
+        running.delete(asyncId);
+        previous.delete(asyncId);
+    }
+}
+const hook = asyncHooks.createHook({
+    init,
+    before,
+    after,
+    destroy,
+});
+const enableContext = () => {
+    context.enabled = true;
+    return hook.enable();
+};
+export { context, newContext, enableContext };

package/lib/env.d.ts

@@ -0,0 +1,5 @@
+export declare const envs: {
+    isProd: boolean;
+    isDev: boolean;
+    isTest: boolean;
+};

package/lib/env.js

@@ -0,0 +1,5 @@
+export const envs = {
+    isProd: process.env.NODE_ENV === 'production',
+    isDev: process.env.NODE_ENV === 'development',
+    isTest: process.env.NODE_ENV === 'test',
+};

package/lib/index.d.ts

@@ -0,0 +1,5 @@
+export { BareHttp } from './server.js';
+export type { BareHttpType } from './server.js';
+export type { BareRequest } from './request.js';
+export { context } from './context/index.js';
+export { logMe } from './logger/index.js';

package/lib/index.js

@@ -0,0 +1,3 @@
+export { BareHttp } from './server.js';
+export { context } from './context/index.js';
+export { logMe } from './logger/index.js';

package/lib/logger/index.d.ts

@@ -0,0 +1,16 @@
+import { serializeHttp } from './serializers.js';
+interface LogMeFn {
+    (obj: unknown, ...args: []): void;
+    (msg: string, ...args: any[]): void;
+}
+type LogMe = {
+    info: LogMeFn;
+    warn: LogMeFn;
+    error: LogMeFn;
+    fatal: LogMeFn;
+    debug: LogMeFn;
+    trace: LogMeFn;
+};
+export declare const logHttp: (...params: Parameters<typeof serializeHttp>) => void;
+export declare const logMe: LogMe;
+export {};

package/lib/logger/index.js

@@ -0,0 +1,26 @@
+import pino, { destination } from 'pino';
+import { serializeLog, serializeHttp } from './serializers.js';
+import { envs } from '../env.js';
+const asyncDest = envs.isProd ? [destination({ sync: false })] : [];
+const pinoCommonOptions = {
+    timestamp: () => `,"time":"${new Date()[envs.isProd ? 'toISOString' : 'toLocaleTimeString']()}"`,
+    formatters: {
+        level: (label) => ({ level: label }),
+    },
+    messageKey: 'message',
+    transport: envs.isProd ? undefined : { target: 'pino-pretty', options: { colorize: true } },
+};
+const logger = pino(pinoCommonOptions, asyncDest[0]);
+export const logHttp = (...params) => {
+    const { level, logObject } = serializeHttp(...params);
+    logger[level](logObject);
+};
+// TODO: remove the test condition
+export const logMe = {
+    debug: (...args) => !envs.isTest && logger.debug(serializeLog(...args)),
+    info: (...args) => !envs.isTest && logger.info(serializeLog(...args)),
+    warn: (...args) => !envs.isTest && logger.warn(serializeLog(...args)),
+    error: (...args) => !envs.isTest && logger.error(serializeLog(...args)),
+    fatal: (...args) => !envs.isTest && logger.fatal(serializeLog(...args)),
+    trace: (...args) => !envs.isTest && logger.trace(serializeLog(...args)),
+};

package/lib/logger/serializers.d.ts

@@ -0,0 +1,28 @@
+import type { IncomingMessage, ServerResponse } from 'http';
+export declare function parseError(e: any, meta: any): any;
+export declare function serializeLog(...args: any[]): any;
+export declare function getStatusLevel(statusCode: number): "error" | "info" | "warn";
+export declare function serializeHttp(headers: {
+    [k: string]: any;
+}, startDate: Date, remoteClient: string, req: IncomingMessage, res: ServerResponse): {
+    level: string;
+    logObject: {
+        message: string;
+        timestamp: number;
+        trace: string | number | undefined;
+        request: {
+            headers: import("node:http").IncomingHttpHeaders;
+            http_version: string;
+            id: any;
+            method: string | undefined;
+            url: string | undefined;
+        };
+        response: {
+            status_code: number;
+            headers: {
+                [k: string]: any;
+            };
+        };
+        duration: any;
+    };
+};

package/lib/logger/serializers.js

@@ -0,0 +1,78 @@
+import callsites from 'callsites';
+import { context } from '../context/index.js';
+import util from 'util';
+export function parseError(e, meta) {
+    const toSend = { error: { ...e }, ...meta };
+    toSend.message = e.message;
+    toSend.error.stack = e.stack;
+    toSend.error.kind = e.constructor.name;
+    return toSend;
+}
+const makeLoggerMetadata = (method) => ({
+    name: 'pino',
+    version: 'v1.0.0',
+    method_name: method,
+});
+const parseArgs = (argSlice) => argSlice.map((arg) => {
+    if (util.types.isNativeError(arg))
+        return parseError(arg, {});
+    return arg;
+});
+export function serializeLog(...args) {
+    const site = callsites()[2];
+    const meta = {
+        timestamp: Date.now(),
+        location: `${site.getFileName()}:${site.getLineNumber()}:${site.getColumnNumber()}`,
+        logger: makeLoggerMetadata(site.getFunctionName()),
+        trace: context.current?.store.get('id'),
+    };
+    if (!args.length)
+        return { message: 'EMPTY_LOG', ...meta };
+    if (args.length === 1) {
+        if (typeof args[0] === 'string')
+            return { message: args[0], ...meta };
+        if (util.types.isNativeError(args[0]))
+            return parseError(args[0], meta);
+        if (args[0].message)
+            return { message: args[0].message, ...args };
+        return { message: 'EMPTY_MESSAGE', args: args[0], ...meta };
+    }
+    if (typeof args[0] === 'string')
+        return { message: args.shift(), args: parseArgs(args), ...meta };
+    return { message: 'EMPTY_MESSAGE', args: parseArgs(args), ...meta };
+}
+function apacheLogFormat(startDate, remoteClient, content, req, statusCode) {
+    return `${req.headers['x-forwarded-for'] || req.socket.remoteAddress} ${remoteClient || '-'} ${startDate.toISOString()} "${req.method} ${req.url} HTTP/${req.httpVersionMajor}.${req.httpVersionMinor}" ${statusCode} ${content || '-'}`;
+}
+export function getStatusLevel(statusCode) {
+    if (statusCode >= 400 && statusCode < 500) {
+        return 'warn';
+    }
+    else if (statusCode >= 500) {
+        return 'error';
+    }
+    return 'info';
+}
+export function serializeHttp(headers, startDate, remoteClient, req, res) {
+    const executionId = context.current?.store.get('id');
+    return {
+        level: getStatusLevel(res.statusCode),
+        logObject: {
+            message: apacheLogFormat(startDate, remoteClient, headers['Content-Length'], req, res.statusCode),
+            timestamp: Date.now(),
+            trace: executionId,
+            request: {
+                headers: req.headers,
+                http_version: req.httpVersion,
+                id: req.headers['x-request-id'] || req.id || 'unknown',
+                method: req.method,
+                url: req.url,
+            },
+            response: {
+                status_code: res.statusCode,
+                headers: headers,
+            },
+            duration: headers['X-Processing-Time'] || 'unknown',
+        },
+    };
+}

package/lib/middlewares/cookies/cookie-manager.d.ts

@@ -0,0 +1,25 @@
+import { type ParseOptions, type SerializeOptions } from 'cookie';
+import { secretsOperator } from './signer.js';
+import type { BareRequest } from '../../request.js';
+export type CookiesManagerOptions = Omit<SerializeOptions, 'expires'> & {
+    expires?: Date | number;
+    signed?: boolean;
+    parseOptions?: ParseOptions;
+    secret?: string | string[];
+};
+export declare class CookiesManager {
+    private options;
+    private flow;
+    signer: null | ReturnType<typeof secretsOperator>;
+    constructor(options: CookiesManagerOptions | undefined, flow: BareRequest);
+    setCookie(name: string, value: string, options?: CookiesManagerOptions, signer?: ReturnType<typeof secretsOperator>): void;
+    clearCookie(name: string, options?: CookiesManagerOptions): void;
+    parseCookie(rawCookie?: string): {
+        [k: string]: string;
+    };
+    unsignCookie(value: any): {
+        valid: boolean;
+        renew: boolean;
+        value: string | null;
+    } | undefined;
+}