@thomasfosterau/pulpit 0.0.0-stage → 0.1.0

package/src/budgets.ts

@@ -0,0 +1,338 @@
+/**
+ * **Write budgets** (pulpit#199): a declared ceiling on how many writes of
+ * one kind an account may make in a rolling window, so a family that takes
+ * user content (comments, proposals, reports, posts) throttles it without
+ * every application re-adding the check.
+ *
+ * - **Declared once per family and action.** A {@link WriteBudget} names a
+ *   limit and a window; {@link bindBudget} binds it to a family's type, a
+ *   {@link BudgetCounter} and the access policy, and checks the declaration
+ *   (a malformed one throws {@link BudgetDeclarationError} when it is bound).
+ * - **Spent inside the write.** A chain write spends through
+ *   {@link budgetHook}, a before hook, so a write over budget appends
+ *   nothing; `./proposals`' `submit` and `./moderation`'s report `file` take
+ *   the bound budget as an opt-in and spend it before their insert. Either
+ *   way the refusal is `WriteRejected` with the reason {@link RATE_LIMITED},
+ *   which {@link isRateLimited} tells apart from every other refusal (the
+ *   wire's 429).
+ * - **Exempt above a rung.** An account the budget's `exempt` rung admits
+ *   (the moderate rung, by default) spends nothing.
+ * - **One counter seam.** The owner's decision on #199: count within the
+ *   write's transaction, with the seam shaped so an atomic counter can be
+ *   plugged in later. {@link countingCounter} is the counting
+ *   implementation, one indexed `count(*)` over the family's own rows; a
+ *   counter that holds its own state (a Durable Object, a locked row)
+ *   implements {@link BudgetCounter.take} directly.
+ *
+ * @copyright Thomas Foster
+ * @module pulpit/budgets
+ * @since 0.1.0
+ */
+
+import * as Clock from "effect/Clock";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import {
+  WriteRejected,
+  type AccessPolicy,
+  type BeforeWriteHook,
+  type Viewer,
+  type ViewerAccount,
+} from "./subtype.ts";
+
+/**
+ * The `WriteRejected` reason a write over its budget carries, so the wire
+ * can answer 429 rather than 422.
+ *
+ * @since 0.1.0
+ */
+export const RATE_LIMITED = "rate-limited";
+
+/**
+ * Whether a refusal is a write budget's ({@link RATE_LIMITED}), not another
+ * hook's.
+ *
+ * @example
+ * ```ts
+ * import { strictEqual } from "node:assert";
+ * import { isRateLimited, RATE_LIMITED } from "@thomasfosterau/pulpit/budgets";
+ * import { WriteRejected } from "@thomasfosterau/pulpit/subtype";
+ *
+ * const refusal = new WriteRejected({ type: "comments", id: "c-1", action: "create", reason: RATE_LIMITED });
+ * strictEqual(isRateLimited(refusal), true);
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const isRateLimited = (error: WriteRejected): boolean => error.reason === RATE_LIMITED;
+
+/**
+ * A write budget: at most `limit` writes per account in any window of
+ * `windowSeconds`, for every account the `exempt` rung doesn't admit.
+ *
+ * @since 0.1.0
+ */
+export interface WriteBudget {
+  /** The most writes one account may make in a window: a positive safe integer. */
+  readonly limit: number;
+  /** The window's length, in seconds: a positive safe integer. */
+  readonly windowSeconds: number;
+  /**
+   * The rung that spends nothing, read from the access policy (as
+   * `./edges`' `rungGate` reads one). Absent, the moderate rung.
+   */
+  // oxlint-disable-next-line effect/prefer-option-over-null -- the optional-field convention (AGENTS.md → Conventions); absent is the moderate rung
+  readonly exempt?: ((policy: AccessPolicy) => (account: ViewerAccount) => boolean) | undefined;
+}
+
+/**
+ * A budget declaration that can never admit a write as intended (a limit or
+ * window that is not a positive safe integer), thrown by {@link bindBudget}
+ * when the budget is bound, never as an Effect failure.
+ *
+ * @since 0.1.0
+ */
+export class BudgetDeclarationError extends Schema.TaggedError<
+  BudgetDeclarationError,
+  { readonly brand: unique symbol }
+>()("BudgetDeclarationError", { type: Schema.String, reason: Schema.String }) {}
+
+/**
+ * What a {@link BudgetCounter} is asked: whether the account may make one
+ * more write of `action` on the family `type`, given the window that
+ * started at `since` and the budget's `limit`.
+ *
+ * @since 0.1.0
+ */
+export interface BudgetRequest {
+  readonly type: string;
+  readonly action: string;
+  readonly accountId: string;
+  readonly since: Date;
+  readonly now: Date;
+  readonly limit: number;
+}
+
+/**
+ * The counter seam: spend one write against the budget, answering whether
+ * it was within it. Runs in the caller's transaction. A counting
+ * implementation ({@link countingCounter}) reads the writes already made,
+ * which the write itself then adds to; an atomic one (a Durable Object, a
+ * row taken `FOR UPDATE`) records the spend itself, and must spend nothing
+ * when it answers `false`. See the package README → Seams.
+ *
+ * @since 0.1.0
+ */
+export interface BudgetCounter<E, R> {
+  readonly take: (request: BudgetRequest) => Effect.Effect<boolean, E, R>;
+}
+
+/**
+ * The read {@link countingCounter} counts with: how many writes of `action`
+ * on `type` the account made at or after `since`, as one indexed
+ * `count(*)` over the family's own rows (`author_id`, `created_at`).
+ *
+ * @since 0.1.0
+ */
+export interface WriteCountStore<E, R> {
+  readonly countSince: (query: {
+    readonly type: string;
+    readonly action: string;
+    readonly accountId: string;
+    readonly since: Date;
+  }) => Effect.Effect<number, E, R>;
+}
+
+/**
+ * The count-within-the-transaction counter (gardeneria's
+ * `assertNotRateLimitedE`): a write is within budget while fewer than
+ * `limit` writes were made in the window. It spends nothing itself: the
+ * write's own row is the spend, and a write that rolls back took none.
+ * **It is exact but not atomic:** two concurrent transactions can both
+ * count `limit - 1` and both write. A family that must hold its limit under
+ * concurrency fills {@link BudgetCounter} with an atomic counter instead.
+ *
+ * @example
+ * ```ts
+ * import { strictEqual } from "node:assert";
+ * import * as Effect from "effect/Effect";
+ * import { countingCounter } from "@thomasfosterau/pulpit/budgets";
+ *
+ * const counter = countingCounter({ countSince: () => Effect.succeed(2) });
+ * const request = {
+ *   type: "comments",
+ *   action: "create",
+ *   accountId: "u-1",
+ *   since: new Date(0),
+ *   now: new Date(60_000),
+ *   limit: 3,
+ * };
+ * strictEqual(Effect.runSync(counter.take(request)), true);
+ * strictEqual(Effect.runSync(counter.take({ ...request, limit: 2 })), false);
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const countingCounter = <E, R>(store: WriteCountStore<E, R>): BudgetCounter<E, R> => ({
+  take: (request) =>
+    Effect.map(
+      store.countSince({
+        type: request.type,
+        action: request.action,
+        accountId: request.accountId,
+        since: request.since,
+      }),
+      (count) => count < request.limit,
+    ),
+});
+
+/**
+ * A budget bound to its family: {@link BoundBudget.spend} spends one write.
+ *
+ * @since 0.1.0
+ */
+export interface BoundBudget<E, R> {
+  readonly type: string;
+  readonly budget: WriteBudget;
+  /**
+   * Spend one write of `action` by `viewer` on the node `id`. An anonymous
+   * viewer spends nothing (the write's own gate refuses it), nor does one
+   * the exempt rung admits. Over budget it fails `WriteRejected` with
+   * {@link RATE_LIMITED}.
+   */
+  readonly spend: (
+    viewer: Viewer,
+    action: string,
+    id: string,
+  ) => Effect.Effect<void, WriteRejected | E, R>;
+}
+
+const positiveSafeInteger = (value: number) => Number.isSafeInteger(value) && value > 0;
+
+/**
+ * Bind a {@link WriteBudget} to a family's type, its counter and the access
+ * policy. Throws {@link BudgetDeclarationError} for a limit or window that
+ * is not a positive safe integer.
+ *
+ * @example
+ * ```ts
+ * import { strictEqual } from "node:assert";
+ * import * as Effect from "effect/Effect";
+ * import * as Exit from "effect/Exit";
+ * import * as Option from "effect/Option";
+ * import { bindBudget } from "@thomasfosterau/pulpit/budgets";
+ * import { makeInMemoryBudgetCounter } from "@thomasfosterau/pulpit/testing";
+ *
+ * const policy = {
+ *   canViewPrivate: () => false,
+ *   canViewDeleted: () => false,
+ *   canModerate: () => false,
+ *   canWriteCorpus: () => false,
+ * };
+ * const comments = bindBudget({
+ *   type: "comments",
+ *   budget: { limit: 1, windowSeconds: 60 },
+ *   counter: makeInMemoryBudgetCounter(),
+ *   policy,
+ * });
+ * const member = Option.some({ id: "u-1", role: "member" });
+ * const twice = Effect.gen(function* () {
+ *   yield* comments.spend(member, "create", "c-1");
+ *   return yield* Effect.exit(comments.spend(member, "create", "c-2"));
+ * });
+ * strictEqual(Exit.isFailure(Effect.runSync(twice)), true);
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const bindBudget = <E, R>(definition: {
+  readonly type: string;
+  readonly budget: WriteBudget;
+  readonly counter: BudgetCounter<E, R>;
+  readonly policy: AccessPolicy;
+}): BoundBudget<E, R> => {
+  const { type, budget, counter, policy } = definition;
+  if (!positiveSafeInteger(budget.limit)) {
+    throw new BudgetDeclarationError({ type, reason: "limit must be a positive safe integer" });
+  }
+  if (!positiveSafeInteger(budget.windowSeconds)) {
+    throw new BudgetDeclarationError({
+      type,
+      reason: "windowSeconds must be a positive safe integer",
+    });
+  }
+  const exempt = (budget.exempt ?? ((rungs: AccessPolicy) => rungs.canModerate))(policy);
+  const windowMillis = budget.windowSeconds * 1000;
+
+  const spend = (viewer: Viewer, action: string, id: string) =>
+    Option.match(
+      Option.filter(viewer, (account) => !exempt(account)),
+      {
+        onNone: () => Effect.void,
+        onSome: (account) =>
+          Effect.flatMap(Clock.currentTimeMillis, (millis) =>
+            Effect.flatMap(
+              counter.take({
+                type,
+                action,
+                accountId: account.id,
+                since: DateTime.toDate(DateTime.makeUnsafe(millis - windowMillis)),
+                now: DateTime.toDate(DateTime.makeUnsafe(millis)),
+                limit: budget.limit,
+              }),
+              (within) =>
+                within
+                  ? Effect.void
+                  : Effect.fail(new WriteRejected({ type, id, action, reason: RATE_LIMITED })),
+            ),
+          ),
+      },
+    );
+
+  return { type, budget, spend };
+};
+
+/**
+ * A bound budget as a before hook for a chain write (`./subtype`'s
+ * `hooks.before`), spending one write on each of the `actions` it lists
+ * (`create`, by default) and passing the patch through. A localised write
+ * spends once: the hook's `locales` pass spends nothing.
+ *
+ * @example
+ * ```ts
+ * import { strictEqual } from "node:assert";
+ * import { bindBudget, budgetHook } from "@thomasfosterau/pulpit/budgets";
+ * import { makeInMemoryBudgetCounter } from "@thomasfosterau/pulpit/testing";
+ *
+ * const policy = {
+ *   canViewPrivate: () => false,
+ *   canViewDeleted: () => false,
+ *   canModerate: () => false,
+ *   canWriteCorpus: () => false,
+ * };
+ * const hook = budgetHook(
+ *   bindBudget({
+ *     type: "comments",
+ *     budget: { limit: 10, windowSeconds: 3600 },
+ *     counter: makeInMemoryBudgetCounter(),
+ *     policy,
+ *   }),
+ * );
+ * strictEqual(hook.name, "comments.budget");
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const budgetHook = <E, R>(
+  bound: BoundBudget<E, R>,
+  actions: ReadonlyArray<string> = ["create"],
+): BeforeWriteHook<E, R> => ({
+  name: `${bound.type}.budget`,
+  run: (event) =>
+    actions.includes(event.action)
+      ? Effect.as(bound.spend(event.viewer, event.action, event.id), event.patch)
+      : Effect.succeed(event.patch),
+  locales: (event) => Effect.succeed(event.locales ?? {}),
+});

package/src/cache.ts

@@ -0,0 +1,218 @@
+/**
+ * **The reference resource cache** (pulpit#205) — `./subtype`'s
+ * {@link ResourceCacheSeam}, with a read-through `get`, over a minimal
+ * versioned key-value seam ({@link VersionedKv}).
+ *
+ * The behavioural spec is the four apps' own caches (website's, gardeneria's,
+ * preferenceflow's and in-the-dark's `apps/api/src/cache.ts`), which this
+ * replaces: one implementation of the contract the kernel already states.
+ *
+ * - **Compare-on-set** (pulpit#121). Every entry carries the version it
+ *   speaks for, and the KV seam's one conditional write keeps the highest:
+ *   a `set` or `delete` below the stored version changes nothing, and an
+ *   eviction raises the version, so a racing writer's late write-through can
+ *   never re-cache a resource older than one already replaced or evicted.
+ * - **An eviction wins a tie.** A tombstone outranks a value at the same
+ *   version: only a strictly newer write clears it, so a read-through that
+ *   loaded the row before an unpublish at that version can't re-cache it.
+ *   The cache stores a rank, `2·version` for a value and `2·version + 1` for
+ *   a tombstone, as the entry's `version`, so the seam still compares one
+ *   number.
+ * - **Tombstones outlive values.** A tombstone is kept for
+ *   `tombstoneTtlSeconds` (by default a day, and never less than the value
+ *   TTL), which must exceed the longest a write can be in flight: a late
+ *   write-through that arrives after its tombstone has expired is no longer
+ *   ordered against it.
+ * - **Serveability on both sides** (`CACHE-AUTH-005`). `set` refuses (and
+ *   evicts) a resource the `serveable` policy refuses, and `get` checks it
+ *   again, so a policy change can't serve a stale cached private row.
+ * - **Decode or evict.** `get` decodes the stored value with the resource's
+ *   schema; a value that no longer decodes (the schema moved) is evicted and
+ *   read as a miss.
+ * - **A TTL backstop.** Every write carries the configured TTL, so an entry
+ *   no write ever evicted still expires.
+ * - **Never fails.** A KV failure reads as a miss and skips a write: the
+ *   cache is an optimisation, and the store stays the source of truth.
+ *
+ * The KV seam is the application's (a Durable Object, Redis, a SQL table):
+ * nothing here imports a platform. Workers KV alone has no conditional
+ * write, so it can't fill {@link VersionedKv.putIfNotBehind}.
+ *
+ * @copyright Thomas Foster
+ * @module pulpit/cache
+ * @since 0.1.0
+ */
+
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import type { ResourceCacheSeam } from "./subtype.ts";
+
+// ── The KV seam ───────────────────────────────────────────────────────
+
+/**
+ * One stored entry: the rank it is ordered by, and the encoded resource, or
+ * none for an eviction (a tombstone that keeps the rank). `makeResourceCache`
+ * stores `2·version` for a value and `2·version + 1` for a tombstone, so a
+ * tombstone outranks a value at the same node version.
+ *
+ * @since 0.1.0
+ */
+export interface KvEntry {
+  readonly version: bigint;
+  readonly value: Option.Option<Schema.Json>;
+}
+
+/**
+ * The minimal versioned key-value store an application supplies. A store
+ * seam: no policy, fails only with its `E`. See the package README → Seams.
+ *
+ * @since 0.1.0
+ */
+export interface VersionedKv<E, R> {
+  /** The entry at `key`, or none (never written, or expired). */
+  readonly get: (key: string) => Effect.Effect<Option.Option<KvEntry>, E, R>;
+  /**
+   * Write `entry` at `key` with a TTL of `ttlSeconds`, **in one atomic
+   * step**, unless the stored entry's version is above `entry.version`;
+   * whether it wrote. A store with no conditional write cannot fill this
+   * seam.
+   */
+  readonly putIfNotBehind: (
+    key: string,
+    entry: KvEntry,
+    ttlSeconds: number,
+  ) => Effect.Effect<boolean, E, R>;
+}
+
+// ── The cache ─────────────────────────────────────────────────────────
+
+/**
+ * {@link makeResourceCache}'s configuration.
+ *
+ * @since 0.1.0
+ */
+export interface ResourceCacheOptions<Resource, E, R> {
+  readonly kv: VersionedKv<E, R>;
+  /** The resource's schema: its JSON encoding in the store, decoded on every read. */
+  readonly schema: Schema.Codec<Resource, Schema.Json>;
+  /** The `CACHE-AUTH-005` serveability policy (typically `./publication`'s `serveablePolicy`). */
+  readonly serveable: (resource: Resource) => boolean;
+  /** The key prefix, typically the leaf's type and a schema generation (`posts:v3:`). */
+  readonly prefix: string;
+  /** The TTL backstop every value write carries, in seconds (clamped to at least 1). */
+  readonly ttlSeconds: number;
+  /**
+   * How long an eviction's tombstone is kept, in seconds: it must exceed the
+   * longest a write-through or read-through fill can be in flight, since a
+   * stale write that lands after its tombstone expired is no longer refused.
+   * Defaults to a day ({@link DEFAULT_TOMBSTONE_TTL_SECONDS}), and is never
+   * less than `ttlSeconds`.
+   */
+  // oxlint-disable-next-line effect/prefer-option-over-null -- an optional field is `?: T | undefined` (AGENTS.md → Conventions); the omitted key is the default
+  readonly tombstoneTtlSeconds?: number | undefined;
+}
+
+/**
+ * The default time an eviction's tombstone is kept: one day, far longer than
+ * any request can be in flight.
+ *
+ * @since 0.1.0
+ */
+export const DEFAULT_TOMBSTONE_TTL_SECONDS = 86_400;
+
+/**
+ * A resource cache: the kernel's write-through seam plus the read-through
+ * `get`.
+ *
+ * @since 0.1.0
+ */
+export interface ResourceCache<Resource, R> extends ResourceCacheSeam<Resource, R> {
+  /**
+   * The cached resource for `id`: none on a miss, an eviction, a value that
+   * no longer decodes (evicted at its version) or one the policy no longer
+   * serves (evicted likewise). Never fails.
+   */
+  readonly get: (id: string) => Effect.Effect<Option.Option<Resource>, never, R>;
+}
+
+/**
+ * The reference {@link ResourceCacheSeam} over a {@link VersionedKv}.
+ *
+ * @example
+ * ```ts
+ * import { deepStrictEqual } from "node:assert";
+ * import * as Effect from "effect/Effect";
+ * import * as Option from "effect/Option";
+ * import * as Schema from "effect/Schema";
+ * import { makeResourceCache } from "@thomasfosterau/pulpit/cache";
+ * import { makeInMemoryVersionedKv } from "@thomasfosterau/pulpit/testing";
+ *
+ * const Post = Schema.Struct({ id: Schema.String, visibility: Schema.String });
+ * const cache = makeResourceCache({
+ *   kv: makeInMemoryVersionedKv(),
+ *   schema: Post,
+ *   serveable: (post) => post.visibility === "public",
+ *   prefix: "posts:v1:",
+ *   ttlSeconds: 3600,
+ * });
+ * const program = Effect.gen(function* () {
+ *   yield* cache.set("p-1", { id: "p-1", visibility: "public" }, 1n);
+ *   yield* cache.set("p-1", { id: "p-1", visibility: "private" }, 0n); // behind: no-op
+ *   return yield* cache.get("p-1");
+ * });
+ * deepStrictEqual(Effect.runSync(program), Option.some({ id: "p-1", visibility: "public" }));
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const makeResourceCache = <Resource, E, R>(
+  options: ResourceCacheOptions<Resource, E, R>,
+): ResourceCache<Resource, R> => {
+  const { kv, serveable, prefix } = options;
+  const ttl = Math.max(1, Math.trunc(options.ttlSeconds) || 1);
+  const tombstoneTtl = Math.max(
+    ttl,
+    Math.trunc(options.tombstoneTtlSeconds ?? DEFAULT_TOMBSTONE_TTL_SECONDS) || ttl,
+  );
+  const encode = Schema.encodeOption(options.schema);
+  const decode = Schema.decodeUnknownOption(options.schema);
+  const keyOf = (id: string) => `${prefix}${id}`;
+
+  /**
+   * The conditional write at the entry's rank (`2·version`, plus one for a
+   * tombstone, so an eviction wins a tie), a KV failure skipped (the cache
+   * never fails). A tombstone carries the longer TTL.
+   */
+  const write = (id: string, version: bigint, value: Option.Option<Schema.Json>) =>
+    Effect.ignore(
+      kv.putIfNotBehind(
+        keyOf(id),
+        { version: version * 2n + (Option.isNone(value) ? 1n : 0n), value },
+        Option.isNone(value) ? tombstoneTtl : ttl,
+      ),
+    );
+  const evict = (id: string, version: bigint) => write(id, version, Option.none());
+
+  const set = (id: string, resource: Resource, version: bigint) => {
+    // Refuse (and evict) what the policy doesn't serve, or what doesn't encode.
+    const encoded = serveable(resource) ? encode(resource) : Option.none();
+    return write(id, version, encoded);
+  };
+
+  const get = (id: string) =>
+    Effect.gen(function* () {
+      const stored = yield* Effect.orElseSucceed(kv.get(keyOf(id)), () => Option.none<KvEntry>());
+      if (Option.isNone(stored) || Option.isNone(stored.value.value))
+        return Option.none<Resource>();
+      const resource = decode(stored.value.value.value);
+      if (Option.isNone(resource) || !serveable(resource.value)) {
+        // Decode or evict, and never serve what the policy now refuses (CACHE-AUTH-005).
+        yield* evict(id, stored.value.version / 2n);
+        return Option.none<Resource>();
+      }
+      return resource;
+    });
+
+  return { set, delete: evict, get };
+};