@akterjs/effect 0.0.0-stage → 0.1.0

package/src/contract/secret/actor-secrets.adapter.ts

@@ -0,0 +1,87 @@
+import { Array as Arr, Config, ConfigProvider, Context, Effect, Layer, Option } from "effect";
+import type { Redacted } from "effect";
+
+import type { ActorDefinition } from "#src/contract/actor/actor.contract";
+import { ActorState } from "#src/contract/state/actor-state.service";
+import { SecretUnavailableError } from "./secret-unavailable.errors.js";
+import type { SecretRefusal } from "./secret.schema.js";
+
+/** One actor type asking for one of its secrets. */
+interface SecretRequest {
+  readonly actor: string;
+  readonly secret: string;
+}
+
+type SecretRead = Effect.Effect<Redacted.Redacted, SecretUnavailableError>;
+
+/** An actor's secret by name: only a name its `secrets` declares, read in a job activity. */
+type SecretOf<Definition extends ActorDefinition> = (secret: Definition["secrets"][number]) => SecretRead;
+
+/** An actor type's name and the secrets it declares. */
+interface SecretSource {
+  readonly name: string;
+  readonly secrets: readonly string[];
+}
+
+const refused =
+  (reason: SecretRefusal) =>
+  ({ actor, secret }: SecretRequest): SecretUnavailableError =>
+    SecretUnavailableError.make({ actor, reason, secret });
+
+/** Reads each secret by its own name through `provider`: the process environment by default. */
+const fromProvider =
+  (provider: ConfigProvider.ConfigProvider) =>
+  (request: SecretRequest): SecretRead =>
+    Config.option(Config.Redacted(request.secret)).pipe(
+      Effect.provideService(ConfigProvider.ConfigProvider, provider),
+      Effect.mapError(() => refused("unavailable")(request)),
+      Effect.flatMap((found) => Effect.mapError(Effect.fromOption(found), () => refused("unset")(request))),
+    );
+
+/**
+ * Where an engine's actors read their secrets. A host provides it to the app's job runtime, so job activities reach
+ * it through `Actor.secret(name)`. Nothing else asks it directly: `Actor.secret` checks the declaration first.
+ */
+export class ActorSecrets extends Context.Service<
+  ActorSecrets,
+  { readonly read: (request: SecretRequest) => SecretRead }
+>()("@akterjs/effect/contract/secret/actor-secrets.adapter/ActorSecrets") {
+  /**
+   * Secrets from the `ConfigProvider` current when it is built, each under its own name. `Akter.jobs` and `Story.run`
+   * provide it, so `akter dev` and scripts read the process environment (Bun loads `.env`), and a test builds them
+   * under a `ConfigProvider` of its own.
+   */
+  public static readonly fromConfig: Layer.Layer<ActorSecrets> = Layer.effect(
+    this,
+    Effect.map(ConfigProvider.ConfigProvider, (provider) => ({ read: fromProvider(provider) })),
+  );
+
+  public static secretOf<Definition extends ActorDefinition>(source: SecretSource): SecretOf<Definition>;
+  public static secretOf({ name, secrets: declared }: SecretSource): (secret: string) => SecretRead {
+    return (secret) =>
+      Effect.gen(function* readSecret() {
+        const request = { actor: name, secret };
+
+        if (!Arr.contains(declared, secret)) {
+          return yield* refused("undeclared")(request);
+        }
+
+        // Every handler runs with ActorState: a command, query, create or result must not depend on a secret.
+        const handler = yield* Effect.serviceOption(ActorState);
+
+        if (Option.isSome(handler)) {
+          return yield* refused("command")(request);
+        }
+
+        const secrets = yield* Effect.serviceOption(ActorSecrets);
+
+        if (Option.isNone(secrets)) {
+          return yield* refused("unavailable")(request);
+        }
+
+        return yield* secrets.value.read(request);
+      });
+  }
+}
+
+export type { SecretOf, SecretRequest };

package/src/contract/secret/invalid-secret-name.errors.ts

@@ -0,0 +1,10 @@
+import { Schema } from "effect";
+
+/** An actor declared a secret whose name isn't a `SecretName`, so no environment could ever set it. */
+export class InvalidSecretNameError extends Schema.TaggedError<
+  InvalidSecretNameError,
+  { readonly brand: unique symbol }
+>()("InvalidSecretNameError", {
+  actor: Schema.String,
+  secret: Schema.String,
+}) {}

package/src/contract/secret/secret-unavailable.errors.ts

@@ -0,0 +1,13 @@
+import { Schema } from "effect";
+
+import { SecretRefusal } from "./secret.schema.js";
+
+/** An actor's secret could not be read; `reason` says why (`SecretRefusal`). */
+export class SecretUnavailableError extends Schema.TaggedError<
+  SecretUnavailableError,
+  { readonly brand: unique symbol }
+>()("SecretUnavailableError", {
+  actor: Schema.String,
+  reason: SecretRefusal,
+  secret: Schema.String,
+}) {}

package/src/contract/secret/secret.schema.ts

@@ -0,0 +1,43 @@
+import { Schema } from "effect";
+
+const secretNamePattern = /^[A-Z][A-Z0-9_]{0,127}$/u;
+const headerPattern = /^[A-Za-z0-9-]+$/u;
+const printablePattern = /^[\t -~]*$/u;
+
+/**
+ * A secret's name, as Akter Cloud stores it for an environment and as an environment variable: an uppercase letter,
+ * then up to 127 uppercase letters, digits or underscores.
+ */
+const SecretName = Schema.String.check(Schema.isPattern(secretNamePattern)).annotate({
+  description: "A secret's name, as an environment variable.",
+});
+
+/**
+ * Why a secret could not be read:
+ *
+ * - `undeclared`: the actor doesn't list it in its `secrets`, so it may not read it.
+ * - `unset`: the actor declares it, but the environment has no value for it.
+ * - `unavailable`: this engine delivers no secrets, or couldn't open them just now.
+ * - `command`: a command, query, create or result handler asked; secrets are read in job activities.
+ */
+const SecretRefusal = Schema.Literals(["undeclared", "unset", "unavailable", "command"]);
+
+type SecretRefusal = typeof SecretRefusal.Type;
+
+/** What the platform writes before a credential's value, such as `Bearer `: printable ASCII only. */
+const HeaderPrefix = Schema.String.check(Schema.isPattern(printablePattern));
+
+/** A computer's credential: the secret the platform adds as `header` to its requests to `host`, after `prefix`. */
+const ComputerSecret = Schema.Struct({
+  header: Schema.String.check(Schema.isPattern(headerPattern)),
+  host: Schema.String,
+  prefix: Schema.optionalKey(HeaderPrefix),
+  secret: SecretName,
+}).annotate({
+  description:
+    "A credential the platform adds to the computer's requests to one allowed host. The computer never sees its value.",
+});
+
+type ComputerSecret = typeof ComputerSecret.Type;
+
+export { ComputerSecret, SecretName, SecretRefusal };

package/src/contract/spend/billing-unavailable.errors.ts

@@ -0,0 +1,12 @@
+import { Schema } from "effect";
+
+/**
+ * Akter Cloud couldn't tell whether new spend fits under the caps for too long to admit it safely, so it
+ * refused the call. Nothing ran. Retry after `retryAfterSeconds`.
+ */
+export class BillingUnavailableError extends Schema.TaggedError<
+  BillingUnavailableError,
+  { readonly brand: unique symbol }
+>()("BillingUnavailableError", {
+  retryAfterSeconds: Schema.Int,
+}) {}

package/src/contract/spend/spend-cap-reached.errors.ts

@@ -0,0 +1,17 @@
+import { Schema } from "effect";
+
+/**
+ * Akter Cloud refused new spend because a spend cap is reached. `scope` says whose cap: the
+ * organization's, or the calling API key's. A person raises it in the Cloud API; work already
+ * running is not stopped. Amounts are US dollars for the calendar month `period` (`YYYY-MM`), and
+ * `spentUsd` includes spend that may still be on its way.
+ */
+export class SpendCapReachedError extends Schema.TaggedError<SpendCapReachedError, { readonly brand: unique symbol }>()(
+  "SpendCapReachedError",
+  {
+    capUsd: Schema.Finite,
+    period: Schema.String,
+    scope: Schema.Literals(["organization", "apiKey"]),
+    spentUsd: Schema.Finite,
+  },
+) {}

package/src/contract/state/actor-state.pure.ts

@@ -0,0 +1,192 @@
+import { Array as Arr, Context, Duration, Effect, Exit, Option, Record as Rec, Ref, Schema } from "effect";
+
+import type { ActorState, Scheduling, Sending, Signalling, Starting } from "./actor-state.service.js";
+import type { CommandEnvironment, CommandScope, StateFields } from "#src/contract/actor/actor.contract";
+import type { AnyCommand, Jobs } from "#src/contract/command/command.contract";
+import { jsonCodec } from "#src/contract/json-codec.pure";
+import { TimerId } from "#src/contract/command/timer.schema";
+import type { ScheduledTimer, TimerChanges } from "#src/contract/command/timer.schema";
+import { outboxMessage } from "#src/contract/command/outbox-id.pure";
+import { JobCodecsOf, jobTag } from "#src/contract/command/command.contract";
+import { jobAddress, jobIdOf } from "#src/contract/job/job-id.pure";
+import type { StartedJob } from "#src/contract/job/started-job.schema";
+import { StoredExit } from "#src/contract/job/job-signal.schema";
+import type { JobSignal } from "#src/contract/job/job-signal.schema";
+
+type OutboxMessage = ReturnType<typeof outboxMessage>;
+
+interface PendingChanges extends TimerChanges {
+  readonly jobs: readonly StartedJob[];
+  readonly messages: readonly OutboxMessage[];
+  readonly signals: readonly JobSignal[];
+  readonly state: StateFields;
+}
+
+interface StateSource {
+  readonly actor: string;
+  readonly commands: Readonly<Record<string, AnyCommand>>;
+  readonly environment: CommandEnvironment;
+  readonly jobs: Jobs;
+  readonly state: StateFields;
+}
+
+interface Scoping {
+  readonly environment: CommandEnvironment;
+  readonly principal: CommandScope["principal"];
+}
+
+interface CommandActorState {
+  readonly changes: Ref.Ref<PendingChanges>;
+  readonly service: ActorState["Service"];
+}
+
+const noTimers: TimerChanges = { cancelled: [], scheduled: [] };
+
+const noMessages: readonly OutboxMessage[] = [];
+
+const noJobs: readonly StartedJob[] = [];
+
+const noSignals: readonly JobSignal[] = [];
+
+const onlyCommands = Effect.die("only a command changes an actor's state, timers and outbox");
+
+const refusedActorState: ActorState["Service"] = {
+  attachFile: () => onlyCommands,
+  cancel: () => onlyCommands,
+  patch: () => onlyCommands,
+  removeFile: () => onlyCommands,
+  schedule: () => onlyCommands,
+  send: () => onlyCommands,
+  signal: () => onlyCommands,
+  start: () => onlyCommands,
+};
+
+const scopeOf = ({ environment, principal }: Scoping): CommandScope => ({ ...environment, principal });
+
+const commandName = (commands: Readonly<Record<string, AnyCommand>>, command: AnyCommand): Effect.Effect<string> =>
+  Option.match(
+    Arr.findFirst(Rec.toEntries(commands), ([, declared]) => declared === command),
+    {
+      onNone: () => Effect.die("Akter.schedule names a command this actor does not declare"),
+      onSome: ([name]) => Effect.succeed(name),
+    },
+  );
+
+const ownJob = ({ actor, jobs }: StateSource, { job: { _tag: name } }: Starting): Effect.Effect<string> => {
+  if (Arr.some(Rec.keys(jobs), (member) => jobTag({ actor, member }) === name)) {
+    return Effect.succeed(name);
+  }
+
+  return Effect.die(`Akter.start names ${name}, which is not a job of ${actor}`);
+};
+
+/** The payload as the job's journal keeps it: through the job's own codec, which adds the patches its contract declares. */
+const storedPayloadOf = ({ job, payload }: Starting): Effect.Effect<string, Schema.SchemaError> => {
+  const declared = Option.flatMapNullishOr(
+    Context.get(job.annotations, JobCodecsOf),
+    (codecs) => codecs.startedPayload,
+  );
+
+  const codec = Option.getOrElse(declared, () => jsonCodec(job.payloadSchema));
+
+  return Schema.encodeEffect(codec)(payload);
+};
+
+const startJob = (
+  source: StateSource,
+  changes: Ref.Ref<PendingChanges>,
+): ((starting: Starting) => Effect.Effect<string>) =>
+  Effect.fnUntraced(function* start(starting: Starting) {
+    const { actor, environment } = source;
+    const job = yield* ownJob(source, starting);
+
+    const payload = yield* Effect.orDie(storedPayloadOf(starting));
+    const id = jobIdOf({ actor, id: yield* environment.id, key: environment.key });
+    const started: StartedJob = { id, job, payload };
+
+    yield* Ref.update(changes, (current) => ({ ...current, jobs: Arr.append(current.jobs, started) }));
+
+    return id;
+  });
+
+const ownExecution = ({ actor, environment }: StateSource, job: string): Effect.Effect<void> => {
+  if (Option.exists(jobAddress(job), (address) => address.actor === actor && address.key === environment.key)) {
+    return Effect.void;
+  }
+
+  return Effect.die(
+    `Akter.signal names ${job}, which is not a job of ${actor}/${environment.key}: signal another actor's job with a command sent to that actor`,
+  );
+};
+
+const signalJob = (
+  source: StateSource,
+  changes: Ref.Ref<PendingChanges>,
+): ((signalling: Signalling) => Effect.Effect<void>) =>
+  Effect.fnUntraced(function* signal({ exit: schema, job, name, value }: Signalling) {
+    yield* ownExecution(source, job);
+
+    const encoded = yield* Effect.orDie(Schema.encodeEffect(schema)(Exit.succeed(value)));
+    const exit = yield* Effect.orDie(Schema.encodeEffect(StoredExit)(encoded));
+    const signalled: JobSignal = { deferred: name, exit, id: job };
+
+    yield* Ref.update(changes, (current) => ({ ...current, signals: Arr.append(current.signals, signalled) }));
+  });
+
+const pendingOf = (state: PendingChanges["state"]): PendingChanges => ({
+  ...noTimers,
+  jobs: noJobs,
+  messages: noMessages,
+  signals: noSignals,
+  state,
+});
+
+const commandActorState = Effect.fnUntraced(function* commandActorState(
+  source: StateSource,
+): Effect.fn.Return<CommandActorState> {
+  const { commands, environment, state } = source;
+
+  const changes = yield* Ref.make(pendingOf(state));
+
+  const schedule = Effect.fnUntraced(function* schedule({ command, delay, payload }: Scheduling) {
+    const name = yield* commandName(commands, command);
+    const text = yield* Effect.orDie(Schema.encodeEffect(jsonCodec(command.payload))(payload));
+    const minted = yield* environment.id;
+    const id = TimerId.make(minted);
+    const timer: ScheduledTimer = { after: Duration.fromInputUnsafe(delay), command: name, id, payload: text };
+
+    yield* Ref.update(changes, (current) => ({ ...current, scheduled: Arr.append(current.scheduled, timer) }));
+
+    return id;
+  });
+
+  const send = Effect.fnUntraced(function* send({ command, key, payload }: Sending) {
+    const { actor, member } = command.address;
+    const encodedKey = yield* Effect.orDie(Schema.encodeEffect(command.address.key)(key));
+    const text = yield* Effect.orDie(Schema.encodeEffect(jsonCodec(command.payload))(payload));
+    const id = yield* environment.id;
+    const message = outboxMessage({ actor, id, key: encodedKey, member, payload: text });
+
+    yield* Ref.update(changes, (current) => ({ ...current, messages: Arr.append(current.messages, message) }));
+  });
+
+  const service: ActorState["Service"] = {
+    attachFile: environment.files.attach,
+    cancel: (timerId) =>
+      Ref.update(changes, (current) => ({
+        ...current,
+        cancelled: Arr.append(current.cancelled, timerId),
+        scheduled: Arr.filter(current.scheduled, (timer) => timer.id !== timerId),
+      })),
+    patch: (patch) => Ref.update(changes, (current) => ({ ...current, state: { ...current.state, ...patch } })),
+    removeFile: environment.files.remove,
+    schedule,
+    send,
+    signal: signalJob(source, changes),
+    start: startJob(source, changes),
+  };
+
+  return { changes, service };
+});
+
+export { commandActorState, noJobs, noMessages, noSignals, noTimers, refusedActorState, scopeOf };

package/src/contract/state/actor-state.service.ts

@@ -0,0 +1,69 @@
+import { Context, Effect } from "effect";
+import type { Duration, Exit, Schema } from "effect";
+
+import type { AddressedCommand, Decoded, StateFields } from "#src/contract/actor/actor.contract";
+import type { AnyCommand, StartableJob } from "#src/contract/command/command.contract";
+import type { TimerId } from "#src/contract/command/timer.schema";
+import type { ActorFiles, FileStorage } from "#src/contract/file/actor-files.contract";
+
+interface Sending {
+  readonly command: AddressedCommand;
+  readonly key: Decoded;
+  readonly payload: Decoded;
+}
+
+interface Starting {
+  readonly job: StartableJob;
+  readonly payload: Decoded;
+}
+
+interface Signalling {
+  /** The deferred's exit schema, which encodes `value` as its success. */
+  readonly exit: Schema.Codec<Exit.Exit<unknown, unknown>, Exit.Exit<unknown, unknown>>;
+  readonly job: string;
+  /** The durable deferred's name. */
+  readonly name: string;
+  readonly value: unknown;
+}
+
+interface Scheduling {
+  readonly command: AnyCommand;
+  readonly delay: Duration.Input;
+  readonly payload: Decoded;
+}
+
+interface FileScope {
+  readonly files: FileStorage;
+  readonly now: Effect.Effect<number>;
+}
+
+export class ActorState extends Context.Service<
+  ActorState,
+  {
+    readonly attachFile: FileStorage["attach"];
+    readonly cancel: (timerId: TimerId) => Effect.Effect<void>;
+    readonly patch: (patch: StateFields) => Effect.Effect<void>;
+    readonly removeFile: FileStorage["remove"];
+    readonly schedule: (scheduling: Scheduling) => Effect.Effect<TimerId>;
+    readonly send: (sending: Sending) => Effect.Effect<void>;
+    readonly signal: (signalling: Signalling) => Effect.Effect<void>;
+    readonly start: (starting: Starting) => Effect.Effect<string>;
+  }
+>()("@akterjs/effect/contract/state/actor-state.service/ActorState") {
+  public static files({ files, now }: FileScope): ActorFiles {
+    return {
+      attach: (path, receipt) =>
+        ActorState.use((state) => Effect.flatMap(now, (at) => state.attachFile({ now: at, path, receipt }))),
+      fileUsage: files.fileUsage,
+      list: files.list,
+      read: files.read,
+      remove: (path) => ActorState.use((state) => state.removeFile(path)),
+    };
+  }
+}
+
+export type { Scheduling, Sending, Signalling, Starting };
+
+export type { TimerId } from "#src/contract/command/timer.schema";
+
+export type { FileStorage } from "#src/contract/file/actor-files.contract";

package/src/contract/state/state-migration.pure.ts

@@ -0,0 +1,57 @@
+import { Effect, Option, Result, Schema } from "effect";
+import { dual } from "effect/Function";
+
+import type { StateFields, StateMigration } from "#src/contract/actor/actor.contract";
+import type { PlainSchema } from "#src/contract/command/command.contract";
+import type { ErasedParts } from "#src/contract/hosted/hosted-request.pure";
+import { jsonCodec } from "#src/contract/json-codec.pure";
+import { StateUnreadableError } from "./state-unreadable.errors.js";
+
+const dataFirstArity = 2;
+
+const migrateState: {
+  <From extends PlainSchema, Current extends StateFields>(
+    migrate: (old: From["Type"]) => Current,
+  ): (from: From) => StateMigration<Current>;
+  <From extends PlainSchema, Current extends StateFields>(
+    from: From,
+    migrate: (old: From["Type"]) => Current,
+  ): StateMigration<Current>;
+} = dual(
+  dataFirstArity,
+  <From extends PlainSchema, Current extends StateFields>(
+    from: From,
+    migrate: (old: From["Type"]) => Current,
+  ): StateMigration<Current> => ({
+    upgrade: (stored) => Effect.map(Schema.decodeEffect(jsonCodec(from))(stored), migrate),
+  }),
+);
+
+const migrateStored = (
+  parts: ErasedParts,
+  stored: string,
+): Effect.Effect<string, Schema.SchemaError | StateUnreadableError> =>
+  Option.match(Option.fromUndefinedOr(parts.implementation.state), {
+    onNone: () => Effect.fail(StateUnreadableError.make({ actor: parts.name, message: "no Akter.migrateState" })),
+    onSome: (migration) =>
+      Effect.flatMap(migration.upgrade(stored), Schema.encodeEffect(jsonCodec(parts.definition.state))),
+  });
+
+const upgradeState = Effect.fnUntraced(function* upgradeState(
+  parts: ErasedParts,
+  stored: string,
+): Effect.fn.Return<Option.Option<string>, StateUnreadableError> {
+  const current = yield* Effect.result(Schema.decodeEffect(jsonCodec(parts.definition.state))(stored));
+
+  if (Result.isSuccess(current)) {
+    return Option.none();
+  }
+
+  const upgraded = yield* Effect.mapError(migrateStored(parts, stored), (issue) =>
+    StateUnreadableError.make({ actor: parts.name, message: `${current.failure.message}\n${issue.message}` }),
+  );
+
+  return Option.some(upgraded);
+});
+
+export { migrateState, upgradeState };

package/src/contract/state/state-read.pure.ts

@@ -0,0 +1,40 @@
+import { Effect, Option, Schema } from "effect";
+
+import type { CallersSchemas, HostedError, StateFields, StateSchema } from "#src/contract/actor/actor.contract";
+import { admit } from "#src/contract/caller/caller-admission.pure";
+import { InvalidRequestError } from "#src/contract/client/invalid-request.errors";
+import { jsonCodec } from "#src/contract/json-codec.pure";
+import { startingState } from "#src/contract/hosted/hosted-request.pure";
+
+interface StateSource {
+  readonly callers: CallersSchemas;
+  readonly initial: Option.Option<() => StateFields>;
+  readonly name: string;
+  readonly state: StateSchema;
+}
+
+type StateEncoder = (stored: Option.Option<string>) => Effect.Effect<string, HostedError>;
+
+const stateMember = "state";
+
+const stateReader =
+  (source: StateSource) =>
+  (principal: string): Effect.Effect<StateEncoder, HostedError> => {
+    const encode = Schema.encodeEffect(jsonCodec(source.state));
+
+    const encoder: StateEncoder = (stored) =>
+      Effect.flatMap(startingState(source, stored), (state) =>
+        Effect.mapError(encode(state), (issue) =>
+          InvalidRequestError.make({ actor: source.name, message: issue.message }),
+        ),
+      );
+
+    return Effect.as(
+      admit({ actor: source.name, allowed: Option.none(), callers: source.callers, member: stateMember, principal }),
+      encoder,
+    );
+  };
+
+export { stateReader };
+
+export type { StateEncoder, StateSource };

package/src/contract/state/state-unreadable.errors.ts

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