hapii-js 0.0.0-stage → 2.0.0

package/lib/types/server/state.d.ts

@@ -0,0 +1,79 @@
+import { StateOptions, SameSitePolicy } from '@hapi/statehood';
+
+import { Request } from '../request';
+
+export { SameSitePolicy };
+
+/**
+ * Optional cookie settings
+ * [See docs](https://github.com/hapijs/hapi/blob/master/API.md#-serverstatename-options)
+ */
+export interface ServerStateCookieOptions extends StateOptions<Request> {}
+
+/**
+ * A single object or an array of object where each contains:
+ * * name - the cookie name.
+ * * value - the cookie value.
+ * * options - cookie configuration to override the server settings.
+ */
+export interface ServerStateFormat {
+    name: string;
+    value: string;
+    options: ServerStateCookieOptions;
+}
+
+/**
+ * For context [See docs](https://github.com/hapijs/hapi/blob/master/API.md#-serverstatename-options)
+ * For context [See docs](https://github.com/hapijs/hapi/blob/master/API.md#-serveroptionsstate)
+ */
+export interface ServerState {
+    /**
+     * The server cookies manager.
+     * Access: read only and statehood public interface.
+     */
+    readonly states: object;
+
+    /**
+     * The server cookies manager settings. The settings are based on the values configured in [server.options.state](https://github.com/hapijs/hapi/blob/master/API.md#server.options.state).
+     */
+    readonly settings: ServerStateCookieOptions;
+
+    /**
+     * An object containing the configuration of each cookie added via [server.state()](https://github.com/hapijs/hapi/blob/master/API.md#server.state()) where each key is the
+     * cookie name and value is the configuration object.
+     */
+    readonly cookies: {
+        [key: string]: ServerStateCookieOptions;
+    };
+
+    /**
+     * An array containing the names of all configured cookies.
+     */
+    readonly names: string[];
+
+    /**
+     * Same as calling [server.state()](https://github.com/hapijs/hapi/blob/master/API.md#server.state()).
+     */
+    add(name: string, options?: ServerStateCookieOptions | undefined): void;
+
+    /**
+     * Formats an HTTP 'Set-Cookie' header based on the server.options.state where:
+     * @param cookies - a single object or an array of object where each contains:
+     * * name - the cookie name.
+     * * value - the cookie value.
+     * * options - cookie configuration to override the server settings.
+     * @return Return value: a header string.
+     * Note that this utility uses the server configuration but does not change the server state. It is provided for manual cookie formatting (e.g. when headers are set manually).
+     * [See docs](https://github.com/hapijs/hapi/blob/master/API.md#-async-serverstatesformatcookies)
+     */
+    format(cookies: ServerStateFormat | ServerStateFormat[]): Promise<string>;
+
+    /**
+     * Parses an HTTP 'Cookies' header based on the server.options.state where:
+     * @param header - the HTTP header.
+     * @return Return value: an object where each key is a cookie name and value is the parsed cookie.
+     * Note that this utility uses the server configuration but does not change the server state. It is provided for manual cookie parsing (e.g. when server parsing is disabled).
+     * [See docs](https://github.com/hapijs/hapi/blob/master/API.md#-async-serverstatesparseheader)
+     */
+    parse(header: string): Promise<Record<string, string>>;
+}

package/lib/types/utils.d.ts

@@ -0,0 +1,113 @@
+import * as https from 'https';
+import * as stream from 'stream';
+
+import { Boom } from '@hapi/boom';
+import { ResponseObject as ShotResponseObject } from '@hapi/shot';
+
+import {
+    ReqRef,
+    ReqRefDefaults,
+    MergeRefs,
+    Request} from './request';
+import { ResponseToolkit, Auth } from './response';
+
+/**
+ * All http parser [supported HTTP methods](https://nodejs.org/api/http.html#httpmethods).
+ */
+export type HTTP_METHODS = 'ACL' | 'BIND' | 'CHECKOUT' | 'CONNECT' | 'COPY' | 'DELETE' | 'GET' | 'HEAD' | 'LINK' | 'LOCK' |
+    'M-SEARCH' | 'MERGE' | 'MKACTIVITY' | 'MKCALENDAR' | 'MKCOL' | 'MOVE' | 'NOTIFY' | 'OPTIONS' | 'PATCH' | 'POST' |
+    'PROPFIND' | 'PROPPATCH' | 'PURGE' | 'PUT' | 'REBIND' | 'REPORT' | 'SEARCH' | 'SOURCE' | 'SUBSCRIBE' | 'TRACE' |
+    'UNBIND' | 'UNLINK' | 'UNLOCK' | 'UNSUBSCRIBE';
+
+export type PeekListener = (chunk: string, encoding: string) => void;
+
+export namespace Json {
+    /**
+     * @see {@link https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#The_replacer_parameter}
+     */
+    type StringifyReplacer = ((key: string, value: any) => any) | (string | number)[] | undefined;
+
+    /**
+     * Any value greater than 10 is truncated.
+     */
+    type StringifySpace = number | string;
+
+    /**
+     * For context [See docs](https://github.com/hapijs/hapi/blob/master/API.md#-routeoptionsjson)
+     */
+    interface StringifyArguments {
+        /** the replacer function or array. Defaults to no action. */
+        replacer?: StringifyReplacer | undefined;
+        /** number of spaces to indent nested object keys. Defaults to no indentation. */
+        space?: StringifySpace | undefined;
+        /* string suffix added after conversion to JSON string. Defaults to no suffix. */
+        suffix?: string | undefined;
+        /* calls Hoek.jsonEscape() after conversion to JSON string. Defaults to false. */
+        escape?: boolean | undefined;
+    }
+}
+
+export namespace Lifecycle {
+    /**
+     * Lifecycle methods are the interface between the framework and the application. Many of the request lifecycle steps:
+     * extensions, authentication, handlers, pre-handler methods, and failAction function values are lifecycle methods
+     * provided by the developer and executed by the framework.
+     * Each lifecycle method is a function with the signature await function(request, h, [err]) where:
+     * * request - the request object.
+     * * h - the response toolkit the handler must call to set a response and return control back to the framework.
+     * * err - an error object available only when the method is used as a failAction value.
+     */
+    type Method<
+        Refs extends ReqRef = ReqRefDefaults,
+        R extends ReturnValue<any> = ReturnValue<Refs>
+    > = (
+            this: MergeRefs<Refs>['Bind'],
+            request: Request<Refs>,
+            h: ResponseToolkit<Refs>,
+            err?: Error | undefined
+        ) => R;
+
+    /**
+     * Each lifecycle method must return a value or a promise that resolves into a value. If a lifecycle method returns
+     * without a value or resolves to an undefined value, an Internal Server Error (500) error response is sent.
+     * The return value must be one of:
+     * - Plain value: null, string, number, boolean
+     * - Buffer object
+     * - Error object: plain Error OR a Boom object.
+     * - Stream object
+     * - any object or array
+     * - a toolkit signal:
+     * - a toolkit method response:
+     * - a promise object that resolve to any of the above values
+     * For more info please [See docs](https://github.com/hapijs/hapi/blob/master/API.md#lifecycle-methods)
+     */
+    type ReturnValue<Refs extends ReqRef = ReqRefDefaults> = ReturnValueTypes<Refs> | (Promise<ReturnValueTypes<Refs>>);
+    type ReturnValueTypes<Refs extends ReqRef = ReqRefDefaults> =
+        (null | string | number | boolean) |
+        (Buffer) |
+        (Error | Boom) |
+        (stream.Stream) |
+        (object | object[]) |
+        symbol |
+        Auth<
+            MergeRefs<Refs>['AuthUser'],
+            MergeRefs<Refs>['AuthApp'],
+            MergeRefs<Refs>['AuthCredentialsExtra'],
+            MergeRefs<Refs>['AuthArtifactsExtra']
+        > |
+        ShotResponseObject;
+
+    /**
+     * Various configuration options allows defining how errors are handled. For example, when invalid payload is received or malformed cookie, instead of returning an error, the framework can be
+     * configured to perform another action. When supported the failAction option supports the following values:
+     * * 'error' - return the error object as the response.
+     * * 'log' - report the error but continue processing the request.
+     * * 'ignore' - take no action and continue processing the request.
+     * * a lifecycle method with the signature async function(request, h, err) where:
+     * * * request - the request object.
+     * * * h - the response toolkit.
+     * * * err - the error object.
+     * [See docs](https://github.com/hapijs/hapi/blob/master/API.md#-failaction-configuration)
+     */
+    type FailAction = 'error' | 'log' | 'ignore' | Method;
+}

package/lib/validation.js

@@ -0,0 +1,250 @@
+'use strict';
+
+const Boom = require('@hapi/boom');
+const Hoek = require('@hapi/hoek');
+const Validate = require('@hapi/validate');
+
+
+const internals = {};
+
+
+exports.validator = function (validator) {
+
+    Hoek.assert(validator, 'Missing validator');
+    Hoek.assert(typeof validator.compile === 'function', 'Invalid validator compile method');
+
+    return validator;
+};
+
+
+exports.compile = function (rule, validator, realm, core) {
+
+    validator = validator ?? internals.validator(realm, core);
+
+    // false - nothing allowed
+
+    if (rule === false) {
+        return Validate.object({}).allow(null);
+    }
+
+    // Custom function
+
+    if (typeof rule === 'function') {
+        return rule;
+    }
+
+    // null, undefined, true - anything allowed
+
+    if (!rule ||                            // false tested above
+        rule === true) {
+
+        return null;
+    }
+
+    // {...} - ... allowed
+
+    if (typeof rule.validate === 'function') {
+        return rule;
+    }
+
+    Hoek.assert(validator, 'Cannot set uncompiled validation rules without configuring a validator');
+    return validator.compile(rule);
+};
+
+
+internals.validator = function (realm, core) {
+
+    while (realm) {
+        if (realm.validator) {
+            return realm.validator;
+        }
+
+        realm = realm.parent;
+    }
+
+    return core.validator;
+};
+
+
+exports.headers = function (request) {
+
+    return internals.input('headers', request);
+};
+
+
+exports.params = function (request) {
+
+    return internals.input('params', request);
+};
+
+
+exports.payload = function (request) {
+
+    if (request.method === 'get' ||
+        request.method === 'head') {                // When route.method is '*'
+
+        return;
+    }
+
+    return internals.input('payload', request);
+};
+
+
+exports.query = function (request) {
+
+    return internals.input('query', request);
+};
+
+
+exports.state = function (request) {
+
+    return internals.input('state', request);
+};
+
+
+internals.input = async function (source, request) {
+
+    const localOptions = {
+        context: {
+            headers: request.headers,
+            params: request.params,
+            query: request.query,
+            payload: request.payload,
+            state: request.state,
+            auth: request.auth,
+            app: {
+                route: request.route.settings.app,
+                request: request.app
+            }
+        }
+    };
+
+    delete localOptions.context[source];
+    Hoek.merge(localOptions, request.route.settings.validate.options);
+
+    try {
+        const schema = request.route.settings.validate[source];
+        const bind = request.route.settings.bind;
+
+        var value = await (typeof schema !== 'function' ? internals.validate(request[source], schema, localOptions) : schema.call(bind, request[source], localOptions));
+        return;
+    }
+    catch (err) {
+        var validationError = err;
+    }
+    finally {
+        request.orig[source] = request[source];
+        if (value !== undefined) {
+            request[source] = value;
+        }
+    }
+
+    if (request.route.settings.validate.failAction === 'ignore') {
+        return;
+    }
+
+    // Prepare error
+
+    const defaultError = validationError.isBoom ? validationError : Boom.badRequest(`Invalid request ${source} input`);
+    const detailedError = Boom.boomify(validationError, { statusCode: 400, override: false, data: { defaultError } });
+    detailedError.output.payload.validation = { source, keys: [] };
+    if (validationError.details) {
+        for (const details of validationError.details) {
+            const path = details.path;
+            detailedError.output.payload.validation.keys.push(Hoek.escapeHtml(path.join('.')));
+        }
+    }
+
+    if (request.route.settings.validate.errorFields) {
+        for (const field in request.route.settings.validate.errorFields) {
+            detailedError.output.payload[field] = request.route.settings.validate.errorFields[field];
+        }
+    }
+
+    return request._core.toolkit.failAction(request, request.route.settings.validate.failAction, defaultError, { details: detailedError, tags: ['validation', 'error', source] });
+};
+
+
+exports.response = async function (request) {
+
+    if (request.route.settings.response.sample) {
+        const currentSample = Math.ceil(Math.random() * 100);
+        if (currentSample > request.route.settings.response.sample) {
+            return;
+        }
+    }
+
+    const response = request.response;
+    const statusCode = response.isBoom ? response.output.statusCode : response.statusCode;
+
+    const statusSchema = request.route.settings.response.status[statusCode];
+    if (statusCode >= 400 &&
+        !statusSchema) {
+
+        return;                 // Do not validate errors by default
+    }
+
+    const schema = statusSchema !== undefined ? statusSchema : request.route.settings.response.schema;
+    if (schema === null) {
+        return;                 // No rules
+    }
+
+    if (!response.isBoom &&
+        request.response.variety !== 'plain') {
+
+        throw Boom.badImplementation('Cannot validate non-object response');
+    }
+
+    const localOptions = {
+        context: {
+            headers: request.headers,
+            params: request.params,
+            query: request.query,
+            payload: request.payload,
+            state: request.state,
+            auth: request.auth,
+            app: {
+                route: request.route.settings.app,
+                request: request.app
+            }
+        }
+    };
+
+    const source = response.isBoom ? response.output.payload : response.source;
+    Hoek.merge(localOptions, request.route.settings.response.options);
+
+    try {
+        let value;
+
+        if (typeof schema !== 'function') {
+            value = await internals.validate(source, schema, localOptions);
+        }
+        else {
+            value = await schema(source, localOptions);
+        }
+
+        if (value !== undefined &&
+            request.route.settings.response.modify) {
+
+            if (response.isBoom) {
+                response.output.payload = value;
+            }
+            else {
+                response.source = value;
+            }
+        }
+    }
+    catch (err) {
+        return request._core.toolkit.failAction(request, request.route.settings.response.failAction, err, { tags: ['validation', 'response', 'error'] });
+    }
+};
+
+
+internals.validate = function (value, schema, options) {
+
+    if (typeof schema.validateAsync === 'function') {
+        return schema.validateAsync(value, options);
+    }
+
+    return schema.validate(value, options);
+};

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "hapii-js",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "HTTP Server framework",
+  "version": "2.0.0",
+  "repository": "git://github.com/hapii-js/hapii",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "engines": {
+    "node": ">=14.15.0"
+  },
+  "files": [
+    "lib"
+  ],
+  "keywords": [
+    "framework",
+    "http",
+    "api",
+    "web"
+  ],
+  "eslintConfig": {
+    "extends": [
+      "plugin:@hapi/module"
+    ]
+  },
+  "dependencies": {
+    "@hapi/accept": "^6.0.3",
+    "@hapi/ammo": "^6.0.1",
+    "@hapi/boom": "^10.0.1",
+    "@hapi/bounce": "^3.0.2",
+    "@hapi/call": "^9.0.1",
+    "@hapi/catbox": "^12.1.1",
+    "@hapi/catbox-memory": "^6.0.2",
+    "@hapi/heavy": "^8.0.1",
+    "@hapi/hoek": "^11.0.7",
+    "@hapi/mimos": "^7.0.1",
+    "@hapi/podium": "^5.0.2",
+    "@hapi/shot": "^6.0.2",
+    "@hapi/somever": "^4.1.1",
+    "@hapi/statehood": "^8.2.1",
+    "@hapi/subtext": "^8.1.3",
+    "@hapi/teamwork": "^6.0.1",
+    "@hapi/topo": "^6.0.2",
+    "@hapi/validate": "^2.0.1"
+  },
+  "devDependencies": {
+    "@hapi/code": "^9.0.3",
+    "@hapi/eslint-plugin": "^6.0.0",
+    "@hapi/inert": "^7.1.0",
+    "@hapi/joi-legacy-test": "npm:@hapi/joi@^15.0.0",
+    "@hapi/lab": "^25.3.2",
+    "@hapi/vision": "^7.0.3",
+    "@hapi/wreck": "^18.1.0",
+    "@types/node": "^18.19.130",
+    "handlebars": "^4.7.9",
+    "joi": "^17.13.3",
+    "legacy-readable-stream": "npm:readable-stream@^1.0.34",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "test": "lab -a @hapi/code -t 100 -L -m 5000 -Y",
+    "test-tap": "lab -a @hapi/code -r tap -o tests.tap -m 5000",
+    "test-cov-html": "lab -a @hapi/code -r html -o coverage.html -m 5000"
+  },
+  "license": "BSD-3-Clause"
+}