@uniflowed/server 0.0.0-alpha.10

package/cache.js

@@ -0,0 +1,341 @@
+// @flow
+//
+// `@uniflowed/server/cache`: the cache, and the two ways to invalidate it.
+//
+// `uf.config.js` has had `rendering.cache` in it for a long time, and until now
+// the four switches under it were read once, copied into
+// `dist/uf-build-manifest.json` and read by nothing. Two of them mean something
+// from here on — `route` and `fetch` — and two of them do not, which is stated
+// rather than implied: `data` and `actions` are refused by the configuration
+// loader, by name, because a key that accepts `true` and changes nothing is
+// worse than a key that is not there. See ubugeeei-prod/uf#277.
+//
+// # What is here
+//
+// * [`createCacheStore`] — the store. Its contract is written out in
+//   `./internal/cache-store.js`: what a key is, what an entry is, when an entry
+//   is stale, who evicts, and what happens to a request that arrives while an
+//   entry is being filled. Read that before this.
+// * [`cacheLife`] and [`cacheTag`] — what a render says about the entry it is
+//   filling, from inside the render.
+// * [`noStore`] — what it says when the answer must not be kept.
+// * [`revalidateTag`] and [`revalidatePath`] — what a server action or a route
+//   handler says when the data changed.
+// * [`createCachedFetch`] — the fetch cache, as a wrapper.
+//
+// # What is not here, and will not be quietly added
+//
+// **No entry is stored without a stated lifetime.** There is no "cache forever"
+// and no default lifetime. A route that never calls [`cacheLife`] is rendered
+// for every request exactly as it is today, whatever `rendering.cache.route`
+// says — the switch decides whether a *stated* lifetime is honoured, not
+// whether uf starts keeping documents nobody asked it to keep.
+//
+// **A render that read the request is never stored.** `cookies()`, `headers()`
+// and `draftMode()` are how a document comes to be about one person, and a
+// document about one person in a cache shared by every person is the worst bug
+// a framework can have. `./fetch.js` counts those reads across the whole render
+// and refuses to store when the count moved. It is a runtime refusal today;
+// `crates/uf_rsc` already answers "is this call reachable from here" for
+// server-only imports, and turning the same question on a cached scope is what
+// would make it a build error instead. #277 argues that, and it is not done.
+//
+// # Where it lives
+//
+// In memory, in one process. Four processes behind a load balancer hold four of
+// these and disagree; a restart empties it; `revalidateTag` in one of them does
+// not reach the other three. That is the whole truth about it today and there
+// is no configuration that changes it. What would is a durable store behind
+// `resolve`, which is an adapter's to provide.
+
+import type {
+  CacheLifetime,
+  CacheOptions,
+  CacheRequest,
+  CacheStoreOptions,
+} from "./internal/cache-store.js";
+import { CacheStore, currentScope } from "./internal/cache-store.js";
+import type { CacheKey } from "./internal/cache-key.js";
+import { currentContext } from "./internal/context.js";
+
+export type { CacheKey } from "./internal/cache-key.js";
+export type {
+  CacheEntry,
+  CacheLifetime,
+  CacheOptions,
+  CacheOutcome,
+  CacheRequest,
+  CacheResult,
+  CacheStats,
+  CacheStoreOptions,
+} from "./internal/cache-store.js";
+export { CacheStore } from "./internal/cache-store.js";
+
+/**
+ * Raised when something that only means anything inside a cached fill is called
+ * outside one.
+ *
+ * Names the binding, for the same reason `OutsideRequestError` does: "no cache
+ * scope" leaves a reader hunting for which call was the one out of place.
+ */
+export class OutsideCacheScopeError extends Error {
+  /** The binding that was called, e.g. `cacheTag`. */
+  binding: string;
+
+  constructor(binding: string) {
+    super(
+      `@uniflowed/server: ${binding}() was called outside a cached scope. ` +
+        "It states something about the entry being filled, and nothing is being filled here — " +
+        "a module's top level, a client component, or a request answered by a host that " +
+        "established no render scope.",
+    );
+    this.name = "OutsideCacheScopeError";
+    this.binding = binding;
+  }
+}
+
+/** Raised when the cache is asked about from outside a request that has one. */
+export class OutsideCachedRequestError extends Error {
+  /** The binding that was called, e.g. `revalidateTag`. */
+  binding: string;
+
+  constructor(binding: string) {
+    super(
+      `@uniflowed/server: ${binding}() needs the cache the host installed for this request, ` +
+        "and there is not one here. Either this is outside a request, or the host answered it " +
+        "without passing `cache` to createFetchHandler — which is what `rendering.cache` in " +
+        "uf.config.js turns on.",
+    );
+    this.name = "OutsideCachedRequestError";
+    this.binding = binding;
+  }
+}
+
+/**
+ * A cache.
+ *
+ * A function rather than the constructor as the front door, so the store can
+ * grow a second implementation — a durable one, from an adapter — without every
+ * caller having named a class.
+ */
+export function createCacheStore(options?: CacheStoreOptions): CacheStore {
+  return new CacheStore(options);
+}
+
+/**
+ * How long the entry this render is filling stays usable.
+ *
+ * Called from inside the render, by whatever knows the answer — a loader knows
+ * how often its data changes and the handler above it does not. Called twice,
+ * the *shorter* lifetime wins: a page composed of a thing that changes hourly
+ * and a thing that changes by the minute is a page that changes by the minute,
+ * and taking the longer one would serve the fast half stale for an hour.
+ */
+export function cacheLife(lifetime: CacheLifetime): void {
+  const scope = currentScope();
+  if (scope == null) {
+    throw new OutsideCacheScopeError("cacheLife");
+  }
+  const held = scope.lifetime;
+  if (held == null || lifetime.revalidate < held.revalidate) {
+    scope.lifetime = lifetime;
+  }
+}
+
+/**
+ * Label the entry this render is filling, so `revalidateTag` can reach it.
+ *
+ * Tags are what make invalidation a statement about meaning rather than about
+ * spelling: a mutation says "posts changed" and every entry that read a post
+ * goes, without the mutation knowing which URLs those were.
+ */
+export function cacheTag(...tags: $ReadOnlyArray<string>): void {
+  const scope = currentScope();
+  if (scope == null) {
+    throw new OutsideCacheScopeError("cacheTag");
+  }
+  for (const tag of tags) {
+    if (typeof tag !== "string" || tag === "") {
+      throw new TypeError(
+        "@uniflowed/server: a cache tag is a non-empty string; " +
+          `cacheTag received ${JSON.stringify(tag)}.`,
+      );
+    }
+    scope.tags.push(tag);
+  }
+}
+
+/**
+ * Refuse to store the entry this render is filling.
+ *
+ * `reason` is kept because the interesting question about an uncached page is
+ * never "is it cached" but "why is it not", and the answer is usually six
+ * frames down in somebody else's module. The first reason wins: what stopped an
+ * answer being stored is the first thing that did.
+ */
+export function noStore(reason: string = "noStore() was called"): void {
+  const scope = currentScope();
+  if (scope == null) {
+    throw new OutsideCacheScopeError("noStore");
+  }
+  scope.denied ??= reason;
+}
+
+/** The cache the host installed for this request, or a named failure. */
+function require$Cache(binding: string): CacheOptions {
+  const cache = requestCache();
+  if (cache == null) {
+    throw new OutsideCachedRequestError(binding);
+  }
+  return cache;
+}
+
+/**
+ * Expire every entry filled under `tag`. Answers how many went.
+ *
+ * Expired, not marked stale: a tag is invalidated because somebody changed the
+ * thing it names, so the entry is known wrong rather than possibly old. See
+ * `./internal/cache-store.js`, which argues the difference.
+ *
+ * In this process. A deployment with four of them has four caches and this
+ * empties one — which is why the count comes back rather than nothing, so a
+ * caller can log what it actually did rather than what it meant to.
+ */
+export function revalidateTag(tag: string): number {
+  return require$Cache("revalidateTag").store.revalidateTag(tag);
+}
+
+/** Expire every entry filled for `path`. Answers how many went. */
+export function revalidatePath(path: string): number {
+  return require$Cache("revalidatePath").store.revalidatePath(path);
+}
+
+/** The cache answering this request, or `null` where the host installed none. */
+export function requestCache(): CacheOptions | null {
+  return currentContext()?.cache ?? null;
+}
+
+/** A request, plus what it says about caching itself. */
+export type CachedRequestOptions = {
+  readonly method?: string,
+  readonly searchParams?: { readonly [string]: string | number | boolean },
+  /** Absent means "do not cache this", which is the default and stays it. */
+  readonly cache?: FetchCacheOptions,
+  ...
+};
+
+/**
+ * The half of a fetch client this module calls.
+ *
+ * Declared structurally rather than imported from `@uniflowed/fetch`, and that
+ * is a decision rather than an oversight. `@uniflowed/fetch`'s own header says
+ * what it is — a failed response that is a failed promise, a timeout, and a
+ * retry policy — and a cache is none of those three; putting one inside it
+ * would make the thin wrapper thick, and would put a server cache in a package
+ * a client bundle imports. So the caching lives on the server side and reaches
+ * the client through the one method it calls, exactly as
+ * `./internal/application.js` names the two methods of a Node stream rather
+ * than importing `node:stream` into a module a worker has to bundle.
+ */
+export type CacheableClient = {
+  readonly request: <T>(path: string, options?: CachedRequestOptions) => Promise<T>,
+  ...
+};
+
+/** What one cached request states about its entry. */
+export type FetchCacheOptions = {|
+  readonly lifetime: CacheLifetime,
+  readonly tags?: $ReadOnlyArray<string>,
+  /** Overrides the key built from the client's name, the method and the URL. */
+  readonly key?: CacheKey,
+|};
+
+/** A client that caches the requests which ask to be cached. */
+export type CachedFetchClient = {|
+  readonly request: <T>(path: string, options?: CachedRequestOptions) => Promise<T>,
+|};
+
+/** Everything the fetch cache needs. */
+export type CachedFetchOptions = {|
+  readonly client: CacheableClient,
+  /**
+   * What distinguishes this client from another one in the same store.
+   *
+   * Required, and it is the one piece of ceremony here worth defending: two
+   * clients with different `baseURL`s both request `/users`, and a key built
+   * from the path alone would file one client's answer under the other's name.
+   * A client does not publish its `baseURL`, so the caller names it.
+   */
+  readonly name: string,
+  /** Defaults to the store the host installed for this request. */
+  readonly store?: CacheStore,
+|};
+
+/**
+ * A fetch client whose cacheable requests are cached.
+ *
+ * Opt-in per call, and that is the whole safety argument: a request with no
+ * `cache` option behaves exactly as the underlying client's does, so wrapping a
+ * client changes nothing until somebody states a lifetime for one request.
+ * There is no "cache every GET" mode, because every GET is not cacheable and a
+ * framework guessing which ones are is how a cache serves one person's account
+ * page to another.
+ *
+ * With no store — `rendering.cache.fetch` off, or outside a request — every
+ * call passes straight through. Slower, never wrong.
+ */
+export function createCachedFetch(options: CachedFetchOptions): CachedFetchClient {
+  const { client, name } = options;
+
+  function storeFor(): CacheStore | null {
+    if (options.store != null) {
+      return options.store;
+    }
+    const installed = requestCache();
+    return installed != null && installed.fetch === true ? installed.store : null;
+  }
+
+  return {
+    request<T>(path: string, requestOptions?: CachedRequestOptions): Promise<T> {
+      const caching = requestOptions?.cache;
+      const store = caching == null ? null : storeFor();
+      if (caching == null || store == null) {
+        return client.request(path, requestOptions);
+      }
+      const request: CacheRequest = {
+        key: caching.key ?? [
+          "fetch",
+          name,
+          (requestOptions?.method ?? "GET").toUpperCase(),
+          path,
+          searchOf(requestOptions?.searchParams),
+        ],
+        lifetime: caching.lifetime,
+        tags: caching.tags,
+      };
+      return store
+        .resolve(request, () => client.request(path, requestOptions))
+        .then((result) => result.value);
+    },
+  };
+}
+
+/**
+ * The search parameters as one string, in the order the caller wrote them.
+ *
+ * Not sorted, deliberately, and it is the one place this key is looser than it
+ * could be: `?a=1&b=2` and `?b=2&a=1` are two entries. Sorting would merge them
+ * — and would also merge two requests to a server that treats repeated or
+ * ordered parameters as meaning something, which is a wrong answer where two
+ * entries are only a wasted one. A caller that minds passes `key`.
+ */
+function searchOf(params?: { readonly [string]: string | number | boolean }): string {
+  if (params == null) {
+    return "";
+  }
+  const search = new URLSearchParams();
+  for (const key of Object.keys(params)) {
+    search.set(key, String(params[key]));
+  }
+  return search.toString();
+}

package/edge.js

@@ -0,0 +1,158 @@
+// @flow
+//
+// `@uniflowed/server/edge`: the Cloudflare Workers half of serving a build.
+//
+// [`./fetch.js`] answers the application's half of a request and touches no
+// filesystem, because that is the half a worker runs. This is everything that
+// is left on a worker, and there is much less of it than there is on Node: a
+// worker has no socket to take and no directory to read, so what remains is
+// the request lifecycle and the one decision `./node.js` makes with `stat` —
+// does a file the build already wrote answer this, or does the application.
+//
+// # Where the static half went
+//
+// To the platform. Workers static assets are uploaded beside the script and
+// served by Cloudflare's own asset server; the Worker reaches them through the
+// `ASSETS` binding declared in `wrangler.json`, which answers a `Request` with
+// a `Response` exactly as `createStaticHandler` does — and answers `404` where
+// that returns `null`, which is the only translation this module performs.
+//
+// The Worker asks *first*, and `uf build --adapter edge` writes
+// `"run_worker_first": true` so that it can. That looks like the wrong way
+// round — Cloudflare's default is to serve a matching asset without invoking
+// the script at all, which is faster and resolves a file/handler collision the
+// same way — but the default also puts the resolution order in a platform
+// setting rather than in uf, and `tests/library/deploy.test.js` cannot drive a
+// platform setting. Asking here means one order, written once, checked by the
+// test that checks `uf start`'s. See ubugeeei-prod/uf#391.
+//
+// # Who owns the request, and the one thing a worker cannot promise
+//
+// `after()` says "once the response has been sent", and there is no such line
+// in a worker: [`createWorkerFetch`] has a `Response` in hand, and the platform
+// writes its body after the handler has returned. `ctx.waitUntil` is the
+// documented way to keep the isolate alive for work that outlives the handler,
+// so that is what `settle` is handed — which means an `after()` callback on
+// this target begins when the response has been *decided* rather than when its
+// last byte is out. For a streamed document those are a document apart. It is
+// written down here, in `docs/app/reference/cli/_uf.page.mdx`, and it is the
+// one behavioural difference between this target and the other three.
+//
+// `beginRequest` is passed in rather than imported, for the reason `./node.js`
+// gives at length: the request lives in an `AsyncLocalStorage` belonging to a
+// module instance, and the instance the application reads is the one bundled
+// into the `handler.js` beside the generated `worker.js`. See
+// ubugeeei-prod/uf#389.
+
+import type { RequestLifecycle } from "./internal/context.js";
+
+export type { RequestLifecycle } from "./internal/context.js";
+
+/**
+ * The `ASSETS` binding, as much of it as this module uses.
+ *
+ * One method, declared structurally: a worker's bindings are supplied by the
+ * runtime, and naming the whole of Cloudflare's `Fetcher` here would be this
+ * package holding a copy of another project's types.
+ */
+export type AssetsBinding = {
+  readonly fetch: (request: Request) => Promise<Response>,
+  ...
+};
+
+/**
+ * The `env` a Worker's `fetch` is called with.
+ *
+ * Inexact, because a project's own bindings — a KV namespace, a secret — are
+ * in here too and are none of this module's business. `ASSETS` is optional
+ * because a Worker deployed without an assets directory has no such binding,
+ * and the honest answer for that deployment is "the application answers
+ * everything" rather than a `TypeError` on the first request.
+ */
+export type EdgeEnvironment = {
+  readonly ASSETS?: AssetsBinding,
+  ...
+};
+
+/**
+ * The `ctx` a Worker's `fetch` is called with.
+ *
+ * `waitUntil` only. `passThroughOnException` exists and is deliberately not
+ * used: it serves the origin's response when the script throws, and a Worker
+ * that *is* the origin has nothing to pass through to.
+ */
+export type ExecutionContext = {
+  readonly waitUntil: (promise: Promise<mixed>) => mixed,
+  ...
+};
+
+/** Everything the worker half needs to answer a request. */
+export type WorkerHandlerOptions = {|
+  /** The application, from the generated `handler.js`. */
+  readonly handle: (request: Request) => Promise<Response>,
+  /** That same module's `beginRequest`; see the header. */
+  readonly beginRequest: (request: Request) => RequestLifecycle,
+|};
+
+/**
+ * A built uf application as a Worker's `fetch`.
+ *
+ * Static assets first, then the application — the order `uf preview` cannot
+ * deviate from and therefore the order every other front door matches. The
+ * asset lookup is skipped for anything that is not a `GET` or a `HEAD`, which
+ * is what `createStaticHandler` does and for the same reason: a `POST` to a
+ * path that happens to have a file under it belongs to a route handler.
+ *
+ * A `404` from the assets binding means "no such asset", not "the site has no
+ * such page": `wrangler.json` sets `"not_found_handling": "none"` so that the
+ * miss falls through to here, and the 404 a visitor sees is the project's own
+ * `_uf.not-found` rendered by the application. Any other status is the asset's
+ * answer and is returned as it stands.
+ */
+export function createWorkerFetch(
+  options: WorkerHandlerOptions,
+): (request: Request, env: EdgeEnvironment, ctx?: ExecutionContext) => Promise<Response> {
+  const { handle, beginRequest } = options;
+
+  return async function fetchFromWorker(
+    request: Request,
+    env: EdgeEnvironment,
+    ctx?: ExecutionContext,
+  ): Promise<Response> {
+    const lifecycle = beginRequest(request);
+    try {
+      return await lifecycle.run(async () => {
+        const assets = env?.ASSETS;
+        const method = request.method.toUpperCase();
+        if (assets != null && (method === "GET" || method === "HEAD")) {
+          const asset = await assets.fetch(request);
+          if (asset.status !== 404) return asset;
+        }
+        return await handle(request);
+      });
+    } catch (error) {
+      // The same 500 `./node.js`'s `nodeListener` writes, and for the same
+      // reasons: the body must not carry the stack, because the body goes to
+      // whoever asked, and the console is where the operator is already
+      // looking. Without this the answer would be Cloudflare's own error page,
+      // which is a different answer from `uf start`'s for the same failure —
+      // and the whole claim of the seam is that there is one answer.
+      console.error(error);
+      return new Response("500 Internal Server Error\n", {
+        status: 500,
+        headers: { "content-type": "text/plain; charset=utf-8" },
+      });
+    } finally {
+      // Scheduled rather than awaited: awaiting it here would hold the
+      // response back until every `after()` callback had finished, which is
+      // the opposite of what `after()` is for. Where there is no `ctx` — a
+      // test, or a host that calls this directly — it is awaited, because
+      // dropping the promise would lose both the work and its rejection.
+      if (ctx != null) {
+        ctx.waitUntil(lifecycle.settle());
+      } else {
+        await lifecycle.settle();
+      }
+    }
+  };
+}