@hot-updater/server 1.0.0-rc.18 → 1.0.0-rc.21

package/src/database/busy.spec.ts

@@ -1,45 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { isDatabaseBusyError } from "./busy";
-import { DatabaseConflictError, DatabaseTransactionError } from "./errors";
-
-const failure = (message: string, fields: object) =>
-  Object.assign(new Error(message), fields);
-
-describe("isDatabaseBusyError", () => {
-  it.each([
-    [
-      "a transaction out of retries",
-      new DatabaseConflictError("The transaction conflicted 8 times."),
-    ],
-    [
-      "a throttled DynamoDB read",
-      failure("Throughput exceeds the current capacity of your table.", {
-        name: "ProvisionedThroughputExceededException",
-      }),
-    ],
-    ["an HTTP 429", failure("Too Many Requests", { status: 429 })],
-    [
-      "an AWS SDK 429",
-      failure("Too Many Requests", { $metadata: { httpStatusCode: 429 } }),
-    ],
-    [
-      "Firestore's RESOURCE_EXHAUSTED",
-      failure("8 RESOURCE_EXHAUSTED: Quota exceeded.", { code: 8 }),
-    ],
-  ])("holds for %s", (_case, error) => {
-    expect(isDatabaseBusyError(error)).toBe(true);
-  });
-
-  it.each([
-    ["a gauge below zero", new DatabaseTransactionError("gauge below zero")],
-    ["MongoDB's unknown error, also code 8", failure("unknown", { code: 8 })],
-    [
-      "a refused connection",
-      failure("connect ECONNREFUSED", { code: "ECONNREFUSED" }),
-    ],
-    ["a thrown string", "busy"],
-  ])("does not hold for %s", (_case, error) => {
-    expect(isDatabaseBusyError(error)).toBe(false);
-  });
-});

package/src/database/busy.ts

@@ -1,50 +0,0 @@
-import { DatabaseConflictError } from "./errors";
-
-/** Error names the AWS SDKs give a throttled request, as their retry strategy classifies them. */
-const THROTTLING_NAMES = new Set([
-  "ProvisionedThroughputExceededException",
-  "RequestLimitExceeded",
-  "RequestThrottled",
-  "RequestThrottledException",
-  "SlowDown",
-  "ThrottledException",
-  "Throttling",
-  "ThrottlingException",
-  "TooManyRequestsException",
-]);
-
-/** gRPC's RESOURCE_EXHAUSTED, the status Firestore throttles a request with. */
-const RESOURCE_EXHAUSTED = 8;
-
-interface ErrorFields {
-  readonly name?: unknown;
-  readonly code?: unknown;
-  readonly message?: unknown;
-  readonly status?: unknown;
-  readonly statusCode?: unknown;
-  readonly $metadata?: { readonly httpStatusCode?: unknown };
-}
-
-/**
- * Whether the database is busy rather than broken, so the same request can
- * succeed later: a transaction ran out of retries, or the backend throttled
- * a request. Writes already retry transient failures, throttled ones
- * included, until the budget runs out. A throttled read throws the backend's
- * own error, so it is recognized by what the backends call it: a name the
- * AWS SDKs retry as throttling, HTTP 429, or gRPC's RESOURCE_EXHAUSTED.
- */
-export const isDatabaseBusyError = (error: unknown): boolean => {
-  if (error instanceof DatabaseConflictError) return true;
-  if (typeof error !== "object" || error === null) return false;
-  const { name, code, message, status, statusCode, $metadata } =
-    error as ErrorFields;
-  return (
-    (typeof name === "string" && THROTTLING_NAMES.has(name)) ||
-    [status, statusCode, $metadata?.httpStatusCode].includes(429) ||
-    // A gRPC error's message starts with its status name; other drivers use
-    // numeric codes too, such as MongoDB's 8 for an unknown error.
-    (code === RESOURCE_EXHAUSTED &&
-      typeof message === "string" &&
-      message.includes("RESOURCE_EXHAUSTED"))
-  );
-};

package/src/database/cursor.ts

@@ -1,65 +0,0 @@
-import {
-  type DatabaseKey,
-  isKeyValue,
-} from "@hot-updater/plugin-core/internal";
-
-export class DatabaseCursorError extends Error {
-  readonly name = "DatabaseCursorError";
-}
-
-const encoder = new TextEncoder();
-const decoder = new TextDecoder();
-
-const toBase64Url = (text: string): string => {
-  let binary = "";
-  for (const byte of encoder.encode(text)) binary += String.fromCharCode(byte);
-  return btoa(binary)
-    .replaceAll("+", "-")
-    .replaceAll("/", "_")
-    .replace(/=+$/u, "");
-};
-
-const fromBase64Url = (value: string): string => {
-  const binary = atob(value.replaceAll("-", "+").replaceAll("_", "/"));
-  return decoder.decode(Uint8Array.from(binary, (char) => char.charCodeAt(0)));
-};
-
-/** A stable 32-bit FNV-1a hash of the text's UTF-8 bytes. */
-export const fnv1a = (text: string): number => {
-  let hash = 0x811c9dc5;
-  for (const byte of encoder.encode(text)) {
-    hash = Math.imul(hash ^ byte, 0x01000193) >>> 0;
-  }
-  return hash;
-};
-
-/** A hash of the request's identity; a cursor only resumes the same read. */
-export const cursorScope = (parts: readonly unknown[]): string =>
-  fnv1a(JSON.stringify(parts)).toString(36);
-
-export const encodeCursor = (scope: string, after: DatabaseKey): string =>
-  toBase64Url(JSON.stringify([scope, after]));
-
-/** The order tuple a cursor resumes after; rejects a cursor from another read. */
-export const decodeCursor = (scope: string, cursor: string): DatabaseKey => {
-  let decoded: unknown;
-  try {
-    decoded = JSON.parse(fromBase64Url(cursor));
-  } catch {
-    decoded = undefined;
-  }
-  const [from, after] = Array.isArray(decoded) ? decoded : [];
-  if (
-    typeof from !== "string" ||
-    !Array.isArray(after) ||
-    !after.every(isKeyValue)
-  ) {
-    throw new DatabaseCursorError("The cursor is malformed.");
-  }
-  if (from !== scope) {
-    throw new DatabaseCursorError(
-      "The cursor belongs to a read with another model, index, filter, order, or range.",
-    );
-  }
-  return after;
-};

package/src/database/database.ts

@@ -1,366 +0,0 @@
-import type { AggregateBatching } from "@hot-updater/plugin-core";
-import {
-  DATABASE_VERSION_COLUMN,
-  type DatabaseKeyValue,
-  type StoredRow,
-} from "@hot-updater/plugin-core/internal";
-
-import { createAggregateBatches } from "./aggregateBatching";
-import { createEngine, type DatabaseEngineOptions } from "./engine";
-import type { Page, ReadInput } from "./engineReads";
-import {
-  assertOutsideTransaction,
-  type TransactionEngine,
-} from "./engineTransaction";
-import type { SchemaModule } from "./resolveSchema";
-import type {
-  AggregateDefinition,
-  FieldType,
-  FieldValue,
-  ModuleSchema,
-  RowOf,
-  TableDefinition,
-} from "./schema";
-
-type TableNames<S extends ModuleSchema> = {
-  [K in keyof S]: S[K] extends TableDefinition ? K : never;
-}[keyof S] &
-  string;
-
-type AggregateNames<S extends ModuleSchema> = {
-  [K in keyof S]: S[K] extends AggregateDefinition ? K : never;
-}[keyof S] &
-  string;
-
-/** Reference counters: how many rows of another table point at this one. */
-type RefColumns = { readonly [K: `_refs_${string}`]: number };
-
-/** Engine columns every stored row carries. */
-export type EngineColumns = { readonly _v: number } & RefColumns;
-
-type DerivedValues<TDerived> = {
-  -readonly [K in keyof TDerived]: TDerived[K] extends FieldType
-    ? FieldValue<TDerived[K]> | readonly FieldValue<TDerived[K]>[] | null
-    : never;
-};
-
-type Values<TModel> =
-  TModel extends TableDefinition<infer TFields, infer TDerived>
-    ? RowOf<TFields> & DerivedValues<TDerived>
-    : TModel extends AggregateDefinition<
-          infer TFields,
-          infer TMetric,
-          infer _TIndexes,
-          infer TSketch
-        >
-      ? RowOf<TFields> & { -readonly [K in TMetric]: number } & {
-          -readonly [K in TSketch]: string;
-        }
-      : never;
-
-/** A row read in a transaction, `_v` included, so the transaction can write it back. */
-export type TableRow<TModel> = Values<TModel> & EngineColumns;
-/** A row read outside a transaction, without `_v`, which only a transaction's guard uses. */
-export type ReadRow<TModel> = Values<TModel> & RefColumns;
-export type AggregateRow<TModel> = Values<TModel>;
-
-type IndexesOf<TModel> = TModel extends { readonly indexes: infer I }
-  ? I
-  : never;
-type IndexName<TModel> = keyof IndexesOf<TModel> & string;
-type IndexFields<
-  TModel,
-  TIndex,
-  TPart extends "eq" | "sort",
-> = IndexesOf<TModel>[TIndex & keyof IndexesOf<TModel>] extends {
-  readonly [P in TPart]: readonly (infer F)[];
-}
-  ? F & keyof Values<TModel>
-  : never;
-
-type KeyValueOf<TModel, TField extends keyof Values<TModel>> = Exclude<
-  Values<TModel>[TField],
-  null | readonly unknown[]
->;
-
-type FirstOrderField<TModel, TIndex> = IndexesOf<TModel>[TIndex &
-  keyof IndexesOf<TModel>] extends {
-  readonly sort: readonly [infer F, ...unknown[]];
-}
-  ? F & keyof Values<TModel>
-  : TModel extends { readonly key: readonly (infer K)[] }
-    ? K & keyof Values<TModel>
-    : never;
-
-export interface ReadOptions<TModel, TIndex> {
-  readonly index: TIndex;
-  /** Every eq field of the index; null never matches. */
-  readonly where: {
-    readonly [F in IndexFields<TModel, TIndex, "eq">]: KeyValueOf<TModel, F>;
-  };
-  /** Bounds on the first order field, or on a prefix of the order tuple (sort fields, then the key). */
-  readonly range?: {
-    readonly [B in "gt" | "gte" | "lt" | "lte"]?:
-      | KeyValueOf<TModel, FirstOrderField<TModel, TIndex>>
-      | readonly [
-          KeyValueOf<TModel, FirstOrderField<TModel, TIndex>>,
-          ...DatabaseKeyValue[],
-        ];
-  };
-  readonly order?: "asc" | "desc";
-  readonly limit: number;
-  readonly cursor?: string;
-}
-
-type UniqueLookups<TModel> =
-  TModel extends TableDefinition<infer TFields, infer _D, infer TIndexes>
-    ?
-        | {
-            [F in keyof TFields]: TFields[F] extends { readonly unique: true }
-              ? {
-                  readonly [P in F]: KeyValueOf<
-                    TModel,
-                    P & keyof Values<TModel>
-                  >;
-                }
-              : never;
-          }[keyof TFields]
-        | {
-            [I in keyof TIndexes]: TIndexes[I] extends {
-              readonly unique: true;
-              readonly eq: readonly (infer E)[];
-            }
-              ? {
-                  readonly [P in E & string]: KeyValueOf<
-                    TModel,
-                    P & keyof Values<TModel>
-                  >;
-                }
-              : never;
-          }[keyof TIndexes]
-    : never;
-
-/** A table's key values. */
-export type KeyLookup<TModel> =
-  TModel extends TableDefinition<infer _F>
-    ? {
-        readonly [K in TModel["key"][number]]: KeyValueOf<
-          TModel,
-          K & keyof Values<TModel>
-        >;
-      }
-    : never;
-
-/** The key, or the eq fields of a unique index. */
-export type Lookup<TModel> = KeyLookup<TModel> | UniqueLookups<TModel>;
-
-type RootedIndexName<TModel> = {
-  [I in keyof IndexesOf<TModel>]: IndexesOf<TModel>[I] extends {
-    readonly root: object;
-  }
-    ? I
-    : never;
-}[keyof IndexesOf<TModel>] &
-  string;
-
-type OptionalFields<TFields> = {
-  [K in keyof TFields]: TFields[K] extends { readonly required: false }
-    ? K
-    : never;
-}[keyof TFields];
-
-/** Declared fields, optional ones omittable; derived fields and engine columns are computed. */
-export type CreateRow<TModel> =
-  TModel extends TableDefinition<infer TFields>
-    ? Omit<RowOf<TFields>, OptionalFields<TFields>> &
-        Partial<Pick<RowOf<TFields>, OptionalFields<TFields>>>
-    : never;
-
-/** Changed non-key fields. */
-export type UpdateSet<TModel> =
-  TModel extends TableDefinition<infer TFields, infer _D, infer _I, infer TKey>
-    ? Partial<Omit<RowOf<TFields>, TKey[number]>>
-    : never;
-
-export type AggregateIdentity<TModel> =
-  TModel extends AggregateDefinition<infer TFields> ? RowOf<TFields> : never;
-
-/** Counter and gauge deltas, and sketches to merge. */
-export type AggregateChanges<TModel> =
-  TModel extends AggregateDefinition<
-    infer _F,
-    infer TMetric,
-    infer _I,
-    infer TSketch
-  >
-    ? { readonly [K in TMetric]?: number } & {
-        readonly [K in TSketch]?: string;
-      }
-    : never;
-
-/** Reads are recorded and guarded at commit; writes apply only if every guard holds. */
-export interface HotUpdaterTransaction<S extends ModuleSchema> {
-  findOne<M extends TableNames<S>>(
-    model: M,
-    lookup: Lookup<S[M]>,
-  ): Promise<TableRow<S[M]> | null>;
-  /** Rooted indexes only: the parent row guards the whole range. */
-  findMany<M extends TableNames<S>, I extends RootedIndexName<S[M]>>(
-    model: M,
-    options: ReadOptions<S[M], I>,
-  ): Promise<Page<TableRow<S[M]>>>;
-  create<M extends TableNames<S>>(model: M, row: CreateRow<S[M]>): void;
-  /** Patches a row this transaction read, by key or through a rooted range. */
-  update<M extends TableNames<S>>(
-    model: M,
-    row: TableRow<S[M]>,
-    set: UpdateSet<S[M]>,
-  ): void;
-  /** Deletes a row this transaction read, cascading to its children first. */
-  delete<M extends TableNames<S>>(model: M, row: TableRow<S[M]>): Promise<void>;
-  /**
-   * Changes one shard row of an aggregate. Gauges of a sharded aggregate need
-   * `shardBy`, so every change keyed by one value lands on one shard.
-   */
-  aggregate<M extends AggregateNames<S>>(
-    model: M,
-    identity: AggregateIdentity<S[M]>,
-    changes: AggregateChanges<S[M]>,
-    options?: { readonly shardBy?: string },
-  ): void;
-}
-
-/** A table name, or the reason an aggregate cannot be read this way. */
-export type FindManyModel<S extends ModuleSchema, M> =
-  M extends TableNames<S>
-    ? M
-    : "findMany reads tables; read aggregates with findAggregates";
-
-/** An aggregate name, or the reason a table cannot be read this way. */
-export type FindAggregatesModel<S extends ModuleSchema, M> =
-  M extends AggregateNames<S>
-    ? M
-    : "findAggregates reads aggregates; read tables with findMany";
-
-/** A module's database handle. There is no count, offset, or free-form filter. */
-export interface HotUpdaterDatabase<S extends ModuleSchema> {
-  findOne<M extends TableNames<S>>(
-    model: M,
-    lookup: Lookup<S[M]>,
-  ): Promise<ReadRow<S[M]> | null>;
-  /** Rows by key in one batch read, in the keys' order. */
-  findByKeys<M extends TableNames<S>>(
-    model: M,
-    keys: readonly KeyLookup<S[M]>[],
-  ): Promise<(ReadRow<S[M]> | null)[]>;
-  findMany<M extends keyof S & string, I extends IndexName<S[M]>>(
-    model: FindManyModel<S, M>,
-    options: ReadOptions<S[M], I>,
-  ): Promise<Page<ReadRow<S[M]>>>;
-  findAggregates<M extends keyof S & string, I extends IndexName<S[M]>>(
-    model: FindAggregatesModel<S, M>,
-    options: ReadOptions<S[M], I>,
-  ): Promise<Page<AggregateRow<S[M]>>>;
-  /** Reruns `fn` when a guarded read changed, within a jittered retry budget. */
-  transaction<R>(fn: (tx: HotUpdaterTransaction<S>) => Promise<R>): Promise<R>;
-}
-
-/** The engine plus `database(module)`, which hands a module its typed handle. */
-export const createDatabaseEngine = ({
-  batching,
-  now = Date.now,
-  ...options
-}: DatabaseEngineOptions & {
-  /**
-   * Batches changes to aggregates declared `batched`; the schema must
-   * include `aggregateBatchingModule`.
-   */
-  readonly batching?: AggregateBatching;
-  /** The clock batching times its flushes and compactions by. */
-  readonly now?: () => number;
-}) => {
-  const engine = createEngine(options);
-  const { reads } = engine;
-  const batches =
-    batching &&
-    createAggregateBatches({
-      engine,
-      adapter: options.adapter,
-      schema: options.schema,
-      batching,
-      now,
-    });
-  const transaction = batches?.transaction ?? engine.transaction;
-  const outside =
-    <A extends unknown[], T>(read: (...args: A) => T) =>
-    (...args: A): T => {
-      assertOutsideTransaction();
-      return read(...args);
-    };
-  /** No read outside a transaction returns `_v`, which a key-value index copy lacks. */
-  const bare = (row: StoredRow | null) =>
-    row &&
-    Object.fromEntries(
-      Object.entries(row).filter(
-        ([column]) => column !== DATABASE_VERSION_COLUMN,
-      ),
-    );
-  const barePage = async (page: Promise<Page<StoredRow>>) => {
-    const { rows, next } = await page;
-    return { rows: rows.map(bare), ...(next === undefined ? {} : { next }) };
-  };
-  return {
-    ...engine,
-    /** Applies batched aggregate changes still pending: this process's buffer and the log. */
-    flush: async () => {
-      await batches?.flush();
-    },
-    dispose: async () => {
-      await batches?.dispose();
-    },
-    database<S extends ModuleSchema>(
-      module: SchemaModule & { readonly schema: S },
-    ): HotUpdaterDatabase<S> {
-      const name = (model: string) =>
-        module.namespace ? `${module.namespace}_${model}` : model;
-      return {
-        findOne: outside(
-          async (model, lookup) =>
-            bare(await reads.findOne(name(model), lookup as never)) as never,
-        ),
-        findByKeys: outside(
-          async (model, keys) =>
-            (await reads.findByKeys(name(model), keys as never)).map(
-              bare,
-            ) as never,
-        ),
-        findMany: outside(
-          (model, input) =>
-            barePage(reads.findMany(name(model), input as ReadInput)) as never,
-        ),
-        findAggregates: outside(async (model, input) => {
-          await batches?.beforeRead(name(model));
-          return (await barePage(
-            reads.findAggregates(name(model), input as ReadInput),
-          )) as never;
-        }),
-        transaction: (fn) =>
-          transaction((tx: TransactionEngine) =>
-            fn({
-              findOne: (model, lookup) =>
-                tx.findOne(name(model), lookup as never) as never,
-              findMany: (model, input) =>
-                tx.findMany(name(model), input as ReadInput) as never,
-              create: (model, row) => tx.create(name(model), row),
-              update: (model, row, set) => tx.update(name(model), row, set),
-              delete: (model, row) => tx.delete(name(model), row),
-              aggregate: (model, identity, changes, options) =>
-                tx.aggregate(name(model), identity, changes, options),
-            }),
-          ),
-      };
-    },
-  };
-};
-
-export type DatabaseEngine = ReturnType<typeof createDatabaseEngine>;

package/src/database/database.types.spec.ts

@@ -1,135 +0,0 @@
-import { describe, expectTypeOf, it } from "vitest";
-
-import type {
-  FindAggregatesModel,
-  FindManyModel,
-  HotUpdaterDatabase,
-  Lookup,
-} from "./database";
-import { defineAggregate, defineTable } from "./schema";
-
-const schema = {
-  bundles: defineTable(
-    {
-      id: { type: "string" },
-      platform: { type: "string" },
-      tag: { type: "string", required: false },
-      hash: { type: "string", unique: true },
-    },
-    {
-      key: ["id"],
-      indexes: {
-        byPlatform: { eq: ["platform"], sort: ["id"] },
-        byTag: { eq: ["tag"], sort: ["id"] },
-      },
-    },
-  ),
-  totals: defineAggregate(
-    { scope: { type: "string" } },
-    {
-      key: ["scope"],
-      counters: ["hits"],
-      indexes: { all: { eq: [], sort: ["scope"] } },
-    },
-  ),
-} as const;
-
-type Schema = typeof schema;
-
-/** The callback is type-checked and never runs. */
-const typeOnly = (check: (db: HotUpdaterDatabase<Schema>) => void) =>
-  void check;
-
-describe("database API types", () => {
-  it("names the right read in its error text", () => {
-    expectTypeOf<
-      FindManyModel<Schema, "totals">
-    >().toEqualTypeOf<"findMany reads tables; read aggregates with findAggregates">();
-    expectTypeOf<
-      FindAggregatesModel<Schema, "bundles">
-    >().toEqualTypeOf<"findAggregates reads aggregates; read tables with findMany">();
-    typeOnly((db) => {
-      // @ts-expect-error Aggregates are read with findAggregates.
-      void db.findMany("totals", { index: "all", where: {}, limit: 1 });
-      void db.findAggregates(
-        // @ts-expect-error Tables are read with findMany.
-        "bundles",
-        { index: "byPlatform", where: { platform: "ios" }, limit: 1 },
-      );
-    });
-  });
-
-  it("has no count, offset, or free-form filter", () => {
-    expectTypeOf<keyof HotUpdaterDatabase<Schema>>().toEqualTypeOf<
-      "findOne" | "findByKeys" | "findMany" | "findAggregates" | "transaction"
-    >();
-    typeOnly((db) => {
-      // @ts-expect-error There is no count.
-      void db.count;
-      void db.findMany("bundles", {
-        index: "byPlatform",
-        where: { platform: "ios" },
-        limit: 1,
-        // @ts-expect-error There is no offset.
-        offset: 5,
-      });
-    });
-  });
-
-  it("reads only declared indexes with every eq field bound to a value", () => {
-    typeOnly((db) => {
-      void db.findMany("bundles", {
-        // @ts-expect-error byHash is not a declared index.
-        index: "byHash",
-        where: { platform: "ios", tag: "beta" },
-        limit: 1,
-      });
-      void db.findMany("bundles", {
-        index: "byPlatform",
-        // @ts-expect-error byPlatform needs its platform field.
-        where: {},
-        limit: 1,
-      });
-      void db.findMany("bundles", {
-        index: "byTag",
-        // @ts-expect-error A sparse index never matches null.
-        where: { tag: null },
-        limit: 1,
-      });
-      void db.findMany("bundles", {
-        index: "byTag",
-        where: { tag: "beta" },
-        limit: 1,
-      });
-    });
-  });
-
-  it("creates full rows and updates only non-key fields in a transaction", () => {
-    typeOnly((db) => {
-      void db.transaction(async (tx) => {
-        tx.create("bundles", { id: "b", platform: "ios", hash: "h" });
-        // @ts-expect-error hash is required.
-        tx.create("bundles", { id: "b", platform: "ios" });
-        const row = await tx.findOne("bundles", { id: "b" });
-        if (row === null) return;
-        tx.update("bundles", row, { tag: null });
-        // @ts-expect-error Key fields cannot change.
-        tx.update("bundles", row, { id: "c" });
-        // @ts-expect-error Aggregates are not written through create.
-        tx.create("totals", { scope: "s" });
-      });
-    });
-  });
-
-  it("finds one row only by its key or a unique field", () => {
-    expectTypeOf<Lookup<Schema["bundles"]>>().toEqualTypeOf<
-      { readonly id: string } | { readonly hash: string }
-    >();
-    typeOnly((db) => {
-      // @ts-expect-error platform is neither the key nor unique.
-      void db.findOne("bundles", { platform: "ios" });
-      // @ts-expect-error findOne reads tables.
-      void db.findOne("totals", { scope: "s" });
-    });
-  });
-});