@akterjs/effect 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,217 @@
+import { Array as Arr, Context, Duration, Effect, Layer, Predicate, Record as Rec, Schedule, Stream } from "effect";
+import type { Scope } from "effect";
+import { SecureRandom } from "effect/crypto";
+import { RpcClient } from "effect/rpc";
+
+import { creationModesOf } from "./actor-rpc.contract.js";
+import type { ActorRpcs, LiveUpdate } from "./actor-rpc.contract.js";
+import type { ActorClient } from "./actor-client.contract.js";
+import type { ActorDefinition } from "#src/contract/actor/actor.contract";
+import { ActorSecrets } from "#src/contract/secret/actor-secrets.adapter";
+import type { SecretOf } from "#src/contract/secret/actor-secrets.adapter";
+import { ActorComputerClients } from "#src/contract/computer/computer-client.adapter";
+import type { ComputerClientOf } from "#src/contract/computer/computer-client.adapter";
+import { ActorFileClients } from "#src/contract/file/file-client.adapter";
+import type { FileClientOf } from "#src/contract/file/file-client.adapter";
+
+type ClientServices = ActorClients | RpcClient.Protocol | Scope.Scope;
+
+type ClientOf<Definition extends ActorDefinition> = (
+  key: Definition["key"]["Type"],
+) => Effect.Effect<ActorClient<Definition>, never, ClientServices>;
+
+interface ClientSource {
+  readonly definition: ActorDefinition;
+  readonly name: string;
+  readonly rpcs: ActorRpcs;
+}
+
+interface WireValue {
+  readonly wire: unique symbol;
+}
+
+interface WireFailure {
+  readonly _tag: string;
+}
+
+interface WireRequest {
+  readonly commandId?: string;
+  readonly into?: WireValue;
+  readonly key: WireValue;
+  readonly payload?: WireValue;
+}
+
+type WireCall = (payload: WireValue) => Effect.Effect<WireValue, WireFailure>;
+
+type WireSend = (tag: string, request: WireRequest) => Effect.Effect<WireValue, WireFailure>;
+
+type WireUpdates = Stream.Stream<LiveUpdate<WireValue>, WireFailure>;
+
+type WireWatch = (tag: string, request: WireRequest) => WireUpdates;
+
+type WireQuery = WireCall & { readonly subscribe: (payload: WireValue) => WireUpdates };
+
+type WireWarm = Effect.Effect<WireValue, WireFailure>;
+
+type WireFork = (into: WireValue) => Effect.Effect<WireClient, WireFailure>;
+
+type WireClient = Readonly<Record<string, WireCall | WireFork | WireQuery | WireUpdates | WireWarm>>;
+
+interface WireSenders {
+  readonly send: WireSend;
+  readonly watch: WireWatch;
+}
+
+const retryMillis = 50;
+
+const retryLimit = 5;
+
+const resumeCapMillis = 5000;
+
+const noVersion = -1;
+
+const isTransportFailure = (failure: WireFailure): boolean => Predicate.isTagged(failure, "RpcClientError");
+
+const resubscribing = Schedule.min([
+  Schedule.exponential(Duration.millis(retryMillis)),
+  Schedule.spaced(Duration.millis(resumeCapMillis)),
+]).pipe(Schedule.while(({ input }: { readonly input: WireFailure }) => isTransportFailure(input)));
+
+const resumed = (updates: WireUpdates): WireUpdates =>
+  updates.pipe(
+    Stream.retry(resubscribing),
+    Stream.mapAccum(
+      () => noVersion,
+      (last, update): readonly [number, readonly LiveUpdate<WireValue>[]] => {
+        if (update.version > last) {
+          return [update.version, [update]];
+        }
+
+        return [last, []];
+      },
+    ),
+  );
+
+function wireSenders(rpcs: ActorRpcs): Effect.Effect<WireSenders, never, RpcClient.Protocol | Scope.Scope>;
+function wireSenders(rpcs: ActorRpcs): Effect.Effect<unknown, never, RpcClient.Protocol | Scope.Scope> {
+  return Effect.map(RpcClient.make(rpcs, { flatten: true }), (client) => ({ send: client, watch: client }));
+}
+
+/** One actor's wire client: its commands, queries and creation by member, and the members every actor has. */
+interface WiredActor {
+  readonly [member: string]: WireCall | WireFork | WireQuery | WireUpdates | WireWarm;
+  readonly fork: WireFork;
+  readonly state: WireUpdates;
+  readonly warm: WireWarm;
+}
+
+interface Wiring {
+  readonly random: SecureRandom.SecureRandom["Service"];
+  readonly senders: WireSenders;
+  readonly source: ClientSource;
+}
+
+// Sends a request that changes the actor under one new id, retried with that id while the transport fails, so a lost
+// Reply runs it once.
+const sendOnce = (
+  { random, senders }: Wiring,
+  tag: string,
+  request: Omit<WireRequest, "commandId">,
+): Effect.Effect<WireValue, WireFailure> =>
+  Effect.flatMap(random.uuidV7(), (commandId) =>
+    Effect.retry(senders.send(tag, { ...request, commandId }), {
+      schedule: Schedule.exponential(Duration.millis(retryMillis)),
+      times: retryLimit,
+      while: isTransportFailure,
+    }),
+  );
+
+const queriesOf = ({ senders, source }: Wiring, key: WireValue): Readonly<Record<string, WireQuery>> =>
+  Rec.map(source.definition.queries, (_declaration, member): WireQuery => {
+    const call: WireCall = (payload) => senders.send(`${source.name}/${member}`, { key, payload });
+
+    return Object.assign(call, {
+      subscribe: (payload: WireValue) => resumed(senders.watch(`${source.name}/${member}/subscribe`, { key, payload })),
+    });
+  });
+
+const wireClient = (wiring: Wiring, key: WireValue): WiredActor => {
+  const { definition, name } = wiring.source;
+  const { send, watch } = wiring.senders;
+
+  const command =
+    (tag: string): WireCall =>
+    (payload) =>
+      sendOnce(wiring, tag, { key, payload });
+
+  const creation = Rec.fromEntries(
+    Arr.map(creationModesOf(definition.create), (mode) => [mode, command(`${name}/${mode}`)] as const),
+  );
+
+  const fork: WireFork = (into) => Effect.as(sendOnce(wiring, `${name}/fork`, { into, key }), wireClient(wiring, into));
+
+  return {
+    ...Rec.map(definition.commands, (_declaration, member) => command(`${name}/${member}`)),
+    ...creation,
+    ...queriesOf(wiring, key),
+    fork,
+    state: resumed(watch(`${name}/state/subscribe`, { key })),
+    warm: send(`${name}/warm`, { key }),
+  };
+};
+
+export class ActorClients extends Context.Service<
+  ActorClients,
+  {
+    readonly connect: (
+      source: ClientSource,
+      key: WireValue,
+    ) => Effect.Effect<WireClient, never, RpcClient.Protocol | Scope.Scope>;
+  }
+>()("@akterjs/effect/contract/client/actor-client.adapter/ActorClients") {
+  public static computerOf<Definition extends ActorDefinition>(
+    source: Pick<ClientSource, "definition" | "name">,
+  ): ComputerClientOf<Definition> {
+    return ActorComputerClients.clientOf<Definition>(source);
+  }
+
+  public static filesOf<Definition extends ActorDefinition>(
+    source: Pick<ClientSource, "definition" | "name">,
+  ): FileClientOf<Definition> {
+    return ActorFileClients.clientOf<Definition>(source);
+  }
+
+  /** The actor's declared secrets, read in its job activities (`ActorSecrets`). */
+  public static secretOf<Definition extends ActorDefinition>(
+    source: Pick<ClientSource, "definition" | "name">,
+  ): SecretOf<Definition> {
+    return ActorSecrets.secretOf<Definition>({ name: source.name, secrets: source.definition.secrets });
+  }
+
+  public static readonly layer = Layer.effect(
+    ActorClients,
+    Effect.gen(function* makeActorClients() {
+      const random = yield* SecureRandom.SecureRandom;
+
+      return {
+        connect: (source, key): Effect.Effect<WireClient, never, RpcClient.Protocol | Scope.Scope> =>
+          Effect.map(wireSenders(source.rpcs), (senders) => wireClient({ random, senders, source }, key)),
+      };
+    }),
+  );
+
+  public static clientOf<Definition extends ActorDefinition>(source: ClientSource): ClientOf<Definition>;
+  public static clientOf(source: ClientSource): (key: WireValue) => Effect.Effect<WireClient, never, ClientServices> {
+    return (key) => ActorClients.use((clients) => clients.connect(source, key));
+  }
+}
+
+export type { ClientOf };
+
+export type { ActorClient, QueryClient } from "./actor-client.contract.js";
+
+export type { ComputerClientOf } from "#src/contract/computer/computer-client.adapter";
+
+export type { FileClientOf } from "#src/contract/file/file-client.adapter";
+
+export type { SecretOf } from "#src/contract/secret/actor-secrets.adapter";

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

@@ -0,0 +1,53 @@
+import type { Effect, Schema, Stream } from "effect";
+import type { RpcClientError } from "effect/rpc";
+
+import type { LiveUpdate } from "./actor-rpc.contract.js";
+import type { ActorDefinition } from "#src/contract/actor/actor.contract";
+import type { AnyCommand, AnyQuery } from "#src/contract/command/command.contract";
+import type { HostedFailure } from "#src/contract/hosted/hosted-failure.schema";
+import type { ActorAlreadyExistsError, UnauthenticatedError } from "./client-failure.contract.js";
+
+type ClientFailure<Declaration extends AnyCommand | AnyQuery> =
+  | Declaration["error"]["Type"]
+  | RpcClientError.RpcClientError
+  | UnauthenticatedError
+  | (typeof HostedFailure)["Type"];
+
+type ClientCall<Declaration extends AnyCommand | AnyQuery> = (
+  payload: Declaration["payload"]["Type"],
+) => Effect.Effect<Declaration["success"]["Type"], ClientFailure<Declaration>>;
+
+type QueryClient<Declaration extends AnyQuery> = ClientCall<Declaration> & {
+  readonly subscribe: (
+    payload: Declaration["payload"]["Type"],
+  ) => Stream.Stream<LiveUpdate<Declaration["success"]["Type"]>, ClientFailure<Declaration>>;
+};
+
+type StateFailure = RpcClientError.RpcClientError | UnauthenticatedError | (typeof HostedFailure)["Type"];
+
+type CreationClient<Definition extends ActorDefinition> = Definition["create"] extends Schema.Never
+  ? unknown
+  : {
+      readonly create: (
+        input: Definition["create"]["Type"],
+      ) => Effect.Effect<void, ActorAlreadyExistsError | StateFailure>;
+      readonly ensure: (input: Definition["create"]["Type"]) => Effect.Effect<void, StateFailure>;
+    };
+
+type ForkClientFailure = ActorAlreadyExistsError | StateFailure;
+
+type ActorClient<Definition extends ActorDefinition> = {
+  readonly [Member in keyof Definition["commands"]]: ClientCall<Definition["commands"][Member]>;
+} & {
+  readonly [Member in keyof Definition["queries"]]: QueryClient<Definition["queries"][Member]>;
+} & {
+  /**
+   * Forks this actor into a new one at `into`, with this actor's state and files at one cut and nothing in flight
+   * (ADR 0017), and answers the copy's client. A retried fork makes one copy.
+   */
+  readonly fork: (into: Definition["key"]["Type"]) => Effect.Effect<ActorClient<Definition>, ForkClientFailure>;
+  readonly state: Stream.Stream<LiveUpdate<Definition["state"]["Type"]>, StateFailure>;
+  readonly warm: Effect.Effect<void, StateFailure>;
+} & CreationClient<Definition>;
+
+export type { ActorClient, QueryClient };

package/src/contract/client/actor-rpc.contract.ts

@@ -0,0 +1,91 @@
+import { Schema, SchemaAST } from "effect";
+import type { Rpc, RpcGroup, RpcSchema } from "effect/rpc";
+
+import { ActorAlreadyExistsError } from "#src/contract/actor/actor-already-exists.errors";
+import type { KeySchema } from "#src/contract/actor/actor.contract";
+import type { Authentication } from "#src/contract/caller/authentication.api";
+import type { CommandId } from "#src/contract/command/command-id.schema";
+import type { PlainSchema } from "#src/contract/command/command.contract";
+import type { ComputerRpc } from "#src/contract/computer/rpc/computer-rpc.contract";
+import type { FileRpc } from "#src/contract/file/rpc/file-rpc.contract";
+import type { ForkRpc } from "#src/contract/fork/fork-rpc.contract";
+
+type ActorRpc =
+  | Rpc.Rpc<
+      `${string}/${string}`,
+      Schema.Struct<{ readonly commandId: typeof CommandId; readonly key: KeySchema; readonly payload: PlainSchema }>,
+      PlainSchema,
+      PlainSchema,
+      typeof Authentication
+    >
+  | Rpc.Rpc<
+      `${string}/${string}`,
+      Schema.Struct<{ readonly key: KeySchema; readonly payload: PlainSchema }>,
+      PlainSchema,
+      PlainSchema,
+      typeof Authentication
+    >
+  | Rpc.Rpc<
+      `${string}/warm`,
+      Schema.Struct<{ readonly key: KeySchema }>,
+      typeof Schema.Void,
+      PlainSchema,
+      typeof Authentication
+    >
+  | Rpc.Rpc<
+      `${string}/${string}/subscribe`,
+      Schema.Struct<{ readonly key: KeySchema; readonly payload: PlainSchema }>,
+      RpcSchema.Stream<PlainSchema, PlainSchema>,
+      typeof Schema.Never,
+      typeof Authentication
+    >
+  | Rpc.Rpc<
+      `${string}/${string}/subscribe`,
+      Schema.Struct<{ readonly key: KeySchema }>,
+      RpcSchema.Stream<PlainSchema, PlainSchema>,
+      typeof Schema.Never,
+      typeof Authentication
+    >
+  | Rpc.AddMiddleware<FileRpc, typeof Authentication>
+  | Rpc.AddMiddleware<ForkRpc, typeof Authentication>
+  | Rpc.AddMiddleware<ComputerRpc, typeof Authentication>;
+
+// Tags are `<Actor>/<member>` and `<Actor>/<member>/subscribe` (docs/adr/0016).
+// File streams use `<Actor>/files/<operation>` (contract/file/rpc/file-rpc.contract.ts), forking an actor uses
+// `<Actor>/fork` (contract/fork/fork-rpc.contract.ts), and an actor's computers use `<Actor>/computer/<operation>`
+// (contract/computer/rpc/computer-rpc.contract.ts). The member names `files`, `computer` and `fork` are reserved.
+type ActorRpcs = RpcGroup.RpcGroup<ActorRpc>;
+
+type CreationMode = "create" | "ensure";
+
+const creationModes: readonly CreationMode[] = ["create", "ensure"];
+
+const creationErrors: Readonly<Record<CreationMode, PlainSchema>> = {
+  create: ActorAlreadyExistsError,
+  ensure: Schema.Never,
+};
+
+const creationModesOf = (create: PlainSchema): readonly CreationMode[] => {
+  if (SchemaAST.isNever(create.ast)) {
+    return [];
+  }
+
+  return creationModes;
+};
+
+interface LiveUpdate<Value> {
+  readonly value: Value;
+  readonly version: number;
+}
+
+export { creationErrors, creationModesOf };
+
+export type { ActorRpc, ActorRpcs, CreationMode, LiveUpdate };
+
+export type { FileTag } from "#src/contract/file/rpc/file-rpc.contract";
+
+export { fileRpcsOf } from "#src/contract/file/rpc/file-rpc.contract";
+
+export { forkRpcOf } from "#src/contract/fork/fork-rpc.contract";
+
+export { computerRpcsOf } from "#src/contract/computer/rpc/computer-rpc.contract";

package/src/contract/client/actor-unavailable.errors.ts

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

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

@@ -0,0 +1,53 @@
+export { ActorAlreadyExistsError } from "#src/contract/actor/actor-already-exists.errors";
+
+export { ActorErasedError } from "#src/contract/actor/actor-erased.errors";
+
+export { ActorNotCreatedError } from "#src/contract/actor/actor-not-created.errors";
+
+export { ActorUnavailableError } from "./actor-unavailable.errors.js";
+
+export { CallerNotAllowedError } from "#src/contract/caller/caller-not-allowed.errors";
+
+export { UnauthenticatedError } from "#src/contract/caller/unauthenticated.errors";
+
+export { CommandIdExpiredError } from "#src/contract/command/command-id-expired.errors";
+
+export { HandlerFailedError } from "#src/contract/hosted/handler-failed.errors";
+
+export { InvalidRequestError } from "./invalid-request.errors.js";
+
+export { BillingUnavailableError } from "#src/contract/spend/billing-unavailable.errors";
+
+export { SpendCapReachedError } from "#src/contract/spend/spend-cap-reached.errors";
+
+export { StorageLimitError } from "./storage-limit.errors.js";
+
+export { BlobTransferError } from "#src/contract/file/blob-transfer.errors";
+
+export { CheckpointExpiredError } from "#src/contract/computer/checkpoint-expired.errors";
+
+export { ComputerHeldError } from "#src/contract/computer/computer-held.errors";
+
+export { ComputerLimitError } from "#src/contract/computer/computer-limit.errors";
+
+export { ComputerLostError } from "#src/contract/computer/computer-lost.errors";
+
+export { ComputerNotFoundError } from "#src/contract/computer/computer-not-found.errors";
+
+export { ComputersUnavailableError } from "#src/contract/computer/computers-unavailable.errors";
+
+export { StepNotFoundError } from "#src/contract/computer/step/step-not-found.errors";
+
+export { FileAccessDeniedError } from "#src/contract/file/access/file-access-denied.errors";
+
+export { FileNotFoundError } from "#src/contract/file/file-not-found.errors";
+
+export { FileTooLargeError } from "#src/contract/file/rpc/file-too-large.errors";
+
+export { FilesUnavailableError } from "#src/contract/file/files-unavailable.errors";
+
+export { InvalidFileRequestError } from "#src/contract/file/invalid-file-request.errors";
+
+export { InvalidSecretNameError } from "#src/contract/secret/invalid-secret-name.errors";
+
+export { SecretUnavailableError } from "#src/contract/secret/secret-unavailable.errors";

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

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

package/src/contract/client/storage-limit.errors.ts

@@ -0,0 +1,16 @@
+import { Schema } from "effect";
+
+/**
+ * Akter Cloud refused a write because the app environment's stored data reached its ceiling: `dataBytes` of
+ * `ceilingBytes`, as read from storage at `readAt` (epoch milliseconds). Nothing ran. Queries and downloads still
+ * work; a write succeeds again once data is removed or the ceiling is raised.
+ */
+export class StorageLimitError extends Schema.TaggedError<StorageLimitError, { readonly brand: unique symbol }>()(
+  "StorageLimitError",
+  {
+    actor: Schema.String,
+    ceilingBytes: Schema.Finite,
+    dataBytes: Schema.Finite,
+    readAt: Schema.Int,
+  },
+) {}

package/src/contract/command/command-id-expired.errors.ts

@@ -0,0 +1,11 @@
+import { Schema } from "effect";
+
+export class CommandIdExpiredError extends Schema.TaggedError<
+  CommandIdExpiredError,
+  { readonly brand: unique symbol }
+>()("CommandIdExpiredError", {
+  actor: Schema.String,
+  commandId: Schema.String,
+  keptSince: Schema.Int,
+  mintedAt: Schema.Int,
+}) {}

package/src/contract/command/command-id.schema.ts

@@ -0,0 +1,5 @@
+import { Schema } from "effect";
+
+export const CommandId = Schema.String.pipe(Schema.brand("CommandId"));
+
+export type CommandId = typeof CommandId.Type;