@akterjs/effect 0.0.0-stage → 0.1.0

package/src/contract/actor/host-interface.pure.ts

@@ -0,0 +1,60 @@
+import { Option, Schema, String as Str } from "effect";
+
+/**
+ * The version of what an Akter Cloud host reads from an app's bundle: the `HostedActor` each actor registers (its
+ * fields and runners) and what those runners return, such as `HostedOutcome`. A bundle carries its own copy of this
+ * package, so a host serves bundles built with older akter releases and must read each by the version it was built
+ * with (akter-cloud ADR 0027). Raise it in the same commit as any change a host has to read differently.
+ *
+ * - 0: before Akter.signal. A `HostedActor` has no `hostInterface`, and its outcomes have no `signals`.
+ * - 1: outcomes carry `signals`; each `HostedActor` names its version.
+ */
+const hostInterface = 1;
+
+/** The version of a bundle built before versions were named. */
+const unnamedHostInterface = 0;
+
+/** The oldest version a host built with this package serves: the current one and the one before it. */
+const oldestHostInterface = unnamedHostInterface;
+
+/** The version a registered actor was built with; a bundle from before versions were named is 0. */
+const hostInterfaceOf = (actor: { readonly hostInterface?: number | undefined }): number =>
+  actor.hostInterface ?? unnamedHostInterface;
+
+/**
+ * The first line of a bundle `akter deploy` builds names its version, so Akter Cloud's control plane can read it from
+ * the stored bundle without loading tenant code, and refuse a deploy or a host program roll that wouldn't serve it.
+ */
+const markerPrefix = "// akter-host-interface: ";
+
+/** Enough of a bundle's start to hold its marker line. */
+const markerBytes = 64;
+
+const decodeVersion = Schema.decodeUnknownOption(
+  Schema.FiniteFromString.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(unnamedHostInterface)),
+);
+
+/** The line `akter deploy` puts first in a bundle built with host interface `version`. */
+const hostInterfaceLine = (version: number): string => `${markerPrefix}${String(version)}\n`;
+
+/** The version a bundle's first line names; a bundle without that line was built before it, and is version 0. */
+const bundleHostInterface = (bundle: Uint8Array): number => {
+  const head = new globalThis.TextDecoder().decode(bundle.subarray(unnamedHostInterface, markerBytes));
+  const [first] = Str.split(head, "\n");
+  const marked = Option.filter(Option.fromNullishOr(first), Str.startsWith(markerPrefix));
+  const named = Option.flatMap(marked, (line) => decodeVersion(Str.slice(markerPrefix.length)(line)));
+
+  return Option.getOrElse(named, () => unnamedHostInterface);
+};
+
+/** Whether a host built with this package serves a build with host interface `version`. */
+const servesHostInterface = (version: number): boolean => version >= oldestHostInterface && version <= hostInterface;
+
+export {
+  bundleHostInterface,
+  hostInterface,
+  hostInterfaceLine,
+  hostInterfaceOf,
+  oldestHostInterface,
+  servesHostInterface,
+};

package/src/contract/actor/reserved-member.errors.ts

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

package/src/contract/akter.service.ts

@@ -0,0 +1,233 @@
+import { Context, Effect, Layer, Schema } from "effect";
+import type { Duration } from "effect";
+
+import {
+  commandsOf,
+  definitionOf,
+  fileAccess,
+  handlersKey,
+  initialOf,
+  principalOf,
+  rpcsOf,
+} from "#src/contract/actor/actor-definition.pure";
+import { ActorClients } from "#src/contract/client/actor-client.adapter";
+import { ActorJournal } from "#src/contract/history/actor-journal.service";
+import type { ActorHistory } from "#src/contract/history/actor-journal.service";
+import { ActorState } from "#src/contract/state/actor-state.service";
+import type { TimerId } from "#src/contract/state/actor-state.service";
+import type {
+  Actor,
+  ActorOptions,
+  AddressedCommand,
+  CommandScope,
+  DefinitionOf,
+  OptionsCheck,
+} from "#src/contract/actor/actor.contract";
+import { command, job, jobsOf, query } from "#src/contract/command/command.contract";
+import type { AnyCommand, StartableJob } from "#src/contract/command/command.contract";
+import { HostedActors } from "#src/contract/hosted/hosted-actor.service";
+import { ActorPrincipal, Principal, PrincipalId } from "#src/contract/caller/principal.schema";
+import { migrateState } from "#src/contract/state/state-migration.pure";
+
+export class Akter extends Context.Service<Akter, CommandScope>()("@akterjs/effect/contract/akter.service/Akter") {
+  public static readonly ActorPrincipal = ActorPrincipal;
+
+  public static readonly Principal = Principal;
+
+  public static readonly PrincipalId = PrincipalId;
+  public static readonly actorKey = Akter.use((scope) => Effect.succeed(scope.key));
+
+  public static readonly cancel = (timerId: TimerId): Effect.Effect<void, never, ActorState> =>
+    ActorState.use((state) => state.cancel(timerId));
+
+  public static readonly command = command;
+
+  /** Declares which caller kinds may make file calls to an actor: `files: Akter.fileAccess({ callers: ["member"] })`. */
+  public static readonly fileAccess = fileAccess;
+
+  public static readonly files = Akter.use((scope) => Effect.as(scope.files.available, ActorState.files(scope)));
+
+  public static readonly id = Akter.use((scope) => scope.id);
+
+  public static readonly job = job;
+
+  public static readonly migrateState = migrateState;
+
+  public static readonly now = Akter.use((scope) => scope.now);
+
+  public static readonly principal = Akter.use((scope) => Effect.succeed(scope.principal));
+
+  public static readonly query = query;
+
+  public static readonly sql = Akter.use((scope) => Effect.succeed(scope.sql));
+
+  public static schedule<Target extends AnyCommand>(
+    delay: Duration.Input,
+    target: Target,
+    payload: Target["payload"]["Type"],
+  ): Effect.Effect<TimerId, never, ActorState> {
+    return ActorState.use((state) => state.schedule({ command: target, delay, payload }));
+  }
+
+  public static send<Target extends AddressedCommand>(
+    target: Target,
+    key: Target["address"]["key"]["Type"],
+    payload: Target["payload"]["Type"],
+  ): Effect.Effect<void, never, ActorState> {
+    return ActorState.use((state) => state.send({ command: target, key, payload }));
+  }
+
+  /**
+   * Signals one of this actor's jobs waiting in `DurableDeferred.await(deferred)` with `value`. The signal is stored
+   * with the command and wakes the job once the command commits, so a command that fails signals nothing, and a
+   * retried command signals once. A job that has finished, was never started or already has that signal ignores it.
+   * Signal another actor's job by sending that actor a command that signals it.
+   */
+  public static signal<Success extends Schema.Codec<unknown, unknown>>(
+    deferred: {
+      readonly errorSchema: Schema.Codec<unknown, unknown>;
+      readonly name: string;
+      readonly successSchema: Success;
+    },
+    signalling: { readonly job: string; readonly value: Success["Type"] },
+  ): Effect.Effect<void, never, ActorState> {
+    const exit = Schema.Exit(deferred.successSchema, deferred.errorSchema, Schema.Defect());
+
+    return ActorState.use((state) => state.signal({ ...signalling, exit, name: deferred.name }));
+  }
+
+  public static start<Target extends StartableJob>(
+    target: Target,
+    payload: Target["payloadSchema"]["Type"],
+  ): Effect.Effect<string, never, ActorState> {
+    return ActorState.use((state) => state.start({ job: target, payload }));
+  }
+
+  public static make<const Name extends string, const Options extends ActorOptions>(
+    name: Name,
+    options: Options & OptionsCheck<Options>,
+  ): Actor<Name, DefinitionOf<Options>> & ActorHistory<DefinitionOf<Options>> {
+    const declared = definitionOf<Options>({ name, options });
+    const commands = commandsOf({ definition: declared, name });
+    const definition: DefinitionOf<Options> = { ...declared, commands };
+    const initial = initialOf<Options>(options);
+
+    const provide = <Success, Failure>(
+      effect: Effect.Effect<Success, Failure, Akter | ActorState>,
+      scope: CommandScope,
+      state: ActorState["Service"],
+    ): Effect.Effect<Success, Failure> =>
+      Effect.provideService(Effect.provideService(effect, ActorState, state), Akter, scope);
+
+    const handlers = handlersKey(name);
+    const rpcs = rpcsOf({ definition, name });
+
+    return {
+      ...definition,
+      client: ActorClients.clientOf<DefinitionOf<Options>>({ definition, name, rpcs }),
+      commands,
+      computer: ActorClients.computerOf<DefinitionOf<Options>>({ definition, name }),
+      files: ActorClients.filesOf<DefinitionOf<Options>>({ definition, name }),
+      handlers,
+      history: ActorJournal.history<DefinitionOf<Options>>({ definition, name }),
+      historyCoveredSince: ActorJournal.coveredSince<DefinitionOf<Options>>({ definition, name }),
+      historyStream: ActorJournal.historyStream<DefinitionOf<Options>>({ definition, name }),
+      initial,
+      jobs: jobsOf({ jobs: definition.jobs, name }),
+      name,
+      principal: principalOf<DefinitionOf<Options>, Akter>(Akter.principal),
+      rpcs,
+      secret: ActorClients.secretOf<DefinitionOf<Options>>({ definition, name }),
+      toLayer: (implementation) =>
+        Layer.effect(
+          handlers,
+          Effect.flatMap(HostedActors, (hosting) =>
+            hosting.register({ definition, initial, name, provide }, implementation),
+          ),
+        ).pipe(Layer.provide(HostedActors.layer)),
+      update: (patch) => ActorState.use((state) => state.patch(patch)),
+    };
+  }
+}
+
+export type {
+  Actor,
+  ActorDefinition,
+  ActorHandlers,
+  CommandHandler,
+  CreateHandler,
+  DefinitionOf,
+  FinishedJob,
+  FileAuthorizer,
+  FileRules,
+  Implementation,
+  ImplementationOf,
+  Migration,
+  Migrations,
+  QueryHandler,
+  ResultHandler,
+  StateMigration,
+} from "#src/contract/actor/actor.contract";
+
+export type { Command, Job, Query } from "#src/contract/command/command.contract";
+
+export type { ActorFiles } from "#src/contract/file/actor-files.contract";
+
+export type {
+  ActorComputers,
+  ComputerClient,
+  ComputerFork,
+  ComputerHold,
+} from "#src/contract/computer/computer-client.contract";
+
+export type { CheckpointExpiredError } from "#src/contract/computer/checkpoint-expired.errors";
+
+export type {
+  Computer,
+  ComputerName,
+  ComputerSize,
+  ComputerSpec,
+  ComputerState,
+  ExecRequest,
+  ExecResult,
+} from "#src/contract/computer/computer.schema";
+
+export type { ComputerHeldError } from "#src/contract/computer/computer-held.errors";
+
+export type { ComputerLimitError } from "#src/contract/computer/computer-limit.errors";
+
+export type { ComputerLostError } from "#src/contract/computer/computer-lost.errors";
+
+export type { ComputerNotFoundError } from "#src/contract/computer/computer-not-found.errors";
+
+export type { ComputersUnavailableError } from "#src/contract/computer/computers-unavailable.errors";
+
+export type { ComputerStep, StepRequest, StepState } from "#src/contract/computer/step/computer-step.schema";
+
+export type { StepNotFoundError } from "#src/contract/computer/step/step-not-found.errors";
+
+export type { FileClient, FileListing } from "#src/contract/file/file-client.contract";
+
+export type { FileAccess } from "#src/contract/file/access/file-access.contract";
+
+export type { FilesUnavailableError } from "#src/contract/file/files-unavailable.errors";
+
+export type { SecretOf } from "#src/contract/secret/actor-secrets.adapter";
+
+export type { InvalidSecretNameError } from "#src/contract/secret/invalid-secret-name.errors";
+
+export type { SecretUnavailableError } from "#src/contract/secret/secret-unavailable.errors";
+
+export type { ComputerSecret, SecretRefusal } from "#src/contract/secret/secret.schema";
+
+export type {
+  ActorHistory,
+  CoveredSinceOf,
+  HistoryEntry,
+  HistoryOf,
+  HistoryOptions,
+  HistoryStreamOf,
+  HistoryWindow,
+  RecordedCommand,
+  UnreadableCommand,
+} from "#src/contract/history/actor-journal.service";

package/src/contract/caller/authentication.api.ts

@@ -0,0 +1,9 @@
+import { RpcMiddleware } from "effect/rpc";
+
+import type { CurrentCaller } from "./current-caller.service.js";
+import { UnauthenticatedError } from "./unauthenticated.errors.js";
+
+export class Authentication extends RpcMiddleware.Service<Authentication, { provides: CurrentCaller }>()(
+  "@akterjs/effect/contract/caller/authentication.api/Authentication",
+  { error: UnauthenticatedError },
+) {}

package/src/contract/caller/caller-admission.pure.ts

@@ -0,0 +1,90 @@
+import { Array as Arr, Effect, Option, Record as Rec, Schema } from "effect";
+
+import type { CallersSchemas, HostedError } from "#src/contract/actor/actor.contract";
+import { CallerNotAllowedError } from "./caller-not-allowed.errors.js";
+import { Caller, actorKind } from "./caller.schema.js";
+import { InvalidRequestError } from "#src/contract/client/invalid-request.errors";
+import { jsonCodec } from "#src/contract/json-codec.pure";
+import type { Principal } from "./principal.schema.js";
+
+interface Admission {
+  readonly actor: string;
+  readonly allowed: Option.Option<readonly string[]>;
+  readonly callers: CallersSchemas;
+  readonly member: string;
+  readonly principal: string;
+}
+
+const invalid =
+  (actor: string) =>
+  (issue: { readonly message: string }): InvalidRequestError =>
+    InvalidRequestError.make({ actor, message: issue.message });
+
+const unreadable = "unreadable";
+
+const identified = Schema.Struct({ id: Schema.String });
+
+const logRefusal = (admission: Admission, { _tag: refusal }: HostedError): Effect.Effect<void> => {
+  const caller = Schema.decodeOption(jsonCodec(Caller))(admission.principal);
+  const id = Option.flatMap(caller, (decoded) => Schema.decodeUnknownOption(identified)(decoded.principal));
+
+  return Effect.logWarning("caller refused").pipe(
+    Effect.annotateLogs({
+      actor: admission.actor,
+      kind: Option.match(caller, { onNone: () => unreadable, onSome: ({ kind }) => kind }),
+      member: admission.member,
+      principal: Option.match(id, { onNone: () => unreadable, onSome: (decoded) => decoded.id }),
+      refusal,
+    }),
+  );
+};
+
+const gate = Effect.fnUntraced(function* gate({
+  actor,
+  allowed,
+  callers,
+  member,
+  principal,
+}: Admission): Effect.fn.Return<Principal, HostedError> {
+  const caller = yield* Effect.mapError(Schema.decodeEffect(jsonCodec(Caller))(principal), invalid(actor));
+  const schema = Rec.get(callers, caller.kind);
+  const listed = Option.match(allowed, { onNone: () => caller.kind !== actorKind, onSome: Arr.contains(caller.kind) });
+
+  if (Option.isNone(schema) || !listed) {
+    return yield* CallerNotAllowedError.make({ actor, kind: caller.kind, member });
+  }
+
+  return yield* Effect.mapError(
+    Schema.decodeEffect(Schema.toCodecJson(schema.value))(caller.principal),
+    invalid(actor),
+  );
+});
+
+/**
+ * The caller kinds that operate an app rather than use it: on Akter Cloud a signed-in member of the organization
+ * (`user`) and an API key (`apiKey`), and in `akter dev` its default developer. Fork admits only these, among the kinds
+ * the actor declares, because it runs no handler (akter-cloud threat model, FK1). File calls admit the kinds the actor's
+ * `Akter.fileAccess` lists, and its `files.authorize` rule decides each one (FG1).
+ */
+const operatorKinds: readonly string[] = ["user", "apiKey"];
+
+const admit = (admission: Admission): Effect.Effect<Principal, HostedError> =>
+  Effect.tapError(gate(admission), (refused) => logRefusal(admission, refused));
+
+interface Claim {
+  readonly actor: string;
+  readonly caller: Caller;
+}
+
+const clientPrincipal = ({ actor, caller }: Claim): Effect.Effect<string, InvalidRequestError> => {
+  if (caller.kind === actorKind) {
+    return InvalidRequestError.make({
+      actor,
+      message: `the ${actorKind} caller is the engine's, for delivered messages only`,
+    });
+  }
+
+  return Effect.orDie(Schema.encodeEffect(jsonCodec(Caller))(caller));
+};
+
+export { admit, clientPrincipal, operatorKinds };

package/src/contract/caller/caller-not-allowed.errors.ts

@@ -0,0 +1,26 @@
+import { Schema } from "effect";
+
+/**
+ * The caller's kind may not call this member. Its message names the refused kind and the declaration that admits it,
+ * such as `apiKey` for a script, agent or bench signed in with an Akter Cloud API key.
+ */
+export class CallerNotAllowedError extends Schema.TaggedError<
+  CallerNotAllowedError,
+  { readonly brand: unique symbol }
+>()("CallerNotAllowedError", {
+  actor: Schema.String,
+  kind: Schema.String,
+  member: Schema.String,
+}) {
+  public override get message(): string {
+    if (this.member === "akter.files") {
+      return `${this.actor}'s files refuse caller kind "${this.kind}". To admit it, list it in the actor's files: Akter.fileAccess({ callers: ["${this.kind}"] }), and allow it in files.authorize.`;
+    }
+
+    if (this.member === "fork") {
+      return `${this.actor}.fork refuses caller kind "${this.kind}". Fork admits only an app's operators, the "user" and "apiKey" caller kinds.`;
+    }
+
+    return `${this.actor}.${this.member} refuses caller kind "${this.kind}". To admit it, declare it on the actor, as in callers: { ${this.kind}: Akter.Principal, user: Akter.Principal }, and add "${this.kind}" to the member's callers if it lists them.`;
+  }
+}

package/src/contract/caller/caller.schema.ts

@@ -0,0 +1,7 @@
+import { Schema } from "effect";
+
+export const Caller = Schema.Struct({ kind: Schema.String, principal: Schema.Json });
+
+export type Caller = typeof Caller.Type;
+
+export const actorKind = "actor";

package/src/contract/caller/current-caller.service.ts

@@ -0,0 +1,7 @@
+import { Context } from "effect";
+
+import type { Caller } from "./caller.schema.js";
+
+export class CurrentCaller extends Context.Service<CurrentCaller, Caller>()(
+  "@akterjs/effect/contract/caller/current-caller.service/CurrentCaller",
+) {}

package/src/contract/caller/principal.schema.ts

@@ -0,0 +1,13 @@
+import { Schema } from "effect";
+
+export const PrincipalId = Schema.String.pipe(Schema.brand("PrincipalId"));
+
+export type PrincipalId = typeof PrincipalId.Type;
+
+export const Principal = Schema.Struct({ id: PrincipalId });
+
+export type Principal = typeof Principal.Type;
+
+export const ActorPrincipal = Schema.Struct({ actor: Schema.String, id: PrincipalId, key: Schema.String });
+
+export type ActorPrincipal = typeof ActorPrincipal.Type;

package/src/contract/caller/unauthenticated.errors.ts

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