Add shared plugin helpers

Author: mrbbot

packages/tre/src/plugins/shared/constants.ts

@@ -0,0 +1,36 @@
+import { Headers } from "undici";
+import { Worker_Binding } from "../../runtime";
+import { Persistence, PersistenceSchema } from "./gateway";
+
+export const SOCKET_ENTRY = "entry";
+
+export const HEADER_PERSIST = "MF-Persist";
+
+export const BINDING_SERVICE_LOOPBACK = "MINIFLARE_LOOPBACK";
+export const BINDING_TEXT_PLUGIN = "MINIFLARE_PLUGIN";
+export const BINDING_TEXT_NAMESPACE = "MINIFLARE_NAMESPACE";
+export const BINDING_TEXT_PERSIST = "MINIFLARE_PERSIST";
+
+// TODO: make this an inherited worker in core plugin
+export const SCRIPT_PLUGIN_NAMESPACE_PERSIST = `addEventListener("fetch", (event) => {
+  let request = event.request;
+  const url = new URL(request.url);
+  url.pathname = \`/\${${BINDING_TEXT_PLUGIN}}/\${${BINDING_TEXT_NAMESPACE}}\${url.pathname}\`;
+  if (globalThis.${BINDING_TEXT_PERSIST} !== undefined) {
+    request = new Request(request);
+    request.headers.set("${HEADER_PERSIST}", ${BINDING_TEXT_PERSIST});
+  }
+  event.respondWith(${BINDING_SERVICE_LOOPBACK}.fetch(url, request));
+});`;
+
+export function encodePersist(persist: Persistence): Worker_Binding[] {
+  if (persist === undefined) return [];
+  else return [{ name: BINDING_TEXT_PERSIST, text: JSON.stringify(persist) }];
+}
+
+export function decodePersist(headers: Headers): Persistence {
+  const header = headers.get(HEADER_PERSIST);
+  return header === null
+    ? undefined
+    : PersistenceSchema.parse(JSON.parse(header));
+}

packages/tre/src/plugins/shared/gateway.ts

@@ -0,0 +1,54 @@
+import path from "path";
+import { Clock, Storage, defaultClock, sanitisePath } from "@miniflare/shared";
+import { FileStorage } from "@miniflare/storage-file";
+import { MemoryStorage } from "@miniflare/storage-memory";
+import { z } from "zod";
+
+// TODO: explain why persist passed as header, want options set to be atomic,
+//  if set gateway before script update, may be using new persist before new script
+export const PersistenceSchema = z.boolean().or(z.string()).optional();
+export type Persistence = z.infer<typeof PersistenceSchema>;
+
+export interface GatewayConstructor<Gateway> {
+  new (storage: Storage, clock: Clock): Gateway;
+}
+
+const DEFAULT_PERSIST_ROOT = ".mf";
+
+export class GatewayFactory<Gateway> {
+  readonly #memoryStorages = new Map<string, MemoryStorage>();
+  readonly #gateways = new Map<string, [Persistence, Gateway]>();
+
+  constructor(
+    private readonly pluginName: string,
+    private readonly gatewayClass: GatewayConstructor<Gateway>
+  ) {}
+
+  #storage(namespace: string, persist: Persistence): Storage {
+    if (persist === undefined || persist === false) {
+      let storage = this.#memoryStorages.get(namespace);
+      if (storage !== undefined) return storage;
+      this.#memoryStorages.set(namespace, (storage = new MemoryStorage()));
+      return storage;
+    }
+
+    const sanitised = sanitisePath(namespace);
+    const root =
+      persist === true
+        ? path.join(DEFAULT_PERSIST_ROOT, this.pluginName, sanitised)
+        : path.join(persist, sanitised);
+    return new FileStorage(root);
+
+    // TODO: support Redis/SQLite storages?
+  }
+
+  get(namespace: string, persist: Persistence): Gateway {
+    const cached = this.#gateways.get(namespace);
+    if (cached !== undefined && cached[0] === persist) return cached[1];
+
+    const storage = this.#storage(namespace, persist);
+    const gateway = new this.gatewayClass(storage, defaultClock);
+    this.#gateways.set(namespace, [persist, gateway]);
+    return gateway;
+  }
+}

packages/tre/src/plugins/shared/index.ts

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import { Awaitable, OptionalZodTypeOf } from "../../helpers";
+import { Service, Worker_Binding } from "../../runtime";
+import { GatewayConstructor } from "./gateway";
+import { RouterConstructor } from "./router";
+
+export interface PluginServicesOptions<
+  Options extends z.ZodType,
+  SharedOptions extends z.ZodType | undefined
+> {
+  options: z.infer<Options>;
+  optionsVersion: number;
+  sharedOptions: OptionalZodTypeOf<SharedOptions>;
+  workerBindings: Worker_Binding[];
+  workerIndex: number;
+}
+
+export interface PluginBase<
+  Options extends z.ZodType,
+  SharedOptions extends z.ZodType | undefined
+> {
+  options: Options;
+  getBindings(
+    options: z.infer<Options>
+  ): Awaitable<Worker_Binding[] | undefined>;
+  getServices(
+    options: PluginServicesOptions<Options, SharedOptions>
+  ): Awaitable<Service[] | undefined>;
+}
+
+export type Plugin<
+  Options extends z.ZodType,
+  SharedOptions extends z.ZodType | undefined = undefined,
+  Gateway = undefined
+> = PluginBase<Options, SharedOptions> &
+  (SharedOptions extends undefined
+    ? { sharedOptions?: undefined }
+    : { sharedOptions: SharedOptions }) &
+  (Gateway extends undefined
+    ? { gateway?: undefined; router?: undefined }
+    : {
+        gateway: GatewayConstructor<Gateway>;
+        router: RouterConstructor<Gateway>;
+      });
+
+export * from "./constants";
+export * from "./gateway";
+export * from "./router";

packages/tre/src/plugins/shared/router.ts

@@ -0,0 +1,70 @@
+import { Awaitable } from "@miniflare/shared";
+import { Request, Response } from "undici";
+import { GatewayFactory } from "./gateway";
+
+export type RouteHandler<Params = unknown> = (
+  req: Request,
+  params: Params,
+  url: URL
+) => Awaitable<Response>;
+
+export abstract class Router<Gateway> {
+  // Routes added by @METHOD decorators
+  routes?: Map<string, (readonly [RegExp, string | symbol])[]>;
+
+  constructor(protected readonly gatewayFactory: GatewayFactory<Gateway>) {
+    // Make sure this.routes isn't undefined and has the prototype's value
+    this.routes = new.target.prototype.routes;
+  }
+
+  async route(req: Request, url?: URL): Promise<Response | undefined> {
+    url ??= new URL(req.url);
+    const methodRoutes = this.routes?.get(req.method);
+    if (methodRoutes !== undefined) {
+      for (const [path, key] of methodRoutes) {
+        const match = path.exec(url.pathname);
+        if (match !== null) {
+          return (this as unknown as Record<string | symbol, RouteHandler>)[
+            key
+          ](req, match.groups, url);
+        }
+      }
+    }
+  }
+}
+
+export interface RouterConstructor<Gateway> {
+  new (gatewayFactory: GatewayFactory<Gateway>): Router<Gateway>;
+}
+
+function pathToRegexp(path: string): RegExp {
+  // Optionally allow trailing slashes
+  if (!path.endsWith("/")) path += "/?";
+  // Escape forward slashes
+  path = path.replace(/\//g, "\\/");
+  // Replace `:key` with named capture groups
+  path = path.replace(/:(\w+)/g, "(?<$1>[^\\/]+)");
+  // Return RegExp, asserting start and end of line
+  return new RegExp(`^${path}$`);
+}
+
+const createRouteDecorator =
+  (method: string) =>
+  (path: string) =>
+  (prototype: typeof Router.prototype, key: string | symbol) => {
+    const route = [pathToRegexp(path), key] as const;
+    const routes = (prototype.routes ??= new Map<
+      string,
+      (readonly [RegExp, string | symbol])[]
+    >());
+    const methodRoutes = routes.get(method);
+    if (methodRoutes) methodRoutes.push(route);
+    else routes.set(method, [route]);
+  };
+
+export const GET = createRouteDecorator("GET");
+export const HEAD = createRouteDecorator("HEAD");
+export const POST = createRouteDecorator("POST");
+export const PUT = createRouteDecorator("PUT");
+export const DELETE = createRouteDecorator("DELETE");
+export const PATCH = createRouteDecorator("PATCH");

packages/tre/test/plugins/shared/router.spec.ts

@@ -0,0 +1,91 @@
+import assert from "assert";
+import {
+  GET,
+  GatewayFactory,
+  POST,
+  RouteHandler,
+  Router,
+} from "@miniflare/tre";
+import test from "ava";
+import { Request, Response } from "undici";
+
+// TODO: update to AVA 4
+
+class TestGateway {
+  constructor() {}
+}
+
+class TestRouter extends Router<TestGateway> {
+  constructor() {
+    super(new GatewayFactory("test", TestGateway));
+  }
+
+  @GET("/params/:foo/:bar")
+  get: RouteHandler<{ foo: string; bar: string }> = (req, params, url) => {
+    return Response.json({
+      method: req.method,
+      pathname: url.pathname,
+      searchParams: Object.fromEntries(url.searchParams),
+      params,
+    });
+  };
+
+  @POST("/")
+  echo: RouteHandler = async (req) => {
+    const body = await req.text();
+    return new Response(`body:${body}`);
+  };
+
+  @POST("/twice")
+  echoTwice: RouteHandler = async (req) => {
+    const body = await req.text();
+    return new Response(`body:${body}:${body}`);
+  };
+}
+
+test("Router: routes requests", async (t) => {
+  const router = new TestRouter();
+
+  // Check routing with params and search params
+  let res = await router.route(
+    new Request("http://localhost/params/one/two?q=thing")
+  );
+  assert(res);
+  t.is(res.status, 200);
+  t.deepEqual(await res.json(), {
+    method: "GET",
+    pathname: "/params/one/two",
+    searchParams: { q: "thing" },
+    params: { foo: "one", bar: "two" },
+  });
+
+  // Check trailing slash allowed
+  res = await router.route(new Request("http://localhost/params/a/b/"));
+  assert(res);
+  t.is(res.status, 200);
+  t.like(await res.json(), { params: { foo: "a", bar: "b" } });
+
+  // Check routing with body and `async` handler
+  res = await router.route(
+    new Request("http://localhost/", { method: "POST", body: "test" })
+  );
+  assert(res);
+  t.is(res.status, 200);
+  t.is(await res.text(), "body:test");
+
+  // Check routing with multiple handlers for same method
+  res = await router.route(
+    new Request("http://localhost/twice", { method: "POST", body: "test" })
+  );
+  assert(res);
+  t.is(res.status, 200);
+  t.is(await res.text(), "body:test:test");
+
+  // Check unknown route doesn't match
+  res = await router.route(new Request("http://localhost/unknown"));
+  t.is(res, undefined);
+
+  // Check unknown method but known path doesn't match
+  res = await router.route(new Request("http://localhost/", { method: "PUT" }));
+  t.is(res, undefined);
+});