@ohos-ports/layer0-prefetch 4.20.0-beta.0 → 4.20.0-beta.1

package/node_modules/@layer0/core/router/Router.d.ts

@@ -0,0 +1,439 @@
+import { PreloadRequestConfig } from './Preload';
+import BackendOptions from './BackendOptions';
+import PluginBase from '../plugins/PluginBase';
+import PreloadRequests from './PreloadRequests';
+import Request from './Request';
+import Response from './Response';
+import ResponseWriter from './ResponseWriter';
+import RouteCriteria from './RouteCriteria';
+import RouteGroup, { StaticOptions, BasicAuthOptions } from './RouteGroup';
+import RouteGroupList from './RouteGroupList';
+export interface RouterOptions {
+    /**
+     * If `true`, built in routes under /__layer0__/ will be not be added to the router.
+     */
+    excludeBuiltInRoutes?: boolean;
+    /**
+     * If `true`, duplicate queries in request will not be transformed to array
+     */
+    allowReqQueryDuplicates?: boolean;
+}
+/**
+ * A router.
+ */
+export default class Router {
+    readonly routeGroups: RouteGroupList;
+    readonly preloadRequests: PreloadRequests;
+    readonly allowReqQueryDuplicates: boolean;
+    private readonly plugins;
+    private readonly destinations;
+    private nextRouterIndex;
+    private newRequestId?;
+    /**
+     * Index is used to determine the precedence of a router when routing rules
+     * have not resolved to a specific destination. The router with the lowest
+     * number wins.
+     * @private
+     *
+     */
+    private _index;
+    constructor(options?: RouterOptions);
+    /**
+     * Returns a manifest of all static assets to be served via router.static
+     * @private
+     */
+    getStaticAssetManifest(): {
+        [key: string]: string[];
+    };
+    /**
+     * Allows the lambda handler to add the __js__ backend in the cloud
+     * @private
+     * @param name
+     * @param value
+     */
+    setBackend(name: string, value: BackendOptions): this;
+    /**
+     * Constructs plugin and pushes it to registered plugins
+     * @param pluginInstance A plugin to use.
+     * @returns {Router} A self-reference, suitable for chaining.
+     */
+    use(pluginInstance: PluginBase): this;
+    /**
+     * Adds a named destination to which you can map traffic using the traffic shaping settings in your environment
+     * in Layer0 developer console
+     * @param name The name of the destination
+     * @param router A router to use when handling requests
+     * @returns {Router} A self-reference, suitable for chaining.
+     */
+    destination(name: string, router: Router): this;
+    /**
+     * Returns all plugins, including those registered on destination routers.
+     */
+    getPlugins(): PluginBase[];
+    /**
+     * Sets the index at which the router has been added to its parent router
+     * @private
+     * @param index
+     */
+    setIndex(index: number): void;
+    /**
+     * Returns the index at which the router has been added to its parent router
+     * @private
+     * @returns router's index
+     */
+    get index(): number;
+    /**
+     * Adds a RouteGroup to router and calls route register function for group.
+     * @private
+     * @param name Group name
+     * @param registerRoutesFn Group route register function
+     * @returns {Router} A self-reference, suitable for chaining.
+     */
+    group(name: string, registerRoutesFn: (group: RouteGroup) => void): this;
+    /**
+     * Adds a route matching all methods.
+     *
+     * Example:
+     *
+     * ```js
+     *  new Router().match('/p/:productId', ({ cache, proxy }) => {
+     *    cache({
+     *      edge: {
+     *        maxAgeSeconds: 60 * 60 * 24
+     *      }
+     *    })
+     *
+     *    proxy('origin')
+     *  })
+     * ```
+     *
+     * @param criteria Either the path as a string or an object with `path`, `method`, and `headers`.
+     * @param handler A handler function that will be called when the route is matched
+     * @returns {Router} A self-reference, suitable for chaining.
+     */
+    match(criteria: RouteCriteria | string, handler: RouteHandler): this;
+    /**
+     * Adds preload config for router
+     *
+     * ```js
+     *  new Router().preload(
+     *    async () => [{ path: '/foo', headers: { foo: 'bar' } }],
+     *    [{ path: '/bar' }]
+     *  )
+     * ```
+     *
+     * @param preloadOptions
+     */
+    prerender(...preloadOptions: Array<PreloadRequestConfig[] | (() => Promise<PreloadRequestConfig[]>) | (() => PreloadRequestConfig[])>): this;
+    /**
+     * Adds a route matching the given HTTP method.
+     *
+     * @param method HTTP method
+     * @param criteria Either the path as a string or an object with `path`, `headers` and `cookies`.
+     * @param handler A handler function that will be called when the route is matched
+     * @private
+     */
+    private matchMethod;
+    /**
+     * Adds a route matching `HEAD` HTTP method.
+     *
+     * @param criteria Either the path as a string or an object with `path`, `headers` and `cookies`.
+     * @param handler A handler function that will be called when the route is matched
+     * @returns {Router} A self-reference, suitable for chaining.
+     */
+    head(criteria: RouteCriteria | string, handler: RouteHandler): this;
+    /**
+     * Adds a route matching `GET` HTTP method.
+     *
+     * @param criteria Either the path as a string or an object with `path`, `headers` and `cookies`.
+     * @param handler A handler function that will be called when the route is matched
+     * @returns {Router} A self-reference, suitable for chaining.
+     */
+    get(criteria: RouteCriteria | string, handler: RouteHandler): this;
+    /**
+     * Adds a route matching `POST` HTTP method.
+     *
+     * @param criteria Either the path as a string or an object with `path`, `headers` and `cookies`.
+     * @param handler A handler function that will be called when the route is matched
+     * @returns {Router} A self-reference, suitable for chaining.
+     */
+    post(criteria: RouteCriteria | string, handler: RouteHandler): this;
+    /**
+     * Adds a route matching `DELETE` HTTP method.
+     *
+     * @param criteria Either the path as a string or an object with `path`, `headers` and `cookies`.
+     * @param handler A handler function that will be called when the route is matched
+     * @returns {Router} A self-reference, suitable for chaining.
+     */
+    delete(criteria: RouteCriteria | string, handler: RouteHandler): this;
+    /**
+     * Adds a route matching `PUT` HTTP method.
+     *
+     * @param criteria Either the path as a string or an object with `path`, `headers` and `cookies`.
+     * @param handler A handler function that will be called when the route is matched
+     * @returns {Router} A self-reference, suitable for chaining.
+     */
+    put(criteria: RouteCriteria | string, handler: RouteHandler): this;
+    /**
+     * Adds a route matching `PATCH` HTTP method.
+     *
+     * @param criteria Either the path as a string or an object with `path`, `headers` and `cookies`.
+     * @param handler A handler function that will be called when the route is matched
+     * @returns {Router} A self-reference, suitable for chaining.
+     */
+    patch(criteria: RouteCriteria | string, handler: RouteHandler): this;
+    /**
+     * Adds a route matching `OPTIONS` HTTP method.
+     *
+     * @param criteria Either the path as a string or an object with `path`, `headers` and `cookies`.
+     * @param handler A handler function that will be called when the route is matched
+     * @returns {Router} A self-reference, suitable for chaining.
+     */
+    options(criteria: RouteCriteria | string, handler: RouteHandler): this;
+    /**
+     * Adds a route that will run if no other routes are matched
+     * @param handler A handler function that will be called when no other route is matched
+     * @returns A self-reference, suitable for chaining.
+     */
+    fallback(handler: RouteHandler): this;
+    /**
+     * Adds a route that matches all requests with internal error header.
+     * @param handler A handler function that will be called when the route is matched
+     * @returns {Router} A self-reference, suitable for chaining.
+     */
+    catch(error: RegExp | string | number, handler: RouteHandler): this;
+    /**
+     * Disables crawling of permalinks by setting the `x-robots-tag: noindex` response header
+     * for hosts matching layer0.link or layer0-perma.link.
+     *
+     * ```js
+     *  new Router().noIndexPermalink()
+     * ```
+     *
+     * * @returns {Router} A self-reference, suitable for chaining.
+     */
+    noIndexPermalink(): this;
+    /**
+     * Checks headers for validity and updates them as needed.
+     *
+     * Notes:
+     * - If x-request-id is not present we generate it and later inject it into
+     * the response.
+     * - If accept-encoding includes gzip then we use it but eliminating everything else
+     * as we don't support other encodings. If there is no gzip in accept-encoding
+     * then we delete it entirely forcing upstream to return uncoded response.
+     * - We emulate the edge router by injecting the same headers it injects:
+     *    - x-0-client-ip
+     *    - x-forwarded-for
+     */
+    private processRequestHeaders;
+    /**
+     * Emulates edge by injecting device headers into the request prior to routing.
+     *
+     * Notes:
+     * - This code must be the same as the the generated edge router.
+     * - This code has been directly translated from ECL compiler
+     * - We emulate the edge router by injecting the same headers it injects:
+     *    - x-0-device
+     *    - x-0-vendor
+     *    - x-0-browser
+     *    - x-0-device-is-bot
+     */
+    private processRequestDeviceHeaders;
+    /**
+     * Emulates edge by injecting Geolocation headers into the request prior to routing.
+     *  - x-0-geo-city
+     *  - x-0-geo-country-code
+     *  - x-0-geo-latitude
+     *  - x-0-geo-longitude
+     *  - x-0-geo-postal-code
+     */
+    private processRequestGeoHeaders;
+    /**
+     * Adds the `rawBody` (Buffer) and `body` (String) to the request
+     * @param req
+     */
+    private processRequestBody;
+    /**
+     * Checks if the number of user headers is within the limits.
+     *
+     * Notes:
+     * - User headers are all those that do not have `x-0-` prefix.
+     * - We check user headers counts in the router because in local
+     * development the router is running on "the edge" and we want to
+     * simulate the edge behavior (which actually has hard limits on
+     * header count - see `LAYER0_MAX_USER_HEADERS_ALLOWED` for more info)
+     */
+    private isUserHeaderCountWithinLimits;
+    /**
+     * Patches writeHead method of the response so that we can do any post-response work.
+     *
+     * Notes:
+     * - Injects response ID header when this same component has generated the request ID.
+     * All components that actually generate the request ID before processing the request
+     * or going upstream are then also responsible for sending back the request ID downstream.
+     * - Return status 542 when there are too many response headers.
+     *
+     * @param req The request
+     * @param res The response
+     */
+    private patchResWriteHead;
+    /**
+     * Handles a request, sending the response by running the handler for each matched route.
+     * @param req The request
+     * @param res The response
+     */
+    run: (req: Request, res: Response) => Promise<void>;
+    /**
+     * Both edge and @core/router have a built-in fallback that has the following rules:
+     *
+     * 1. On HTTP protocol return a 301 with the same request path in `location` header but on HTTPS
+     * protocol.
+     * 2. On HTTPS protocol return a 404.
+     *
+     * One complication is that in local development HTTPS does not exist - it is only emulated.
+     * Therefore in local development we could go into a redirect loop if the HTTP is emulated
+     * through the `local_layer0_emulate_http_protocol` cookie. There are a few options:
+     *
+     * 1. Always return 404 in local development.
+     * 2. If the cookie is present, issue 301 but unset the cookie in the response.
+     * 3. If the cookie is not present, return 301.
+     *
+     * We feel that the least surprising is simply always issuing 404 as that is also the original behavior.
+     *
+     * @param res
+     */
+    private builtInFallback;
+    /**
+     * Adds routes for all static assets in a directory tree.
+     *
+     * **Example**
+     *
+     * ```js
+     *  router.static('public')
+     * ```
+     *
+     * To only serve files matching a particular pattern, use the `glob` options:
+     *
+     * ```js
+     *  router.static('public', {
+     *    glob: '*.css'
+     *  })
+     * ```
+     *
+     * By default the path on which files are served corresponds to the path within the directory,
+     * so for example, `public/css/main.css` would be served at `'/css/main.css'`,
+     * you can override this using the `path` option:
+     *
+     * ```js
+     *  router.static('public', {
+     *    paths: file => ['/assets/ + file] // will serve public/css/main.css at /assets/css/main.css
+     *  })
+     * ```
+     *
+     * You can add caching or other additional handler logic using the `handler` option:
+     *
+     * ```js
+     *  router.static('public', {
+     *    handler: (file) => ({ cache }) => {
+     *      cache({
+     *        browser: {
+     *          maxAgeSeconds: 60 * 60
+     *        },
+     *        edge: {
+     *          maxAgeSeconds: 60 * 60 * 24,
+     *          staleWhileRevalidateSeconds: 60 * 60
+     *        }
+     *      })
+     *    }
+     *  })
+     * ```
+     *
+     * @param sourcePath The path to a directory containing static assets relative to the root of your project.
+     * @param options
+     * @returns A self-reference, suitable for chaining.
+     */
+    static(sourcePath: string, options?: StaticOptions): this;
+    /**
+     * Shorthand for adding GraphQL body matching
+     *
+     * Examples:
+     *
+     * // by default the path is graphql
+     * new Router().graphqlOperation("GetRates")
+     *
+     * or
+     *
+     * // with optional non-default path
+     * new Router().graphqlOperation({ path: "/gql-api", name: "GetRates" })
+     *
+     * @param criteria Either the operation name as a string or an object with `path`, `name`.
+     * @param handler A handler function that will be called when the route is matched
+     *
+     * @returns A self-reference, suitable for chaining.
+     */
+    graphqlOperation(criteria: string | RegExp | {
+        path: string;
+        name: string | RegExp;
+    }, handler: RouteHandler): this;
+    /**
+     * Adds Basic Authentication.
+     *
+     * **example**
+     *
+     * ```js
+     *  router
+     *    .requireBasicAuth({ username: 'user', password: 's3cr3t!' })
+     *    // ...include additional routes below...
+     * ```
+     *
+     * You can also require basic auth for a subset of URLs using the `criteria` option:
+     *
+     * ```js
+     *  router
+     *    .requireBasicAuth({ criteria: '/secret/:path*', username: 'user', password: 's3cr3t!' })
+     *    // ...include additional routes below...
+     * ```
+     *
+     * The criteria option accepts a path pattern as a string, or a RouteCriteria object.
+     *
+     * @param options
+     * @returns A self-reference, suitable for chaining.
+     */
+    requireBasicAuth(options: BasicAuthOptions): this;
+    /**
+     * Returns edge config from current router
+     * @private
+     */
+    createEdgeConfig(): Promise<import("../types").EdgeConfig>;
+    /**
+     * Returns preload config from current router
+     * @private
+     */
+    createPreloadConfig(): Promise<import("./Preload").CompiledPreloadOptions>;
+    /**
+     * @private
+     */
+    getDestinations(): {
+        [name: string]: Router;
+    };
+    /**
+     * @private
+     */
+    getRouteGroups(): RouteGroupList;
+    /**
+     * Returns a string summarizing all routes for debugging purposes. Don't rely on the format
+     * of this string as we may improve it over time.
+     */
+    toString(): string;
+    /**
+     * Returns true if the request came through Layer0 edge.
+     *
+     * Notes:
+     * - If the request came through Layer0 edge then `x-0-version` has been injected.
+     *
+     * @param req The request
+     */
+    static isRequestFromEdge(req: Request): boolean;
+}
+export declare type RouteHandler = (respond: ResponseWriter) => void;