@fastly/expressly 1.0.0--canary.4.2464710183.0

package/dist/lib/routing/response/status-codes.js

@@ -0,0 +1,57 @@
+// See: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status
+export const statusText = {
+    100: "Continue",
+    101: "Switching Protocols",
+    103: "Early Hints",
+    200: "OK",
+    201: "Created",
+    202: "Accepted",
+    203: "Non-Authoritative Information",
+    204: "No Content",
+    205: "Reset Content",
+    206: "Partial Content",
+    300: "Multiple Choices",
+    301: "Moved Permanently",
+    302: "Found",
+    303: "See Other",
+    304: "Not Modified",
+    307: "Temporary Redirect",
+    308: "Permanent Redirect",
+    400: "Bad Request",
+    401: "Unauthorized",
+    402: "Payment Required",
+    403: "Forbidden",
+    404: "Not Found",
+    405: "Method Not Allowed",
+    406: "Not Acceptable",
+    407: "Proxy Authentication Required",
+    408: "Request Timeout",
+    409: "Conflict",
+    410: "Gone",
+    411: "Length Required",
+    412: "Precondition Failed",
+    413: "Payload Too Large",
+    414: "URI Too Long",
+    415: "Unsupported Media Type",
+    416: "Range Not Satisfiable",
+    417: "Expectation Failed",
+    418: "I'm a teapot",
+    422: "Unprocessable Entity",
+    425: "Too Early",
+    426: "Upgrade Required",
+    428: "Precondition Required",
+    429: "Too Many Requests",
+    431: "Request Header Fields Too Large",
+    451: "Unavailable For Legal Reasons",
+    500: "Internal Server Error",
+    501: "Not Implemented",
+    502: "Bad Gateway",
+    503: "Service Unavailable",
+    504: "Gateway Timeout",
+    505: "HTTP Version Not Supported",
+    506: "Variant Also Negotiates",
+    507: "Insufficient Storage",
+    508: "Loop Detected",
+    510: "Not Extended",
+    511: "Network Authentication Required"
+};

package/dist/lib/routing/response/surrogate-keys.d.ts

@@ -0,0 +1,9 @@
+/// <reference types="@fastly/js-compute" />
+export declare class SurrogateKeys extends Set {
+    private headers;
+    constructor(headers: Headers);
+    clear(): void;
+    add(key: string): this;
+    delete(key: string): boolean;
+    private serialize;
+}

package/dist/lib/routing/response/surrogate-keys.js

@@ -0,0 +1,29 @@
+export class SurrogateKeys extends Set {
+    constructor(headers) {
+        super();
+        this.headers = headers;
+    }
+    clear() {
+        this.headers.delete("Surrogate-Key");
+        super.clear();
+    }
+    add(key) {
+        super.add(key);
+        this.serialize();
+        return this;
+    }
+    delete(key) {
+        const deleteResult = super.delete(key);
+        this.serialize();
+        return deleteResult;
+    }
+    serialize() {
+        if (this.size) {
+            const keys = [];
+            for (const [key] of this.entries()) {
+                keys.push(key);
+            }
+            this.headers.set("Surrogate-Key", keys.join(" "));
+        }
+    }
+}

package/dist/lib/routing/router.d.ts

@@ -0,0 +1,32 @@
+import { EConfig } from ".";
+import { RequestHandler, RequestHandlerCallback } from "./request-handler";
+import { ErrorMiddleware, ErrorMiddlewareCallback } from "./error-middleware";
+export declare class Router {
+    requestHandlers: Array<RequestHandler>;
+    errorHandlers: Array<ErrorMiddleware>;
+    config: EConfig;
+    constructor(config?: EConfig);
+    listen(): void;
+    private handler;
+    use(path: string | RequestHandlerCallback | ErrorMiddlewareCallback, callback?: RequestHandlerCallback | ErrorMiddlewareCallback): void;
+    route(methods: string[], pattern: string, callback: RequestHandlerCallback): void;
+    all(pattern: string, callback: RequestHandlerCallback): void;
+    get(pattern: string, callback: RequestHandlerCallback): void;
+    post(pattern: string, callback: RequestHandlerCallback): void;
+    put(pattern: string, callback: RequestHandlerCallback): void;
+    delete(pattern: string, callback: RequestHandlerCallback): void;
+    head(pattern: string, callback: RequestHandlerCallback): void;
+    options(pattern: string, callback: RequestHandlerCallback): void;
+    patch(pattern: string, callback: RequestHandlerCallback): void;
+    private runRequestHandlers;
+    private runErrorHandlers;
+    /**
+     * Creates a function used to check if the request method and path match a router configuration.
+     * @param methods An array of HTTP method(s) or "*" to match all methods.
+     * @param pattern A path string compatible with path-to-regexp (see: https://www.npmjs.com/package/path-to-regexp)
+     * @param extractRequestParameters Whether to extract parameters from a request
+     * @returns 405 if the method is not allowed, 404 if the path doesn't match, 0 otherwise.
+     */
+    private routeMatcher;
+    private static serializeResponse;
+}

package/dist/lib/routing/router.js

@@ -0,0 +1,165 @@
+import { match } from "path-to-regexp";
+import { RequestHandler } from "./request-handler";
+import { ErrorMiddleware } from "./error-middleware";
+import { ErrorNotFound, ErrorMethodNotAllowed } from "./errors";
+import { ERequest } from "./request";
+import { EResponse } from "./response";
+const pathMatcherCache = new Map();
+const defaultErrorHandler = (auto405) => async (err, req, res) => {
+    if (err instanceof ErrorNotFound || (err instanceof ErrorMethodNotAllowed && !auto405)) {
+        return res.sendStatus(404);
+    }
+    else if (err instanceof ErrorMethodNotAllowed) {
+        res.headers.set("Allow", err.allow);
+        return res.sendStatus(405);
+    }
+    res.withStatus(500).json({ error: err });
+};
+export class Router {
+    constructor(config) {
+        this.requestHandlers = [];
+        this.errorHandlers = [];
+        this.config = {
+            parseCookie: true,
+            auto405: true,
+            extractRequestParameters: true,
+            autoContentType: false
+        };
+        this.config = {
+            ...this.config,
+            ...config
+        };
+    }
+    listen() {
+        addEventListener("fetch", (event) => event.respondWith(this.handler(event)));
+    }
+    async handler(event) {
+        const req = new ERequest(this.config, event);
+        const res = new EResponse(this.config);
+        try {
+            // Run middleware and request handler stack.
+            await this.runRequestHandlers(req, res);
+        }
+        catch (err) {
+            // Add default error handler.
+            this.use(defaultErrorHandler(this.config.auto405));
+            // Run error handler stack.
+            await this.runErrorHandlers(err, req, res);
+        }
+        return Router.serializeResponse(res);
+    }
+    // Middleware attach point.
+    use(path, callback) {
+        const cb = path instanceof Function ? path : callback;
+        const matcher = path instanceof Function ? () => 0 : this.routeMatcher(["*"], path);
+        if (cb.length === 3) {
+            this.errorHandlers.push(new ErrorMiddleware(matcher, cb));
+        }
+        else {
+            this.requestHandlers.push(new RequestHandler(matcher, cb));
+        }
+    }
+    // Router API.
+    route(methods, pattern, callback) {
+        this.requestHandlers.push(new RequestHandler(this.routeMatcher(methods.map(m => m.toUpperCase()), pattern), callback));
+    }
+    all(pattern, callback) {
+        this.route(["*"], pattern, callback);
+    }
+    get(pattern, callback) {
+        this.route(["GET"], pattern, callback);
+    }
+    post(pattern, callback) {
+        this.route(["POST"], pattern, callback);
+    }
+    put(pattern, callback) {
+        this.route(["PUT"], pattern, callback);
+    }
+    delete(pattern, callback) {
+        this.route(["DELETE"], pattern, callback);
+    }
+    head(pattern, callback) {
+        this.route(["HEAD"], pattern, callback);
+    }
+    options(pattern, callback) {
+        this.route(["OPTIONS"], pattern, callback);
+    }
+    patch(pattern, callback) {
+        this.route(["PATCH"], pattern, callback);
+    }
+    // Request handler runner.
+    async runRequestHandlers(req, res) {
+        let checkResult;
+        const allowedMethods = [];
+        for (let a of this.requestHandlers) {
+            if (res.hasEnded) {
+                break;
+            }
+            checkResult = a.check(req);
+            if (checkResult === 0) {
+                await a.run(req, res);
+            }
+            else if (checkResult.length) {
+                allowedMethods.push(checkResult);
+            }
+        }
+        if (allowedMethods.length) {
+            throw new ErrorMethodNotAllowed(allowedMethods);
+        }
+        else if (checkResult === 404) {
+            throw new ErrorNotFound();
+        }
+    }
+    // Error handler runner.
+    async runErrorHandlers(err, req, res) {
+        for (let eH of this.errorHandlers) {
+            if (res.hasEnded) {
+                break;
+            }
+            if (eH.check(req) === 0) {
+                await eH.run(err, req, res);
+            }
+        }
+    }
+    /**
+     * Creates a function used to check if the request method and path match a router configuration.
+     * @param methods An array of HTTP method(s) or "*" to match all methods.
+     * @param pattern A path string compatible with path-to-regexp (see: https://www.npmjs.com/package/path-to-regexp)
+     * @param extractRequestParameters Whether to extract parameters from a request
+     * @returns 405 if the method is not allowed, 404 if the path doesn't match, 0 otherwise.
+     */
+    routeMatcher(methods, pattern) {
+        return (req) => {
+            const methodAllowed = methods.some(m => m === "*" || m === req.method);
+            if (pattern === "*" || pattern === "(.*)") {
+                return methodAllowed ? 0 : methods;
+            }
+            else {
+                // Cache pattern matcher.
+                if (!pathMatcherCache.has(pattern)) {
+                    pathMatcherCache.set(pattern, match(pattern, { decode: decodeURIComponent }));
+                }
+                // Match on pathname.
+                let { path, params } = pathMatcherCache.get(pattern)(req.url.pathname) || {};
+                if (path) {
+                    if (this.config.extractRequestParameters) {
+                        req.params = params;
+                    }
+                    return methodAllowed ? 0 : methods;
+                }
+            }
+            // Route not found.
+            return 404;
+        };
+    }
+    static serializeResponse(res) {
+        // Default to 200 / 204 if no status was set by middleware / route handler.
+        if (res.status === 0) {
+            res.status = Boolean(res.body) ? 200 : 204;
+        }
+        return new Response(res.body, {
+            headers: res.headers,
+            status: res.status,
+        });
+    }
+}

package/docs/.nvmrc

@@ -0,0 +1 @@
+16

package/docs/README.md

@@ -0,0 +1,27 @@
+# expressly documentation
+
+The [**expressly** documentation website](https://expressly.edgecompute.app) is built using [Docusaurus](https://docusaurus.io/).
+
+### Installation
+
+```
+$ yarn install
+```
+
+### Local development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+To make changes, edit the Markdown files in [`docs/`](./docs).
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory.

package/docs/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

package/docs/docs/config.md

@@ -0,0 +1,52 @@
+---
+sidebar_position: 7
+---
+
+# Configuration
+
+**expressly**'s router can be initialized with an optional configuration object:
+
+```javascript
+const router = new Router({
+  parseCookie: true,
+  auto405: true,
+  extractRequestParameters: true,
+  autoContentType: true,
+});
+```
+
+## Options
+
+### parseCookie
+
+> Default 🟢 `true`
+
+When set to `true`, enables parsing of the `Cookie` request header and exposes [`req.cookies`](handling-data/cookies.md#request-cookies).
+
+### auto405
+
+> Default 🟢 `true`
+
+When set to `true`, **expressly** will respond with HTTP `405 Method Not Allowed` and automatically set the [`Allow` header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Allow) if it cannot match the client request method on a matched path.
+
+In the example below, a `POST` request to the `/users` path will result in a HTTP 405 response.
+
+```javascript
+const router = new Router({ auto405: true });
+router.get("/users", (req, res) => { ... });
+router.listen();
+```
+
+Setting `auto405: false` above will cause **expressly** to respond with HTTP 404.
+
+### extractRequestParameters
+
+> Default 🟢 `true`
+
+When set to `true`, exposes `req.params`, an object containing properties mapped to any [named route "parameters"](./routing#path-parameters).
+
+### autoContentType
+
+> Default 🔴 `false` 🔥 experimental
+
+When set to `true`, [`res.send`](handling-data/response.md#ressend) will try to [infer the `Content-Type` header](https://expressjs.com/en/4x/api.html#res.send) from the data it is passed, if the header is not set.

package/docs/docs/handling-data/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Handling data",
+  "position": 4
+}

package/docs/docs/handling-data/cookies.md

@@ -0,0 +1,103 @@
+---
+sidebar_position: 4
+---
+
+# Cookies
+
+## Request cookies
+
+You can retrieve the cookies sent by the client by accessing the `req.cookies` object, which implements the [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) interface.
+
+```javascript
+router.get("/", (req, res) => {
+    res.json({
+        session: req.cookies.get("session")
+    })
+})
+```
+
+The `req.cookies.entries()` method returns an iterator for all cookie key/value pairs.
+
+```javascript
+// List all cookie names and values.
+for (const [name, value] of req.cookies.entries()) {
+  console.log(`${name}=${value}`);
+}
+```
+
+If you need only the keys or values, use `req.cookies.keys()` or `req.cookies.values()`, respectively.
+
+Use `req.cookies.delete(name)` to delete a cookie:
+
+```javascript
+router.get("/", (req, res) => {
+    req.cookies.delete("auth");
+    const beresp = await fetch(req, { backend: "my-origin" });
+    // ...
+})
+```
+
+## Response cookies
+
+Setting response cookies is done by calling `res.cookie(key, value[, options])`.
+
+```javascript
+router.get("/", (req, res) => {
+    res.cookie("user", "me");
+    res.cookie("auth", "AUTH_TOKEN_HERE", { maxAge: 3600, path: "/" })
+    res.send("Cookie set!")
+})
+```
+
+Calling `res.clearCookie(key[, options])` will expire a response cookie:
+
+```javascript
+router.get("/", (req, res) => {
+    res.clearCookie("auth", { path: "/" })
+    res.send("Cookie expired!")
+})
+```
+
+### Options
+
+`res.cookie()` accepts the following properties in the `options` object:
+
+#### [domain](https://tools.ietf.org/html/rfc6265#section-5.2.3)
+
+Specifies the `string` value for the `Domain` attribute. By default, no domain is set, and most clients will consider the cookie to apply to only the current domain.
+
+#### [expires](https://tools.ietf.org/html/rfc6265#section-5.2.1)
+
+A `Date` object or `string` that determines the value for the `Expires` attribute. By default, this is not set, and most clients will consider this a "non-persistent cookie".
+
+> **Note:** The [cookie storage model specification](https://tools.ietf.org/html/rfc6265#section-5.3) states that if both `expires` and
+`maxAge` are set, then `maxAge` takes precedence.
+
+#### [maxAge](https://tools.ietf.org/html/rfc6265#section-5.2.2)
+
+A `number` (in seconds) that determines the value for the `Max-Age` attribute. By default, no maximum cookie age is set.
+
+#### [httpOnly](https://tools.ietf.org/html/rfc6265#section-5.2.6)
+
+A `boolean` value. When truthy, the `HttpOnly` attribute is set, otherwise it is not. By default, the `HttpOnly` attribute is not set.
+
+#### [path](https://tools.ietf.org/html/rfc6265#section-5.2.4)
+
+Specifies the `string` value for the `Path` attribute. 
+
+#### [sameSite](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-09#section-5.4.7)
+
+Specifies the `boolean` or `string` value for the `SameSite` attribute:
+
+  - `true` will set the `SameSite` attribute to `Strict` for strict same site enforcement.
+  - `false` will not set the `SameSite` attribute.
+  - `'lax'` will set the `SameSite` attribute to `Lax` for lax same site enforcement.
+  - `'none'` will set the `SameSite` attribute to `None` for an explicit cross-site cookie.
+  - `'strict'` will set the `SameSite` attribute to `Strict` for strict same site enforcement.
+
+> **Note:** This is an attribute that has not yet been fully standardized, and may change in the future.
+This also means many clients may ignore this attribute until they understand it.
+
+#### [secure](https://tools.ietf.org/html/rfc6265#section-5.2.5)
+
+Specifies the `boolean` value for the `Secure` attribute. When truthy, the `Secure` attribute is set, otherwise it is not. By default, the `Secure` attribute is not set.

package/docs/docs/handling-data/headers.md

@@ -0,0 +1,110 @@
+---
+sidebar_position: 3
+---
+
+# Headers
+
+**expressly** simplifies header manipulation on `Request` and `Response` objects.
+
+> 🚨 **Unlike Express**, both `req.headers` and `res.headers` implement the standard [Headers](https://developer.mozilla.org/en-US/docs/Web/API/Headers) interface of the Fetch API. 
+
+## Get header values
+
+Use `*.headers.get(name)` to retrieve the values of a HTTP header.
+
+> 💡 **Header names are case-insensitive**!
+
+```javascript
+router.get("/", (req, res) => {
+  res.json({
+    userAgent: req.headers.get("user-agent"),
+    host: req.headers.get("host"),
+  });
+});
+```
+
+The `.headers.entries()` method returns an iterator for all header key/value pairs.
+
+```javascript
+// List all header names and values.
+for (const [name, value] of req.headers.entries()) {
+  console.log(`${name}: ${value}`);
+}
+```
+
+If you need only the keys or values, use [`*.headers.keys()`](https://developer.mozilla.org/en-US/docs/Web/API/Headers/keys) or [`*.headers.values()`](https://developer.mozilla.org/en-US/docs/Web/API/Headers/values), respectively.
+
+## Check if set
+
+If you need to check whether a header is set, use `*.headers.has(name)`:
+
+```javascript
+router.use((req, res) => {
+  if (!req.headers.has("x-api-key")) {
+    res.sendStatus(403);
+  }
+});
+```
+
+## Set headers
+
+Set request or response headers by calling `*.headers.set(key, value)`.
+
+```javascript
+router.get("/", (req, res) => {
+  res.headers.set("content-type", "text/html");
+  res.send("<html><body><h1>This is HTML!</h1></body></html>");
+});
+```
+
+## Append headers
+
+Append to request or response headers by calling `*.headers.append(key, value)`.
+
+```javascript
+router.get("/", (req, res) => {
+  res.headers.append("set-cookie", "auth=token");
+  res.headers.append("set-cookie", "user=me");
+  res.send("Hello world!");
+});
+```
+
+## Remove headers
+
+Remove request or response headers by calling `*.headers.delete(key)`.
+
+```javascript
+router.get("/", (req, res) => {
+  req.headers.delete("x-api-key");
+  // ...
+});
+```
+
+## Aliases
+
+### req/res.set
+
+Aliased helpers to set HTTP header values. To set multiple fields at once, pass an object as the only parameter.
+
+```javascript
+res.set("content-type", "text/plain");
+
+req.set({
+  "x-api-key": "my-api-key",
+  "x-debug": "1",
+  "host": "example.com"
+});
+```
+
+### req/res.append
+
+Aliased helpers to append HTTP header values. To set multiple fields at once, pass an object as the only parameter. To append iteratively to a single header, pass an array of strings as its value.
+
+```javascript
+res.append("link", ["<http://localhost/>", "<http://localhost:3000/>"]);
+
+req.append({
+  "warning": "199 Miscellaneous warning",
+  "x-forwarded-for": "example.com"
+});
+```

package/docs/docs/handling-data/request.md

@@ -0,0 +1,82 @@
+---
+sidebar_position: 1
+title: Request
+---
+
+# The Request object
+
+## Properties
+
+### req.url
+The [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) object corresponding to the request URL.
+
+### req.query
+Request [query string parameters](search-params.md).
+
+### req.params
+An object containing properties mapped to any [named route "parameters"](../routing#path-parameters), if the [`extractRequestParameters`](../config.md#extractRequestParameters) configuration option is enabled.
+
+### req.cookies
+A Map containing [request cookies](cookies.md#request-cookies), if the [`parseCookie`](../config.md#parseCookie) configuration option is enabled.
+
+### req.headers
+Request [headers](headers.md).
+
+### req.path
+The path part of the request URL.
+
+### req.ip
+The remote IP address of the request
+
+### req.protocol
+The request protocol string: either `http` or (for TLS requests) `https`.
+
+### req.secure
+A boolean value that is `true` if a TLS connection is established.
+
+### req.subdomains
+An array of subdomains in the domain name of the request.
+
+### req.hostname
+The hostname derived from the `Host` HTTP header.
+
+## Working with the request body
+
+**expressly** can parse the body of a **req**uest in multiple ways.
+
+### As plain text
+
+```javascript
+router.post("/submit", async (req, res) => {
+    let body = await req.text();
+
+    res.send(`You posted: "${body}"`)
+})
+```
+
+### As JSON
+
+```javascript
+router.post("/submit", async (req, res) => {
+    // Parse body as JSON
+    let body = await req.json();
+
+    // Check if the body contains the key "item"
+    if ("item" in body) {
+        res.send(`item: ${body.item}`)
+    } else {
+        res.send("You must include item in your body!")
+    }
+})
+```
+
+### As an ArrayBuffer
+
+```javascript
+router.post("/submit", async (req, res) => {
+    // Parse body into an ArrayBuffer
+    let body = await req.arrayBuffer();
+
+    console.debug(body);
+})
+```