@akterjs/effect 0.0.0-stage → 0.1.0

package/src/contract/file/rpc/file-rpc.contract.ts

@@ -0,0 +1,148 @@
+import { Schema } from "effect";
+import { Rpc } from "effect/rpc";
+import type { RpcSchema } from "effect/rpc";
+
+import { HostedFailure } from "#src/contract/hosted/hosted-failure.schema";
+import { BlobTransferError } from "#src/contract/file/blob-transfer.errors";
+import { FileAccessDeniedError } from "#src/contract/file/access/file-access-denied.errors";
+import { FileNotFoundError } from "#src/contract/file/file-not-found.errors";
+import { FilesUnavailableError } from "#src/contract/file/files-unavailable.errors";
+import { FileTooLargeError } from "#src/contract/file/rpc/file-too-large.errors";
+import { InvalidFileRequestError } from "#src/contract/file/invalid-file-request.errors";
+
+/** The largest chunk a download stream sends, and the largest one an upload may append. */
+const fileChunkBytes = 262_144;
+
+const uploadChunkBytes = 1_048_576;
+
+const FileRpcFailure = Schema.Union([
+  HostedFailure,
+  BlobTransferError,
+  FileAccessDeniedError,
+  FileNotFoundError,
+  FilesUnavailableError,
+  FileTooLargeError,
+  InvalidFileRequestError,
+]);
+
+const WireFileRef = Schema.Struct({
+  bytes: Schema.Int,
+  path: Schema.String,
+  sha256: Schema.String,
+  writtenAt: Schema.Int,
+});
+
+const WireFilePage = Schema.Struct({
+  cursor: Schema.OptionFromNullOr(Schema.String),
+  entries: Schema.Array(WireFileRef),
+});
+
+const WireFileUsagePage = Schema.Struct({ ...WireFilePage.fields, bytes: Schema.BigIntFromString });
+
+const Listing = {
+  cursor: Schema.optionalKey(Schema.String),
+  key: Schema.String,
+  limit: Schema.optionalKey(Schema.Int),
+  prefix: Schema.optionalKey(Schema.String),
+};
+
+const Chunk = Schema.Uint8ArrayFromBase64;
+
+type FileRpcOperation = "download" | "list" | "upload/append" | "upload/close" | "upload/open" | "usage";
+
+type FileTag<Operation extends FileRpcOperation = FileRpcOperation> = `${string}/files/${Operation}`;
+
+const fileTag = <Operation extends FileRpcOperation>({
+  actor,
+  operation,
+}: {
+  readonly actor: string;
+  readonly operation: Operation;
+}): FileTag<Operation> => `${actor}/files/${operation}`;
+
+type FileRpcFailureSchema = typeof FileRpcFailure;
+
+type FileRpcFailureType = FileRpcFailureSchema["Type"];
+
+type FileRpc =
+  | Rpc.Rpc<FileTag<"list">, Schema.Struct<typeof Listing>, typeof WireFilePage, FileRpcFailureSchema>
+  | Rpc.Rpc<FileTag<"usage">, Schema.Struct<typeof Listing>, typeof WireFileUsagePage, FileRpcFailureSchema>
+  | Rpc.Rpc<
+      FileTag<"download">,
+      Schema.Struct<{
+        readonly key: Schema.String;
+        readonly length: Schema.optionalKey<Schema.Int>;
+        readonly offset: Schema.optionalKey<Schema.Int>;
+        readonly path: Schema.String;
+      }>,
+      RpcSchema.Stream<typeof Chunk, FileRpcFailureSchema>
+    >
+  | Rpc.Rpc<
+      FileTag<"upload/open">,
+      Schema.Struct<{ readonly key: Schema.String }>,
+      Schema.Struct<{ readonly upload: Schema.String }>,
+      FileRpcFailureSchema
+    >
+  | Rpc.Rpc<
+      FileTag<"upload/append">,
+      Schema.Struct<{
+        readonly bytes: typeof Chunk;
+        readonly key: Schema.String;
+        readonly offset: Schema.Int;
+        readonly upload: Schema.String;
+      }>,
+      Schema.Struct<{ readonly received: Schema.Int }>,
+      FileRpcFailureSchema
+    >
+  | Rpc.Rpc<
+      FileTag<"upload/close">,
+      Schema.Struct<{ readonly bytes: Schema.Int; readonly key: Schema.String; readonly upload: Schema.String }>,
+      Schema.Struct<{ readonly receipt: Schema.String }>,
+      FileRpcFailureSchema
+    >;
+
+/**
+ * The file streams of one actor, under the tags docs/adr/0016 reserves: `<Actor>/files/<operation>`. Every payload
+ * carries the actor's encoded key as a string, as the actor's other RPCs do on the wire. Effect RPC has no client
+ * streams, so an upload is a short session: `upload/open` returns an id, `upload/append` sends chunks of at most
+ * 1 MiB in order and is idempotent by offset, and `upload/close` checks the length and returns the receipt a command
+ * attaches. A download streams chunks of at most 256 KiB.
+ */
+const fileRpcsOf = (actor: string): readonly FileRpc[] => [
+  Rpc.make(fileTag({ actor, operation: "list" }), { error: FileRpcFailure, payload: Listing, success: WireFilePage }),
+  Rpc.make(fileTag({ actor, operation: "usage" }), {
+    error: FileRpcFailure,
+    payload: Listing,
+    success: WireFileUsagePage,
+  }),
+  Rpc.make(fileTag({ actor, operation: "download" }), {
+    error: FileRpcFailure,
+    payload: {
+      key: Schema.String,
+      length: Schema.optionalKey(Schema.Int),
+      offset: Schema.optionalKey(Schema.Int),
+      path: Schema.String,
+    },
+    stream: true,
+    success: Chunk,
+  }),
+  Rpc.make(fileTag({ actor, operation: "upload/open" }), {
+    error: FileRpcFailure,
+    payload: { key: Schema.String },
+    success: Schema.Struct({ upload: Schema.String }),
+  }),
+  Rpc.make(fileTag({ actor, operation: "upload/append" }), {
+    error: FileRpcFailure,
+    payload: { bytes: Chunk, key: Schema.String, offset: Schema.Int, upload: Schema.String },
+    success: Schema.Struct({ received: Schema.Int }),
+  }),
+  Rpc.make(fileTag({ actor, operation: "upload/close" }), {
+    error: FileRpcFailure,
+    payload: { bytes: Schema.Int, key: Schema.String, upload: Schema.String },
+    success: Schema.Struct({ receipt: Schema.String }),
+  }),
+];
+
+export { fileChunkBytes, fileRpcsOf, fileTag, uploadChunkBytes };
+
+export type { FileRpc, FileRpcFailureType, FileRpcOperation, FileTag };

package/src/contract/file/rpc/file-too-large.errors.ts

@@ -0,0 +1,10 @@
+import { Schema } from "effect";
+
+/**
+ * An upload would pass the largest file the server accepts, `maximumBytes`, so the chunk was refused and the upload
+ * dropped. Nothing was attached. Split the content into smaller files.
+ */
+export class FileTooLargeError extends Schema.TaggedError<FileTooLargeError, { readonly brand: unique symbol }>()(
+  "FileTooLargeError",
+  { actor: Schema.String, maximumBytes: Schema.Int },
+) {}

package/src/contract/file/rpc/rpc-file-clients.layer.ts

@@ -0,0 +1,184 @@
+import {
+  Array as Arr,
+  Duration,
+  Effect,
+  Layer,
+  Match,
+  Option,
+  Predicate,
+  Record as Rec,
+  Schedule,
+  Stream,
+} from "effect";
+import type { Context, Scope } from "effect";
+import { RpcClient, RpcGroup } from "effect/rpc";
+import type { RpcClientError } from "effect/rpc";
+
+import { Authentication } from "#src/contract/caller/authentication.api";
+import type { UnauthenticatedError } from "#src/contract/caller/unauthenticated.errors";
+import { ActorUnavailableError } from "#src/contract/client/actor-unavailable.errors";
+import { ActorFileClients } from "#src/contract/file/file-client.adapter";
+import type {
+  FileAddress,
+  FileClient,
+  FileClientFailure,
+  FileListing,
+  FileRange,
+} from "#src/contract/file/file-client.contract";
+import { fileRpcsOf, fileTag, uploadChunkBytes } from "./file-rpc.contract.js";
+import type { FileRpcFailureType, FileRpcOperation } from "./file-rpc.contract.js";
+
+type WireFailure = FileRpcFailureType | RpcClientError.RpcClientError | UnauthenticatedError;
+
+/** Every field a file RPC's payload may carry besides the key; each operation sends its own. */
+interface Payload {
+  readonly bytes?: Uint8Array | number;
+  readonly cursor?: string;
+  readonly key?: string;
+  readonly length?: number;
+  readonly limit?: number;
+  readonly offset?: number;
+  readonly path?: string;
+  readonly prefix?: string;
+  readonly upload?: string;
+}
+
+interface Wire {
+  readonly send: <Value>(tag: string, payload: Payload) => Effect.Effect<Value, WireFailure>;
+  readonly watch: (tag: string, payload: Payload) => Stream.Stream<Uint8Array, WireFailure>;
+}
+
+interface Bound {
+  readonly address: FileAddress;
+  readonly protocol: Context.Context<RpcClient.Protocol>;
+}
+
+const retryMillis = 50;
+
+const retryLimit = 5;
+
+const firstByte = 0;
+
+const one = 1;
+
+function wireOf(actor: string): Effect.Effect<Wire, never, RpcClient.Protocol | Scope.Scope>;
+function wireOf(actor: string): Effect.Effect<unknown, never, RpcClient.Protocol | Scope.Scope> {
+  const group = RpcGroup.make(...fileRpcsOf(actor)).middleware(Authentication);
+
+  return Effect.map(RpcClient.make(group, { flatten: true }), (client) => ({ send: client, watch: client }));
+}
+
+const unavailable = (actor: string, message: string): FileClientFailure =>
+  ActorUnavailableError.make({ actor, message });
+
+/**
+ * What a network file client answers for a failure: a lost reply, after its retries, means the actor is unavailable,
+ * and the actor RPC failures a file request can't cause fold into the same retryable answer.
+ */
+const clientFailure =
+  (actor: string) =>
+  (failure: WireFailure): FileClientFailure =>
+    Match.value(failure).pipe(
+      Match.tags({
+        ActorNotCreatedError: () => unavailable(actor, "the actor's files are unavailable"),
+        CommandIdExpiredError: () => unavailable(actor, "the actor's files are unavailable"),
+        HandlerFailedError: () => unavailable(actor, "the actor's files are unavailable"),
+        RpcClientError: () => unavailable(actor, "the server didn't answer. Retry shortly."),
+      }),
+      Match.orElse((other): FileClientFailure => other),
+    );
+
+const tagOf = (address: FileAddress, operation: FileRpcOperation): string =>
+  fileTag({ actor: address.actor, operation });
+
+/** One unary file RPC. A lost reply is retried, which every file RPC allows: reads, and appends by their offset. */
+const call = <Value>(
+  { address, protocol }: Bound,
+  operation: FileRpcOperation,
+  payload: Payload,
+): Effect.Effect<Value, FileClientFailure> => {
+  const sent = Effect.flatMap(wireOf(address.actor), (wire) =>
+    wire.send<Value>(tagOf(address, operation), { ...payload, key: address.key }),
+  );
+
+  const retried = Effect.retry(Effect.scoped(sent), {
+    schedule: Schedule.exponential(Duration.millis(retryMillis)),
+    times: retryLimit,
+    while: (failure) => Predicate.isTagged(failure, "RpcClientError"),
+  });
+
+  return Effect.provideContext(Effect.mapError(retried, clientFailure(address.actor)), protocol);
+};
+
+const listingOf = ({ cursor, limit, prefix }: FileListing): FileListing => ({
+  ...Rec.getSomes({ cursor: Option.fromNullishOr(cursor), prefix: Option.fromNullishOr(prefix) }),
+  ...Rec.getSomes({ limit: Option.fromNullishOr(limit) }),
+});
+
+const slices = (bytes: Uint8Array): readonly Uint8Array[] =>
+  Arr.makeBy(Math.max(one, Math.ceil(bytes.length / uploadChunkBytes)), (index) =>
+    bytes.subarray(index * uploadChunkBytes, (index + one) * uploadChunkBytes),
+  );
+
+const appendAll = <Failure, Services>(
+  bound: Bound,
+  upload: string,
+  source: Stream.Stream<Uint8Array, Failure, Services>,
+): Effect.Effect<number, Failure | FileClientFailure, Services> =>
+  source.pipe(
+    Stream.flatMap((chunk) => Stream.fromIterable(slices(chunk))),
+    Stream.filter((chunk) => chunk.length > firstByte),
+    Stream.runFoldEffect(
+      () => firstByte,
+      (offset, bytes) => Effect.as(call(bound, "upload/append", { bytes, offset, upload }), offset + bytes.length),
+    ),
+  );
+
+/** An upload is a session: `upload/open`, the source's bytes as ordered `upload/append` chunks, then `upload/close`. */
+const uploadWith =
+  (bound: Bound): FileClient["upload"] =>
+  <Failure, Services>(
+    source: Stream.Stream<Uint8Array, Failure, Services>,
+  ): Effect.Effect<string, Failure | FileClientFailure, Services> =>
+    Effect.gen(function* upload() {
+      const opened = yield* call<{ readonly upload: string }>(bound, "upload/open", {});
+      const bytes = yield* appendAll(bound, opened.upload, source);
+      const closed = yield* call<{ readonly receipt: string }>(bound, "upload/close", { bytes, upload: opened.upload });
+
+      return closed.receipt;
+    });
+
+const downloadWith =
+  ({ address, protocol }: Bound): FileClient["download"] =>
+  (path: string, range?: FileRange): Stream.Stream<Uint8Array, FileClientFailure> => {
+    const bytes = Stream.unwrap(
+      Effect.map(wireOf(address.actor), (wire) =>
+        wire.watch(tagOf(address, "download"), { key: address.key, path, ...range }),
+      ),
+    );
+
+    return Stream.provideContext(Stream.mapError(bytes, clientFailure(address.actor)), protocol);
+  };
+
+const clientWith = (bound: Bound): FileClient => ({
+  download: downloadWith(bound),
+  fileUsage: (listing = {}) => call(bound, "usage", listingOf(listing)),
+  list: (listing = {}) => call(bound, "list", listingOf(listing)),
+  upload: uploadWith(bound),
+});
+
+/**
+ * File clients that reach an actor's files over its `<Actor>/files/<operation>` RPCs, for `@akterjs/client` and the
+ * in-process client. They give the same `FileClient` an actor's own host gives, so customer code is the same either
+ * way.
+ */
+const rpcFileClients: Layer.Layer<ActorFileClients, never, RpcClient.Protocol> = Layer.effect(
+  ActorFileClients,
+  Effect.map(Effect.context<RpcClient.Protocol>(), (protocol) => ({
+    connect: (address: FileAddress): FileClient => clientWith({ address, protocol }),
+  })),
+);
+
+export { rpcFileClients };
+
+export type { ActorFileClients } from "#src/contract/file/file-client.adapter";

package/src/contract/fork/fork-rpc.contract.ts

@@ -0,0 +1,44 @@
+import { Schema } from "effect";
+import { Rpc } from "effect/rpc";
+
+import { ActorAlreadyExistsError } from "#src/contract/actor/actor-already-exists.errors";
+import type { KeySchema } from "#src/contract/actor/actor.contract";
+import { CommandId } from "#src/contract/command/command-id.schema";
+import { HostedFailure } from "#src/contract/hosted/hosted-failure.schema";
+
+/** What a fork answers: the parent's commit version at the cut the child was copied from. */
+const Forked = Schema.Struct({ version: Schema.Int });
+
+type Forked = typeof Forked.Type;
+
+const ForkFailure = Schema.Union([HostedFailure, ActorAlreadyExistsError]);
+
+type ForkFailure = typeof ForkFailure.Type;
+
+type ForkTag = `${string}/fork`;
+
+type ForkRpc = Rpc.Rpc<
+  ForkTag,
+  Schema.Struct<{ readonly commandId: typeof CommandId; readonly into: KeySchema; readonly key: KeySchema }>,
+  typeof Forked,
+  typeof ForkFailure
+>;
+
+const forkTag = (actor: string): ForkTag => `${actor}/fork`;
+
+/**
+ * Forks one actor under the tag docs/adr/0016 reserves: `<Actor>/fork` copies the actor at `key`, at one cut between
+ * two of its commands, into a new actor of the same kind at `into` (ADR 0017, ADR 0018). The copy starts quiet, with
+ * its own key, and nothing reads it before it is whole. `commandId` names the fork, so a retry with it answers the
+ * same fork instead of making a second copy.
+ */
+const forkRpcOf = ({ actor, key }: { readonly actor: string; readonly key: KeySchema }): ForkRpc =>
+  Rpc.make(forkTag(actor), {
+    error: ForkFailure,
+    payload: { commandId: CommandId, into: key, key },
+    success: Forked,
+  });
+
+export { Forked, ForkFailure, forkRpcOf, forkTag };
+
+export type { ForkRpc, ForkTag };

package/src/contract/history/actor-journal.service.ts

@@ -0,0 +1,195 @@
+import { Array as Arr, Clock, Context, Duration, Effect, Option, Schema, Stream } from "effect";
+
+import type { ActorUnavailableError } from "#src/contract/client/actor-unavailable.errors";
+import type { ActorErasedError } from "#src/contract/actor/actor-erased.errors";
+import type { ActorDefinition, Decoded } from "#src/contract/actor/actor.contract";
+import { decodeEntries } from "./history-entry.pure.js";
+import type { ErasedEntry, HistoryEntry } from "./history-entry.pure.js";
+import { InvalidRequestError } from "#src/contract/client/invalid-request.errors";
+
+interface JournalEntry {
+  readonly at: number;
+  readonly command: string;
+  readonly commandId: string;
+  readonly exit: string;
+  readonly payload: string;
+  readonly principal: string;
+  readonly seq: number;
+}
+
+interface JournalScope {
+  readonly actor: string;
+  readonly key: string;
+  readonly since: number;
+}
+
+interface JournalRead extends JournalScope {
+  readonly after: number;
+  readonly limit: number;
+}
+
+interface JournalWindow {
+  readonly coveredSince: number;
+  readonly entries: readonly JournalEntry[];
+}
+
+type JournalFailure = ActorErasedError | ActorUnavailableError | InvalidRequestError;
+
+interface HistorySource {
+  readonly definition: ActorDefinition;
+  readonly name: string;
+}
+
+interface HistoryWindow<Entry> {
+  readonly coveredSince: number;
+  readonly entries: readonly Entry[];
+}
+
+interface HistoryOptions {
+  readonly since?: Duration.Input;
+}
+
+type HistoryOf<Definition extends ActorDefinition> = (
+  key: Definition["key"]["Type"],
+  options?: HistoryOptions,
+) => Effect.Effect<HistoryWindow<HistoryEntry<Definition>>, JournalFailure, ActorJournal>;
+
+type HistoryStreamOf<Definition extends ActorDefinition> = (
+  key: Definition["key"]["Type"],
+  options?: HistoryOptions,
+) => Stream.Stream<HistoryWindow<HistoryEntry<Definition>>, JournalFailure, ActorJournal>;
+
+type CoveredSinceOf<Definition extends ActorDefinition> = (
+  key: Definition["key"]["Type"],
+  options?: HistoryOptions,
+) => Effect.Effect<number, JournalFailure, ActorJournal>;
+
+type ErasedCoveredSince = (
+  key: Decoded,
+  options?: HistoryOptions,
+) => Effect.Effect<number, JournalFailure, ActorJournal>;
+
+type ErasedHistory = (
+  key: Decoded,
+  options?: HistoryOptions,
+) => Effect.Effect<HistoryWindow<ErasedEntry>, JournalFailure, ActorJournal>;
+
+type ErasedHistoryStream = (
+  key: Decoded,
+  options?: HistoryOptions,
+) => Stream.Stream<HistoryWindow<ErasedEntry>, JournalFailure, ActorJournal>;
+
+interface ActorHistory<Definition extends ActorDefinition> {
+  readonly history: HistoryOf<Definition>;
+  readonly historyCoveredSince: CoveredSinceOf<Definition>;
+  readonly historyStream: HistoryStreamOf<Definition>;
+}
+
+const everything = 0;
+
+const beforeFirst = 0;
+
+const pageSize = 500;
+
+const sinceOf = (now: number, options: HistoryOptions): number =>
+  Option.match(Option.fromNullishOr(options.since), {
+    onNone: () => everything,
+    onSome: (since) => now - Duration.toMillis(since),
+  });
+
+const nextAfter = (entries: readonly JournalEntry[]): Option.Option<number> =>
+  Option.map(
+    Option.filter(Arr.last(entries), () => entries.length === pageSize),
+    (entry) => entry.seq,
+  );
+
+const scopeOf = Effect.fnUntraced(function* scopeOf(source: HistorySource, key: Decoded, options: HistoryOptions) {
+  const encoded = yield* Schema.encodeUnknownEffect(source.definition.key)(key).pipe(
+    Effect.mapError((issue) => InvalidRequestError.make({ actor: source.name, message: issue.message })),
+  );
+
+  const now = yield* Clock.currentTimeMillis;
+
+  return { actor: source.name, key: encoded, since: sinceOf(now, options) };
+});
+
+const joined = (pages: Iterable<HistoryWindow<ErasedEntry>>): HistoryWindow<ErasedEntry> => {
+  const all = Arr.fromIterable(pages);
+
+  return {
+    coveredSince: Option.match(Arr.last(all), { onNone: () => everything, onSome: (page) => page.coveredSince }),
+    entries: Arr.flatMap(all, (page) => page.entries),
+  };
+};
+
+export class ActorJournal extends Context.Service<
+  ActorJournal,
+  {
+    readonly coveredSince: (request: JournalScope) => Effect.Effect<number, JournalFailure>;
+    readonly read: (request: JournalRead) => Effect.Effect<JournalWindow, JournalFailure>;
+  }
+>()("@akterjs/effect/contract/history/actor-journal.service/ActorJournal") {
+  public static coveredSince<Definition extends ActorDefinition>(source: HistorySource): CoveredSinceOf<Definition>;
+  public static coveredSince(source: HistorySource): ErasedCoveredSince {
+    return Effect.fnUntraced(function* coveredSince(key: Decoded, options: HistoryOptions = {}) {
+      const scope = yield* scopeOf(source, key, options);
+      const journal = yield* ActorJournal;
+
+      return yield* journal.coveredSince(scope);
+    });
+  }
+
+  public static history<Definition extends ActorDefinition>(source: HistorySource): HistoryOf<Definition>;
+  public static history(source: HistorySource): ErasedHistory {
+    const stream = ActorJournal.historyStream(source);
+
+    return (key, options) => Effect.map(Stream.runCollect(stream(key, options)), joined);
+  }
+
+  public static historyStream<Definition extends ActorDefinition>(source: HistorySource): HistoryStreamOf<Definition>;
+  public static historyStream(source: HistorySource): ErasedHistoryStream {
+    const decode = decodeEntries(source);
+
+    const pagesOf = Effect.fnUntraced(function* pagesOf(key: Decoded, options: HistoryOptions) {
+      const scope = yield* scopeOf(source, key, options);
+      const journal = yield* ActorJournal;
+      const window = { ...scope, limit: pageSize };
+
+      const page = (
+        after: number,
+      ): Effect.Effect<readonly [readonly HistoryWindow<ErasedEntry>[], Option.Option<number>], JournalFailure> =>
+        Effect.flatMap(journal.read({ ...window, after }), (read) =>
+          Effect.map(
+            decode(read.entries),
+            (entries) => [[{ coveredSince: read.coveredSince, entries }], nextAfter(read.entries)] as const,
+          ),
+        );
+
+      return Stream.paginate(beforeFirst, page);
+    });
+
+    return (key, options = {}) => Stream.unwrap(pagesOf(key, options));
+  }
+}
+
+export type {
+  CreatedEntry,
+  HistoryEntry,
+  JobResultEntry,
+  RecordedCommand,
+  UnreadableCommand,
+} from "./history-entry.pure.js";
+
+export type {
+  ActorHistory,
+  CoveredSinceOf,
+  HistoryOf,
+  HistoryOptions,
+  HistoryStreamOf,
+  HistoryWindow,
+  JournalEntry,
+  JournalFailure,
+  JournalRead,
+  JournalScope,
+  JournalWindow,
+};