@akterjs/client 0.0.0-stage → 0.1.1

package/src/actor-protocol.layer.ts

@@ -0,0 +1,331 @@
+import {
+  Array as Arr,
+  Clock,
+  Effect,
+  FiberMap,
+  Latch,
+  Option,
+  Predicate,
+  Record as Rec,
+  Ref,
+  Schema,
+  String as Str,
+} from "effect";
+import type { Scope } from "effect";
+import type { HttpClient } from "effect/http";
+import { RpcClient, RpcClientError, RpcMessage } from "effect/rpc";
+import { Socket } from "effect/socket";
+
+import { trackedFloors } from "./read-floors.pure.js";
+import type { ReadFloors } from "./read-floors.pure.js";
+import { remoteInterrupts } from "./remote-interrupt.pure.js";
+import type { RemoteInterrupts } from "./remote-interrupt.pure.js";
+
+type Headers = () => Readonly<Record<string, string>>;
+
+type Deliver = (response: RpcMessage.FromServerEncoded) => Effect.Effect<void>;
+
+type RequestId = RpcMessage.RequestEncoded["id"];
+
+type Frame = Uint8Array | string;
+
+interface ActorProtocolOptions {
+  readonly headers: Headers;
+  readonly http: HttpClient.HttpClient;
+  readonly url: string;
+  readonly webSocket: typeof globalThis.WebSocket;
+}
+
+interface Live {
+  readonly deliver: Deliver;
+  readonly request: RpcMessage.RequestEncoded;
+}
+
+interface Opened {
+  readonly reader: Socket.Reader;
+  readonly writer: Socket.Writer;
+}
+
+interface Receiving extends Opened {
+  readonly deliver: Deliver;
+  readonly ended: Latch.Latch;
+  readonly seen: Ref.Ref<number>;
+}
+
+const streamSuffix = "/subscribe";
+
+const liveProtocol = "akter-rpc";
+
+const authProtocol = "akter-auth.";
+
+const authorizationHeader = "authorization";
+
+const bearerPrefix = "Bearer ";
+
+const pingEvery = "10 seconds";
+
+const silentMillis = 25_000;
+
+const openTimeout = "10 seconds";
+
+const normalClose = 1000;
+
+const ClientProtocolError = Schema.TaggedStruct("ClientProtocolError", {
+  error: RpcClientError.RpcClientError,
+  requestIds: Schema.Array(Schema.Union([Schema.String, Schema.Finite])),
+});
+
+const JsonText = Schema.fromJsonString(Schema.Unknown);
+
+const encodeJson = Schema.encodeEffect(JsonText);
+
+const decodeJson = Schema.decodeEffect(JsonText);
+
+const utf8 = new globalThis.TextDecoder();
+
+function serverMessages(values: readonly unknown[]): readonly RpcMessage.FromServerEncoded[];
+function serverMessages(values: readonly unknown[]): readonly unknown[] {
+  return values;
+}
+
+const textOf = (message: RpcMessage.FromClientEncoded): Effect.Effect<string> => Effect.orDie(encodeJson(message));
+
+const tokenOf = (headers: Readonly<Record<string, string>>): Option.Option<string> =>
+  Option.map(
+    Option.filter(Rec.get(headers, authorizationHeader), Str.startsWith(bearerPrefix)),
+    Str.slice(bearerPrefix.length),
+  );
+
+const withoutAuthorization = (headers: Readonly<Record<string, string>>): readonly [string, string][] =>
+  Arr.filter(Rec.toEntries(headers), ([name]) => Str.toLowerCase(name) !== authorizationHeader);
+
+const socketUrl = (url: string, request: RpcMessage.RequestEncoded): Effect.Effect<string> =>
+  Effect.map(textOf({ ...request, headers: [] }), (text) => {
+    const target = new globalThis.URL(url);
+
+    target.protocol = Str.replace(/^http/u, "ws")(target.protocol);
+    target.searchParams.set("request", text);
+
+    return target.href;
+  });
+
+const lost = (message: string, cause: unknown): RpcClientError.RpcClientError =>
+  RpcClientError.RpcClientError.make({ reason: RpcClientError.RpcClientDefect.make({ cause, message }) });
+
+const textFrom = (frame: Frame): string => {
+  if (Predicate.isString(frame)) {
+    return frame;
+  }
+
+  return utf8.decode(frame);
+};
+
+const decodeFrame = (
+  frame: Frame,
+): Effect.Effect<readonly RpcMessage.FromServerEncoded[], RpcClientError.RpcClientError> =>
+  Effect.mapBoth(decodeJson(textFrom(frame)), {
+    onFailure: (cause) => lost("the live socket sent a frame that isn't RPC JSON", cause),
+    onSuccess: (decoded) => serverMessages(Arr.ensure(decoded)),
+  });
+
+const opened = (
+  { headers, url, webSocket }: ActorProtocolOptions,
+  request: RpcMessage.RequestEncoded,
+): Effect.Effect<Opened, Socket.SocketError, Scope.Scope> =>
+  Effect.gen(function* openLiveSocket() {
+    const sent = headers();
+    const credentials = Option.map(tokenOf(sent), (token) => `${authProtocol}${token}`);
+    const protocols = [liveProtocol, ...Option.toArray(credentials)];
+
+    const target = yield* socketUrl(url, request);
+
+    const socket = yield* Socket.fromWebSocket(
+      Effect.acquireRelease(
+        Effect.sync(() => new webSocket(target, protocols)),
+        (native) =>
+          Effect.sync(() => {
+            native.close(normalClose);
+          }),
+      ),
+      { openTimeout },
+    );
+
+    const reader = yield* socket.reader;
+    const writer = yield* socket.writer;
+    const opening = yield* textOf({ ...request, headers: [...request.headers, ...withoutAuthorization(sent)] });
+
+    yield* writer.write(opening);
+
+    return { reader, writer };
+  });
+
+const received =
+  ({ deliver, ended }: Receiving) =>
+  (response: RpcMessage.FromServerEncoded): Effect.Effect<void> => {
+    if (Predicate.isTagged(response, "Pong")) {
+      return Effect.void;
+    }
+
+    if (RpcMessage.isTerminalResponse(response)) {
+      return Effect.andThen(deliver(response), Latch.open(ended));
+    }
+
+    return deliver(response);
+  };
+
+const receiving = (live: Receiving): Effect.Effect<never, RpcClientError.RpcClientError | Socket.SocketError> => {
+  const onFrame = (frame: Frame): Effect.Effect<void, RpcClientError.RpcClientError> =>
+    Effect.flatMap(decodeFrame(frame), (responses) =>
+      Effect.andThen(
+        Effect.flatMap(Clock.currentTimeMillis, (now) => Ref.set(live.seen, now)),
+        Effect.forEach(responses, received(live), { discard: true }),
+      ),
+    );
+
+  return Effect.forever(Effect.flatMap(live.reader.pull, (frames) => Effect.forEach(frames, onFrame)));
+};
+
+const pinging = ({
+  seen,
+  writer,
+}: Receiving): Effect.Effect<never, RpcClientError.RpcClientError | Socket.SocketError> =>
+  Effect.forever(
+    Effect.gen(function* pingLiveSocket() {
+      yield* Effect.sleep(pingEvery);
+
+      const now = yield* Clock.currentTimeMillis;
+      const last = yield* Ref.get(seen);
+
+      if (now - last > silentMillis) {
+        return yield* lost("the live socket went silent", now - last);
+      }
+
+      const frame = yield* textOf(RpcMessage.constPing);
+
+      return yield* writer.write(frame);
+    }),
+  );
+
+const transportFailure = (
+  failure: RpcClientError.RpcClientError | Socket.SocketError,
+): RpcClientError.RpcClientError => {
+  if (Predicate.isTagged(failure, "RpcClientError")) {
+    return failure;
+  }
+
+  return RpcClientError.RpcClientError.make({ reason: failure.reason });
+};
+
+const liveStream =
+  (options: ActorProtocolOptions, writers: Map<RequestId, Socket.Writer>) =>
+  ({ deliver, request }: Live): Effect.Effect<void> => {
+    const served = Effect.gen(function* serveLiveRequest() {
+      const { reader, writer } = yield* opened(options, request);
+      const ended = yield* Latch.make();
+      const now = yield* Clock.currentTimeMillis;
+      const live = { deliver, ended, reader, seen: yield* Ref.make(now), writer };
+
+      yield* Effect.acquireRelease(
+        Effect.sync(() => writers.set(request.id, writer)),
+        () => Effect.sync(() => writers.delete(request.id)),
+      );
+
+      yield* Effect.raceFirst(Effect.raceFirst(receiving(live), pinging(live)), ended.await);
+    });
+
+    return Effect.matchEffect(Effect.scoped(served), {
+      onFailure: (failure) =>
+        deliver(ClientProtocolError.make({ error: transportFailure(failure), requestIds: [request.id] })),
+      onSuccess: () => Effect.void,
+    });
+  };
+
+const liveRequestOf = (message: RpcMessage.FromClientEncoded): Option.Option<RpcMessage.RequestEncoded> => {
+  if (Predicate.isTagged(message, "Request") && Str.endsWith(streamSuffix)(message.tag)) {
+    return Option.some(message);
+  }
+
+  return Option.none();
+};
+
+interface Deliveries {
+  readonly deliverTo: (clientId: number) => Deliver;
+  readonly floors: ReadFloors;
+  readonly interrupts: RemoteInterrupts;
+  readonly run: RpcClient.Protocol["Service"]["run"];
+}
+
+const deliveries = (http: RpcClient.Protocol["Service"]): Deliveries => {
+  const delivers = new Map<number, Deliver>();
+  const floors = trackedFloors();
+  const interrupts = remoteInterrupts();
+
+  const deliverTo =
+    (clientId: number): Deliver =>
+    (response) =>
+      Option.match(Option.fromNullishOr(delivers.get(clientId)), {
+        onNone: () => Effect.void,
+        onSome: (deliver) => deliver(interrupts.received(clientId, response)),
+      });
+
+  const run: Deliveries["run"] = (clientId, deliver) =>
+    Effect.ensuring(
+      Effect.suspend(() => {
+        delivers.set(clientId, deliver);
+
+        return http.run(clientId, (response) =>
+          Effect.andThen(
+            Effect.sync(() => {
+              floors.received(clientId, response);
+            }),
+            Effect.suspend(() => deliver(interrupts.received(clientId, response))),
+          ),
+        );
+      }),
+      Effect.sync(() => delivers.delete(clientId)),
+    );
+
+  return { deliverTo, floors, interrupts, run };
+};
+
+const actorProtocol = Effect.fnUntraced(function* actorProtocol(options: ActorProtocolOptions) {
+  const http = yield* RpcClient.makeProtocolHttp(options.http);
+  const lives = yield* FiberMap.make<RequestId>();
+  const writers = new Map<RequestId, Socket.Writer>();
+  const { deliverTo, floors, interrupts, run } = deliveries(http);
+  const serve = liveStream(options, writers);
+
+  const writeTo = (requestId: RequestId, message: RpcMessage.FromClientEncoded): Effect.Effect<void> =>
+    Option.match(Option.fromNullishOr(writers.get(requestId)), {
+      onNone: () => Effect.void,
+      onSome: (writer) => Effect.ignore(Effect.flatMap(textOf(message), (frame) => writer.write(frame))),
+    });
+
+  const send: RpcClient.Protocol["Service"]["send"] = (clientId, message, transferables) => {
+    const live = liveRequestOf(message);
+
+    interrupts.sent(clientId, message);
+
+    if (Option.isSome(live)) {
+      const streamed = serve({ deliver: deliverTo(clientId), request: live.value });
+
+      return Effect.asVoid(FiberMap.run(lives, live.value.id, streamed));
+    }
+
+    if (Predicate.isTagged(message, "Ack")) {
+      return writeTo(message.requestId, message);
+    }
+
+    if (Predicate.isTagged(message, "Interrupt")) {
+      return Effect.andThen(writeTo(message.requestId, message), FiberMap.remove(lives, message.requestId));
+    }
+
+    return http.send(clientId, floors.sent(clientId, message), transferables);
+  };
+
+  return RpcClient.Protocol.of({ codecFor: http.codecFor, run, send, supportsAck: true, supportsTransferables: false });
+});
+
+export { actorProtocol };
+
+export type { ActorProtocolOptions };

package/src/actor-rpc.pure.ts

@@ -0,0 +1,179 @@
+import { Array as Arr, Effect, Schema, Stream } from "effect";
+import type { Cause, Duration, Scope } from "effect";
+import { Rpc, RpcClient, RpcGroup } from "effect/rpc";
+
+import type { ActorKind, ActorRequest } from "./actor-operations.pure.js";
+
+// What a request or reply looks like on the wire for a caller without the app's contract, such as the akter CLI or
+// The MCP server: key and payload go as the JSON the actor's own schemas decode, and the answer or error comes back
+// As the JSON the actor encoded.
+interface WireFailure {
+  readonly _tag: string;
+}
+
+type WireRequest = Readonly<Record<string, Schema.Json>>;
+
+type WireSend = (tag: string, request: WireRequest) => Effect.Effect<Schema.Json | undefined, WireFailure>;
+
+type WireWatch = (tag: string, request: WireRequest) => Stream.Stream<Schema.Json, WireFailure>;
+
+type Wired = Effect.Effect<unknown, never, RpcClient.Protocol | Scope.Scope>;
+
+const commandFields = { commandId: Schema.String, key: Schema.Json, payload: Schema.Json };
+
+const queryFields = { key: Schema.Json, payload: Schema.Json };
+
+const keyFields = { key: Schema.Json };
+
+const computerFields = { computer: Schema.Json, key: Schema.Json };
+
+const listFields = {
+  cursor: Schema.optionalKey(Schema.Json),
+  key: Schema.Json,
+  limit: Schema.optionalKey(Schema.Json),
+  prefix: Schema.optionalKey(Schema.Json),
+};
+
+// The RPCs a kind sends: one each, except an upload, a session that opens, appends and closes.
+type WireKind = ActorKind | "files/upload/append" | "files/upload/close" | "files/upload/open";
+
+// Each RPC's fields are those of its RPC in rpcsOf, fileRpcsOf and computerRpcsOf (akter ADR 0016).
+const fieldsOf: Readonly<Record<WireKind, Schema.Struct.Fields>> = {
+  call: commandFields,
+  "computers/cp": { ...computerFields, computerPath: Schema.Json, direction: Schema.Json, path: Schema.Json },
+  "computers/delete": computerFields,
+  "computers/get": computerFields,
+  "computers/list": keyFields,
+  "computers/logs": {
+    ...computerFields,
+    after: Schema.optionalKey(Schema.Json),
+    limit: Schema.optionalKey(Schema.Json),
+  },
+  "computers/pause": computerFields,
+  "computers/resume": computerFields,
+  "computers/stop": computerFields,
+  create: commandFields,
+  ensure: commandFields,
+  "files/download": {
+    key: Schema.Json,
+    length: Schema.optionalKey(Schema.Json),
+    offset: Schema.optionalKey(Schema.Json),
+    path: Schema.Json,
+  },
+  "files/list": listFields,
+  "files/upload": keyFields,
+  "files/upload/append": { bytes: Schema.Json, key: Schema.Json, offset: Schema.Json, upload: Schema.Json },
+  "files/upload/close": { bytes: Schema.Json, key: Schema.Json, upload: Schema.Json },
+  "files/upload/open": keyFields,
+  "files/usage": listFields,
+  fork: { commandId: Schema.String, into: Schema.Json, key: Schema.Json },
+  query: queryFields,
+  state: keyFields,
+  "steps/get": { key: Schema.Json, step: Schema.Json },
+  "steps/list": { key: Schema.Json, limit: Schema.optionalKey(Schema.Json) },
+  warm: keyFields,
+  watch: queryFields,
+};
+
+interface Addressed {
+  readonly kind: WireKind;
+  readonly tag: string;
+}
+
+// A one-RPC client for the request, so RpcClient encodes and decodes it as the typed actor client does.
+function unaryClient(addressed: Addressed): Effect.Effect<WireSend, never, RpcClient.Protocol | Scope.Scope>;
+function unaryClient({ kind, tag }: Addressed): Wired {
+  const rpc = Rpc.make(tag, {
+    error: Schema.Json,
+    payload: Schema.Struct(fieldsOf[kind]),
+    success: Schema.UndefinedOr(Schema.Json),
+  });
+
+  return RpcClient.make(RpcGroup.make(rpc), { flatten: true });
+}
+
+function streamClient(addressed: Addressed): Effect.Effect<WireWatch, never, RpcClient.Protocol | Scope.Scope>;
+function streamClient({ kind, tag }: Addressed): Wired {
+  const rpc = Rpc.make(tag, {
+    error: Schema.Json,
+    payload: Schema.Struct(fieldsOf[kind]),
+    stream: true,
+    success: Schema.Json,
+  });
+
+  return RpcClient.make(RpcGroup.make(rpc), { flatten: true });
+}
+
+// The largest chunk one upload append sends (akter ADR 0016's files RPC group).
+const uploadChunkBytes = 1_048_576;
+
+const Base64 = Schema.Uint8ArrayFromBase64;
+
+const Opened = Schema.Struct({ upload: Schema.String });
+
+type Transferring = RpcClient.Protocol | Scope.Scope;
+
+type TransferFailure = Cause.TimeoutError | WireFailure;
+
+// A file transfer: the operation's request, as actorRequestOf builds it, and how long each RPC may take.
+interface Transfer {
+  readonly request: ActorRequest;
+  readonly wait: Duration.Input;
+}
+
+interface Session extends Transfer {
+  readonly content: Uint8Array;
+  readonly upload: string;
+}
+
+// Sends the bytes in order, at most 1 MiB an append, each at its offset so a retried one is taken once.
+const appended = Effect.fnUntraced(function* appended({ content, request, upload, wait }: Session) {
+  const tag = `${request.tag}/append`;
+  const append = yield* unaryClient({ kind: "files/upload/append", tag });
+  const count = Math.ceil(content.length / uploadChunkBytes);
+
+  const chunks = Arr.makeBy(count, (index) => ({
+    bytes: content.subarray(index * uploadChunkBytes, index * uploadChunkBytes + uploadChunkBytes),
+    offset: index * uploadChunkBytes,
+  }));
+
+  yield* Effect.forEach(chunks, ({ bytes, offset }) =>
+    Effect.flatMap(Effect.orDie(Schema.encodeEffect(Base64)(bytes)), (encoded) =>
+      Effect.timeout(append(tag, { ...request.payload, bytes: encoded, offset, upload }), wait),
+    ),
+  );
+});
+
+// Uploads a file through the session its RPCs make: open it, append the bytes, then close it with their length. The
+// Answer is the close RPC's own, { receipt }, which a command attaches at a path.
+const uploadSession = (
+  upload: Transfer & { readonly content: Uint8Array },
+): Effect.Effect<Schema.Json | undefined, TransferFailure, Transferring> =>
+  Effect.gen(function* runUploadSession() {
+    const { content, request, wait } = upload;
+    const open = yield* unaryClient({ kind: "files/upload/open", tag: `${request.tag}/open` });
+    const close = yield* unaryClient({ kind: "files/upload/close", tag: `${request.tag}/close` });
+    const opened = yield* Effect.timeout(open(`${request.tag}/open`, request.payload), wait);
+    const session = yield* Effect.orDie(Schema.decodeUnknownEffect(Opened)(opened));
+
+    yield* appended({ content, request, upload: session.upload, wait });
+
+    const closing = { ...request.payload, bytes: content.length, upload: session.upload };
+
+    return yield* Effect.timeout(close(`${request.tag}/close`, closing), wait);
+  });
+
+// Downloads a file whole: every base64 chunk the download RPC streams, or a failure, never part of a file.
+const downloadChunks = ({
+  request,
+  wait,
+}: Transfer): Effect.Effect<readonly Schema.Json[], TransferFailure, Transferring> =>
+  Effect.gen(function* collectDownload() {
+    const download = yield* streamClient({ kind: "files/download", tag: request.tag });
+
+    return yield* Effect.timeout(Stream.runCollect(download(request.tag, request.payload)), wait);
+  });
+
+export { downloadChunks, streamClient, unaryClient, uploadChunkBytes, uploadSession };
+
+export type { Transfer, TransferFailure, WireFailure, WireKind, WireRequest };

package/src/akter-client.layer.ts

@@ -0,0 +1,67 @@
+import { Effect, Layer } from "effect";
+import { SecureRandom } from "effect/crypto";
+import { FetchHttpClient, HttpClient, HttpClientRequest } from "effect/http";
+import { RpcClient, RpcSerialization } from "effect/rpc";
+
+import { ActorClients } from "@akterjs/effect/contract/actor-client";
+import { rpcFileClients } from "@akterjs/effect/contract/file-clients";
+import type { ActorFileClients } from "@akterjs/effect/contract/file-clients";
+
+import { actorProtocol } from "./actor-protocol.layer.js";
+
+interface AkterClientOptions {
+  readonly fetch?: typeof globalThis.fetch;
+  readonly headers?: () => Readonly<Record<string, string>>;
+  readonly url: string;
+  readonly webSocket?: typeof globalThis.WebSocket;
+}
+
+const noHeaders = (): Readonly<Record<string, string>> => ({});
+
+const rpcPath = "/rpc";
+
+export const akterClient = ({
+  fetch = globalThis.fetch,
+  headers = noHeaders,
+  url,
+  webSocket = globalThis.WebSocket,
+}: AkterClientOptions): Layer.Layer<ActorClients | ActorFileClients | RpcClient.Protocol> => {
+  const rpcUrl = new globalThis.URL(rpcPath, url).href;
+
+  const httpClient = Layer.effect(
+    HttpClient.HttpClient,
+    Effect.gen(function* withHeaders() {
+      const client = yield* HttpClient.HttpClient;
+
+      return HttpClient.mapRequest(client, (request) =>
+        HttpClientRequest.setHeaders(HttpClientRequest.prependUrl(request, rpcUrl), headers()),
+      );
+    }),
+  ).pipe(Layer.provide(FetchHttpClient.layer), Layer.provide(Layer.succeed(FetchHttpClient.Fetch)(fetch)));
+
+  const protocol = Layer.effect(
+    RpcClient.Protocol,
+    Effect.flatMap(HttpClient.HttpClient, (http) => actorProtocol({ headers, http, url: rpcUrl, webSocket })),
+  ).pipe(Layer.provide([httpClient, RpcSerialization.layerNdjson]));
+
+  const clients = Layer.merge(ActorClients.layer.pipe(Layer.provide(SecureRandom.layerWebCrypto)), rpcFileClients);
+
+  return Layer.provideMerge(clients, protocol);
+};
+
+export {
+  ActorAlreadyExistsError,
+  ActorNotCreatedError,
+  ActorErasedError,
+  ActorUnavailableError,
+  BillingUnavailableError,
+  CallerNotAllowedError,
+  CommandIdExpiredError,
+  HandlerFailedError,
+  InvalidRequestError,
+  SpendCapReachedError,
+  StorageLimitError,
+  UnauthenticatedError,
+} from "@akterjs/effect/contract/errors";
+
+export type { AkterClientOptions };