@fastly/expressly 1.0.0-alpha.1 → 1.0.1-0

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,16 @@
+---
+name: Bug report
+about: Tell us about a bug to help us improve
+title: ''
+labels: bug
+assignees: doramatadora
+
+---
+
+**Version**
+
+Please provide the version of `expressly` that you're using.
+
+**What happened**
+
+Please describe what you did, what you expected to happen, and what happened instead.

package/.github/workflows/docs.yml

@@ -0,0 +1,52 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+
+concurrency:
+  group: ${{ github.ref_name }}-docs
+  cancel-in-progress: true
+
+jobs:
+  publish-docs:
+    name: Publish
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ./docs
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          node-version: 16
+          cache: yarn
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile --prefer-offline
+      - name: Node modules cache
+        id: node-modules-cache
+        uses: actions/cache@v2
+        with:
+          path: node_modules
+          key: ${{ runner.os }}-expressly-docs-${{ secrets.cache_key_epoch_time }}-${{ hashFiles('yarn.lock') }}
+      - name: Compile docs
+        run: yarn build
+      - name: Install Rust toolchain
+        uses: actions-rs/toolchain@v1
+        with:
+            toolchain: stable
+            target: wasm32-wasi
+      - name: Deploy docs to Compute@Edge
+        uses: fastly/compute-actions@main
+        with:
+          project_directory: ./docs/static-host
+        env:
+          FASTLY_API_TOKEN: ${{ secrets.FASTLY_API_TOKEN }}
+      - name: Purge expressly.edgecompute.app
+        env:
+          FASTLY_API_TOKEN: ${{ secrets.FASTLY_API_TOKEN }}
+        run: |
+          curl -s -H "Fastly-Key: $FASTLY_API_TOKEN" -X POST "https://api.fastly.com/service/44O0OSuWrOWkzVek5Gg4QN/purge_all"
+        

package/.github/workflows/release.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  - workflow_dispatch
+  - pull_request
+
+concurrency:
+  group: ${{ github.ref_name }}-expressly
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: expressly
+    runs-on: ubuntu-latest
+    env:
+      GH_TOKEN: ${{ secrets.AUTO_GH_TOKEN }}
+      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+      NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          node-version: 16
+          cache: yarn
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile --prefer-offline
+      - name: Node modules cache
+        id: node-modules-cache
+        uses: actions/cache@v2
+        with:
+          path: node_modules
+          key: ${{ runner.os }}-expressly-${{ secrets.cache_key_epoch_time }}-${{ hashFiles('yarn.lock') }}
+      - name: Compile expressly
+        run: yarn build
+      - name: Publish
+        run: |
+          git fetch origin 'refs/tags/*:refs/tags/*'
+          yarn auto shipit

package/.husky/pre-commit

@@ -0,0 +1,4 @@
+#!/bin/sh
+. "$(dirname "$0")/_/husky.sh"
+
+yarn pretty-quick --staged

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# v1.0.0 (Wed Jun 08 2022)
+
+#### ⚠️ Pushed to `main`
+
+- update auto config ([@doramatadora](https://github.com/doramatadora))
+
+#### Authors: 1
+
+- Dora Militaru ([@doramatadora](https://github.com/doramatadora))

package/README.md

@@ -53,3 +53,4 @@ This will start your service on [http://localhost:7676](http://localhost:7676).
 ## Examples
 
 Check out the JavaScript code examples for Compute@Edge on Fastly's [Developer Hub](https://developer.fastly.com/solutions/examples/javascript/).
+ß

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);
+})
+```

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

@@ -0,0 +1,162 @@
+---
+sidebar_position: 2
+---
+
+# Response
+
+The **res**ponse object is the primary way to send data back to the client. **expressly** provides methods to set the response status, headers, and body.
+
+## res.send()
+
+The easiest way to deliver a response is to use the **res.send()** method. This method takes a single argument, which is the response body.
+The response body can be:
+
+* A `string`,
+
+```javascript
+router.get('/', (req, res) => {
+  res.send('Hello World!');
+});
+```
+
+* A `ReadableStream`,
+
+```javascript
+router.get("/api", async (req, res) => {
+  let originRequest = await fetch(
+    "https://example.com", { backend: "my-origin" }
+  );
+
+  res.send(res.body);
+});
+```
+
+* Or a `Response`:
+
+```javascript
+router.get("/origin", async (req, res) => {
+  res.send(await fetch(
+    "https://example.com", { backend: "my-origin" }
+  ));
+});
+```
+> 💡 If the _experimental_ [`autoContentType`](../config.md#parseCookie) configuration option is enabled, `res.send` 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.
+
+## res.end()
+
+Use to quickly end the response without any data. If you need to respond with data, instead use methods such as [`res.send()`](#ressend) or [`res.json()`](#resjson).
+
+```javascript
+router.get('/', (req, res) => {
+  res.end();
+});
+```
+
+## res.sendStatus()
+
+Sets the response HTTP status code to statusCode and sends the registered status message as the text response body.
+
+```javascript
+router.get('/', (req, res) => {
+  res.sendStatus(403); // "Forbidden"
+});
+```
+
+## res.redirect()
+
+When you want to redirect the user to another page, you can use the `res.redirect()` method. It will set a redirect status code and set the `Location` header to the URL you want to redirect to.
+
+```javascript
+router.get('/', function(req, res) {
+  res.redirect('/about');
+});
+```
+> 💡 This method accepts a second, optional argument – the redirect status code (defaults to `302`).
+
+```javascript
+router.get("/redirect", async (req, res) => {
+  res.redirect("https://fastly.com", 307);
+});
+```
+
+## res.json()
+
+To return a serialized JSON response (`Content-Type: application/json`):
+
+```javascript
+router.get('/', function(req, res) {
+  res.json({
+    message: 'Hello world!'
+  });
+});
+```
+
+## res.text()
+
+To return a plain-text response (`Content-Type: text/plain`):
+
+```javascript
+router.get("/api", async (req, res) => {
+  res.text("Hello world!");
+});
+```
+
+## res.html()
+
+To return a HTML response (`Content-Type: text/html[; charset=my-charset]`):
+
+```javascript
+router.get("/page", async (req, res) => {
+  // Takes a second, optional argument specifying a charset:
+  res.html("<html><body><h1>This is HTML!</h1></body></html>", "utf-8");
+});
+```
+
+## res.withStatus()
+
+**expressly** provides a chainable method to set the status code of a response:
+
+```javascript
+router.get("/page", async (req, res) => {
+  res
+    .withStatus(404)
+    .html("<html><body><h1>Page not found</h1></body></html>");
+});
+```
+
+
+## Response headers
+
+[Read more](../handling-data/headers.md) about manipulating response (and request) headers with **expressly**.
+
+
+## Cookies
+
+[Read how to](../handling-data/cookies.md#response-cookies) set and expire response cookies.
+
+## Cache segmentation
+
+### res.vary()
+
+Appends a field to the `Vary` response header.
+
+```javascript
+res.vary("x-feature-flags");
+```
+
+### res.surrogateKeys
+
+**expressly** exposes `res.surrogateKeys`, a [`Set`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) object that allows you to manipulate the [`Surrogate-Key` header](https://developer.fastly.com/reference/http/http-headers/Surrogate-Key/).
+
+
+```javascript
+res.surrogateKeys.add("seasonal");
+res.surrogateKeys.add("vegan");
+res.surrogateKeys.delete("low-carb");
+
+// List all surrogate keys
+for (const key of res.surrogateKeys) {
+  console.log(key);
+}
+```
+