@akterjs/effect 0.0.0-stage → 0.1.1

package/src/serve/engine/actor-fork.service.ts

@@ -0,0 +1,403 @@
+import { Array as Arr, Context, Effect, FileSystem, Option, Semaphore } from "effect";
+
+import {
+  ActorAlreadyExistsError,
+  ActorNotCreatedError,
+  InvalidRequestError,
+} from "#src/contract/client/client-failure.contract";
+import { ActorDatabase } from "#src/host/actor/actor-database.service";
+import type { OpenedActor } from "#src/host/actor/actor-database.service";
+import { LocalBlobHomes } from "#src/host/file/local-blob-home.service";
+import { ForkComputers } from "#src/host/fork/fork-computers.adapter";
+import type { ComputersFork, Held } from "#src/host/fork/fork-computers.adapter";
+import {
+  forkedFiles,
+  forkIdOf,
+  markPublished,
+  prepareForks,
+  quietCopy,
+  recordedFork,
+  recordIntent,
+} from "#src/host/fork/actor-fork.sql";
+import { committedVersion } from "#src/serve/live/live-tables.sql";
+
+import { ActorLocation } from "./actor-location.service.js";
+import type { ActorAddress, ActorFiles, StagedFork } from "./actor-location.service.js";
+import { unavailable } from "./actor-residents.pure.js";
+import type { OpenFailure, Residents } from "./actor-residents.pure.js";
+
+interface ForkCall extends ActorAddress {
+  readonly commandId: string;
+  readonly into: string;
+}
+
+interface ForkResident {
+  readonly exclusive: <Success, Failure, Needs>(
+    effect: Effect.Effect<Success, Failure, Needs>,
+  ) => Effect.Effect<Success, Failure, Needs>;
+  readonly forking: Semaphore.Semaphore;
+  readonly opened: OpenedActor;
+}
+
+/** What the fork needs from the host that runs it. */
+interface ForkHost<Resident extends ForkResident> {
+  readonly identity: (address: ActorAddress) => string;
+  readonly residents: Residents<Resident>;
+  readonly served: (address: ActorAddress) => Effect.Effect<OpenedActor["actor"], OpenFailure>;
+  readonly stored: (address: ActorAddress) => Effect.Effect<boolean, OpenFailure>;
+}
+
+interface Forking {
+  readonly call: ForkCall;
+  readonly child: ActorAddress;
+  readonly host: ForkHost<ForkResident>;
+  readonly resident: ForkResident;
+  readonly staged: ActorFiles;
+}
+
+type ForkFailure = ActorAlreadyExistsError | ActorNotCreatedError | InvalidRequestError | OpenFailure;
+
+type ForkServices = ActorDatabase | ActorLocation | FileSystem.FileSystem | ForkComputers;
+
+const oneFork = 1;
+
+const reused = ({ actor, commandId }: ForkCall): InvalidRequestError =>
+  InvalidRequestError.make({ actor, message: `the fork id ${commandId} already forked this actor into another key` });
+
+/** The fork the parent recorded under this id, if any; the same id can't name a fork into another key. */
+const recorded = Effect.fnUntraced(function* recorded({ call, resident }: Forking) {
+  const { sql } = resident.opened;
+
+  const found = yield* resident.exclusive(
+    Effect.andThen(prepareForks(sql), recordedFork({ commandId: call.commandId, sql })),
+  );
+
+  if (Option.isSome(found) && found.value.child !== call.into) {
+    return yield* reused(call);
+  }
+
+  return found;
+});
+
+/** The fork's computers: the parent's, copied into the child under the store's computers directory. */
+const computersOf = ({
+  call,
+  child,
+}: Pick<Forking, "call" | "child">): Effect.Effect<ComputersFork, never, ActorLocation> =>
+  ActorLocation.use((location) =>
+    Effect.succeed({
+      child,
+      fork: call.commandId,
+      parent: { actor: call.actor, key: call.key },
+      root: location.computers,
+    }),
+  );
+
+/** Whether the child is already this fork's, published before a crash or a lost reply; any other child refuses. */
+const publishedChild = Effect.fnUntraced(function* publishedChild({ call, child, host }: Forking) {
+  if (!(yield* host.stored(child))) {
+    return false;
+  }
+
+  const { database } = yield* ActorLocation.use((location) => Effect.succeed(location.locate(child)));
+  const databases = yield* ActorDatabase;
+  const forkId = yield* Effect.scoped(Effect.flatMap(databases.openCopy(database), forkIdOf));
+
+  if (Option.contains(forkId, call.commandId)) {
+    return true;
+  }
+
+  return yield* ActorAlreadyExistsError.make({ actor: call.actor });
+});
+
+/**
+ * Removes what an unfinished attempt of this fork left: its staged copy, and the files it claimed for the child. A
+ * child that is stored keeps its claims, and so does one whose catalog row doesn't name this parent: either is an
+ * actor of its own. Akter dev keeps every actor's files in one home, so the parent's home is the child's.
+ */
+const discardStaged = Effect.fnUntraced(function* discardStaged(forking: Forking) {
+  const { call, child, host, resident, staged } = forking;
+  const fileSystem = yield* FileSystem.FileSystem;
+  const files = Option.fromNullishOr(resident.opened.fileSession);
+  const stored = yield* host.stored(child);
+
+  if (Option.isSome(files) && !stored) {
+    yield* files.value.home.catalog.abandon({ actor: host.identity(child), origin: host.identity(call) });
+  }
+
+  if (!stored) {
+    const computers = yield* computersOf(forking);
+
+    yield* ForkComputers.use((forked) => forked.discard(computers));
+  }
+
+  yield* fileSystem.remove(staged.directory, { force: true, recursive: true });
+});
+
+/** Copies the parent at one cut between two of its commands, after recording the fork's intent. */
+const cut = Effect.fnUntraced(function* cut({ call, resident, staged }: Forking) {
+  const { sql } = resident.opened;
+  const fileSystem = yield* FileSystem.FileSystem;
+
+  const cutParent = Effect.gen(function* cutParent() {
+    const version = yield* committedVersion(sql);
+
+    yield* recordIntent({ commandId: call.commandId, into: call.into, sql, version });
+    yield* fileSystem.makeDirectory(staged.directory, { recursive: true });
+    yield* sql`VACUUM INTO ${staged.database}`;
+
+    return version;
+  });
+
+  return yield* resident.exclusive(cutParent);
+});
+
+const quiet = Effect.fnUntraced(function* quiet({ call, staged }: Forking, version: number) {
+  const databases = yield* ActorDatabase;
+  const lineage = { forkId: call.commandId, origin: ActorLocation.named(call), version };
+
+  yield* Effect.scoped(Effect.flatMap(databases.openCopy(staged.database), (sql) => quietCopy({ ...lineage, sql })));
+});
+
+const unavailableBy =
+  (actor: string) =>
+  (failure: { readonly message: string }): OpenFailure =>
+    unavailable(actor)({ message: `the fork didn't finish: ${failure.message}` });
+
+/** Inherits the parent's files at the cut into the staged child, under the child's own claims and grants. */
+const forkFiles = Effect.fnUntraced(function* forkFiles({ call, child, host, resident, staged }: Forking) {
+  const files = Option.fromNullishOr(resident.opened.fileSession);
+
+  if (Option.isNone(files)) {
+    return;
+  }
+
+  const actor = yield* host.served(child);
+  const databases = yield* ActorDatabase;
+  const opening = { actor, filename: staged.database, identity: host.identity(child) };
+
+  yield* Effect.scoped(
+    Effect.gen(function* inheritFiles() {
+      const opened = yield* Effect.mapError(databases.open(opening), unavailableBy(call.actor));
+      const target = yield* Effect.orDie(Effect.fromNullishOr(opened.fileSession));
+      const source = files.value;
+
+      yield* source.home.transfers.fork({
+        into: target.home,
+        operation: call.commandId,
+        source: source.owner,
+        target: target.owner,
+      });
+    }),
+  );
+});
+
+const publish = Effect.fnUntraced(function* publish({ call, child, resident, staged }: Forking) {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const { directory } = yield* ActorLocation.use((location) => Effect.succeed(location.locate(child)));
+
+  yield* fileSystem.rename(staged.directory, directory);
+  yield* resident.exclusive(markPublished({ commandId: call.commandId, sql: resident.opened.sql }));
+});
+
+const copy = Effect.fnUntraced(function* copy(forking: Forking, computers: ComputersFork, held: readonly Held[]) {
+  const version = yield* cut(forking);
+
+  yield* quiet(forking, version);
+  yield* forkFiles(forking);
+  yield* ForkComputers.use((forked) => forked.copy({ ...computers, held }));
+  yield* publish(forking);
+
+  return version;
+});
+
+/**
+ * Builds the child: holds the parent's computers, so none changes from before the cut until the child has its copy
+ * of each, cuts and copies, publishes, then lets go of them. A failure lets go of them too.
+ */
+const build = Effect.fnUntraced(function* build(forking: Forking) {
+  yield* discardStaged(forking);
+
+  const computers = yield* computersOf(forking);
+  const forked = yield* ForkComputers;
+  const held = yield* forked.hold(computers);
+  const releasing = { ...computers, held: Option.some(held) };
+  const released = Effect.ignore(forked.release(releasing));
+  const version = yield* Effect.onError(copy(forking, computers, held), () => released);
+
+  yield* forked.settle(releasing);
+
+  return version;
+});
+
+/** Lets go of the parent's computers again for a fork its parent or child shows published before a crash. */
+const settledAgain = (forking: Forking): Effect.Effect<void, OpenFailure, ForkServices> =>
+  Effect.flatMap(Effect.all([computersOf(forking), ForkComputers]), ([computers, forked]) =>
+    forked.settle({ ...computers, held: Option.none() }),
+  );
+
+/**
+ * One fork, under the parent's fork gate so no command commits between the cut and the copy of its files. A fork the
+ * parent already published answers its version again. Otherwise the child is built beside its directory and appears
+ * by one rename, so nothing reads a partial child; a failed attempt removes what it built, and a retry rebuilds it.
+ */
+const forkHeld = Effect.fnUntraced(function* forkHeld(forking: Forking) {
+  const found = yield* recorded(forking);
+  const settled = settledAgain(forking);
+
+  if (Option.isSome(found) && found.value.state === "published") {
+    yield* settled;
+
+    return found.value.version;
+  }
+
+  if (yield* publishedChild(forking)) {
+    yield* forking.resident.exclusive(
+      markPublished({ commandId: forking.call.commandId, sql: forking.resident.opened.sql }),
+    );
+    yield* settled;
+
+    return yield* Effect.map(Effect.orDie(Effect.fromOption(found)), (record) => record.version);
+  }
+
+  return yield* build(forking).pipe(Effect.onError(() => Effect.ignore(discardStaged(forking))));
+});
+
+/** The one copy a fork makes, answered as a fork's failures: a storage or file failure is a retryable unavailable. */
+const forkOnce = Effect.fnUntraced(function* forkOnce(forking: Forking) {
+  const unfinished = unavailableBy(forking.call.actor);
+
+  return yield* forkHeld(forking).pipe(
+    Effect.catchTags({
+      BlobTransferError: (failure) => Effect.fail(unfinished(failure)),
+      PlatformError: (failure) => Effect.fail(unfinished(failure)),
+      SqlError: (failure) => Effect.fail(unfinished(failure)),
+    }),
+  );
+});
+
+/**
+ * Forks actors on one host. Forks run one at a time, so two forks can't both find a child key free and publish into
+ * it; each holds its parent's fork gate from the cut until the child has its files, and holds the child's address
+ * from the check that it's free until the copy is renamed into place, so no command or upload creates the child
+ * meanwhile.
+ */
+const forkedBy = <Resident extends ForkResident>(
+  host: ForkHost<Resident>,
+): ((call: ForkCall) => Effect.Effect<number, ForkFailure, ForkServices>) => {
+  const serial = Semaphore.makeUnsafe(oneFork);
+
+  return Effect.fnUntraced(function* forkActor(call: ForkCall) {
+    const child = { actor: call.actor, key: call.into };
+
+    if (call.into === call.key) {
+      return yield* InvalidRequestError.make({ actor: call.actor, message: "an actor can't fork into itself" });
+    }
+
+    if (!(yield* host.stored(call))) {
+      return yield* ActorNotCreatedError.make({ actor: call.actor });
+    }
+
+    const staged = yield* ActorLocation.use((location) =>
+      Effect.succeed(location.stage({ address: child, fork: call.commandId })),
+    );
+
+    return yield* serial.withPermits(oneFork)(
+      host.residents.use(call, (resident) =>
+        forkOnce({ call, child, host, resident, staged }).pipe(
+          host.residents.holding(child),
+          resident.forking.withPermits(oneFork),
+        ),
+      ),
+    );
+  });
+};
+
+type Homes = Option.Option<LocalBlobHomes["Service"]>;
+
+/** The file fork a staged copy began, if it was quieted as this fork and its files were forked. */
+const forkedIn = Effect.fnUntraced(function* forkedIn({ files, fork }: StagedFork) {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const databases = yield* ActorDatabase;
+
+  if (!(yield* fileSystem.exists(files.database))) {
+    return Option.none();
+  }
+
+  const read = Effect.flatMap(databases.openCopy(files.database), (sql) =>
+    Effect.flatMap(forkIdOf(sql), (forkId) => {
+      if (!Option.contains(forkId, fork)) {
+        return Effect.succeedNone;
+      }
+
+      return forkedFiles(sql);
+    }),
+  );
+
+  return yield* Effect.scoped(read);
+});
+
+type SweepFailure = Effect.Error<ReturnType<typeof forkedIn>> | Effect.Error<LocalBlobHomes["Service"]["get"]>;
+
+const sweepWith = (
+  homes: Homes,
+  stored: ReadonlySet<string>,
+): ((staged: StagedFork) => Effect.Effect<void, SweepFailure, ForkServices>) =>
+  Effect.fnUntraced(function* sweepOne(staged: StagedFork) {
+    const fileSystem = yield* FileSystem.FileSystem;
+    const forked = yield* forkedIn(staged);
+    const claimed = Option.filter(forked, (files) => !stored.has(files.actor));
+
+    if (Option.isSome(claimed) && Option.isSome(homes)) {
+      const home = yield* homes.value.get;
+
+      yield* home.catalog.abandon(claimed.value);
+    }
+
+    yield* fileSystem.remove(staged.files.directory, { force: true, recursive: true });
+  });
+
+/**
+ * Sweeps what forks that crashed before publishing left, when a host starts and before it forks or opens an actor:
+ * each staged copy, and the claims it took for a child that isn't stored and whose catalog row names the fork's
+ * parent. A retry of such a fork rebuilds it from its parent's intent.
+ */
+const sweepStaged = Effect.fnUntraced(function* sweepStaged(identity: (address: ActorAddress) => string) {
+  const location = yield* ActorLocation;
+  const staged = yield* location.staged;
+  const named = Effect.map(location.list, (actors) => new Set(Arr.map(actors, ActorLocation.named)));
+
+  yield* ForkComputers.use((forked) => forked.sweep(location.computers, named));
+
+  if (!Arr.isReadonlyArrayNonEmpty(staged)) {
+    return;
+  }
+
+  const actors = yield* location.list;
+  const stored = new Set(Arr.map(actors, identity));
+  const homes = yield* Effect.serviceOption(LocalBlobHomes);
+
+  yield* Effect.forEach(staged, sweepWith(homes, stored), { discard: true });
+});
+
+/**
+ * Forks a stored actor into a new key at a cut between two of its commits. `forkedBy(host)` makes the fork route of
+ * one host; the copy starts quiet and is published by one rename. `sweepStaged` clears what crashed forks left.
+ */
+export class ActorForks extends Context.Service<
+  ActorForks,
+  {
+    readonly computers: typeof ForkComputers.layer;
+    readonly forkedBy: typeof forkedBy;
+    readonly sweepStaged: typeof sweepStaged;
+  }
+>()("@akterjs/effect/serve/engine/actor-fork.service/ActorForks") {
+  public static readonly forkedBy = forkedBy;
+
+  public static readonly sweepStaged = sweepStaged;
+
+  /** The fork's computers, which the host provides to its fork route and its sweep. */
+  public static readonly computers = ForkComputers.layer;
+}
+
+export type { ForkCall, ForkFailure, ForkResident, ForkServices };

package/src/serve/engine/actor-holding.pure.ts

@@ -0,0 +1,28 @@
+import { Effect, RcMap, Scope, Semaphore } from "effect";
+
+import type { ActorAddress } from "./actor-location.service.js";
+
+/** Runs an effect while no resident opens at the address, so nothing creates its database meanwhile. */
+type Holding = (
+  address: ActorAddress,
+) => <Value, Failure, Needs>(effect: Effect.Effect<Value, Failure, Needs>) => Effect.Effect<Value, Failure, Needs>;
+
+const onePermit = 1;
+
+/** One lock per address while anything holds it, so opening one actor never waits on another's. */
+const addressHolding = (idOf: (address: ActorAddress) => string): Effect.Effect<Holding, never, Scope.Scope> =>
+  Effect.map(
+    RcMap.make({ lookup: (_id: string) => Semaphore.make(onePermit) }),
+    (locks): Holding =>
+      (address) =>
+      (effect) =>
+        Effect.scopedWith((scope) => {
+          const lock = Scope.provide(RcMap.get(locks, idOf(address)), scope);
+
+          return Effect.flatMap(lock, (held) => held.withPermits(onePermit)(effect));
+        }),
+  );
+
+export { addressHolding };
+
+export type { Holding };