@akterjs/client 0.0.0-stage → 0.1.1

package/src/promise-client.adapter.ts

@@ -0,0 +1,354 @@
+import { Array as Arr, Effect, Fiber, ManagedRuntime, Option, Record as Rec, Schema, Stream } from "effect";
+import type { Scope } from "effect";
+import type { RpcClient } from "effect/rpc";
+
+import type { FileClient } from "@akterjs/effect/contract";
+import type { ActorClients } from "@akterjs/effect/contract/actor-client";
+
+import { akterClient } from "./akter-client.layer.js";
+import type { AkterClientOptions } from "./akter-client.layer.js";
+import { promiseFiles } from "./promise-files.pure.js";
+import type { PromiseFiles } from "./promise-files.pure.js";
+
+type ClientServices = ActorClients | RpcClient.Protocol | Scope.Scope;
+
+interface ClientActor {
+  readonly client: (key: never) => Effect.Effect<object, never, ClientServices>;
+  readonly fileAccess: Option.Option<unknown>;
+  readonly files: (key: never) => Effect.Effect<FileClient, Error>;
+  readonly key: Schema.Top & { readonly DecodingServices: never; readonly Encoded: string };
+  readonly name: string;
+  readonly queries: Readonly<Record<string, { readonly payload: Schema.Top }>>;
+}
+
+type EffectClientOf<Actor extends ClientActor> = Effect.Success<ReturnType<Actor["client"]>>;
+
+type Stop = () => void;
+
+type OnError = (error: Error) => void;
+
+type PromiseCall<Call> = Call extends (payload: infer Payload) => Effect.Effect<infer Success, infer _Failure>
+  ? (payload: Payload) => Promise<Success>
+  : never;
+
+/** A query declared without a payload subscribes as `subscribe(onUpdate, onError?)`; one with a payload takes it first. */
+type PromiseSubscribe<Call> = Call extends {
+  readonly subscribe: (payload: infer Payload) => Stream.Stream<infer Update, infer _Failure>;
+}
+  ? undefined extends Payload
+    ? { readonly subscribe: (onUpdate: (update: Update) => void, onError?: OnError) => Stop }
+    : { readonly subscribe: (payload: Payload, onUpdate: (update: Update) => void, onError?: OnError) => Stop }
+  : unknown;
+
+type PromiseState<Updates> =
+  Updates extends Stream.Stream<infer Update, infer _Failure>
+    ? { readonly subscribe: (onUpdate: (update: Update) => void, onError?: OnError) => Stop }
+    : never;
+
+/** An actor's files, when its contract declares file calls (`files: Akter.fileAccess(...)`); otherwise none. */
+type PromiseFilesOf<Actor extends ClientActor> =
+  Actor["fileAccess"] extends Option.None<unknown> ? unknown : { readonly files: PromiseFiles };
+
+type PromiseActor<Actor extends ClientActor> = {
+  readonly [Member in Exclude<keyof EffectClientOf<Actor>, "files" | "fork" | "state" | "warm">]: PromiseCall<
+    EffectClientOf<Actor>[Member]
+  > &
+    PromiseSubscribe<EffectClientOf<Actor>[Member]>;
+} & PromiseFilesOf<Actor> & {
+    /** Forks this actor into a new one at `into` and answers the copy's client (ADR 0017). */
+    readonly fork: (into: Actor["key"]["Encoded"]) => Promise<PromiseActor<Actor>>;
+    readonly state: PromiseState<EffectClientOf<Actor>["state" & keyof EffectClientOf<Actor>]>;
+    readonly warm: () => Promise<void>;
+  };
+
+type PromiseClient<Actors extends readonly ClientActor[]> = {
+  readonly [Actor in Actors[number] as Actor["name"]]: (key: Actor["key"]["Encoded"]) => PromiseActor<Actor>;
+} & {
+  readonly close: () => Promise<void>;
+};
+
+interface PromiseClientOptions<Actors extends readonly ClientActor[]> extends AkterClientOptions {
+  readonly actors: Actors;
+}
+
+interface WireValue {
+  readonly wire: unique symbol;
+}
+
+type WireUpdates = Stream.Stream<WireValue, Error>;
+
+type WireCall = ((payload: WireValue) => Effect.Effect<WireValue, Error>) & {
+  readonly subscribe: (payload?: WireValue) => WireUpdates;
+};
+
+type WireWarm = Effect.Effect<WireValue, Error>;
+
+type WireFork = (into: WireValue) => Effect.Effect<unknown, Error>;
+
+type WireMember = WireCall | WireFork | WireUpdates | WireWarm;
+
+type OnUpdate = (update: WireValue) => void;
+
+type WithPayload = (payload: WireValue, onUpdate: OnUpdate, onError?: OnError) => Stop;
+
+type WithoutPayload = (onUpdate: OnUpdate, onError?: OnError) => Stop;
+
+interface WireSubscription {
+  readonly subscribe: WithPayload | WithoutPayload;
+}
+
+interface WireStateSubscription {
+  readonly subscribe: WithoutPayload;
+}
+
+type WireActor = (key: string) => object;
+
+interface WirePromiseClient {
+  readonly [actor: string]: WireActor | (() => Promise<void>);
+  readonly close: () => Promise<void>;
+}
+
+interface WireClientActor {
+  readonly client: (key: WireValue) => Effect.Effect<Readonly<Record<string, WireMember>>, never, ClientServices>;
+  readonly fileAccess: Option.Option<unknown>;
+  readonly files: (key: WireValue) => Effect.Effect<FileClient, Error>;
+  readonly key: Schema.Codec<WireValue, string>;
+  readonly name: string;
+  readonly queries: Readonly<Record<string, { readonly payload: Schema.Top }>>;
+}
+
+const filesMember = "files";
+
+const stateMember = "state";
+
+const warmMember = "warm";
+
+const forkMember = "fork";
+
+const thenMember = "then";
+
+function wireActor(actor: ClientActor): WireClientActor;
+function wireActor(actor: ClientActor): ClientActor {
+  return actor;
+}
+
+function asCall(member: WireMember): WireCall;
+function asCall(member: WireMember): WireMember {
+  return member;
+}
+
+function asWarm(member: WireMember): WireWarm;
+function asWarm(member: WireMember): WireMember {
+  return member;
+}
+
+function asFork(member: WireMember): WireFork;
+function asFork(member: WireMember): WireMember {
+  return member;
+}
+
+function asUpdates(member: WireMember): WireUpdates;
+function asUpdates(member: WireMember): WireMember {
+  return member;
+}
+
+type Runtime = ManagedRuntime.ManagedRuntime<ActorClients | RpcClient.Protocol, never>;
+
+interface Listener {
+  readonly onError?: OnError | undefined;
+  readonly onUpdate: OnUpdate;
+  readonly updates: Stream.Stream<WireValue, Error, ActorClients | RpcClient.Protocol>;
+}
+
+const listen = (runtime: Runtime, { onError, onUpdate, updates }: Listener): Stop => {
+  const delivered = Stream.runForEach(updates, (update) =>
+    Effect.sync(() => {
+      onUpdate(update);
+    }),
+  );
+
+  const reported = Effect.matchEffect(delivered, {
+    onFailure: (error) =>
+      Effect.sync(() => {
+        onError?.(error);
+      }),
+    onSuccess: () => Effect.void,
+  });
+
+  const fiber = runtime.runFork(reported);
+
+  return () => {
+    runtime.runFork(Fiber.interrupt(fiber));
+  };
+};
+
+const listenTo =
+  (runtime: Runtime, updates: Effect.Effect<WireUpdates, Schema.SchemaError, ClientServices>): WithoutPayload =>
+  (onUpdate, onError) =>
+    listen(runtime, { onError, onUpdate, updates: Stream.unwrap(updates) });
+
+const memberOf = (
+  actor: WireClientActor,
+  key: string,
+  member: string,
+): Effect.Effect<WireMember, Schema.SchemaError, ClientServices> =>
+  Effect.gen(function* findMember() {
+    const decoded = yield* Schema.decodeEffect(actor.key)(key);
+    const client = yield* actor.client(decoded);
+
+    return yield* Option.match(Rec.get(client, member), {
+      onNone: () => Effect.die(`${actor.name} has no member ${member}`),
+      onSome: Effect.succeed,
+    });
+  });
+
+interface Addressed {
+  readonly actor: WireClientActor;
+  readonly key: string;
+  readonly runtime: Runtime;
+}
+
+const callOf =
+  ({ actor, key, runtime }: Addressed) =>
+  (member: string): ((payload: WireValue) => Promise<WireValue>) & WireSubscription => {
+    const found = memberOf(actor, key, member);
+
+    const call = (payload: WireValue): Promise<WireValue> =>
+      runtime.runPromise(Effect.scoped(Effect.flatMap(found, (send) => asCall(send)(payload))));
+
+    // A query declared without a payload has the Schema.Void payload, and subscribes with no payload argument.
+    if (Option.exists(Rec.get(actor.queries, member), (query) => query.payload === Schema.Void)) {
+      return Object.assign(call, {
+        subscribe: listenTo(
+          runtime,
+          Effect.map(found, (query) => asCall(query).subscribe()),
+        ),
+      });
+    }
+
+    const withPayload: WithPayload = (payload, onUpdate, onError) =>
+      listenTo(
+        runtime,
+        Effect.map(found, (query) => asCall(query).subscribe(payload)),
+      )(onUpdate, onError);
+
+    return Object.assign(call, { subscribe: withPayload });
+  };
+
+interface Handle extends Addressed {
+  // Makes the handle on another key of the same actor, such as a fork's copy.
+  readonly open: WireActor;
+}
+
+// Forks the actor at `key` into `into`, then answers a handle on the copy like the one `key` has.
+const forkOf =
+  ({ actor, key, open, runtime }: Handle) =>
+  (into: string): Promise<object> => {
+    const forked = Effect.gen(function* forkActor() {
+      const fork = yield* Effect.map(memberOf(actor, key, forkMember), asFork);
+      const decoded = yield* Schema.decodeEffect(actor.key)(into);
+
+      yield* fork(decoded);
+    });
+
+    return runtime.runPromise(Effect.as(Effect.scoped(forked), open(into)));
+  };
+
+const stateOf = ({ actor, key, runtime }: Addressed): WireStateSubscription => ({
+  subscribe: (onUpdate, onError) => {
+    const updates = Stream.unwrap(Effect.map(memberOf(actor, key, stateMember), asUpdates));
+
+    return listen(runtime, { onError, onUpdate, updates });
+  },
+});
+
+const warmOf = ({ actor, key, runtime }: Addressed): (() => Promise<void>) => {
+  const warmed = Effect.flatMap(memberOf(actor, key, warmMember), (warm) => Effect.asVoid(asWarm(warm)));
+
+  return (): Promise<void> => runtime.runPromise(Effect.scoped(warmed));
+};
+
+const filesOf = ({ actor, key, runtime }: Addressed): PromiseFiles => {
+  const connected = Effect.flatMap(Schema.decodeEffect(actor.key)(key), actor.files);
+
+  return promiseFiles({ connected, run: (effect) => runtime.runPromise(effect) });
+};
+
+// A command or query, or the handle's fork and warm.
+const actionMember = (handle: Handle, member: string): object => {
+  if (member === forkMember) {
+    return forkOf(handle);
+  }
+
+  if (member === warmMember) {
+    return warmOf(handle);
+  }
+
+  return callOf(handle)(member);
+};
+
+const handleMember = (handle: Handle, member: string): object | undefined => {
+  // A handle is no promise: a fork resolves to one, and a promise would call its `then` as a member.
+  if (member === thenMember) {
+    return Option.getOrUndefined(Option.none<object>());
+  }
+
+  if (member === stateMember) {
+    return stateOf(handle);
+  }
+
+  if (member === filesMember) {
+    return Option.getOrUndefined(Option.map(handle.actor.fileAccess, () => filesOf(handle)));
+  }
+
+  return actionMember(handle, member);
+};
+
+const handleOf =
+  (runtime: Runtime, actor: WireClientActor): WireActor =>
+  (key) => {
+    const handle = { actor, key, open: handleOf(runtime, actor), runtime };
+
+    return new Proxy({}, { get: (_target, property) => handleMember(handle, String(property)) });
+  };
+
+function createClient<const Actors extends readonly ClientActor[]>(
+  options: PromiseClientOptions<Actors>,
+): PromiseClient<Actors>;
+function createClient({ actors, ...connection }: PromiseClientOptions<readonly ClientActor[]>): WirePromiseClient {
+  const runtime = ManagedRuntime.make(akterClient(connection));
+
+  return {
+    ...Rec.fromEntries(Arr.map(actors, (actor) => [actor.name, handleOf(runtime, wireActor(actor))] as const)),
+    close: () => runtime.dispose(),
+  };
+}
+
+export { createClient };
+
+export {
+  ActorAlreadyExistsError,
+  ActorNotCreatedError,
+  ActorErasedError,
+  ActorUnavailableError,
+  BillingUnavailableError,
+  BlobTransferError,
+  CallerNotAllowedError,
+  CommandIdExpiredError,
+  FileAccessDeniedError,
+  FileNotFoundError,
+  FilesUnavailableError,
+  FileTooLargeError,
+  HandlerFailedError,
+  InvalidFileRequestError,
+  InvalidRequestError,
+  SpendCapReachedError,
+  StorageLimitError,
+  UnauthenticatedError,
+} from "@akterjs/effect/contract/errors";
+
+export { UploadSourceError } from "./upload-source.errors.js";
+
+export type { PromiseActor, PromiseClient, PromiseClientOptions };
+
+export type { FileListing, FilePage, FileRange, FileRef, FileUsage, PromiseFiles } from "./promise-files.pure.js";

package/src/promise-files.pure.ts

@@ -0,0 +1,106 @@
+import { Effect, Option, Predicate, Record as Rec, Stream } from "effect";
+import type { FileClient, FileListing as EffectListing } from "@akterjs/effect/contract";
+
+import { UploadSourceError } from "./upload-source.errors.js";
+
+/** One file an actor holds. */
+interface FileRef {
+  readonly bytes: number;
+  readonly path: string;
+  readonly sha256: string;
+  readonly writtenAt: number;
+}
+
+/** Which files to list: those under `prefix`, at most `limit`, after the `cursor` a previous page returned. */
+interface FileListing {
+  readonly cursor?: string | undefined;
+  readonly limit?: number | undefined;
+  readonly prefix?: string | undefined;
+}
+
+/** A byte range of one file. */
+interface FileRange {
+  readonly length: number;
+  readonly offset: number;
+}
+
+/** One page of files; `cursor` is present when there are more. */
+interface FilePage {
+  readonly cursor?: string;
+  readonly entries: readonly FileRef[];
+}
+
+/** One page of files and the total bytes every file the listing matches holds. */
+interface FileUsage extends FilePage {
+  readonly bytes: number;
+}
+
+/**
+ * An actor's files over its `<Actor>/files/*` RPCs (ADR 0016). `upload` returns the receipt a command attaches the file
+ * with; the others read what the actor holds. Each rejects with the hosted error classes the Effect client fails with.
+ */
+interface PromiseFiles {
+  readonly download: (path: string, range?: FileRange) => Promise<ReadableStream<Uint8Array>>;
+  readonly list: (listing?: FileListing) => Promise<FilePage>;
+  readonly upload: (body: ReadableStream<Uint8Array> | Uint8Array) => Promise<string>;
+  readonly usage: (listing?: FileListing) => Promise<FileUsage>;
+}
+
+interface Filing {
+  /** Connects to one actor's files. */
+  readonly connected: Effect.Effect<FileClient, Error>;
+  /** Runs an effect on the client's runtime. */
+  readonly run: <Success>(effect: Effect.Effect<Success, Error>) => Promise<Success>;
+}
+
+interface EffectPage {
+  readonly cursor: Option.Option<string>;
+  readonly entries: readonly FileRef[];
+}
+
+const pageOf = ({ cursor, entries }: EffectPage): FilePage =>
+  Option.match(cursor, {
+    onNone: (): FilePage => ({ entries }),
+    onSome: (next): FilePage => ({ cursor: next, entries }),
+  });
+
+const listingOf = ({ cursor, limit, prefix }: FileListing = {}): EffectListing => ({
+  ...Rec.getSomes({ cursor: Option.fromUndefinedOr(cursor), prefix: Option.fromUndefinedOr(prefix) }),
+  ...Rec.getSomes({ limit: Option.fromUndefinedOr(limit) }),
+});
+
+const sourceOf = (body: ReadableStream<Uint8Array> | Uint8Array): Stream.Stream<Uint8Array, UploadSourceError> => {
+  if (Predicate.isUint8Array(body)) {
+    return Stream.make(body);
+  }
+
+  return Stream.fromReadableStream({
+    evaluate: () => body,
+    onError: (cause) => UploadSourceError.make({ message: `the upload's source stream failed: ${String(cause)}` }),
+  });
+};
+
+/** The Promise face of one actor's file client. */
+const promiseFiles = ({ connected, run }: Filing): PromiseFiles => ({
+  download: (path, range) =>
+    run(Effect.map(connected, (files) => Stream.toReadableStream(files.download(path, range)))),
+  list: (listing) =>
+    run(
+      Effect.map(
+        Effect.flatMap(connected, (files) => files.list(listingOf(listing))),
+        pageOf,
+      ),
+    ),
+  upload: (body) => run(Effect.flatMap(connected, (files) => files.upload(sourceOf(body)))),
+  usage: (listing) =>
+    run(
+      Effect.map(
+        Effect.flatMap(connected, (files) => files.fileUsage(listingOf(listing))),
+        (usage): FileUsage => ({ ...pageOf(usage), bytes: Number(usage.bytes) }),
+      ),
+    ),
+});
+
+export { promiseFiles };
+
+export type { FileListing, FilePage, FileRange, FileRef, FileUsage, PromiseFiles };

package/src/read-floors.pure.ts

@@ -0,0 +1,82 @@
+import { Array as Arr, Option, Predicate, Schema, String as Str } from "effect";
+import type { RpcMessage } from "effect/rpc";
+
+// The highest commit version this client has seen for each actor, sent as each request's `akter-floor` header.
+// Akter Cloud answers each command and query `Exit` with the actor's `version`, and never serves a cached reading
+// Older than a request's floor, so a query after the client's own command reads that command's write.
+// A server that sends no versions, such as `akter dev`, never gets a floor.
+interface ReadFloors {
+  readonly received: (clientId: number, response: RpcMessage.FromServerEncoded) => void;
+  readonly sent: (clientId: number, message: RpcMessage.FromClientEncoded) => RpcMessage.FromClientEncoded;
+}
+
+const floorHeader = "akter-floor";
+
+const Keyed = Schema.Struct({ key: Schema.Unknown });
+
+const Versioned = Schema.Struct({ requestId: Schema.Union([Schema.String, Schema.Finite]), version: Schema.Int });
+
+const KeyText = Schema.fromJsonString(Schema.Unknown);
+
+const keyedOf = Schema.decodeUnknownOption(Keyed);
+
+const versionedOf = Schema.decodeUnknownOption(Versioned);
+
+const keyTextOf = Schema.encodeUnknownOption(KeyText);
+
+const actorKeyOf = ({ payload, tag }: RpcMessage.RequestEncoded): Option.Option<string> =>
+  Option.flatMap(keyedOf(payload), ({ key }) =>
+    Option.map(
+      keyTextOf(key),
+      (keyText) => `${Option.getOrElse(Arr.head(Str.split(tag, "/")), () => tag)}\n${keyText}`,
+    ),
+  );
+
+const pendingOf = (clientId: number, requestId: number | string): string => `${clientId}/${requestId}`;
+
+const trackedFloors = (): ReadFloors => {
+  const floors = new Map<string, number>();
+  const pending = new Map<string, string>();
+
+  const floored = (clientId: number, request: RpcMessage.RequestEncoded): RpcMessage.RequestEncoded =>
+    Option.match(actorKeyOf(request), {
+      onNone: () => request,
+      onSome: (actorKey) => {
+        pending.set(pendingOf(clientId, request.id), actorKey);
+
+        return Option.match(Option.fromNullishOr(floors.get(actorKey)), {
+          onNone: () => request,
+          onSome: (floor) => ({ ...request, headers: [...request.headers, [floorHeader, String(floor)]] }),
+        });
+      },
+    });
+
+  const sent: ReadFloors["sent"] = (clientId, message) => {
+    if (Predicate.isTagged(message, "Request")) {
+      return floored(clientId, message);
+    }
+
+    return message;
+  };
+
+  const received: ReadFloors["received"] = (clientId, response) => {
+    if (!Predicate.isTagged(response, "Exit")) {
+      return;
+    }
+
+    const id = pendingOf(clientId, response.requestId);
+    const actorKey = pending.get(id);
+
+    pending.delete(id);
+
+    Option.map(Option.all([Option.fromNullishOr(actorKey), versionedOf(response)]), ([key, { version }]) => {
+      floors.set(key, Math.max(version, floors.get(key) ?? version));
+    });
+  };
+
+  return { received, sent };
+};
+
+export { trackedFloors };
+
+export type { ReadFloors };

package/src/remote-interrupt.pure.ts

@@ -0,0 +1,79 @@
+import { Array as Arr, Option, Predicate, Schema, String as Str } from "effect";
+import type { RpcMessage } from "effect/rpc";
+
+import { ActorUnavailableError } from "@akterjs/effect/contract/errors";
+
+/**
+ * What a server's answers become before they reach a caller: an `Exit` whose cause is only interrupts says the server
+ * stopped the request without an answer. Left alone, the caller's fiber ends interrupted with no message, and a CLI
+ * built on Effect's `runMain` exits 130 and prints nothing. This answers it as `ActorUnavailableError` for the request's
+ * actor instead, a typed error every call can fail with, which says to retry.
+ */
+interface RemoteInterrupts {
+  readonly received: (clientId: number, response: RpcMessage.FromServerEncoded) => RpcMessage.FromServerEncoded;
+  readonly sent: (clientId: number, message: RpcMessage.FromClientEncoded) => void;
+}
+
+const InterruptReasons = Schema.NonEmptyArray(Schema.TaggedStruct("Interrupt", {}));
+
+const InterruptedOnly = Schema.Struct({ exit: Schema.TaggedStruct("Failure", { cause: InterruptReasons }) });
+
+const UnavailableWire = Schema.toEncoded(ActorUnavailableError);
+
+const FailReason = Schema.TaggedStruct("Fail", { error: UnavailableWire });
+
+/** An encoded exit that failed with one error, as Effect RPC writes it. */
+const FailedExit = Schema.TaggedStruct("Failure", { cause: Schema.Tuple([FailReason]) });
+
+const isInterruptedOnly = Schema.is(InterruptedOnly);
+
+const encodeUnavailable = Schema.encodeOption(ActorUnavailableError);
+
+const message = "the server stopped this request before it answered. Retry shortly.";
+
+const requestOf = (clientId: number, requestId: number | string): string => `${clientId}/${requestId}`;
+
+/** `Room/files/list` and `Room/post` are both Room's. */
+const actorOf = (tag: string): string => Option.getOrElse(Arr.head(Str.split(tag, "/")), () => tag);
+
+const failedWith = (error: typeof UnavailableWire.Type): RpcMessage.ExitEncoded<unknown, unknown> =>
+  FailedExit.make({ cause: [FailReason.make({ error })] });
+
+const answered = (actor: string, response: RpcMessage.ResponseExitEncoded): RpcMessage.FromServerEncoded =>
+  Option.match(encodeUnavailable(ActorUnavailableError.make({ actor, message })), {
+    onNone: () => response,
+    onSome: (error) => ({ ...response, exit: failedWith(error) }),
+  });
+
+const remoteInterrupts = (): RemoteInterrupts => {
+  const actors = new Map<string, string>();
+
+  const sent: RemoteInterrupts["sent"] = (clientId, outgoing) => {
+    if (Predicate.isTagged(outgoing, "Request")) {
+      actors.set(requestOf(clientId, outgoing.id), actorOf(outgoing.tag));
+    }
+  };
+
+  const received: RemoteInterrupts["received"] = (clientId, response) => {
+    if (!Predicate.isTagged(response, "Exit")) {
+      return response;
+    }
+
+    const id = requestOf(clientId, response.requestId);
+    const actor = Option.fromNullishOr(actors.get(id));
+
+    actors.delete(id);
+
+    if (Option.isNone(actor) || !isInterruptedOnly(response)) {
+      return response;
+    }
+
+    return answered(actor.value, response);
+  };
+
+  return { received, sent };
+};
+
+export { remoteInterrupts };
+
+export type { RemoteInterrupts };

package/src/upload-source.errors.ts

@@ -0,0 +1,9 @@
+import { Schema } from "effect";
+
+/** The upload's source stream failed before the upload finished. */
+class UploadSourceError extends Schema.TaggedError<UploadSourceError, { readonly brand: unique symbol }>()(
+  "UploadSourceError",
+  { message: Schema.String },
+) {}
+
+export { UploadSourceError };