@hollware/server 0.1.0 → 0.2.0

package/dist/index.d.mts

@@ -1,26 +1,6 @@
 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/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/ports.d.ts
 /**
  * The ports of the operation handlers: what they need from the world, as interfaces. The D1
@@ -142,6 +122,32 @@ type WriteRefusal = {
   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>;
@@ -186,22 +192,44 @@ interface ContentStore {
    * 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: {
+  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 verdict: Verdict;
+    readonly scheduledAt: string;
     readonly acknowledged: readonly AcknowledgedWarning[];
     readonly actor: Actor;
-    /** What orders the entry in published listings. */
-    readonly sortKey: string;
   }): Promise<{
-    readonly outcome: 'published';
+    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;
@@ -212,6 +240,45 @@ 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,
@@ -228,6 +295,11 @@ interface OperationContext {
   /** 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']>>;
@@ -266,6 +338,8 @@ export interface HollwareEnv {
    * 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;
@@ -294,6 +368,12 @@ export interface HollwareRpc {
 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;
 }
@@ -306,4 +386,4 @@ export type CreateHollware = (config: HollwareConfig) => HollwareWorker;
  */
 export declare const createHollware: CreateHollware;
 //#endregion
-export type { Actor, Clock, ContentStore, EntrySummaryView, EntryView, Handlers, ListQuery, NewRevision, OperationContext, OperationHandler, Principal, RevisionSummary, StoredEntry, StoredPublication, StoredRevision, View, WriteRefusal };
+export type { Actor, Clock, ContentStore, EntrySummaryView, EntryView, EventMessage, Handlers, ListQuery, NewRevision, OperationContext, OperationHandler, OutboxEvent, Principal, PublishWrite, RevisionSummary, StoredEntry, StoredPublication, StoredRevision, StoredSchedule, View, WriteRefusal };