@akterjs/effect 0.0.0-stage → 0.1.0

package/src/host/command/batch/command-batch.sql.ts

@@ -0,0 +1,207 @@
+import { Array as Arr, Context, Effect, HashMap, HashSet, Option, Ref, Schema } from "effect";
+import type { SqlClient, SqlError } from "effect/sql";
+
+import type { RecordedCommand } from "#src/host/command/command-journal.sql";
+
+/**
+ * The journal of one engine batch, kept in memory so a command's bookkeeping needs no round trip of its own.
+ *
+ * An engine that runs many commands in one transaction (akter-cloud) provides `CommandBatch` around each of them.
+ * The first command reads the actor's state, the batch's recorded command ids and the last seq once; later ones read
+ * them from here. Their state and journal writes go to `held`, a client whose statements the engine sends ahead of the
+ * next statement that reaches SQLite, or with the commit, so a handler's own SQL still sees every earlier write. Only
+ * the engine writes `akter_*` tables (handler writes to them are refused), which is what makes the cache sound.
+ */
+interface Journal {
+  /** Command ids whose journal rows were read at the start of the batch, recorded or not. */
+  readonly known: HashSet.HashSet<string>;
+  readonly nextSeq: number;
+  readonly recorded: HashMap.HashMap<string, RecordedCommand>;
+  /** The seq each command recorded in this batch was given. */
+  readonly seqs: HashMap.HashMap<string, number>;
+  readonly state: Option.Option<string>;
+}
+
+interface Batch {
+  readonly commandIds: readonly string[];
+  /** The journal including the running command. */
+  readonly current: Ref.Ref<Option.Option<Journal>>;
+  readonly held: SqlClient.SqlClient;
+  /** The journal as of the last command the engine kept. */
+  readonly kept: Ref.Ref<Option.Option<Journal>>;
+}
+
+interface JournalRead {
+  readonly command: string;
+  readonly commandId: string;
+  readonly exit: string;
+  readonly principal: string;
+}
+
+const CommandBatch = Context.Reference<Option.Option<Batch>>(
+  "@akterjs/effect/host/command/batch/command-batch.sql/CommandBatch",
+  {
+    defaultValue: Option.none,
+  },
+);
+
+const firstSeq = 1;
+const nextOf = 1;
+
+const IdList = Schema.fromJsonString(Schema.Array(Schema.String));
+
+const journalRows = (sql: SqlClient.SqlClient, ids: string): Effect.Effect<readonly JournalRead[], SqlError.SqlError> =>
+  sql<JournalRead>`SELECT command_id AS "commandId", command, exit, principal FROM akter_commands WHERE command_id IN (SELECT value FROM json_each(${ids}))`;
+
+const readJournal = Effect.fnUntraced(function* readJournal(sql: SqlClient.SqlClient, commandIds: readonly string[]) {
+  const ids = yield* Effect.orDie(Schema.encodeEffect(IdList)(commandIds));
+
+  const [states, rows, last] = yield* Effect.all([
+    sql<{ readonly value: string }>`SELECT value FROM akter_state WHERE id = 1`,
+    journalRows(sql, ids),
+    sql<{ readonly seq: number }>`SELECT coalesce(max(seq), 0) AS seq FROM akter_commands`,
+  ]);
+
+  return {
+    known: HashSet.fromIterable(commandIds),
+    nextSeq: Option.match(Arr.head(last), { onNone: () => firstSeq, onSome: (row) => row.seq + nextOf }),
+    recorded: HashMap.fromIterable(
+      Arr.map(rows, ({ commandId, ...recorded }): [string, RecordedCommand] => [commandId, recorded]),
+    ),
+    seqs: HashMap.empty(),
+    state: Option.map(Arr.head(states), (row) => row.value),
+  } satisfies Journal;
+});
+
+/** The batch's journal, read on first use with the engine's real client. */
+const journalOf = (
+  sql: SqlClient.SqlClient,
+): Effect.Effect<Option.Option<readonly [Batch, Journal]>, SqlError.SqlError> =>
+  Effect.flatMap(CommandBatch, (batch) =>
+    Option.match(batch, {
+      onNone: () => Effect.succeedNone,
+      onSome: (open) =>
+        Effect.flatMap(Ref.get(open.current), (current) =>
+          Option.match(current, {
+            onNone: () =>
+              Effect.tap(readJournal(sql, open.commandIds), (read) =>
+                Effect.andThen(Ref.set(open.current, Option.some(read)), Ref.set(open.kept, Option.some(read))),
+              ).pipe(Effect.map((read) => Option.some([open, read] as const))),
+            onSome: (journal) => Effect.succeedSome([open, journal] as const),
+          }),
+        ),
+    }),
+  );
+
+const update = (change: (journal: Journal) => Journal): Effect.Effect<void> =>
+  Effect.flatMap(CommandBatch, (batch) =>
+    Option.match(batch, {
+      onNone: () => Effect.void,
+      onSome: (open) => Ref.update(open.current, Option.map(change)),
+    }),
+  );
+
+/** Whether a batch journal answers for this command id: it was read at the start or recorded since. */
+const answers = (journal: Journal, commandId: string): boolean =>
+  HashSet.has(journal.known, commandId) || HashMap.has(journal.recorded, commandId);
+
+const CommandBatchJournal = {
+  /** Forgets the journal, so the next command reads it again; after journal pruning, for one. */
+  forget: Effect.flatMap(CommandBatch, (batch) =>
+    Option.match(batch, {
+      onNone: () => Effect.void,
+      onSome: (open) => Effect.andThen(Ref.set(open.current, Option.none()), Ref.set(open.kept, Option.none())),
+    }),
+  ),
+  /** Notes a journal row and returns the seq it is written with, or none outside a batch. */
+  record: (commandId: string, recorded: RecordedCommand): Effect.Effect<Option.Option<number>> =>
+    Effect.flatMap(CommandBatch, (batch) =>
+      Option.match(batch, {
+        onNone: () => Effect.succeedNone,
+        onSome: (open) =>
+          Ref.modify(open.current, (current) =>
+            Option.match(current, {
+              onNone: () => [Option.none<number>(), current] as const,
+              onSome: (journal) =>
+                [
+                  Option.some(journal.nextSeq),
+                  Option.some({
+                    ...journal,
+                    nextSeq: journal.nextSeq + nextOf,
+                    recorded: HashMap.set(journal.recorded, commandId, recorded),
+                    seqs: HashMap.set(journal.seqs, commandId, journal.nextSeq),
+                  }),
+                ] as const,
+            }),
+          ),
+      }),
+    ),
+  /** The recorded outcome of `commandId`, from the batch journal when it answers for the id. */
+  recorded: (
+    sql: SqlClient.SqlClient,
+    commandId: string,
+    read: Effect.Effect<Option.Option<RecordedCommand>, SqlError.SqlError>,
+  ): Effect.Effect<Option.Option<RecordedCommand>, SqlError.SqlError> =>
+    Effect.flatMap(journalOf(sql), (opened) =>
+      Option.match(
+        Option.filter(opened, ([, journal]) => answers(journal, commandId)),
+        {
+          onNone: () => read,
+          onSome: ([, journal]) => Effect.succeed(HashMap.get(journal.recorded, commandId)),
+        },
+      ),
+    ),
+  /** Notes a state the running command saved. */
+  saved: (value: string): Effect.Effect<void> => update((journal) => ({ ...journal, state: Option.some(value) })),
+  /** The seq a command recorded in this batch was given, or none when the batch did not record it. */
+  seq: (commandId: string): Effect.Effect<Option.Option<number>> =>
+    Effect.flatMap(CommandBatch, (batch) =>
+      Option.match(batch, {
+        onNone: () => Effect.succeedNone,
+        onSome: (open) =>
+          Effect.map(
+            Ref.get(open.current),
+            Option.flatMap((journal) => HashMap.get(journal.seqs, commandId)),
+          ),
+      }),
+    ),
+  /** The actor's current state, from the batch journal when there is one. */
+  state: (
+    sql: SqlClient.SqlClient,
+    read: Effect.Effect<Option.Option<string>, SqlError.SqlError>,
+  ): Effect.Effect<Option.Option<string>, SqlError.SqlError> =>
+    Effect.flatMap(
+      journalOf(sql),
+      Option.match({ onNone: () => read, onSome: ([, journal]) => Effect.succeed(journal.state) }),
+    ),
+  /** The client for the running command's journal and state writes: the batch's held client, or `sql` itself. */
+  writer: (sql: SqlClient.SqlClient): Effect.Effect<SqlClient.SqlClient> =>
+    Effect.map(CommandBatch, Option.match({ onNone: () => sql, onSome: (open) => open.held })),
+} as const;
+
+const noJournal = (): Effect.Effect<Ref.Ref<Option.Option<Journal>>> => Ref.make(Option.none<Journal>());
+
+/** Opens the in-memory journal of one engine batch over `held`, the client whose writes the engine holds. */
+const commandBatch = Effect.fnUntraced(function* commandBatch({
+  commandIds,
+  held,
+}: {
+  readonly commandIds: readonly string[];
+  readonly held: SqlClient.SqlClient;
+}) {
+  const [current, kept] = yield* Effect.all([noJournal(), noJournal()]);
+
+  return { commandIds, current, held, kept } satisfies Batch;
+});
+
+/** The engine kept the running command: its journal changes stand. */
+const keepCommand = (batch: Batch): Effect.Effect<void> =>
+  Effect.flatMap(Ref.get(batch.current), (current) => Ref.set(batch.kept, current));
+
+/** The engine rolled the running command back: its journal changes go with it. */
+const dropCommand = (batch: Batch): Effect.Effect<void> =>
+  Effect.flatMap(Ref.get(batch.kept), (kept) => Ref.set(batch.current, kept));
+
+export { CommandBatch, CommandBatchJournal, commandBatch, dropCommand, keepCommand };
+
+export type { Batch as CommandBatchScope };

package/src/host/command/command-context.adapter.ts

@@ -0,0 +1,134 @@
+import { Array as Arr, Clock, Context, Effect, Layer, Option, Ref, Schema, Stream } from "effect";
+import { SecureRandom } from "effect/crypto";
+import type { SqlClient } from "effect/sql";
+
+import type { CommandEnvironment } from "#src/contract/actor/actor.contract";
+import type { FileStorage } from "#src/contract/file/actor-files.contract";
+import { StatementDetail } from "#src/contract/hosted/handler-failure.pure";
+import { HandlerSql } from "#src/host/query/query-policy.pure";
+import { captureFileInputs, FileInputs, replayFileInputs } from "./files/command-file-inputs.sql.js";
+import type { FileInputValue } from "./files/command-file-inputs.sql.js";
+
+interface Tracking {
+  readonly files: FileStorage;
+  readonly key: string;
+  readonly sql: SqlClient.SqlClient;
+}
+
+interface TrackedContext {
+  readonly environment: CommandEnvironment;
+  readonly recorded: Effect.Effect<typeof RecordedContext.Encoded>;
+}
+
+interface Sources {
+  readonly files: (files: FileStorage, sql: SqlClient.SqlClient) => Effect.Effect<FileStorage>;
+  readonly id: Effect.Effect<string>;
+  readonly now: Effect.Effect<number>;
+}
+
+const RecordedContext = Schema.Struct({
+  files: FileInputs,
+  ids: Schema.fromJsonString(Schema.Array(Schema.String)),
+  times: Schema.fromJsonString(Schema.Array(Schema.Int)),
+});
+
+type RecordedValues = typeof RecordedContext.Encoded;
+
+/** File storage is the engine's own: its writes to `akter_*` tables are not the handler's, even inside one. */
+const engineFiles = (files: FileStorage): FileStorage => ({
+  attach: (attaching) => Effect.provideService(files.attach(attaching), HandlerSql, false),
+  available: Effect.provideService(files.available, HandlerSql, false),
+  fileUsage: (listing) => Effect.provideService(files.fileUsage(listing), HandlerSql, false),
+  list: (listing) => Effect.provideService(files.list(listing), HandlerSql, false),
+  read: (path, range) => Stream.provideService(files.read(path, range), HandlerSql, false),
+  remove: (path) => Effect.provideService(files.remove(path), HandlerSql, false),
+});
+
+const trackWith = (sources: Effect.Effect<Sources>): ((tracking: Tracking) => Effect.Effect<TrackedContext>) =>
+  Effect.fnUntraced(function* track({ files, key, sql }: Tracking) {
+    const { files: prepareFiles, id, now } = yield* sources;
+    const used = yield* Ref.make<Omit<typeof RecordedContext.Type, "files">>({ ids: [], times: [] });
+    const inputs = yield* Ref.make<readonly FileInputValue[]>([]);
+    const preparedFiles = yield* prepareFiles(captureFileInputs({ files, sql, used: inputs }), sql);
+
+    const environment: CommandEnvironment = {
+      files: engineFiles(preparedFiles),
+      id: Effect.tap(id, (value) =>
+        Ref.update(used, (context) => ({ ...context, ids: Arr.append(context.ids, value) })),
+      ),
+      key,
+      now: Effect.tap(now, (value) =>
+        Ref.update(used, (context) => ({ ...context, times: Arr.append(context.times, value) })),
+      ),
+      sql,
+    };
+
+    const usedInputs = Effect.all({ files: Ref.get(inputs), used: Ref.get(used) });
+
+    const encoded = Effect.flatMap(usedInputs, (values) =>
+      Schema.encodeEffect(RecordedContext)({ ...values.used, files: values.files }),
+    );
+
+    const recorded = Effect.orDie(encoded);
+
+    return { environment, recorded } satisfies TrackedContext;
+  });
+
+const replayedFrom = <Value>(
+  recorded: readonly Value[],
+  fresh: Effect.Effect<Value>,
+): Effect.Effect<Effect.Effect<Value>> =>
+  Effect.map(Ref.make(recorded), (left) =>
+    Effect.flatMap(
+      Ref.modify(left, (values) =>
+        Arr.matchLeft(values, {
+          onEmpty: () => [Option.none<Value>(), values] as const,
+          onNonEmpty: (head, tail) => [Option.some(head), tail] as const,
+        }),
+      ),
+      Option.match({ onNone: () => fresh, onSome: Effect.succeed }),
+    ),
+  );
+
+const replaySources = (
+  random: SecureRandom.SecureRandom["Service"],
+  script: Ref.Ref<RecordedValues>,
+): Effect.Effect<Sources> =>
+  Effect.gen(function* scriptedSources() {
+    const recorded = yield* Effect.orDie(Effect.flatMap(Ref.get(script), Schema.decodeEffect(RecordedContext)));
+    const id = yield* replayedFrom(recorded.ids, random.uuidV7());
+    const now = yield* replayedFrom(recorded.times, Clock.currentTimeMillis);
+
+    return { files: (files, sql) => replayFileInputs({ files, inputs: recorded.files, sql }), id, now };
+  });
+
+export class CommandContext extends Context.Service<
+  CommandContext,
+  {
+    readonly track: (tracking: Tracking) => Effect.Effect<TrackedContext>;
+  }
+>()("@akterjs/effect/host/command/command-context.adapter/CommandContext", {
+  make: Effect.map(SecureRandom.SecureRandom, (random) => ({
+    track: trackWith(
+      Effect.succeed({
+        files: (files: FileStorage) => Effect.succeed(files),
+        id: random.uuidV7(),
+        now: Clock.currentTimeMillis,
+      }),
+    ),
+  })),
+}) {
+  public static readonly layer = Layer.effect(this, this.make).pipe(Layer.provide(SecureRandom.layerWebCrypto));
+
+  /** Whether a failed statement's message reaches the caller or only the host's log. */
+  public static readonly statementDetail = StatementDetail;
+
+  public static replaying(
+    random: SecureRandom.SecureRandom["Service"],
+    script: Ref.Ref<RecordedValues>,
+  ): CommandContext["Service"] {
+    return { track: trackWith(replaySources(random, script)) };
+  }
+}
+
+export type { RecordedValues };

package/src/host/command/command-id-age.pure.ts

@@ -0,0 +1,54 @@
+import { Duration, Effect, Option } from "effect";
+
+import { CommandIdExpiredError } from "#src/contract/command/command-id-expired.errors";
+import { InvalidRequestError } from "#src/contract/client/invalid-request.errors";
+import { mintedIdOf } from "#src/contract/command/outbox-id.pure";
+
+interface IdCheck {
+  readonly actor: string;
+  readonly commandId: string;
+  readonly keptSince: number;
+  readonly now: number;
+}
+
+const clockSkew = Duration.toMillis("5 minutes");
+
+const hexadecimal = 16;
+
+const uuidV7 = /^(?<high>[\da-f]{8})-(?<low>[\da-f]{4})-7[\da-f]{3}-[89ab][\da-f]{3}-[\da-f]{12}$/iu;
+
+const mintedAtOf = (commandId: string): Option.Option<number> => {
+  const minted = uuidV7.exec(mintedIdOf(commandId));
+
+  return Option.map(Option.fromNullishOr(minted?.groups), ({ high, low }) =>
+    Number.parseInt(`${high}${low}`, hexadecimal),
+  );
+};
+
+const checkCommandId = ({
+  actor,
+  commandId,
+  keptSince,
+  now,
+}: IdCheck): Effect.Effect<void, CommandIdExpiredError | InvalidRequestError> => {
+  const mintedAt = mintedAtOf(commandId);
+
+  if (Option.isNone(mintedAt)) {
+    return InvalidRequestError.make({
+      actor,
+      message: `command id ${commandId} is not a UUIDv7, so its age can't be checked against the history retention`,
+    });
+  }
+
+  if (mintedAt.value < keptSince + clockSkew) {
+    return CommandIdExpiredError.make({ actor, commandId, keptSince, mintedAt: mintedAt.value });
+  }
+
+  if (mintedAt.value > now + clockSkew) {
+    return InvalidRequestError.make({ actor, message: `command id ${commandId} was minted more than 5 minutes ahead` });
+  }
+
+  return Effect.void;
+};
+
+export { checkCommandId, clockSkew, mintedAtOf };

package/src/host/command/command-id-reuse.pure.ts

@@ -0,0 +1,90 @@
+import { Array as Arr, Effect, Option, Schema, String as Str } from "effect";
+
+import { Caller, actorKind } from "#src/contract/caller/caller.schema";
+import { InvalidRequestError } from "#src/contract/client/invalid-request.errors";
+import { isOutboxCommandId } from "#src/contract/command/outbox-id.pure";
+import { jsonCodec } from "#src/contract/json-codec.pure";
+import { CommandIdReusedError } from "./command-id-reused.errors.js";
+
+interface Reserving {
+  readonly actor: string;
+  readonly commandId: string;
+}
+
+interface Screening extends Reserving {
+  readonly principal: string;
+}
+
+interface Reuse extends Reserving {
+  readonly member: string;
+  readonly principal: string;
+  readonly recordedMember: string;
+  readonly recordedPrincipal: string;
+}
+
+const resultPrefix = "result:";
+
+const resultMemberPrefix = "akter.result.";
+
+const timerPrefix = "timer:";
+
+const reservedPrefixes: readonly string[] = [resultPrefix, timerPrefix];
+
+const resultCommandId = (executionId: string): string => `${resultPrefix}${executionId}`;
+
+const timerCommandId = (timer: string): string => `${timerPrefix}${timer}`;
+
+const resultMember = (job: string): string => `${resultMemberPrefix}${job}`;
+
+const isResultCommandId: (commandId: string) => boolean = Str.startsWith(resultPrefix);
+
+const isTimerCommandId: (commandId: string) => boolean = Str.startsWith(timerPrefix);
+
+const jobOfResult = (member: string): string => Str.slice(resultMemberPrefix.length)(member);
+
+/** The id of the job whose result `commandId` delivers, the inverse of `resultCommandId`. */
+const jobIdOfResult = (commandId: string): string => Str.slice(resultPrefix.length)(commandId);
+
+const fromActor = (principal: string): boolean =>
+  Option.exists(Schema.decodeOption(jsonCodec(Caller))(principal), (caller) => caller.kind === actorKind);
+
+const refuseReserved = ({ actor, commandId, principal }: Screening): Effect.Effect<void, InvalidRequestError> => {
+  if (isOutboxCommandId(commandId) && !fromActor(principal)) {
+    return InvalidRequestError.make({ actor, message: `command id ${commandId} is reserved for messages actors send` });
+  }
+
+  if (!Arr.some(reservedPrefixes, (prefix) => Str.startsWith(prefix)(commandId))) {
+    return Effect.void;
+  }
+
+  return InvalidRequestError.make({
+    actor,
+    message: `command id ${commandId} is reserved for the actor's own job results and timers`,
+  });
+};
+
+const sameCommand = ({ member, principal, recordedMember, recordedPrincipal }: Reuse): boolean =>
+  member === recordedMember && principal === recordedPrincipal;
+
+const refuseReuse = ({ actor, commandId }: Reuse): Effect.Effect<never, InvalidRequestError> =>
+  Effect.fail(
+    InvalidRequestError.make({ actor, message: `command id ${commandId} was already used by another command` }),
+  );
+
+const reuseDefect = (reuse: Reuse): Effect.Effect<never> => Effect.die(CommandIdReusedError.make(reuse));
+
+export {
+  isResultCommandId,
+  isTimerCommandId,
+  jobIdOfResult,
+  jobOfResult,
+  refuseReserved,
+  refuseReuse,
+  resultCommandId,
+  resultMember,
+  reuseDefect,
+  sameCommand,
+  timerCommandId,
+};
+
+export type { Reuse };

package/src/host/command/command-id-reused.errors.ts

@@ -0,0 +1,13 @@
+import { Schema } from "effect";
+
+export class CommandIdReusedError extends Schema.TaggedError<CommandIdReusedError, { readonly brand: unique symbol }>()(
+  "CommandIdReusedError",
+  {
+    actor: Schema.String,
+    commandId: Schema.String,
+    member: Schema.String,
+    principal: Schema.String,
+    recordedMember: Schema.String,
+    recordedPrincipal: Schema.String,
+  },
+) {}