@akterjs/effect 0.0.0-stage → 0.1.0

package/src/serve/rpc/computer/computer-rpc-access.pure.ts

@@ -0,0 +1,75 @@
+import { Effect, Match, Option, Schema } from "effect";
+
+import type { CallersSchemas, KeySchema } from "#src/contract/actor/actor.contract";
+import { admit, clientPrincipal } from "#src/contract/caller/caller-admission.pure";
+import type { CurrentCaller } from "#src/contract/caller/current-caller.service";
+import { ActorUnavailableError } from "#src/contract/client/actor-unavailable.errors";
+import { InvalidRequestError } from "#src/contract/client/invalid-request.errors";
+import type { ComputerAddress, ComputerClientFailure } from "#src/contract/computer/computer-client.contract";
+import { ComputersUnavailableError } from "#src/contract/computer/computers-unavailable.errors";
+import type { ComputerRpcFailureType } from "#src/contract/computer/rpc/computer-rpc.contract";
+import type { HostedError } from "#src/contract/hosted/hosted-error.contract";
+
+interface ComputerActor {
+  readonly callers: CallersSchemas;
+  readonly key: KeySchema;
+  readonly name: string;
+}
+
+interface Keyed {
+  readonly key: string;
+}
+
+const computerMember = "computer";
+
+const unavailable = ComputersUnavailableError.make({ message: "computers aren't available on this host" });
+
+/** What a computer RPC answers for a failure its schema doesn't carry. */
+const served =
+  (actor: string) =>
+  (failure: ComputerClientFailure | HostedError): ComputerRpcFailureType =>
+    Match.value(failure).pipe(
+      Match.tag("UnauthenticatedError", () =>
+        ActorUnavailableError.make({
+          actor,
+          message: "the caller wasn't authenticated before its computers were read",
+        }),
+      ),
+      Match.tag("ActorAlreadyExistsError", () =>
+        InvalidRequestError.make({ actor, message: "a computer request can't create an actor" }),
+      ),
+      Match.tag("ComputerLimitError", (limit) =>
+        ComputersUnavailableError.make({ message: `computer ${limit.computer} is past its ${limit.limit} limit` }),
+      ),
+      Match.orElse((other): ComputerRpcFailureType => other),
+    );
+
+/**
+ * Admits the caller through the actor's callers gate as a command with no `callers` list is admitted: any caller kind
+ * the actor declares, never the engine's own actor caller. The key must decode with the actor's key schema, so one
+ * actor's request can't name another's computers.
+ */
+const addressOf = ({
+  actor,
+  caller,
+  key,
+}: Keyed & {
+  readonly actor: ComputerActor;
+  readonly caller: CurrentCaller["Service"];
+}): Effect.Effect<ComputerAddress, ComputerRpcFailureType> =>
+  Effect.gen(function* admitted() {
+    const principal = yield* clientPrincipal({ actor: actor.name, caller });
+    const admission = { actor: actor.name, allowed: Option.none(), callers: actor.callers, member: computerMember };
+
+    yield* admit({ ...admission, principal });
+
+    yield* Effect.mapError(Schema.decodeEffect(actor.key)(key), () =>
+      InvalidRequestError.make({ actor: actor.name, message: "the actor key is invalid" }),
+    );
+
+    return { actor: actor.name, key };
+  }).pipe(Effect.mapError(served(actor.name)));
+
+export { addressOf, served, unavailable };
+
+export type { ComputerActor, Keyed };

package/src/serve/rpc/computer/computer-rpc.layer.ts

@@ -0,0 +1,143 @@
+import { Array as Arr, Effect, Option, Record as Rec } from "effect";
+
+import { CurrentCaller } from "#src/contract/caller/current-caller.service";
+import { ActorComputerClients } from "#src/contract/computer/computer-client.adapter";
+import type { ComputerAddress, ComputerClientFailure } from "#src/contract/computer/computer-client.contract";
+import type {
+  Computer,
+  ComputerLogLine,
+  ComputerLogPage,
+  ComputerCopy,
+  ComputerCopyResult,
+} from "#src/contract/computer/computer.schema";
+import { computerTag } from "#src/contract/computer/rpc/computer-rpc.contract";
+import type { ComputerRpcFailureType, ComputerRpcOperation } from "#src/contract/computer/rpc/computer-rpc.contract";
+import { ActorHost } from "#src/serve/engine/actor-host.service";
+import { addressOf, served, unavailable } from "./computer-rpc-access.pure.js";
+import type { ComputerActor, Keyed } from "./computer-rpc-access.pure.js";
+import { stepEntries } from "./step-rpc.handlers.js";
+import type { StepHandler, StepReader } from "./step-rpc.handlers.js";
+import { copyComputerFile } from "./computer-copy.layer.js";
+
+type FileActor = Parameters<typeof copyComputerFile>[number]["actor"];
+
+interface Named extends Keyed {
+  readonly computer: string;
+}
+
+type Logged = Named & ComputerLogPage;
+
+type Answer<Value> = Effect.Effect<Value, ComputerRpcFailureType, CurrentCaller>;
+
+type ComputerHandler =
+  | ((request: ComputerCopy) => Answer<ComputerCopyResult>)
+  | ((request: Keyed) => Answer<readonly Computer[]>)
+  | ((request: Logged) => Answer<readonly ComputerLogLine[]>)
+  | ((request: Named) => Answer<Computer>)
+  | ((request: Named) => Answer<void>)
+  | StepHandler;
+
+type ComputerHandlers = Readonly<Record<string, ComputerHandler>>;
+
+type Clients = ActorComputerClients["Service"];
+
+type Use<Request, Value> = (
+  clients: Clients,
+  address: ComputerAddress,
+  request: Request,
+) => Effect.Effect<Value, ComputerClientFailure, CurrentCaller>;
+
+/** Admits the caller for the actor, then reaches its computers; with no computers on this host, refuses at once. */
+const answered =
+  <Request extends Keyed, Value>(actor: ComputerActor, clients: Option.Option<Clients>, use: Use<Request, Value>) =>
+  (request: Request): Answer<Value> =>
+    Effect.gen(function* answer() {
+      const caller = yield* CurrentCaller;
+      const address = yield* addressOf({ actor, caller, key: request.key });
+      const present = yield* Effect.mapError(Effect.fromOption(clients), () => unavailable);
+
+      return yield* Effect.mapError(use(present, address, request), served(actor.name));
+    });
+
+const pageOf = ({ after, limit }: Logged): ComputerLogPage =>
+  Rec.getSomes({ after: Option.fromNullishOr(after), limit: Option.fromNullishOr(limit) });
+
+const listed: Use<Keyed, readonly Computer[]> = (clients, address) => clients.connect(address).list;
+
+const got: Use<Named, Computer> = (clients, address, { computer }) => clients.connect(address).get(computer);
+
+const paused: Use<Named, Computer> = (clients, address, { computer }) => clients.connect(address).pause(computer);
+
+const resumed: Use<Named, Computer> = (clients, address, { computer }) => clients.connect(address).resume(computer);
+
+const stopped: Use<Named, Computer> = (clients, address, { computer }) => clients.connect(address).stop(computer);
+
+const deleted: Use<Named, void> = (clients, address, { computer }) => clients.connect(address).remove(computer);
+
+const logged: Use<Logged, readonly ComputerLogLine[]> = (clients, address, request) =>
+  clients.logs(address, request.computer, pageOf(request));
+
+type ComputerEntries = readonly (readonly [string, ComputerHandler])[];
+
+interface Serving {
+  readonly clients: Option.Option<Clients>;
+  readonly host: ActorHost["Service"];
+  readonly steps: Option.Option<StepReader>;
+}
+
+const entriesOf = (actor: ComputerActor & Partial<FileActor>, { clients, host, steps }: Serving): ComputerEntries => {
+  const tag = (operation: ComputerRpcOperation): string => computerTag({ actor: actor.name, operation });
+
+  const copied: Use<ComputerCopy, ComputerCopyResult> = (available, address, request) =>
+    copyComputerFile({
+      actor: { ...actor, fileAccess: actor.fileAccess ?? Option.none() },
+      client: available.connect(address),
+      host,
+      request,
+    });
+
+  return [
+    [tag("files"), answered(actor, clients, copied)],
+    [tag("list"), answered(actor, clients, listed)],
+    [tag("get"), answered(actor, clients, got)],
+    [tag("pause"), answered(actor, clients, paused)],
+    [tag("resume"), answered(actor, clients, resumed)],
+    [tag("stop"), answered(actor, clients, stopped)],
+    [tag("delete"), answered(actor, clients, deleted)],
+    [tag("logs"), answered(actor, clients, logged)],
+    ...stepEntries({ actor, steps }),
+  ];
+};
+
+/**
+ * The `<Actor>/computer/<operation>` handlers of every served actor. They admit each caller through the actor's
+ * callers gate, then reach the actor's computers through the host's `ActorComputerClients`; on a host without
+ * computers every one answers `ComputersUnavailableError`. The engine reads an actor's durable steps from its journal
+ * only while it runs computers, so with `AKTER_LOCAL_COMPUTERS` off `steps` and `step` answer the same.
+ */
+const computerRpcHandlers = (
+  actors: readonly (ComputerActor & Partial<FileActor>)[],
+): Effect.Effect<ComputerHandlers, never, ActorHost> =>
+  Effect.map(Effect.all([Effect.serviceOption(ActorComputerClients), ActorHost]), ([clients, host]) => {
+    const steps = Option.as(clients, host);
+
+    return Rec.fromEntries(Arr.flatMap(actors, (actor) => entriesOf(actor, { clients, host, steps })));
+  });
+
+/**
+ * One actor's computer handlers, by tag. `steps` reads its durable steps; a host that doesn't serve them yet passes
+ * none, and `steps` and `step` answer `ComputersUnavailableError`.
+ */
+const computerHandlersFor = ({
+  actor,
+  clients,
+  steps,
+  host,
+}: Serving & { readonly actor: ComputerActor & Partial<FileActor> }): ComputerHandlers =>
+  Rec.fromEntries(entriesOf(actor, { clients, host, steps }));
+
+export { computerHandlersFor, computerRpcHandlers };
+
+export type { ComputerHandlers };
+
+export type { ComputerActor } from "./computer-rpc-access.pure.js";

package/src/serve/rpc/computer/step-rpc.handlers.ts

@@ -0,0 +1,84 @@
+import { Effect, Option, Record as Rec } from "effect";
+
+import { CurrentCaller } from "#src/contract/caller/current-caller.service";
+import { ComputersUnavailableError } from "#src/contract/computer/computers-unavailable.errors";
+import { computerTag } from "#src/contract/computer/rpc/computer-rpc.contract";
+import type { ComputerRpcFailureType } from "#src/contract/computer/rpc/computer-rpc.contract";
+import type { ComputerStep, StepPage } from "#src/contract/computer/step/computer-step.schema";
+import { StepNotFoundError } from "#src/contract/computer/step/step-not-found.errors";
+import type { ActorHost } from "#src/serve/engine/actor-host.service";
+import { addressOf } from "./computer-rpc-access.pure.js";
+import type { ComputerActor, Keyed } from "./computer-rpc-access.pure.js";
+
+/** What reads an actor's durable steps from its journal: the host that owns the actor. */
+type StepReader = Pick<ActorHost["Service"], "step" | "steps">;
+
+type Answer<Value> = Effect.Effect<Value, ComputerRpcFailureType, CurrentCaller>;
+
+type StepHandler =
+  | ((request: Keyed & StepPage) => Answer<readonly ComputerStep[]>)
+  | ((request: Stepped) => Answer<ComputerStep>);
+
+interface Stepped extends Keyed {
+  readonly step: string;
+}
+
+const notServed = ComputersUnavailableError.make({ message: "durable steps aren't served on this host" });
+
+/** Admits the caller for the actor as every computer RPC does, then reads its journal; with no reader, refuses at once. */
+const reading =
+  <Request extends Keyed, Value>(
+    actor: ComputerActor,
+    steps: Option.Option<StepReader>,
+    read: (reader: StepReader, request: Request) => Effect.Effect<Value, ComputerRpcFailureType>,
+  ) =>
+  (request: Request): Answer<Value> =>
+    Effect.gen(function* readSteps() {
+      const caller = yield* CurrentCaller;
+
+      yield* addressOf({ actor, caller, key: request.key });
+
+      const reader = yield* Effect.mapError(Effect.fromOption(steps), () => notServed);
+
+      return yield* read(reader, request);
+    });
+
+const pageOf = (actor: string, { key, limit }: Keyed & StepPage): Parameters<StepReader["steps"]>[number] => ({
+  ...Rec.getSomes({ limit: Option.fromUndefinedOr(limit) }),
+  actor,
+  key,
+});
+
+/**
+ * The `<Actor>/computer/steps` and `<Actor>/computer/step` handlers of one actor: they admit the caller through the
+ * actor's callers gate, then read the actor's own journal through `steps`. With no reader, as on a host that doesn't
+ * serve durable steps yet, both answer `ComputersUnavailableError`.
+ */
+const stepEntries = ({
+  actor,
+  steps,
+}: {
+  readonly actor: ComputerActor;
+  readonly steps: Option.Option<StepReader>;
+}): readonly (readonly [string, StepHandler])[] => [
+  [
+    computerTag({ actor: actor.name, operation: "steps" }),
+    reading(actor, steps, (reader, request: Keyed & StepPage) => reader.steps(pageOf(actor.name, request))),
+  ],
+  [
+    computerTag({ actor: actor.name, operation: "step" }),
+    reading(actor, steps, (reader, { key, step }: Stepped) =>
+      Effect.flatMap(
+        reader.step({ actor: actor.name, key, step }),
+        Option.match({
+          onNone: () => Effect.fail(StepNotFoundError.make({ step })),
+          onSome: (found) => Effect.succeed(found),
+        }),
+      ),
+    ),
+  ],
+];
+
+export { stepEntries };
+
+export type { StepHandler, StepReader };

package/src/serve/rpc/development-authentication.handlers.ts

@@ -0,0 +1,28 @@
+import { Effect, Layer, Option, Schema } from "effect";
+import { Headers } from "effect/http";
+
+import { Authentication } from "#src/contract/caller/authentication.api";
+import { Caller } from "#src/contract/caller/caller.schema";
+import { CurrentCaller } from "#src/contract/caller/current-caller.service";
+import { UnauthenticatedError } from "#src/contract/caller/unauthenticated.errors";
+
+const principalHeader = "akter-principal";
+
+const developmentCaller: Caller = { kind: "user", principal: { id: "developer" } };
+
+const decodeCaller = Schema.decodeEffect(Schema.fromJsonString(Schema.toCodecJson(Caller)));
+
+const callerOf = (headers: Headers.Headers): Effect.Effect<Caller, UnauthenticatedError> =>
+  Option.match(Headers.get(headers, principalHeader), {
+    onNone: () => Effect.succeed(developmentCaller),
+    onSome: (text) =>
+      Effect.mapError(decodeCaller(text), (issue) =>
+        UnauthenticatedError.make({ message: `${principalHeader}: ${issue.message}` }),
+      ),
+  });
+
+const DevelopmentAuthentication = Layer.succeed(Authentication)((effect, { headers }) =>
+  Effect.flatMap(callerOf(headers), (caller) => Effect.provideService(effect, CurrentCaller, caller)),
+);
+
+export { DevelopmentAuthentication, developmentCaller, principalHeader };

package/src/serve/rpc/development-guard.pure.ts

@@ -0,0 +1,39 @@
+import { ByteSize, Effect } from "effect";
+import { HttpIncomingMessage } from "effect/http";
+import type { HttpServerRequest, HttpServerResponse } from "effect/http";
+
+import { allowedHostsOnly, loopbackOriginOnly } from "#src/serve/http/loopback-host.pure";
+import type { AllowedHosts } from "#src/serve/http/loopback-host.pure";
+
+import { ndjsonOnly } from "./ndjson-only.pure.js";
+
+type Response = HttpServerResponse.HttpServerResponse;
+
+interface Guarded {
+  readonly allowedHosts: AllowedHosts;
+  readonly exposed: boolean;
+}
+
+/**
+ * The largest request body the server reads; a larger one is answered 413 before any of it is decoded. A file upload
+ * chunk (1 MiB, base64 in its line) fits with room to spare, and Akter Cloud refuses a call over 4 MiB anyway.
+ */
+const maxBodyMebibytes = 8;
+
+const developmentGuard =
+  ({ allowedHosts, exposed }: Guarded) =>
+  <Failure, Services>(
+    app: Effect.Effect<Response, Failure, Services>,
+  ): Effect.Effect<Response, Failure, Services | HttpServerRequest.HttpServerRequest> => {
+    const typed = ndjsonOnly(
+      Effect.provideService(app, HttpIncomingMessage.MaxBodySize, ByteSize.mebibytes(maxBodyMebibytes)),
+    );
+
+    if (exposed) {
+      return typed.pipe(allowedHostsOnly(allowedHosts));
+    }
+
+    return typed.pipe(loopbackOriginOnly, allowedHostsOnly(allowedHosts));
+  };
+
+export { developmentGuard };

package/src/serve/rpc/file/file-rpc-access.pure.ts

@@ -0,0 +1,119 @@
+import { Effect, Match, Schema } from "effect";
+import type { Option } from "effect";
+
+import type { KeySchema } from "#src/contract/actor/actor.contract";
+import type { admit } from "#src/contract/caller/caller-admission.pure";
+import { clientPrincipal } from "#src/contract/caller/caller-admission.pure";
+import type { CurrentCaller } from "#src/contract/caller/current-caller.service";
+import { ActorUnavailableError } from "#src/contract/client/actor-unavailable.errors";
+import { InvalidRequestError } from "#src/contract/client/invalid-request.errors";
+import { fileAccessMember, fileAccessPayload, fileAccessReply } from "#src/contract/file/access/file-access.contract";
+import type { FileAccessRequest } from "#src/contract/file/access/file-access.contract";
+import type { FileClientFailure } from "#src/contract/file/file-client.contract";
+import type { ActorHost, HostFailure } from "#src/serve/engine/actor-host.service";
+import type { UploadOwner } from "./upload-sessions.pure.js";
+
+interface FileActor {
+  /** Whether the actor declares file calls (`Akter.fileAccess`); the host runs the declaration as `akter.files`. */
+  readonly fileAccess: Option.Option<unknown>;
+  readonly key: KeySchema;
+  readonly name: string;
+}
+
+interface Keyed {
+  readonly key: string;
+}
+
+type Admitted = Effect.Error<ReturnType<typeof admit>>;
+
+/** The failures a file RPC answers, which its schema carries; `served` folds the rest. */
+type Served = Exclude<
+  FileClientFailure | Admitted,
+  { readonly _tag: "ActorAlreadyExistsError" | "SqlError" | "UnauthenticatedError" }
+>;
+
+/**
+ * What a file RPC answers for a failure. A storage failure answers that the actor is unavailable, which a client
+ * retries; its SQL detail stays on the host.
+ */
+const served =
+  (actor: string) =>
+  (failure: FileClientFailure | HostFailure): Served =>
+    Match.value(failure).pipe(
+      Match.tag("SqlError", () =>
+        ActorUnavailableError.make({ actor, message: "the actor's files are unavailable. Retry shortly." }),
+      ),
+      Match.tag("UnauthenticatedError", () =>
+        ActorUnavailableError.make({ actor, message: "the caller wasn't authenticated before its files were read" }),
+      ),
+      Match.tag("ActorAlreadyExistsError", () =>
+        InvalidRequestError.make({ actor, message: "a file request can't create an actor" }),
+      ),
+      Match.orElse((other): Served => other),
+    );
+
+/** Which file call is asked for, and of what: the file's path, a listing's prefix, or empty for an upload. */
+interface Asked {
+  readonly access: (typeof FileAccessRequest)["Type"]["access"];
+  readonly path: string;
+}
+
+const denied = (actor: string): InvalidRequestError =>
+  InvalidRequestError.make({
+    actor,
+    message: `${actor} declares no file calls. To use files, declare them with files: Akter.fileAccess({ callers: [...] }), decide each in files.authorize, and deploy again.`,
+  });
+
+interface Admitting extends Keyed {
+  readonly actor: FileActor;
+  readonly caller: CurrentCaller["Service"];
+}
+
+/**
+ * Who is calling which actor's files, without asking the actor's rule: the actor must declare files, and the key must
+ * decode with its key schema before any file is touched, so one actor's request can't name another's files. An upload's
+ * append and close use this alone: its session was authorized when it opened, and only the same caller may continue it.
+ */
+const callerOf = Effect.fnUntraced(function* callerOf({
+  actor,
+  caller,
+  key,
+}: Admitting): Effect.fn.Return<UploadOwner, Served> {
+  const principal = yield* clientPrincipal({ actor: actor.name, caller });
+  yield* Effect.mapError(Effect.fromOption(actor.fileAccess), () => denied(actor.name));
+
+  yield* Effect.mapError(Schema.decodeEffect(actor.key)(key), () =>
+    InvalidRequestError.make({ actor: actor.name, message: "the actor key is invalid" }),
+  );
+
+  return { address: { actor: actor.name, key }, principal };
+});
+
+/**
+ * Admits the caller to the actor's files (`callerOf`), then runs the actor's `files.authorize` rule as the reserved
+ * `akter.files` query, under the verified caller: the engine admits only the kinds `Akter.fileAccess` declared, never
+ * the engine's own actor caller, and the rule reads the state and `Actor.principal`, never the request. The call is
+ * refused unless the rule succeeds.
+ */
+const ownerOf = Effect.fnUntraced(function* ownerOf({
+  asked,
+  host,
+  ...admitting
+}: Admitting & {
+  readonly asked: Asked;
+  readonly host: ActorHost["Service"];
+}): Effect.fn.Return<UploadOwner, Served> {
+  const owner = yield* callerOf(admitting);
+  const payload = yield* Effect.orDie(Schema.encodeEffect(fileAccessPayload)(asked));
+  const call = { ...owner.address, member: fileAccessMember, payload, principal: owner.principal };
+  const reply = yield* Effect.mapError(host.query(call), served(owner.address.actor));
+  const decided = yield* Effect.orDie(Schema.decodeEffect(fileAccessReply)(reply));
+
+  yield* decided;
+
+  return owner;
+});
+
+export { callerOf, ownerOf, served };
+
+export type { Asked, FileActor, Keyed, Served };