gruber 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 This file documents notable changes to the project
 
+## next
+
+...
+
+## 0.6.0
+
+**new**
+
+- Create the Terminator, an API like [@godaddy/terminus](https://github.com/godaddy/terminus) for cross-platform graceful HTTP shutdown.
+- (unstable) Authorize & Authenticate requests
+- (unstable) Store things in key-value pairs
+- (unstable) `serveHTTP` for Node.js a la `Deno.serve`
+
+**changed**
+
+- Deprecated environment-specific functions in favour of simpler names
+  - `get{Node,Deno}ConfigOptions` → `getConfigurationOptions`
+  - `get{Node,Deno}Configuration` → `getConfiguration`
+  - `get{Node,Deno}PostgresMigratorOptions` → `getPostgresMigratorOptions`
+  - `get{Node,Deno}PostgresMigrator` → `getPostgresMigrator`
+
+**fixes**
+
+- NodeRouter sets the correct `duplex` option
+- FetchRouter ignores the body for `OPTIONS` & `TRACE` methods
+
+**internal**
+
+- Gruber is now primarily TypeScript, with JavaScript tests
+
 ## 0.5.0
 
 **new**

package/README.md

@@ -21,9 +21,6 @@ An isomorphic JavaScript library for creating web apps.
 This is very much a WIP library, it started out as a documentation-driven-development project and I've slowly been building it.
 The various ideas it's composed of have been floating around in my mind for a year or so and writing this has helped explore those ideas.
 
-I quite like this documentation-driven-design.
-It really helps to think through the concepts and ideas of something before spending lots of time building it.
-
 ## About
 
 Gruber is a library of composable utilities for creating isomorphic JavaScript applications,
@@ -100,12 +97,22 @@ npm install gruber
 
 **Deno**
 
-Gruber is available at `esm.r0b.io/gruber@VERSION/mod.ts`.
+Gruber is available at `esm.r0b.io/gruber@VERSION/mod.ts`, add it to your _deno.json_:
 
 > Replace `VERSION` with the one you want to use, maybe see [Releases](https://github.com/robb-j/gruber/releases).
 
+```json
+{
+	"imports": {
+		"gruber/": "https://esm.r0b.io/gruber@VERSION/"
+	}
+}
+```
+
+Then use it like this:
+
 ```js
-import { defineRoute } from "https://esm.r0b.io/gruber@VERSION/mod.ts";
+import { defineRoute } from "gruber/mod.ts";
 ```
 
 ## HTTP server
@@ -130,14 +137,14 @@ export default defineRoute({
 });
 ```
 
-A route is a definition to handle a specific HTTP request by returning a response.
+A route is a definition to handle a specific HTTP request with a response.
 It defines which method and path it is responding to and an asynchronous function to handle the request.
 
 Both the [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request)
 and [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response)
 are from the web Fetch API.
 
-It also has a `url` (as a [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL)) of the request and `params`.
+There is also a `url` (as a [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL)) of the request and `params`.
 The parameters, `params`, are matched from the pathname, part of the result of [URLPattern.exec](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern/exec).
 In this example `name` is matched in the request URL and is used to process the request.
 
@@ -165,7 +172,7 @@ export async function runServer(options) {
 If you were using Deno, the same server would look like:
 
 ```js
-import { DenoRouter } from "@gruber/deno/mod.js";
+import { DenoRouter } from "@gruber/mod.js";
 
 import helloRoute from "./hello-route.js";
 
@@ -210,6 +217,57 @@ try {
 }
 ```
 
+**a terminator**
+
+For highly available deployments and/or where you want a zero downtime deployment,
+you might run your server behind a load balancer.
+When a deployment goes out you run both instances at the same time
+and instantly switch traffic at the network level when the new deployment is up and running.
+
+To help with this your app often implements a `/healthz`-type endpoint that returns when your app is accepting network connections
+or if it is terminating existing connections ready to be descheduled.
+Terminator is here to help with this use-case.
+
+```js
+import { DenoRouter, Terminator } from "@gruber/mod.js";
+
+import { appConfig } from "./config.js";
+import helloRoute from "./hello-route.js";
+
+// 1. Create your Terminator, maybe call them arnie
+export const terminator = new Terminator({
+	timeout: appConfig.env === "development" ? 0 : 5_000,
+});
+
+// 2. Define the health endpoint
+const healthzRoute = defineRoute({
+	method: "GET",
+	pathname: "/healthz",
+	handler: () => terminator.getResponse(),
+});
+
+export const routes = [helloRoute, healthzRoute];
+
+export async function runServer(options) {
+	const router = new DenoRouter({ routes });
+
+	const server = Deno.serve({ port: options.port }, router.forDenoServe());
+
+	// 3. Start the terminator and define the shutdown procedure
+	terminus.start(async () => {
+		await server.shutdown();
+		// Perform clean-up
+		// Close the database connection
+		// ...
+	});
+}
+```
+
+> You might want to have this in separate files, this is just to easily document it in one place.
+
+By default Terminator waits 5 seconds to terminate and listens for `SIGINT` and `SIGTERM`.
+A nice pattern is to skip waiting in development, shown above.
+
 ## Configuration
 
 In production, it's very useful to be able to configure how an app behaves without having to modify the code and redeploy the entire thing.
@@ -243,10 +301,10 @@ Building on the [HTTP server](#http-server) above, we'll setup configuration. St
 
 ```js
 import fs from "node:fs";
-import { getNodeConfiguration } from "gruber";
+import { getConfiguration } from "gruber";
 
 const pkg = JSON.parse(fs.readFileSync("./package.json", "utf8"));
-const config = getNodeConfiguration();
+const config = getConfiguration();
 
 const struct = config.object({
 	env: config.string({ variable: "NODE_ENV", fallback: "development" }),
@@ -448,7 +506,7 @@ and we need to set up our database with **database.js**
 ```js
 import process from "node:process";
 import postgres from "postgres";
-import { loader, getNodePostgresMigrator } from "gruber";
+import { loader, getPostgresMigrator } from "gruber";
 import { appConfig } from "./config.js";
 
 export const useDatabase = loader(() => {
@@ -457,7 +515,7 @@ export const useDatabase = loader(() => {
 });
 
 export async function getMigrator() {
-	return getNodePostgresMigrator({
+	return getPostgresMigrator({
 		directory: new URL("./migrations/", import.meta.url),
 		sql: await useDatabase(),
 	});
@@ -668,7 +726,9 @@ TODO: I'm not happy with this, will need to come back to it.
 
 ## Core library
 
-### defineRoute
+### http
+
+#### defineRoute
 
 `defineRoute` is the way of creating route primatives to be passed to your router to handle web traffic.
 
@@ -687,7 +747,7 @@ export const helloRoute = defineRoute({
 });
 ```
 
-### HTTPError
+#### HTTPError
 
 `HTTPError` is an Error subclass with specific information about HTTP errors.
 Gruber catches these errors and converts them into HTTP Responses.
@@ -770,7 +830,7 @@ class BadJSONRequest extends HTTPError {
 throw new BadJSONRequest({ message: "Something went wrong..." });
 ```
 
-### FetchRouter
+#### FetchRouter
 
 `FetchRouter` is a web-native router for routes defined with `defineRoute`.
 
@@ -807,11 +867,15 @@ Use it to get a `Response` from the provided request, based on the router's rout
 const response = await router.getResponse(new Request("http://localhost"));
 ```
 
+#### unstable http
+
 There are some unstable internal methods too:
 
 - `findMatchingRoutes(request)` is a generator function to get the first route definition that matches the supplied request. It's a generator so as few routes are matched as possible and execution can be stopped if you like.
 - `processMatches(request, matches)` attempts to get a `Response` from a request and an Iterator of route definitions.
 - `handleError(error, request)` converts a error into a Response and triggers the `errorHandler`
+- `getRequestBody(request)` Get the JSON of FormData body of a request
+- `assertRequestBody(struct, body)` Assert the body matches a structure and return the parsed value
 
 ### Postgres
 
@@ -917,6 +981,171 @@ On the error, there are also methods to help use it:
 
 There is also the static method `StructError.chain(error, context)` which is useful for catching errors and applying a context to them (if they are not already a StructError).
 
+### Terminator
+
+Terminator helps you gracefully deploy servers with zero downtime when using a load balancer.
+
+```js
+import { Terminator } from "gruber/terminator.js";
+
+// All options are optional, these are also the defaults
+const arnie = new Terminator({
+	signals: ["SIGINT", "SIGTERM"],
+	timeout: 5_000,
+});
+
+// Generate a HTTP response based on the current state of the Terminator
+// A 200 if running or 503 if terminating
+const response = arnie.getResponse();
+
+// Get the current state of the Terminator, either 'running' or 'terminating'
+arnie.state;
+
+// Start the Terminator process and define the shutdown procedure
+arnie.start(async () => {
+	// shut down things like HTTP servers or database connections
+});
+```
+
+The block passed to `start` can be async and it handles errors by logging them and exiting with a non-zero status code.
+
+### Store
+
+> UNSTABLE
+
+The Store is for when you have values that you want to remember under certain keys.
+It is an abstract interface over that so there can be multiple implementations
+for different storage methods and so it can be inter-operated between different services.
+
+While some implementations may be sync, the interface is based on async so both can co-exist.
+
+There is a rough idea of using absolute paths, e.g. `/some/absolute/path`
+and some stores may offer a "prefix" option to allow multi-tennancy
+so the store internally could put it at `/v1/some/absolute/path`.
+
+```ts
+import { MemoryStore } from "gruber";
+
+const store = new MemoryStore();
+
+// Put geoff in the store
+await store.set("/some/key", { name: "Geoff Testington", age: 42 });
+
+// Put something in the store, just for a bit
+await store.set(
+	"/login/55",
+	{ token: "abcdef" },
+	{ expireAfter: 30 * 1_000 /* 30 seconds */ },
+);
+
+// Retrieve geoff, types optional
+const geoff = await store.get<GeoffRecord>("/some/key");
+
+// Ok, time for geoff to go
+await store.delete("/some/key");
+```
+
+The store is meant for temporary resources, so its mostly meant to be called with the `expireAfter` option
+
+> The `MemoryStore` is also useful for testing, you can provide a TimerService to mock time
+
+There are these experimental stores too:
+
+```ts
+import { PostgresStore, RedisStore } from "gruber";
+import { Sql } from "postgres";
+import { RedisClientType } from "redis";
+
+const sql: Sql;
+const store = new PostgresStore(sql, { tableName: "cache" });
+
+const redis: RedisClientType;
+const store = new RedisStore(redis, { prefix: "/v2" });
+```
+
+### Authorization
+
+> UNSTABLE
+
+A module for checking Request objects have authorization to perform actions on the server
+
+```ts
+import { JWTService, AuthorizationService } from "gruber";
+
+const jwt: JWTService;
+const authz = new AuthorizationService({ cookieName: "my_session" }, jwt);
+
+const { userId, scope } = await authz.getAuthorization(
+	new Request("https://example.com", {
+		headers: { Authorization: "Bearer some-long-secure-token" },
+	}),
+);
+
+const { userId, scope } = await authz.getAuthorization(
+	new Request("https://example.com", {
+		headers: { Cookie: "my_session=some-long-secure-token" },
+	}),
+);
+
+const { userId, scope } = await authz.assertUser(
+	"user:books:read",
+	new Request("https://example.com", {
+		headers: { Authorization: "Bearer some-long-secure-token" },
+	}),
+);
+```
+
+Any of these methods will throw a `HTTPError.unauthorized` (a 401) if the authorization is not present or invalid.
+
+**scopes**
+
+Scopes are abstract hierarchical access to things in your application.
+They are checked from left to right, so if the request has the top-level it allows access to scopes beneath it.
+There is also the special `admin` scope which has access to all resources.
+
+The idea is you might check for `user:books:write` inside a request handler against the scope the request is authorized with. When the user signed in or created that access token, it might only have `user:bookes:read` so now we know they cannot perform this request.
+
+### Authentication
+
+> UNSTABLE
+
+Authentication provides a service to help users get authorization to use the application.
+
+```ts
+import {
+	AuthenticationService,
+	Store,
+	RandomService,
+	JWTService,
+} from "gruber";
+
+const store: Store;
+const jwt: JWTService;
+const random: RandomService; // OR // = useRandom()
+const options = {
+	allowedHosts: () => [new URL("https://example.com")],
+	cookieName: "my_session",
+	sessionDuration: 30 * 24 * 60 * 60 * 1_000, // 30 days
+	loginDuration: 15 * 60 * 1_000, // 15 minutes
+};
+
+const authn = new AuthenticationService(options, store, random, jwt);
+
+// Get the token and code the user must match to complete the authentication
+// These could be sent in a magic link perhaps
+const { token, code } = await authn.start(userId, redirectUrl);
+
+// Use a user-provided token & code to check if they are a valid log in
+const login = await authn.check(token, code);
+
+// If valid, complete the authentication and get back their redirect,
+// headers to set the authz cookie and their raw token too
+const { token, headers, redirect } = await authn.finish(login);
+```
+
+These would obviously be spread accross multiple endpoints and you transfer
+the token / code combination to the user in a way that proves they are who they claim to be.
+
 ### Utilities
 
 #### loader
@@ -1009,11 +1238,11 @@ These are the options:
 For example, to override in Node:
 
 ```js
-import { Configuration, getNodeConfigOptions } from "gruber";
+import { Configuration, getConfigurationOptions } from "gruber";
 import Yaml from "yaml";
 
 const config = new Configuration({
-	...getNodeConfigOptions(),
+	...getConfigurationOptions(),
 	getEnvionmentVariable: () => undefined,
 	stringify: (v) => Yaml.stringify(v),
 	parse: (v) => Yaml.parse(v),
@@ -1199,6 +1428,16 @@ const server = http.createServer((req) => {
 });
 ```
 
+#### getResponseReadable
+
+`getResponseReadable` creates a [streams:Readable](https://nodejs.org/api/stream.html#class-streamreadable) from the body of a fetch Response.
+
+```js
+import { getResponseReadable } from "gruber/node-router.js";
+
+const readable = getResponseReadable(new Response("some body"));
+```
+
 ## Development
 
 WIP stuff

package/core/authentication.d.ts

@@ -0,0 +1,51 @@
+import { RandomService } from "./random.ts";
+import { Store } from "./store.ts";
+import { JWTService } from "./jwt.ts";
+/**
+ * An in-progress authentication, being stored while the client completes their challenge
+ */
+export interface AuthnRequest {
+    userId: number;
+    redirect: string;
+    code: number;
+}
+/**
+ * Intermediary parameters to present to the user to complete their authentication
+ */
+export interface AuthnCheck {
+    token: string;
+    code: number;
+}
+/**
+ * Completed credentials after completing an authentication,
+ * including cookie+redirected headers and the redirect itself
+ */
+export interface AuthnResult {
+    token: string;
+    headers: Headers;
+    redirect: string;
+}
+export interface AbstractAuthenticationService {
+    check(token: string, code: number): Promise<AuthnRequest | null>;
+    start(userId: number, redirectUrl: string | URL): Promise<AuthnCheck>;
+    finish(request: AuthnRequest): Promise<AuthnResult>;
+}
+export declare function formatCode(code: number): string;
+export interface AuthenticationServiceOptions {
+    allowedHosts: () => URL[] | Promise<URL[]>;
+    cookieName: string;
+    /** milliseconds */ loginDuration: number;
+    /** milliseconds */ sessionDuration: number;
+}
+export declare class AuthenticationService implements AbstractAuthenticationService {
+    options: AuthenticationServiceOptions;
+    store: Store;
+    random: RandomService;
+    jwt: JWTService;
+    constructor(options: AuthenticationServiceOptions, store: Store, random: RandomService, jwt: JWTService);
+    _canRedirect(input: string | URL, hosts: URL[]): boolean;
+    check(token: string | undefined | null, code: string | number | undefined | null): Promise<AuthnRequest | null>;
+    start(userId: number, redirectUrl: string | URL): Promise<AuthnCheck>;
+    finish(request: AuthnRequest): Promise<AuthnResult>;
+}
+//# sourceMappingURL=authentication.d.ts.map

package/core/authentication.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authentication.d.ts","sourceRoot":"","sources":["authentication.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAEtC;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,MAAM,EAAE,MAAM,CAAC;IAEf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACb;AAKD;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACb;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,6BAA6B;IAC7C,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IACjE,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACtE,MAAM,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CACpD;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,UAKtC;AAED,MAAM,WAAW,4BAA4B;IAC5C,YAAY,EAAE,MAAM,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,mBAAmB,CAAC,aAAa,EAAE,MAAM,CAAC;IAC1C,mBAAmB,CAAC,eAAe,EAAE,MAAM,CAAC;CAC5C;AAED,qBAAa,qBAAsB,YAAW,6BAA6B;IAElE,OAAO,EAAE,4BAA4B;IACrC,KAAK,EAAE,KAAK;IACZ,MAAM,EAAE,aAAa;IACrB,GAAG,EAAE,UAAU;gBAHf,OAAO,EAAE,4BAA4B,EACrC,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,aAAa,EACrB,GAAG,EAAE,UAAU;IAOvB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE;IAcxC,KAAK,CACV,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAChC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,IAAI,GACtC,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAkBzB,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,UAAU,CAAC;IAoBrE,MAAM,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;CAuBzD"}

package/core/authentication.js

@@ -0,0 +1,81 @@
+import { HTTPError } from "./http.js";
+export function formatCode(code) {
+    return [
+        code.toString().padStart(6, "0").slice(0, 3),
+        code.toString().padStart(6, "0").slice(3, 6),
+    ].join(" ");
+}
+export class AuthenticationService {
+    options;
+    store;
+    random;
+    jwt;
+    constructor(options, store, random, jwt) {
+        this.options = options;
+        this.store = store;
+        this.random = random;
+        this.jwt = jwt;
+    }
+    //
+    // Internal
+    //
+    _canRedirect(input, hosts) {
+        const url = new URL(input);
+        for (const allowed of hosts) {
+            if (url.protocol !== allowed.protocol)
+                continue;
+            if (url.host !== allowed.host)
+                continue;
+            if (url.pathname.startsWith(allowed.pathname))
+                return true;
+        }
+        return false;
+    }
+    //
+    // Public
+    //
+    async check(token, code) {
+        if (typeof code === "string")
+            code = parseInt(code);
+        if (typeof token !== "string" ||
+            typeof code !== "number" ||
+            Number.isNaN(code)) {
+            return null;
+        }
+        const loginRequest = await this.store.get(`/authn/request/${token}`);
+        if (!loginRequest || code !== loginRequest.code)
+            return null;
+        return loginRequest;
+    }
+    async start(userId, redirectUrl) {
+        const allowedHosts = await this.options.allowedHosts();
+        if (!this._canRedirect(redirectUrl, allowedHosts)) {
+            throw HTTPError.badRequest("invalid redirect_uri");
+        }
+        const token = this.random.uuid();
+        const request = {
+            userId,
+            redirect: new URL(redirectUrl).toString(),
+            code: this.random.number(0, 999_999),
+        };
+        await this.store.set(`/authn/request/${token}`, request, {
+            expireAfter: this.options.loginDuration,
+        });
+        return { token, code: request.code };
+    }
+    async finish(request) {
+        const headers = new Headers();
+        headers.set("Location", request.redirect);
+        const token = await this.jwt.sign("user", {
+            userId: request.userId,
+            expireAfter: this.options.sessionDuration,
+        });
+        const duration = Math.floor(this.options.sessionDuration / 1000);
+        // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie
+        headers.append("Set-Cookie", `${this.options.cookieName}=${token}; Max-Age=${duration}; Path=/; HttpOnly`);
+        // TODO: Microsoft "safe links" opens URLs, generates auth then throws it away
+        // Maybe it should be a counter? like 3 you get uses
+        // await cache.delete(`/authn/request/${token}`)
+        return { token, headers, redirect: request.redirect };
+    }
+}