@hollware/server 0.0.2 → 0.2.0

package/README.md

@@ -8,9 +8,9 @@ for the agent era, native to Cloudflare Workers.
 
 ## What it will be
 
-The Hollware Worker: the operation registry behind MCP, Workers RPC and HTTP, authentication,
-and the D1 migrations that shape the database. The migrations ship inside the package, in
-`migrations/`.
+The Hollware Worker: the handlers of the operations that `@hollware/core` specifies, served
+over MCP, Workers RPC and HTTP, authentication, and the D1 migrations that shape the
+database. The migrations ship inside the package, in `migrations/`.
 
 ## Links
 

package/dist/index.d.mts

@@ -1,3 +1,389 @@
+import { AcknowledgedWarning, EntryDocument, EntryLookup, EntryRef, HollwareConfig, OperationByName, OperationName, ResolvedSite, Scope, Verdict, describeSite, getEntry, getTranslations, listEntries } from "@hollware/core";
+import * as z from "zod";
+import { WorkerEntrypoint } from "cloudflare:workers";
+//#region src/ports.d.ts
+/**
+ * The ports of the operation handlers: what they need from the world, as interfaces. The D1
+ * store implements `ContentStore` (`db/`); the handlers (`ops/`) only see this file, so their
+ * tests run on fakes. Every method takes the site first and never sees another site's rows.
+ */
+/** Which revision a read returns: the latest one (MCP) or the published one (RPC). */
+type View = 'head' | 'published';
+/** Who wrote a revision or a publication. */
+interface Actor {
+  readonly kind: 'token' | 'user' | 'oauth_client';
+  readonly userId: string;
+  readonly tokenId: string | null;
+  /** What the client said about itself (the MCP client and, when it says, the model). */
+  readonly meta: Readonly<Record<string, unknown>> | null;
+}
+/** An entry as the store holds it. */
+interface StoredEntry {
+  readonly id: string;
+  readonly collection: string;
+  readonly locale: string;
+  readonly slug: string;
+  readonly translationGroup: string | null;
+  readonly status: 'draft' | 'scheduled' | 'published';
+  /** Moves on every change of the entry; a write against an older one is a conflict. */
+  readonly version: number;
+  readonly headRevision: string;
+  readonly publishedRevision: string | null;
+  /** When the entry was first published; republishing keeps it. */
+  readonly publishedAt: string | null;
+  readonly updatedAt: string;
+}
+/** A revision as the store holds it. */
+interface StoredRevision {
+  readonly id: string;
+  readonly entryId: string;
+  /** The whole file, frontmatter included: the source of truth (ADR-001). */
+  readonly markdown: string;
+  readonly frontmatter: Readonly<Record<string, unknown>>;
+  readonly document: EntryDocument;
+  readonly comarkVersion: string;
+  readonly pipelineVersion: string;
+  readonly wordCount: number;
+  /** The verdict of the `write` phase when the revision was written. */
+  readonly verdict: Verdict;
+  readonly tags: readonly string[];
+  readonly actor: Actor;
+  readonly createdAt: string;
+}
+/** An entry with the revision of the view that was asked for. */
+interface EntryView {
+  readonly entry: StoredEntry;
+  readonly revision: StoredRevision;
+}
+/**
+ * What a listing needs of a revision: its frontmatter and tags, never the Markdown or the
+ * document, which can weigh megabytes on a page of a hundred entries.
+ */
+interface RevisionSummary {
+  readonly id: string;
+  readonly frontmatter: Readonly<Record<string, unknown>>;
+  readonly tags: readonly string[];
+}
+/** An entry with the summary of the revision of the view that was asked for. */
+interface EntrySummaryView {
+  readonly entry: StoredEntry;
+  readonly revision: RevisionSummary;
+}
+/** A publish or an unpublish, as `publications` keeps it (ADR-021). */
+interface StoredPublication {
+  readonly id: string;
+  readonly entryId: string;
+  readonly action: 'publish' | 'unpublish';
+  readonly revisionId: string | null;
+  readonly verdict: Verdict | null;
+  readonly acknowledged: readonly AcknowledgedWarning[];
+  readonly actor: Actor;
+  readonly createdAt: string;
+}
+/** A revision to append. The store adds its id and time. */
+interface NewRevision {
+  readonly markdown: string;
+  readonly frontmatter: Readonly<Record<string, unknown>>;
+  readonly document: EntryDocument;
+  readonly comarkVersion: string;
+  readonly pipelineVersion: string;
+  readonly wordCount: number;
+  readonly verdict: Verdict;
+  readonly tags: readonly string[];
+  readonly actor: Actor;
+}
+interface ListQuery {
+  readonly collection: string;
+  readonly locale?: string;
+  readonly tag?: string;
+  readonly status?: StoredEntry['status'];
+  readonly view: View;
+  readonly limit: number;
+  /** The `nextCursor` of the previous page. */
+  readonly cursor?: string;
+}
+/** The answer to a write that the store could not make. */
+type WriteRefusal = {
+  readonly outcome: 'conflict';
+  readonly currentVersion: number;
+  readonly headRevision: string;
+} | {
+  readonly outcome: 'not_found';
+} |
+/** Another entry already has this slug, or this translation, in the collection and locale. */
+{
+  readonly outcome: 'taken';
+  readonly field: 'slug' | 'translationGroup';
+  readonly by: string;
+} |
+/** The row would be over `MAX_ROW_BYTES` (`limits.ts`); nothing was written. */
+{
+  readonly outcome: 'too_large';
+  readonly bytes: number;
+  readonly limit: number;
+};
+/** A scheduled publication, as the cron trigger reads it. */
+interface StoredSchedule {
+  readonly entryId: string;
+  readonly scheduledAt: string;
+  /** The version the entry had once scheduled; another one means it changed since. */
+  readonly version: number;
+  readonly acknowledged: readonly AcknowledgedWarning[];
+  readonly actor: Actor;
+}
+/** One entry of a publication: what `publish` and `publishGroup` write for it. */
+interface PublishWrite {
+  readonly entryId: string;
+  readonly expectedVersion: number;
+  readonly verdict: Verdict;
+  readonly acknowledged: readonly AcknowledgedWarning[];
+  readonly actor: Actor;
+  /** What orders the entry in published listings. */
+  readonly sortKey: string;
+  /** The event of the publication, written to the outbox in the same batch (ADR-025). */
+  readonly event?: OutboxEvent | null;
+}
+/** An event for the outbox: its id and what subscribers get, as JSON. */
+interface OutboxEvent {
+  readonly id: string;
+  readonly payload: string;
+}
+interface ContentStore {
+  /** The entry with that collection, locale and slug, in the given view, or `null`. */
+  findEntry(site: string, ref: EntryRef, view: View): Promise<EntryView | null>;
+  /** The entry with that id, in the given view, or `null`. */
+  findEntryById(site: string, id: string, view: View): Promise<EntryView | null>;
+  /**
+   * A page of entries. The `head` view is ordered by the last change, the `published` view by
+   * the published sort key, newest first; ties go by id. The cursor is opaque.
+   */
+  listEntries(site: string, query: ListQuery): Promise<{
+    readonly entries: readonly EntrySummaryView[];
+    readonly nextCursor: string | null;
+  }>;
+  /** The entries of a translation group, one per locale, in the given view. */
+  listTranslations(site: string, collection: string, translationGroup: string, view: View): Promise<readonly EntrySummaryView[]>;
+  /** What cross-entry contracts read, scoped to the site. */
+  lookup(site: string): EntryLookup;
+  /** The latest publish or unpublish of an entry, or `null`. */
+  lastPublication(site: string, entryId: string): Promise<StoredPublication | null>;
+  /** Creates an entry at version 1 with its first revision, as a draft. */
+  createEntry(site: string, entry: EntryRef & {
+    readonly translationGroup: string | null;
+    readonly revision: NewRevision;
+  }): Promise<{
+    readonly outcome: 'saved';
+    readonly view: EntryView;
+  } | WriteRefusal>;
+  /**
+   * Appends a revision and makes it the head, if the entry is still at `expectedVersion`. In
+   * one batch: the revision, its tags (only where the revision was inserted) and the entry.
+   */
+  appendRevision(site: string, write: {
+    readonly entryId: string;
+    readonly expectedVersion: number;
+    readonly translationGroup: string | null;
+    readonly revision: NewRevision;
+  }): Promise<{
+    readonly outcome: 'saved';
+    readonly view: EntryView;
+  } | WriteRefusal>;
+  /**
+   * Publishes the head revision, if the entry is still at `expectedVersion`, and appends the
+   * publication with its verdict and acknowledged warnings.
+   */
+  publish(site: string, write: PublishWrite): Promise<{
+    readonly outcome: 'published';
+    readonly view: EntryView;
+  } | WriteRefusal>;
+  /**
+   * Publishes the head revisions of a group of entries in one batch, all or none (ADR-024): every
+   * entry must still be at its `expectedVersion`. A refusal names the entry that caused it.
+   */
+  publishGroup(site: string, writes: readonly PublishWrite[]): Promise<{
+    readonly outcome: 'published';
+    readonly views: readonly EntryView[];
+  } | (WriteRefusal & {
+    readonly entryId: string;
+  })>;
+  /**
+   * Schedules the publication of an entry that is not published, if it is still at
+   * `expectedVersion`: the entry becomes `scheduled` at the next version, and its schedule keeps
+   * the acknowledged warnings and the actor for the cron trigger (ADR-025).
+   */
+  schedule(site: string, write: {
+    readonly entryId: string;
+    readonly expectedVersion: number;
+    readonly scheduledAt: string;
+    readonly acknowledged: readonly AcknowledgedWarning[];
+    readonly actor: Actor;
+  }): Promise<{
+    readonly outcome: 'scheduled';
+    readonly view: EntryView;
+  } | WriteRefusal>;
+  /** The schedules whose time has come, at most 50, oldest first. */
+  dueSchedules(site: string, now: string): Promise<readonly StoredSchedule[]>;
+  /** Takes a scheduled entry back to a draft and drops its schedule. */
+  cancelSchedule(site: string, entryId: string): Promise<void>;
+  /** Takes the entry off the public site and appends the unpublish. */
+  unpublish(site: string, write: {
+    readonly entryId: string;
+    readonly actor: Actor;
+    readonly event?: OutboxEvent | null;
+  }): Promise<{
+    readonly outcome: 'unpublished';
+    readonly view: EntryView;
+  } | WriteRefusal>;
+}
+/** The time, so that tests can fix it. */
+interface Clock {
+  now(): Date;
+}
+//#endregion
+//#region src/events/run.d.ts
+/** A message of the events Queue: the site and the id of an outbox row. */
+interface EventMessage {
+  readonly site: string;
+  readonly id: string;
+}
+/** The part of a Queue binding that sends. */
+interface EventQueue {
+  sendBatch(messages: Iterable<{
+    readonly body: EventMessage;
+  }>): Promise<unknown>;
+}
+/** The part of a Queue message the consumer uses; its body is checked before use. */
+interface EventDelivery {
+  readonly body: unknown;
+  ack(): void;
+  retry(): void;
+}
+//#endregion
+//#region src/auth/types.d.ts
+/**
+ * Who calls an operation. The gateway turns each request into a principal before any handler
+ * runs, and the handlers check their scopes against it at call time (ADR-019).
+ */
+type Principal = {
+  /** A personal token. */
+  readonly kind: 'token';
+  readonly userId: string;
+  readonly tokenId: string;
+  /** The site the token belongs to; it never reaches another one. */
+  readonly site: string;
+  /** The token's own scopes intersected with those of its user's role, as of now. */
+  readonly scopes: readonly Scope[];
+} | {
+  /** A Worker of the same account, over the RPC binding: it reads published content. */
+  readonly kind: 'binding';
+  readonly scopes: readonly ['content:read'];
+};
+//#endregion
+//#region src/ops/types.d.ts
+/**
+ * The handlers of the operations (ADR-017): one per spec of `@hollware/core`, paired by type,
+ * so that a missing handler or a handler for an unknown operation does not compile.
+ */
+/** What a handler gets besides its input. Adapters build it; handlers never see a request. */
+interface OperationContext {
+  readonly site: ResolvedSite;
+  readonly principal: Principal;
+  /** `head` over MCP, `published` over RPC. */
+  readonly view: View;
+  readonly store: ContentStore;
+  readonly clock: Clock;
+  /** What the client said about itself; writes record it as the actor's meta. */
+  readonly client: Readonly<Record<string, unknown>> | null;
+  readonly requestId: string;
+  /**
+   * Called with the ids of the events that a write committed to the outbox, so that they reach
+   * the Queue now rather than at the next sweep of the cron trigger (ADR-025). Absent in tests.
+   */
+  readonly notify?: (eventIds: readonly string[]) => void;
+}
+/** The handler of one operation: its parsed input in, its output out. */
+type OperationHandler<Name extends OperationName> = (input: z.output<OperationByName<Name>['input']>, context: OperationContext) => Promise<z.output<OperationByName<Name>['output']>>;
+/** One handler for every operation. */
+type Handlers = { readonly [Name in OperationName]: OperationHandler<Name>; };
+/** Declares the handlers; the type checks that they pair with the specs one to one. */
+export declare function defineHandlers(handlers: Handlers): Handlers;
+//#endregion
+//#region src/limits.d.ts
+/**
+ * The limits every operation runs under, pinned for the adapters and the store (the v0.1 plan).
+ */
+/**
+ * The largest answer of an operation, in UTF-8 bytes of its JSON. A larger one is the error
+ * `output_too_large`, with a fix that says how to ask for less; content is never truncated.
+ */
+export declare const OUTPUT_CAP_BYTES: number;
+/** How long an operation may take before it answers the error `timeout`. */
+export declare const OPERATION_TIMEOUT_MS = 10000;
+/**
+ * The largest row the store writes, counted in UTF-8 bytes across all its columns. D1 refuses
+ * rows over 2 MB in production, and Miniflare does not enforce it, so the store checks first.
+ */
+export declare const MAX_ROW_BYTES = 1900000;
+/** The most values bound in one statement: D1 allows 100, and lookups go in chunks of this. */
+export declare const MAX_BOUND_PARAMETERS = 90;
+//#endregion
 //#region src/index.d.ts
 export declare const name = "@hollware/server";
-//#endregion
+/** The bindings and variables of the Worker, as its `wrangler.jsonc` declares them. */
+export interface HollwareEnv {
+  /** The D1 database, with the migrations of this package applied. */
+  readonly DB: D1Database;
+  /**
+   * The public URL of the Worker, such as `https://cms.example.com`. It is the only Host and
+   * Origin the Worker answers; without it, every request fails.
+   */
+  readonly HOLLWARE_PUBLIC_URL: string;
+  /** The Queue of publication events (ADR-025); without it, the cron trigger delivers them. */
+  readonly EVENTS?: EventQueue;
+}
+type Output<Spec extends {
+  output: z.ZodType;
+}> = z.output<Spec['output']>;
+/**
+ * The read-only RPC surface that sites of the same account call over a service binding. It
+ * returns published content only; nothing in it writes.
+ */
+export interface HollwareRpc {
+  getEntry(site: string, collection: string, slug: string, locale: string, options?: {
+    readonly formats?: readonly ('markdown' | 'document' | 'html')[];
+  }): Promise<Output<typeof getEntry>>;
+  listEntries(site: string, collection: string, options?: {
+    readonly locale?: string;
+    readonly tag?: string;
+    readonly limit?: number;
+    readonly cursor?: string;
+  }): Promise<Output<typeof listEntries>>;
+  getTranslations(site: string, collection: string, translationGroup: string): Promise<Output<typeof getTranslations>>;
+  describeSite(site: string): Promise<Output<typeof describeSite>>;
+}
+/**
+ * What `createHollware(config)` returns. The user's Worker is
+ * `export default { fetch }` and `export class Hollware extends hollware.Hollware {}`.
+ */
+export interface HollwareWorker {
+  /** MCP at `/mcp`, and the other routes of the gateway. */
+  readonly fetch: (request: Request, env: HollwareEnv, ctx: ExecutionContext) => Promise<Response>;
+  /** The consumer of the events Queue (`queues.consumers` in wrangler.jsonc). */
+  readonly queue: (batch: {
+    readonly messages: readonly EventDelivery[];
+  }, env: HollwareEnv, ctx: ExecutionContext) => Promise<void>;
+  /** The cron trigger of the project (`triggers.crons` in wrangler.jsonc, every minute). */
+  readonly scheduled: (controller: ScheduledController, env: HollwareEnv, ctx: ExecutionContext) => Promise<void>;
+  /** The RPC entrypoint, for the user's Worker to export under the name `Hollware`. */
+  readonly Hollware: new (ctx: ExecutionContext, env: HollwareEnv) => WorkerEntrypoint<HollwareEnv> & HollwareRpc;
+}
+/** Builds the Worker from the config. The config is resolved once, when the Worker starts. */
+export type CreateHollware = (config: HollwareConfig) => HollwareWorker;
+/**
+ * Builds the Worker from the config: `const hollware = createHollware(config)`, then
+ * `export default { fetch: hollware.fetch }` and `export class Hollware extends hollware.Hollware {}`.
+ * The config is resolved once, here; a broken one throws its `ConfigError`.
+ */
+export declare const createHollware: CreateHollware;
+//#endregion
+export type { Actor, Clock, ContentStore, EntrySummaryView, EntryView, EventMessage, Handlers, ListQuery, NewRevision, OperationContext, OperationHandler, OutboxEvent, Principal, PublishWrite, RevisionSummary, StoredEntry, StoredPublication, StoredRevision, StoredSchedule, View, WriteRefusal };