@akterjs/effect 0.0.0-stage → 0.1.1

package/src/contract/description/published-contract.pure.ts

@@ -0,0 +1,187 @@
+import { Array as Arr, Duration, Effect, Option, Predicate, Record as Rec, Schema, String as Str, pipe } from "effect";
+
+interface DeclaredMember {
+  readonly callers: Option.Option<readonly string[]>;
+  readonly error: Schema.Top;
+  readonly payload: Schema.Top;
+  readonly success: Schema.Top;
+}
+
+interface DeclaredQuery extends DeclaredMember {
+  /** Absent from an actor built before queries could declare it, which reads as fresh. */
+  readonly staleFor?: Option.Option<Duration.Duration>;
+}
+
+interface DeclaredActor {
+  readonly callers: Readonly<Record<string, Schema.Top>>;
+  readonly commands: Readonly<Record<string, DeclaredMember>>;
+  readonly create: Schema.Top;
+  readonly fileAccess: Option.Option<DeclaredMember>;
+  readonly key: Schema.Top;
+  readonly name: string;
+  readonly queries: Readonly<Record<string, DeclaredQuery>>;
+}
+
+interface MemberContract extends Schema.JsonObject {
+  readonly callers: readonly string[] | null;
+  readonly error: Schema.Json;
+  readonly payload: Schema.Json;
+  readonly success: Schema.Json;
+}
+
+interface QueryContract extends MemberContract {
+  /** How old an answer may be, in milliseconds, when the query declares `staleFor`; absent means always fresh. */
+  readonly staleForMs?: number;
+}
+
+interface ActorContract extends Schema.JsonObject {
+  readonly callers: Readonly<Record<string, Schema.Json>>;
+  readonly commands: Readonly<Record<string, MemberContract>>;
+  readonly create: Schema.Json;
+  /** Who may make file calls and what the actor's rule refuses with (`FileAccessDeniedError`); null without files. */
+  readonly files: MemberContract | null;
+  readonly key: Schema.Json;
+  readonly queries: Readonly<Record<string, QueryContract>>;
+}
+
+type PublishedContracts = Readonly<Record<string, ActorContract>>;
+
+type JsonNode = Rec.ReadonlyRecord<string, Schema.Json>;
+
+const DEFINITION_PREFIX = "#/$defs/";
+
+const decodeJson = Schema.decodeUnknownEffect(Schema.Json);
+
+const decodeDefinitions = Schema.decodeUnknownEffect(Schema.JsonObject);
+
+const encodeBaseline = Schema.encodeEffect(Schema.fromJsonString(Schema.Json, { space: 2 }));
+
+const isJsonObject = Schema.is(Schema.JsonObject);
+
+const isJsonArray = Schema.is(Schema.Array(Schema.Json));
+
+interface References {
+  readonly definitions: JsonNode;
+  readonly node: Schema.Json;
+  readonly prefix: string;
+}
+
+interface Inlining {
+  readonly definitions: JsonNode;
+  readonly expanding: readonly string[];
+  readonly prefix: string;
+}
+
+type Inline = (node: Schema.Json, inlining: Inlining) => Schema.Json;
+
+const referenceName = (node: JsonNode, prefix: string): Option.Option<string> =>
+  pipe(
+    Rec.get(node, "$ref"),
+    Option.filter(Predicate.isString),
+    Option.filter(Str.startsWith(prefix)),
+    Option.map(Str.slice(prefix.length)),
+  );
+
+const inlinedObject = (node: JsonNode, inlining: Inlining, inline: Inline): Schema.Json => {
+  const name = Option.filter(
+    referenceName(node, inlining.prefix),
+    (candidate) => !Arr.contains(inlining.expanding, candidate),
+  );
+
+  const definition = Option.flatMap(name, (found) => Rec.get(inlining.definitions, found));
+
+  if (Option.isSome(name) && Option.isSome(definition)) {
+    return inline(definition.value, { ...inlining, expanding: [...inlining.expanding, name.value] });
+  }
+
+  return Rec.map(node, (value) => inline(value, inlining));
+};
+
+const inlinedNode = (node: Schema.Json, inlining: Inlining): Schema.Json => {
+  if (isJsonArray(node)) {
+    return Arr.map(node, (item) => inlinedNode(item, inlining));
+  }
+
+  if (!isJsonObject(node)) {
+    return node;
+  }
+
+  return inlinedObject(node, inlining, inlinedNode);
+};
+
+const inlined = ({ definitions, node, prefix }: References): Schema.Json =>
+  inlinedNode(node, { definitions, expanding: [], prefix });
+
+const jsonSchemaOf = Effect.fn("jsonSchemaOf")(function* jsonSchemaOf(schema: Schema.Top) {
+  const document = Schema.toJsonSchemaDocument(schema);
+  const root = yield* decodeJson(document.schema);
+  const definitions = yield* decodeDefinitions(document.definitions);
+
+  return inlined({ definitions, node: root, prefix: DEFINITION_PREFIX });
+});
+
+const memberContract = (member: DeclaredMember): Effect.Effect<MemberContract, Schema.SchemaError> =>
+  Effect.all({
+    callers: Effect.succeed(Option.getOrNull(member.callers)),
+    error: jsonSchemaOf(member.error),
+    payload: jsonSchemaOf(member.payload),
+    success: jsonSchemaOf(member.success),
+  });
+
+const queryContract = (query: DeclaredQuery): Effect.Effect<QueryContract, Schema.SchemaError> =>
+  Effect.map(memberContract(query), (member) =>
+    Option.match(Option.flatten(Option.fromUndefinedOr(query.staleFor)), {
+      onNone: (): QueryContract => member,
+      onSome: (age): QueryContract => ({ ...member, staleForMs: Duration.toMillis(age) }),
+    }),
+  );
+
+/** The actor's file declaration as published, or null when it declares no file calls. */
+const filesContract = (
+  fileAccess: DeclaredActor["fileAccess"],
+): Effect.Effect<MemberContract | null, Schema.SchemaError> =>
+  Effect.map(Effect.transposeOption(Option.map(fileAccess, memberContract)), Option.getOrNull);
+
+const actorContract = (actor: DeclaredActor): Effect.Effect<ActorContract, Schema.SchemaError> =>
+  Effect.all({
+    callers: Effect.all(Rec.map(actor.callers, jsonSchemaOf)),
+    commands: Effect.all(Rec.map(actor.commands, memberContract)),
+    create: jsonSchemaOf(actor.create),
+    files: filesContract(actor.fileAccess),
+    key: jsonSchemaOf(actor.key),
+    queries: Effect.all(Rec.map(actor.queries, queryContract)),
+  });
+
+const namedContract = (actor: DeclaredActor): Effect.Effect<readonly [string, ActorContract], Schema.SchemaError> =>
+  Effect.map(actorContract(actor), (contract): readonly [string, ActorContract] => [actor.name, contract]);
+
+const recordedContracts = (actors: readonly DeclaredActor[]): Effect.Effect<PublishedContracts, Schema.SchemaError> =>
+  Effect.map(Effect.forEach(actors, namedContract), Rec.fromEntries);
+
+const sortedObject = (node: JsonNode, sort: (value: Schema.Json) => Schema.Json): Schema.Json => {
+  const entries = Arr.sortWith(Rec.toEntries(node), ([key]) => key, Str.Order);
+
+  return Rec.fromEntries(Arr.map(entries, ([key, value]): readonly [string, Schema.Json] => [key, sort(value)]));
+};
+
+const sortedKeys = (node: Schema.Json): Schema.Json => {
+  if (isJsonArray(node)) {
+    return Arr.map(node, sortedKeys);
+  }
+
+  if (!isJsonObject(node)) {
+    return node;
+  }
+
+  return sortedObject(node, sortedKeys);
+};
+
+const renderContracts = (contracts: PublishedContracts): Effect.Effect<string, Schema.SchemaError> =>
+  Effect.map(encodeBaseline(sortedKeys(contracts)), (text) => `${text}\n`);
+
+const renderContract = (actor: DeclaredActor): Effect.Effect<string, Schema.SchemaError> =>
+  Effect.flatMap(actorContract(actor), (contract) =>
+    Effect.map(encodeBaseline(sortedKeys(contract)), (text) => `${text}\n`),
+  );
+
+export { inlined, recordedContracts, renderContract, renderContracts };

package/src/contract/file/access/file-access-denied.errors.ts

@@ -0,0 +1,11 @@
+import { Schema } from "effect";
+
+/** The actor's `files.authorize` rule refused this caller's file call. */
+export class FileAccessDeniedError extends Schema.TaggedError<
+  FileAccessDeniedError,
+  { readonly brand: unique symbol }
+>()("FileAccessDeniedError", {
+  access: Schema.Literals(["read", "write"]),
+  message: Schema.String,
+  path: Schema.String,
+}) {}

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

@@ -0,0 +1,56 @@
+import { Option, Schema } from "effect";
+
+import type { Query } from "#src/contract/command/command.contract";
+import { FileAccessDeniedError } from "./file-access-denied.errors.js";
+
+/**
+ * What a file call asks the actor's `files.authorize` rule: `read` for a download, a listing or the usage (`path` is
+ * the file, or the listing's prefix), `write` for an upload (`path` is empty: the command that attaches the upload
+ * names its path, and is gated as a command).
+ */
+const FileAccessRequest = Schema.Struct({ access: Schema.Literals(["read", "write"]), path: Schema.String });
+
+/**
+ * An actor's file declaration: which caller kinds may make file calls at all. Each call then runs the actor's
+ * `files.authorize` rule as a query under the reserved member `akter.files`, so the engine admits the kind, reads the
+ * state and the verified principal, and refuses the call unless the rule succeeds.
+ */
+type FileAccess<Kinds extends string = string> = Query<
+  typeof FileAccessRequest,
+  typeof Schema.Void,
+  typeof FileAccessDeniedError,
+  Kinds
+>;
+
+/** How a file call's question travels to the host as the `akter.files` query's payload. */
+const fileAccessPayload = Schema.fromJsonString(Schema.toCodecJson(FileAccessRequest));
+
+/** The rule's outcome: allowed, refused with `FileAccessDeniedError`, or a defect. */
+const FileAccessExit = Schema.Exit(Schema.Void, FileAccessDeniedError, Schema.Defect());
+
+/** How a host reads the rule's reply: the `akter.files` query's exit, as `HostedActor.runQuery` encodes it. */
+const fileAccessReply = Schema.fromJsonString(Schema.toCodecJson(FileAccessExit));
+
+/** The reserved query member a host runs an actor's `files.authorize` rule under. */
+const fileAccessMember = "akter.files";
+
+/**
+ * Declares which caller kinds may make file calls to an actor (`Akter.make`'s `files` option); without it, the actor has
+ * no file calls.
+ */
+const fileAccess = <const Kinds extends string>(options: {
+  readonly callers: readonly [Kinds, ...Kinds[]];
+}): FileAccess<Kinds> => ({
+  callers: Option.some(options.callers),
+  error: FileAccessDeniedError,
+  payload: FileAccessRequest,
+  // A file call is always decided fresh.
+  staleFor: Option.none(),
+  success: Schema.Void,
+});
+
+export { FileAccessRequest, fileAccess, fileAccessMember, fileAccessPayload, fileAccessReply };
+
+export type { FileAccess };
+
+export type { FileAccessDeniedError } from "./file-access-denied.errors.js";

package/src/contract/file/actor-files.contract.ts

@@ -0,0 +1,78 @@
+import type { Effect, Option, Stream } from "effect";
+import type { SqlError } from "effect/sql";
+
+import type { ActorState } from "#src/contract/state/actor-state.service";
+import type { BlobTransferError } from "./blob-transfer.errors.js";
+import type { FileNotFoundError } from "./file-not-found.errors.js";
+import type { FilesUnavailableError } from "./files-unavailable.errors.js";
+import type { InvalidFileRequestError } from "./invalid-file-request.errors.js";
+
+interface FileRef {
+  readonly bytes: number;
+  readonly path: string;
+  readonly sha256: string;
+  readonly writtenAt: number;
+}
+
+interface FileListing {
+  readonly cursor?: string;
+  readonly limit?: number;
+  readonly prefix?: string;
+}
+
+interface FileRange {
+  readonly length: number;
+  readonly offset: number;
+}
+
+interface FilePage {
+  readonly cursor: Option.Option<string>;
+  readonly entries: readonly FileRef[];
+}
+
+interface FileUsagePage extends FilePage {
+  readonly bytes: bigint;
+}
+
+interface FileAttaching {
+  readonly now: number;
+  readonly path: string;
+  readonly receipt: string;
+}
+
+type FileFailure =
+  | BlobTransferError
+  | FileNotFoundError
+  | FilesUnavailableError
+  | InvalidFileRequestError
+  | SqlError.SqlError;
+
+interface FileReader {
+  readonly list: (listing?: FileListing) => Effect.Effect<FilePage, FileFailure>;
+  readonly fileUsage: (listing?: FileListing) => Effect.Effect<FileUsagePage, FileFailure>;
+  readonly read: (path: string, range?: FileRange) => Stream.Stream<Uint8Array, FileFailure>;
+}
+
+interface FileStorage extends FileReader {
+  readonly available: Effect.Effect<void, FilesUnavailableError>;
+  readonly attach: (attaching: FileAttaching) => Effect.Effect<FileRef, FileFailure>;
+  readonly remove: (path: string) => Effect.Effect<void, FileFailure>;
+}
+
+interface ActorFiles extends FileReader {
+  readonly attach: (path: string, receipt: string) => Effect.Effect<FileRef, FileFailure, ActorState>;
+  readonly remove: (path: string) => Effect.Effect<void, FileFailure, ActorState>;
+}
+
+export type {
+  ActorFiles,
+  FileAttaching,
+  FileFailure,
+  FileListing,
+  FilePage,
+  FileReader,
+  FileRange,
+  FileRef,
+  FileStorage,
+  FileUsagePage,
+};

package/src/contract/file/blob-transfer.errors.ts

@@ -0,0 +1,6 @@
+import { Schema } from "effect";
+
+export class BlobTransferError extends Schema.TaggedError<BlobTransferError, { readonly brand: unique symbol }>()(
+  "BlobTransferError",
+  { blob: Schema.String, message: Schema.String },
+) {}

package/src/contract/file/file-client-failure.contract.ts

@@ -0,0 +1,43 @@
+import type { SqlError } from "effect/sql";
+
+import type {
+  ActorErasedError,
+  ActorUnavailableError,
+  BillingUnavailableError,
+  CallerNotAllowedError,
+  InvalidRequestError,
+  SpendCapReachedError,
+  StorageLimitError,
+  UnauthenticatedError,
+} from "#src/contract/client/client-failure.contract";
+import type { BlobTransferError } from "./blob-transfer.errors.js";
+import type { FileAccessDeniedError } from "./access/file-access-denied.errors.js";
+import type { FileNotFoundError } from "./file-not-found.errors.js";
+import type { FilesUnavailableError } from "./files-unavailable.errors.js";
+import type { FileTooLargeError } from "./rpc/file-too-large.errors.js";
+import type { InvalidFileRequestError } from "./invalid-file-request.errors.js";
+
+/**
+ * What a file client can fail with. A network upload past the server's largest file fails with `FileTooLargeError`.
+ * A network client adds the caller's refusals, `CallerNotAllowedError`, `FileAccessDeniedError` (the actor's
+ * `files.authorize` rule) and `UnauthenticatedError`, and Akter Cloud's refusals, `SpendCapReachedError`, `BillingUnavailableError` and `StorageLimitError`; a
+ * host's own client never refuses its caller.
+ */
+type FileClientFailure =
+  | ActorErasedError
+  | ActorUnavailableError
+  | BillingUnavailableError
+  | BlobTransferError
+  | CallerNotAllowedError
+  | FileAccessDeniedError
+  | FileNotFoundError
+  | FilesUnavailableError
+  | FileTooLargeError
+  | InvalidFileRequestError
+  | InvalidRequestError
+  | SpendCapReachedError
+  | StorageLimitError
+  | SqlError.SqlError
+  | UnauthenticatedError;
+
+export type { FileClientFailure };

package/src/contract/file/file-client.adapter.ts

@@ -0,0 +1,45 @@
+import { Context, Effect, Option, Schema } from "effect";
+
+import type { ActorDefinition, Decoded } from "#src/contract/actor/actor.contract";
+import { InvalidRequestError } from "#src/contract/client/invalid-request.errors";
+import type { FileAddress, FileClient } from "./file-client.contract.js";
+import { FilesUnavailableError } from "./files-unavailable.errors.js";
+
+interface FileClientSource {
+  readonly definition: ActorDefinition;
+  readonly name: string;
+}
+
+type FileClientOf<Definition extends ActorDefinition> = (
+  key: Definition["key"]["Type"],
+) => Effect.Effect<FileClient, FilesUnavailableError | InvalidRequestError>;
+
+export class ActorFileClients extends Context.Service<
+  ActorFileClients,
+  {
+    readonly connect: (address: FileAddress) => FileClient;
+  }
+>()("@akterjs/effect/contract/file/file-client.adapter/ActorFileClients") {
+  public static clientOf<Definition extends ActorDefinition>(source: FileClientSource): FileClientOf<Definition>;
+  public static clientOf({
+    definition,
+    name,
+  }: FileClientSource): (key: Decoded) => Effect.Effect<FileClient, FilesUnavailableError | InvalidRequestError> {
+    return (key) =>
+      Effect.gen(function* connectFiles() {
+        const clients = yield* Effect.serviceOption(ActorFileClients);
+
+        if (Option.isNone(clients)) {
+          return yield* FilesUnavailableError.make({ message: "files aren't available on this host" });
+        }
+
+        const encoded = yield* Schema.encodeEffect(definition.key)(key).pipe(
+          Effect.mapError(() => InvalidRequestError.make({ actor: name, message: "the actor key is invalid" })),
+        );
+
+        return clients.value.connect({ actor: name, key: encoded });
+      });
+  }
+}
+
+export type { FileClientOf };

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

@@ -0,0 +1,24 @@
+import type { Effect, Stream } from "effect";
+
+import type { FileListing, FilePage, FileRange, FileUsagePage } from "./actor-files.contract.js";
+import type { FileClientFailure } from "./file-client-failure.contract.js";
+
+interface FileAddress {
+  readonly actor: string;
+  readonly key: string;
+}
+
+interface FileClient {
+  readonly download: (path: string, range?: FileRange) => Stream.Stream<Uint8Array, FileClientFailure>;
+  readonly fileUsage: (listing?: FileListing) => Effect.Effect<FileUsagePage, FileClientFailure>;
+  readonly list: (listing?: FileListing) => Effect.Effect<FilePage, FileClientFailure>;
+  readonly upload: <Failure, Services>(
+    source: Stream.Stream<Uint8Array, Failure, Services>,
+  ) => Effect.Effect<string, Failure | FileClientFailure, Services>;
+}
+
+export type { FileAddress, FileClient };
+
+export type { FileClientFailure } from "./file-client-failure.contract.js";
+
+export type { FileListing, FilePage, FileRange, FileUsagePage } from "./actor-files.contract.js";

package/src/contract/file/file-listing.pure.ts

@@ -0,0 +1,30 @@
+import { Effect, String as Str } from "effect";
+
+import type { FileListing } from "./actor-files.contract.js";
+import { InvalidFileRequestError } from "./invalid-file-request.errors.js";
+
+type CompleteListing = Required<FileListing>;
+
+const defaultLimit = 100;
+
+const largestLimit = 1000;
+
+const smallestLimit = 1;
+
+const fileListingOf = ({
+  cursor = "",
+  limit = defaultLimit,
+  prefix = "",
+}: FileListing): Effect.Effect<CompleteListing, InvalidFileRequestError> => {
+  if (!Number.isSafeInteger(limit) || limit < smallestLimit || limit > largestLimit) {
+    return Effect.fail(
+      InvalidFileRequestError.make({ message: "a file page limit must be an integer from 1 to 1000", path: prefix }),
+    );
+  }
+
+  return Effect.succeed({ cursor: Str.normalize("NFC")(cursor), limit, prefix: Str.normalize("NFC")(prefix) });
+};
+
+export { fileListingOf };
+
+export type { CompleteListing };

package/src/contract/file/file-not-found.errors.ts

@@ -0,0 +1,6 @@
+import { Schema } from "effect";
+
+export class FileNotFoundError extends Schema.TaggedError<FileNotFoundError, { readonly brand: unique symbol }>()(
+  "FileNotFoundError",
+  { path: Schema.String },
+) {}

package/src/contract/file/file-path.pure.ts

@@ -0,0 +1,37 @@
+import { Array as Arr, Effect, Option, String as Str } from "effect";
+
+import { InvalidFileRequestError } from "./invalid-file-request.errors.js";
+
+interface PathRule {
+  readonly refuses: (path: string) => boolean;
+  readonly why: string;
+}
+
+const dotSegments: readonly string[] = [".", ".."];
+
+const segmentsOf = Str.split("/");
+
+const pathRules: readonly PathRule[] = [
+  { refuses: Str.includes("\0"), why: "contains a NUL character" },
+  { refuses: Str.includes("\\"), why: "contains a backslash" },
+  { refuses: Str.startsWith("/"), why: "is absolute" },
+  { refuses: (path) => Arr.some(segmentsOf(path), Str.isEmpty), why: "has an empty segment" },
+  {
+    refuses: (path) => Arr.some(segmentsOf(path), (segment) => Arr.contains(dotSegments, segment)),
+    why: 'has a "." or ".." segment',
+  },
+];
+
+const filePathOf = (path: string): Effect.Effect<string, InvalidFileRequestError> => {
+  const normalized = Str.normalize("NFC")(path);
+
+  return Option.match(
+    Arr.findFirst(pathRules, (rule) => rule.refuses(normalized)),
+    {
+      onNone: () => Effect.succeed(normalized),
+      onSome: ({ why }) => Effect.fail(InvalidFileRequestError.make({ message: `the file path ${path} ${why}`, path })),
+    },
+  );
+};
+
+export { filePathOf };

package/src/contract/file/files-unavailable.errors.ts

@@ -0,0 +1,8 @@
+import { Schema } from "effect";
+
+export class FilesUnavailableError extends Schema.TaggedError<
+  FilesUnavailableError,
+  { readonly brand: unique symbol }
+>()("FilesUnavailableError", {
+  message: Schema.String,
+}) {}

package/src/contract/file/invalid-file-request.errors.ts

@@ -0,0 +1,9 @@
+import { Schema } from "effect";
+
+export class InvalidFileRequestError extends Schema.TaggedError<
+  InvalidFileRequestError,
+  { readonly brand: unique symbol }
+>()("InvalidFileRequestError", {
+  message: Schema.String,
+  path: Schema.String,
+}) {}