@akterjs/effect 0.0.0-stage → 0.1.0

package/src/serve/live/live-tables.sql.ts

@@ -0,0 +1,148 @@
+import { Array as Arr, Effect, Option, String as Str } from "effect";
+import type { SqlClient, SqlError } from "effect/sql";
+
+import { CommandBatchJournal } from "#src/host/command/batch/command-batch.sql";
+
+interface Compiled {
+  readonly params: readonly unknown[];
+  readonly sql: string;
+}
+
+interface PlanStep {
+  readonly opcode: string;
+  readonly p2: number;
+  readonly p3: number;
+}
+
+type Sql<Value> = Effect.Effect<Value, SqlError.SqlError>;
+
+const stateTable = "akter_state";
+
+const changes = ["INSERT", "UPDATE", "DELETE"] as const;
+
+const tableOpens: readonly string[] = ["OpenRead", "OpenWrite", "ReopenIdx"];
+
+const mainSchema = 0;
+
+const noCommits = 0;
+
+const identifier = (name: string): string => `"${Str.replaceAll('"', '""')(name)}"`;
+
+const literal = (name: string): string => `'${Str.replaceAll("'", "''")(name)}'`;
+
+const trigger = (table: string, change: (typeof changes)[number], condition: string): string => {
+  const name = literal(table);
+
+  return `CREATE TEMP TRIGGER ${identifier(`akter_touched_${Str.toLowerCase(change)}_${table}`)} AFTER ${change} ON ${identifier(table)}${condition} BEGIN INSERT INTO akter_touched (name) SELECT ${name} WHERE NOT EXISTS (SELECT 1 FROM akter_touched WHERE name = ${name}); END`;
+};
+
+const trackChanges = (sql: SqlClient.SqlClient): Sql<void> =>
+  Effect.gen(function* trackingChanges() {
+    yield* sql.unsafe("CREATE TEMP TABLE akter_touched (name TEXT PRIMARY KEY) STRICT");
+
+    const tables = yield* sql<{
+      readonly name: string;
+    }>`SELECT name FROM sqlite_schema WHERE type = 'table' AND substr(name, 1, 7) <> 'sqlite_' AND substr(name, 1, 6) <> 'akter_'`;
+
+    const statements = [
+      ...Arr.flatMap(tables, ({ name }) => Arr.map(changes, (change) => trigger(name, change, ""))),
+      trigger(stateTable, "INSERT", ""),
+      trigger(stateTable, "UPDATE", " WHEN OLD.value IS NOT NEW.value"),
+    ];
+
+    yield* Effect.forEach(statements, (statement) => sql.unsafe(statement), { discard: true });
+  });
+
+const touchedTables = (sql: SqlClient.SqlClient): Sql<readonly string[]> =>
+  Effect.gen(function* drainingTouched() {
+    const touched = yield* sql<{ readonly name: string }>`SELECT name FROM akter_touched`;
+
+    yield* sql`DELETE FROM akter_touched`;
+
+    return Arr.map(touched, (row) => row.name);
+  });
+
+interface Planned {
+  readonly reader: SqlClient.SqlClient;
+  readonly statements: readonly Compiled[];
+}
+
+const tablesRead = ({ reader, statements }: Planned): Sql<readonly string[]> =>
+  Effect.gen(function* readingTables() {
+    const plans = yield* Effect.forEach(statements, (statement) =>
+      reader.unsafe<PlanStep>(`EXPLAIN ${statement.sql}`, statement.params),
+    );
+
+    const opens = Arr.filter(
+      Arr.flatten(plans),
+      (step) => Arr.contains(tableOpens, step.opcode) && step.p3 === mainSchema,
+    );
+
+    const pages = Arr.map(opens, (step) => step.p2);
+
+    const roots = yield* reader<{
+      readonly page: number;
+      readonly table: string;
+    }>`SELECT rootpage AS page, tbl_name AS "table" FROM sqlite_schema WHERE rootpage > 0`;
+
+    const read = Arr.filter(roots, (root) => Arr.contains(pages, root.page));
+
+    return Arr.dedupe(Arr.map(read, (root) => root.table));
+  });
+
+interface Committed {
+  /** SQLite's `schema_version`, which every schema change moves: what a query's plan, and the tables it reads, rest on. */
+  readonly schema: number;
+  readonly version: number;
+}
+
+/** The committed version and the schema it was read against, in one statement. */
+const committedRead = (reader: SqlClient.SqlClient): Sql<Committed> =>
+  Effect.map(
+    reader<Committed>`SELECT COALESCE(MAX(seq), 0) AS version, (SELECT schema_version FROM pragma_schema_version) AS schema FROM akter_commands`,
+    (rows) => Option.getOrElse(Arr.head(rows), () => ({ schema: noCommits, version: noCommits })),
+  );
+
+const committedVersion = (reader: SqlClient.SqlClient): Sql<number> =>
+  Effect.map(
+    reader<{ readonly version: number }>`SELECT COALESCE(MAX(seq), 0) AS version FROM akter_commands`,
+    (rows) => Option.match(Arr.head(rows), { onNone: () => noCommits, onSome: (row) => row.version }),
+  );
+
+interface CommandAt {
+  readonly commandId: string;
+  readonly reader: SqlClient.SqlClient;
+}
+
+const recordedVersion = ({ commandId, reader }: CommandAt): Sql<Option.Option<number>> =>
+  Effect.map(reader<{ readonly seq: number }>`SELECT seq FROM akter_commands WHERE command_id = ${commandId}`, (rows) =>
+    Option.map(Arr.head(rows), (row) => row.seq),
+  );
+
+/** A command recorded in the running engine batch has its seq in the batch journal; any other is read. */
+const commandVersion = (at: CommandAt): Sql<Option.Option<number>> =>
+  Effect.flatMap(CommandBatchJournal.seq(at.commandId), (seq) =>
+    Option.match(seq, { onNone: () => recordedVersion(at), onSome: () => Effect.succeed(seq) }),
+  );
+
+/**
+ * When a command recorded in the journal ran, in epoch milliseconds. One the running engine batch recorded, which is
+ * not in the journal yet, has none: it ran moments ago.
+ */
+const commandCommittedAt = ({ commandId, reader }: CommandAt): Sql<Option.Option<number>> =>
+  Effect.map(reader<{ readonly at: number }>`SELECT at FROM akter_commands WHERE command_id = ${commandId}`, (rows) =>
+    Option.map(Arr.head(rows), (row) => row.at),
+  );
+
+export {
+  commandCommittedAt,
+  commandVersion,
+  committedRead,
+  committedVersion,
+  stateTable,
+  tablesRead,
+  touchedTables,
+  trackChanges,
+};
+
+export type { Compiled };

package/src/serve/live/state-reads.pure.ts

@@ -0,0 +1,22 @@
+import { Effect, Stream } from "effect";
+import type { Option } from "effect";
+
+import type { HostedActor, HostedError } from "#src/contract/actor/actor.contract";
+import type { LiveUpdate } from "#src/contract/client/actor-rpc.contract";
+
+interface StateRead<Failure> {
+  readonly actor: Pick<HostedActor, "readState">;
+  readonly principal: string;
+  readonly updates: Stream.Stream<LiveUpdate<Option.Option<string>>, Failure>;
+}
+
+const stateReads = <Failure>(read: StateRead<Failure>): Stream.Stream<LiveUpdate<string>, Failure | HostedError> =>
+  Stream.unwrap(
+    Effect.map(read.actor.readState(read.principal), (encode) =>
+      Stream.mapEffect(read.updates, ({ value, version }) =>
+        Effect.map(encode(value), (encoded) => ({ value: encoded, version })),
+      ),
+    ),
+  );
+
+export { stateReads };

package/src/serve/rpc/actor-rpc.handlers.ts

@@ -0,0 +1,242 @@
+import { Array as Arr, Effect, Option, Record as Rec, Schema, Stream } from "effect";
+import type { Exit } from "effect";
+import type { Rpc } from "effect/rpc";
+
+import { creationModesOf } from "#src/contract/client/actor-rpc.contract";
+import type { ActorRpc, ActorRpcs, CreationMode, FileTag, LiveUpdate } from "#src/contract/client/actor-rpc.contract";
+import type { KeySchema } from "#src/contract/actor/actor.contract";
+import { admit, clientPrincipal, operatorKinds } from "#src/contract/caller/caller-admission.pure";
+import type { AnyCommand, AnyQuery, PlainSchema } from "#src/contract/command/command.contract";
+import { CurrentCaller } from "#src/contract/caller/current-caller.service";
+import { exitCodec, jsonCodec } from "#src/contract/json-codec.pure";
+
+import { ActorHost } from "#src/serve/engine/actor-host.service";
+import type { CommandCall, HostFailure } from "#src/serve/engine/actor-host.service";
+import { stateUpdates } from "#src/serve/engine/actor-state.pure";
+import type { StatefulActor } from "#src/serve/engine/actor-state.pure";
+
+interface ServedActor extends StatefulActor {
+  readonly commands: Readonly<Record<string, AnyCommand>>;
+  readonly create: PlainSchema;
+  /** The `Akter.fileAccess` declaration the host runs as the `akter.files` query; none means no file calls. */
+  readonly fileAccess: Option.Option<AnyQuery>;
+  readonly key: KeySchema;
+  readonly name: string;
+  readonly queries: Readonly<Record<string, AnyQuery>>;
+  readonly rpcs: ActorRpcs;
+}
+
+interface WireValue {
+  readonly wire: unique symbol;
+}
+
+interface StatePayload {
+  readonly key: WireValue;
+}
+
+interface QueryPayload extends StatePayload {
+  readonly payload: WireValue;
+}
+
+interface CommandPayload extends QueryPayload {
+  readonly commandId: string;
+}
+
+interface ForkPayload extends StatePayload {
+  readonly commandId: string;
+  readonly into: WireValue;
+}
+
+type Declaration = AnyCommand | AnyQuery;
+
+type Reply = Effect.Effect<WireValue, HostFailure | WireValue, CurrentCaller>;
+
+type Updates = Stream.Stream<LiveUpdate<unknown>, HostFailure | WireValue, CurrentCaller>;
+
+type Warmed = Effect.Effect<void, HostFailure, CurrentCaller>;
+
+type Run = (call: CommandCall) => Effect.Effect<string, HostFailure>;
+
+interface Target {
+  readonly actor: ServedActor;
+  readonly declaration: Declaration;
+  readonly host: ActorHost["Service"];
+  readonly member: string;
+}
+
+function wireExit(declaration: Declaration): Schema.Codec<Exit.Exit<WireValue, WireValue>, string>;
+function wireExit(declaration: Declaration): ReturnType<typeof exitCodec> {
+  return exitCodec(declaration);
+}
+
+function wireJson(declaration: Declaration): Schema.Codec<WireValue, string>;
+function wireJson(declaration: Declaration): ReturnType<typeof jsonCodec> {
+  return jsonCodec(declaration.payload);
+}
+
+function wireKey(key: KeySchema): Schema.Codec<WireValue, string>;
+function wireKey(key: KeySchema): KeySchema {
+  return key;
+}
+
+const addressOf = Effect.fnUntraced(function* addressOf(actor: ServedActor, request: StatePayload) {
+  const caller = yield* CurrentCaller;
+  const principal = yield* clientPrincipal({ actor: actor.name, caller });
+  const key = yield* Effect.orDie(Schema.encodeEffect(wireKey(actor.key))(request.key));
+
+  return { actor: actor.name, key, principal };
+});
+
+const callOf = Effect.fnUntraced(function* callOf({ actor, declaration, member }: Target, request: QueryPayload) {
+  const address = yield* addressOf(actor, request);
+  const payload = yield* Effect.orDie(Schema.encodeEffect(wireJson(declaration))(request.payload));
+
+  return { ...address, member, payload };
+});
+
+const replyOf = (declaration: Declaration, reply: string): Effect.Effect<WireValue, WireValue> => {
+  const exit = Effect.orDie(Schema.decodeEffect(wireExit(declaration))(reply));
+
+  return Effect.flatten(exit);
+};
+
+const commandHandler =
+  (target: Target, run: Run) =>
+  (request: CommandPayload): Reply =>
+    Effect.gen(function* handleCommand() {
+      const call = yield* callOf(target, request);
+      const reply = yield* run({ ...call, commandId: request.commandId });
+
+      return yield* replyOf(target.declaration, reply);
+    });
+
+const creationOf = (create: PlainSchema): AnyCommand => ({
+  callers: Option.none(),
+  error: Schema.Never,
+  payload: create,
+  success: Schema.Void,
+});
+
+const createHandler = (
+  actor: ServedActor,
+  host: ActorHost["Service"],
+  mode: CreationMode,
+): ((request: CommandPayload) => Reply) =>
+  commandHandler({ actor, declaration: creationOf(actor.create), host, member: mode }, (call) =>
+    host.create({ ...call, mode }),
+  );
+
+const queryHandler =
+  (target: Target) =>
+  (request: QueryPayload): Reply =>
+    Effect.gen(function* handleQuery() {
+      const call = yield* callOf(target, request);
+      const reply = yield* target.host.query(call);
+
+      return yield* replyOf(target.declaration, reply);
+    });
+
+const subscribeHandler =
+  (target: Target) =>
+  (request: QueryPayload): Updates =>
+    Stream.unwrap(
+      Effect.map(callOf(target, request), (call) =>
+        Stream.mapEffect(target.host.subscribe(call), ({ value, version }) =>
+          Effect.map(replyOf(target.declaration, value), (decoded) => ({ value: decoded, version })),
+        ),
+      ),
+    );
+
+const stateHandler =
+  (actor: ServedActor, host: ActorHost["Service"]) =>
+  (request: StatePayload): Updates =>
+    Stream.unwrap(
+      Effect.map(addressOf(actor, request), ({ key, principal }) =>
+        stateUpdates({ actor, principal, updates: host.state({ actor: actor.name, key }) }),
+      ),
+    );
+
+const warmHandler =
+  (actor: ServedActor, host: ActorHost["Service"]) =>
+  (request: StatePayload): Warmed =>
+    Effect.flatMap(addressOf(actor, request), ({ key }) => host.warm({ actor: actor.name, key }));
+
+const forkMember = "fork";
+
+/**
+ * Forks the actor at `key` into `into`. Only the operator kinds (`user` and `apiKey`) the actor declares may fork,
+ * since the copy holds everything the actor holds and a fork runs no handler that could check the caller.
+ */
+const forkHandler =
+  (actor: ServedActor, host: ActorHost["Service"]) =>
+  (request: ForkPayload): Effect.Effect<{ readonly version: number }, HostFailure | WireValue, CurrentCaller> =>
+    Effect.gen(function* handleFork() {
+      const { key, principal } = yield* addressOf(actor, request);
+
+      const admission = {
+        actor: actor.name,
+        allowed: Option.some(operatorKinds),
+        callers: actor.callers,
+        member: forkMember,
+      };
+
+      yield* admit({ ...admission, principal });
+
+      const into = yield* Effect.orDie(Schema.encodeEffect(wireKey(actor.key))(request.into));
+      const version = yield* host.fork({ actor: actor.name, commandId: request.commandId, into, key });
+
+      return { version };
+    });
+
+interface Served {
+  readonly actors: readonly ServedActor[];
+  readonly host: ActorHost["Service"];
+}
+
+type Forked = Effect.Effect<{ readonly version: number }, HostFailure | WireValue, CurrentCaller>;
+
+type Handlers = Readonly<Record<string, (request: CommandPayload & ForkPayload) => Forked | Reply | Updates | Warmed>>;
+
+type ActorRpcHandlers = {
+  readonly [Current in ActorRpc as Current["_tag"]]: Rpc.ToHandlerFn<Current, CurrentCaller>;
+};
+
+/** Every handler but the file streams, which `file/file-rpc.layer.ts` serves. */
+type CallHandlers = Omit<ActorRpcHandlers, FileTag>;
+
+function handlersOf(served: Served): CallHandlers;
+function handlersOf({ actors, host }: Served): CallHandlers | Handlers {
+  return Rec.fromEntries(
+    Arr.flatMap(actors, (actor) => [
+      ...Arr.map(
+        Rec.toEntries(actor.commands),
+        ([member, declaration]) =>
+          [`${actor.name}/${member}`, commandHandler({ actor, declaration, host, member }, host.command)] as const,
+      ),
+      ...Arr.map(
+        Rec.toEntries(actor.queries),
+        ([member, declaration]) =>
+          [`${actor.name}/${member}`, queryHandler({ actor, declaration, host, member })] as const,
+      ),
+      ...Arr.map(
+        Rec.toEntries(actor.queries),
+        ([member, declaration]) =>
+          [`${actor.name}/${member}/subscribe`, subscribeHandler({ actor, declaration, host, member })] as const,
+      ),
+      ...Arr.map(
+        creationModesOf(actor.create),
+        (mode) => [`${actor.name}/${mode}`, createHandler(actor, host, mode)] as const,
+      ),
+      [`${actor.name}/warm`, warmHandler(actor, host)] as const,
+      [`${actor.name}/state/subscribe`, stateHandler(actor, host)] as const,
+      [`${actor.name}/fork`, forkHandler(actor, host)] as const,
+    ]),
+  );
+}
+
+const actorRpcHandlers = (actors: readonly ServedActor[]): Effect.Effect<CallHandlers, never, ActorHost> =>
+  ActorHost.use((host) => Effect.succeed(handlersOf({ actors, host })));
+
+export { actorRpcHandlers };
+
+export type { ActorRpcHandlers, ServedActor };

package/src/serve/rpc/akter-server.layer.ts

@@ -0,0 +1,119 @@
+import { Array as Arr, Effect, Exit, Layer, Option } from "effect";
+import { HttpRouter, HttpServer } from "effect/http";
+import { RpcGroup, RpcSerialization, RpcServer } from "effect/rpc";
+
+import { ActorRegistry } from "#src/contract/actor/actor-registry.service";
+
+import type { ActorHost } from "#src/serve/engine/actor-host.service";
+import { servedRpcHandlers } from "./served-rpc.layer.js";
+import type { ServedActor } from "./served-rpc.layer.js";
+import { ActorsNotHostedError } from "#src/serve/engine/actors-not-hosted.errors";
+import { DevelopmentAuthentication } from "./development-authentication.handlers.js";
+import { ListenerNotLoopbackError } from "./listener-not-loopback.errors.js";
+import { developmentGuard } from "./development-guard.pure.js";
+
+interface ServeOptions<Actors extends readonly ServedActor[]> {
+  readonly actors: Actors;
+  readonly allowedHosts?: readonly string[] | true;
+  readonly hostname?: string;
+  readonly port?: number;
+  readonly unsafeExposeDevelopmentAuth?: boolean;
+}
+
+const rpcPath = "/rpc";
+
+const loopbackAddress =
+  /^http:\/\/(?:127(?:\.\d{1,3}){3}|\[::1\]|\[::ffff:(?:127(?:\.\d{1,3}){3}|7f[\da-f]{2}:[\da-f]{1,4})\]):\d+$/iu;
+
+const formatted = Option.liftThrowable(HttpServer.formatAddress);
+
+const loopbackOnly = (
+  options: ServeOptions<readonly ServedActor[]>,
+): Effect.Effect<void, ListenerNotLoopbackError, HttpServer.HttpServer> =>
+  HttpServer.HttpServer.use((server) => {
+    const address = formatted(server.address);
+
+    if (
+      options.unsafeExposeDevelopmentAuth === true ||
+      Option.exists(address, (shown) => loopbackAddress.test(shown))
+    ) {
+      return Effect.void;
+    }
+
+    const shown = Option.getOrElse(address, () => "an address it can't format");
+
+    return Effect.fail(
+      ListenerNotLoopbackError.make({
+        address: shown,
+        message: `the listener is on ${shown}, which isn't loopback; development authentication lets any caller pick its principal, so it only serves on 127.0.0.0/8, ::1 or ::ffff:127.0.0.1. Set unsafeExposeDevelopmentAuth to serve it on this address`,
+      }),
+    );
+  });
+
+const unhosted = Effect.fnUntraced(function* unhosted(actors: readonly ServedActor[]) {
+  const registry = yield* Effect.serviceOption(ActorRegistry);
+
+  if (Option.isNone(registry)) {
+    return [];
+  }
+
+  const lookups = yield* Effect.forEach(actors, (actor) => Effect.exit(registry.value.lookup(actor.name)));
+
+  return Arr.map(
+    Arr.filter(Arr.zip(actors, lookups), ([, lookup]) => Exit.isFailure(lookup)),
+    ([actor]) => actor.name,
+  );
+});
+
+const rpcRoutes = (
+  actors: readonly ServedActor[],
+): Effect.Effect<Layer.Layer<never, never, ActorHost | HttpRouter.HttpRouter>, ActorsNotHostedError> =>
+  Effect.gen(function* routes() {
+    const missing = yield* unhosted(actors);
+
+    if (Arr.isReadonlyArrayNonEmpty(missing)) {
+      return yield* ActorsNotHostedError.make({
+        actors: missing,
+        message: `no handlers for ${Arr.join(missing, ", ")}: provide each actor's toLayer to the engine`,
+      });
+    }
+
+    const group = RpcGroup.make().merge(...Arr.map(actors, (actor) => actor.rpcs));
+    const handlers = group.toLayer(servedRpcHandlers(actors));
+
+    const calls = RpcServer.layerHttp({ group, path: rpcPath, protocol: "http" }).pipe(
+      Layer.provide(RpcSerialization.layerNdjson),
+    );
+
+    const live = RpcServer.layerHttp({ group, path: rpcPath, protocol: "websocket" }).pipe(
+      Layer.provide(RpcSerialization.layerJson),
+    );
+
+    return Layer.merge(calls, live).pipe(Layer.provide([handlers, DevelopmentAuthentication]));
+  });
+
+const serve = (
+  options: ServeOptions<readonly ServedActor[]>,
+): Layer.Layer<never, ActorsNotHostedError | ListenerNotLoopbackError, ActorHost | HttpServer.HttpServer> =>
+  Layer.unwrap(
+    Effect.gen(function* makeServer() {
+      yield* loopbackOnly(options);
+
+      const routes = yield* rpcRoutes(options.actors);
+
+      return HttpRouter.serve(routes, {
+        disableListenLog: true,
+        disableLogger: true,
+        middleware: developmentGuard({
+          allowedHosts: options.allowedHosts ?? [],
+          exposed: options.unsafeExposeDevelopmentAuth === true,
+        }),
+      });
+    }),
+  );
+
+export { rpcPath, rpcRoutes, serve };
+
+export type { ServedActor } from "./served-rpc.layer.js";
+
+export type { ServeOptions };

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

@@ -0,0 +1,95 @@
+import { Boolean as Bool, Effect, Predicate, Stream } from "effect";
+
+import { CurrentCaller } from "#src/contract/caller/current-caller.service";
+import { InvalidRequestError } from "#src/contract/client/invalid-request.errors";
+import { ComputerFileRequest, computerFileBytes } from "#src/contract/computer/files/computer-files.schema";
+import type { ComputerCopy, ComputerCopyResult } from "#src/contract/computer/files/computer-files.schema";
+import type { ComputerClient, ComputerClientFailure } from "#src/contract/computer/computer-client.contract";
+import { filePathOf } from "#src/contract/file/file-path.pure";
+import { hostFileClient } from "#src/runtime/local-file-clients.layer";
+import type { ActorHost } from "#src/serve/engine/actor-host.service";
+import { ownerOf } from "#src/serve/rpc/file/file-rpc-access.pure";
+import type { FileActor } from "#src/serve/rpc/file/file-rpc-access.pure";
+
+const invalid = (actor: string, message: string): InvalidRequestError => InvalidRequestError.make({ actor, message });
+
+const collect = <Failure, Services>(
+  actor: string,
+  source: Stream.Stream<Uint8Array, Failure, Services>,
+): Effect.Effect<Uint8Array, Failure | InvalidRequestError, Services> =>
+  Stream.runFoldEffect(
+    source,
+    () => new Uint8Array(),
+    (before, chunk) => {
+      if (before.byteLength + chunk.byteLength > computerFileBytes) {
+        return Effect.fail(invalid(actor, "a computer file holds at most 1 MiB"));
+      }
+
+      const joined = new Uint8Array(before.byteLength + chunk.byteLength);
+
+      joined.set(before);
+      joined.set(chunk, before.byteLength);
+
+      return Effect.succeed(joined);
+    },
+  );
+
+interface Copying {
+  readonly actor: FileActor;
+  readonly client: ComputerClient;
+  readonly host: ActorHost["Service"];
+  readonly request: ComputerCopy;
+}
+
+const transfer = Effect.fnUntraced(function* transfer(
+  { actor, client, request }: Copying,
+  files: ReturnType<typeof hostFileClient>,
+) {
+  const computerPath = yield* filePathOf(request.computerPath);
+
+  if (request.direction === "toComputer") {
+    const content = yield* collect(actor.name, files.download(request.path));
+
+    yield* client.files(request.computer, ComputerFileRequest.cases.Write.make({ content, path: computerPath }));
+
+    return { bytes: content.byteLength } satisfies ComputerCopyResult;
+  }
+
+  const content = yield* client.files(request.computer, ComputerFileRequest.cases.Read.make({ path: computerPath }));
+  const receipt = yield* files.upload(Stream.make(content));
+
+  return { bytes: content.byteLength, receipt } satisfies ComputerCopyResult;
+});
+
+/** Both directions pass the actor's file authorization rule; a copy never bypasses a command to attach a file. */
+const copyComputerFile = Effect.fnUntraced(
+  function* copyComputerFile(copying: Copying) {
+    const { actor, host, request } = copying;
+    const caller = yield* CurrentCaller;
+    const path = yield* filePathOf(request.path);
+
+    const access = Bool.match(request.direction === "toComputer", {
+      onFalse: () => "write" as const,
+      onTrue: () => "read" as const,
+    });
+
+    const asked = { access, path };
+    const { address } = yield* ownerOf({ actor, asked, caller, host, key: request.key });
+
+    return yield* transfer({ ...copying, request: { ...request, path } }, hostFileClient({ address, host }));
+  },
+  Effect.mapError((failure): ComputerClientFailure => {
+    if (
+      Predicate.isTagged(failure, "ComputersUnavailableError") ||
+      Predicate.isTagged(failure, "ComputerHeldError") ||
+      Predicate.isTagged(failure, "ComputerNotFoundError") ||
+      Predicate.isTagged(failure, "ComputerLostError")
+    ) {
+      return failure;
+    }
+
+    return invalid("computer", failure.message);
+  }),
+);
+
+export { copyComputerFile };