ignotum 0.0.13 → 0.0.15

package/src/dev-runtime/managed-sync.ts

@@ -0,0 +1,263 @@
+import { canonicalInvocationInput } from "@ignotum/contracts/runtime/hosted";
+import { ManagedClientMessage, ManagedServerMessage } from "@ignotum/contracts/managed-sync";
+import {
+  sameExecutionSelection,
+  ExecutionSelection,
+  type RecoveryIdentity,
+  type RecoverySessionId,
+} from "@ignotum/contracts/platform";
+import { idViewKey, type SessionState } from "@ignotum/contracts/id";
+import type { ViteDevServer } from "vite";
+import { Clock, Deferred, Effect, PubSub, Schema, Semaphore } from "effect";
+import { SqlClient } from "effect/unstable/sql";
+import * as Socket from "effect/unstable/socket/Socket";
+import { LocalApplicationFiles } from "./files.js";
+import { MutationReplay, QueryInvalidation, createLocalSession } from "./sync.js";
+
+export interface ManagedSyncOptions {
+  readonly selection: () => ExecutionSelection;
+  readonly loadModule?: ViteDevServer["ssrLoadModule"];
+  readonly isServerDependency?: (file: string) => boolean;
+  readonly beforeReload?: (file: string, event: "add" | "change" | "unlink") => Promise<void>;
+}
+
+/** Native managed protocol framing, selection fencing, and durable invocation ownership. */
+export const runManagedSession = Effect.fn("ManagedLocalSync.runSession")(function* (
+  socket: Socket.Socket,
+  options: ManagedSyncOptions,
+  identity: SessionState,
+  refreshIdentity?: Effect.Effect<SessionState>,
+) {
+  const sql = yield* SqlClient.SqlClient;
+  const files = yield* LocalApplicationFiles;
+  const preparations = new Set<import("@ignotum/contracts/runtime/hosted").InvocationId>();
+  const shutdown = yield* Deferred.make<void>();
+  const replays = yield* MutationReplay;
+  const invalidation = yield* QueryInvalidation;
+  const write = yield* socket.writer;
+  const writes = yield* Semaphore.make(1);
+  const messages = yield* Semaphore.make(1);
+  let selection: ExecutionSelection | undefined;
+  let session: Effect.Success<ReturnType<typeof createLocalSession>> | undefined;
+  let clientSessionId: RecoverySessionId | undefined;
+  let expired = false;
+  const send = (message: ManagedServerMessage) =>
+    writes.withPermits(1)(
+      Schema.encodeEffect(Schema.fromJsonString(ManagedServerMessage))(message).pipe(
+        Effect.orDie,
+        Effect.flatMap(write),
+      ),
+    );
+  const error = (
+    code:
+      | "InvalidMessage"
+      | "SessionExpired"
+      | "InvocationIdConflict"
+      | "Unavailable"
+      | "InvalidArguments",
+    message: string,
+    id?: string,
+  ) =>
+    send(
+      id === undefined ? { type: "Error", code, message } : { type: "Error", code, message, id },
+    );
+  const close = Effect.gen(function* () {
+    expired = true;
+    yield* write(new Socket.CloseEvent(1000, "Local managed session ended")).pipe(
+      Effect.ensuring(Deferred.succeed(shutdown, undefined)),
+    );
+  });
+  const checkSelection = Effect.fn("ManagedLocalSync.checkSelection")(function* () {
+    if (expired) return false;
+    if (selection === undefined || sameExecutionSelection(selection, options.selection()))
+      return true;
+    expired = true;
+    yield* send({ type: "UpgradeRequired", selection: options.selection() });
+    yield* close;
+    return false;
+  });
+  const checkIdentity = Effect.fn("ManagedLocalSync.checkIdentity")(function* () {
+    if (expired) return false;
+    const current = refreshIdentity === undefined ? identity : yield* refreshIdentity;
+    if (
+      current.sessionEpoch === identity.sessionEpoch &&
+      idViewKey(current) === idViewKey(identity) &&
+      current.validUntil > (yield* Clock.currentTimeMillis)
+    )
+      return true;
+    expired = true;
+    yield* error("SessionExpired", "The local ID session changed or expired.");
+    yield* close;
+    return false;
+  });
+  const events = yield* invalidation.subscribe;
+  yield* PubSub.take(events).pipe(
+    Effect.andThen(checkSelection()),
+    Effect.flatMap((current) => (current ? checkIdentity() : Effect.succeed(false))),
+    Effect.forever,
+    Effect.forkScoped,
+  );
+  const ownerRows = (invocationId: string) =>
+    sql<{
+      input: string;
+      prepared: number;
+      clientSessionId: string;
+      sessionEpoch: string;
+      selection: string;
+    }>`SELECT input, prepared, clientSessionId, sessionEpoch, selection FROM managed_invocation_owners WHERE id = ${invocationId}`;
+  const owns = (
+    row: { clientSessionId: string; sessionEpoch: string; selection: string },
+    original: ExecutionSelection,
+  ) =>
+    row.clientSessionId === clientSessionId &&
+    row.sessionEpoch === identity.sessionEpoch &&
+    sameExecutionSelection(
+      Schema.decodeSync(Schema.fromJsonString(ExecutionSelection))(row.selection),
+      original,
+    );
+  const outcome = Effect.fn("ManagedLocalSync.outcome")(function* (
+    id: string,
+    recovery: RecoveryIdentity,
+  ) {
+    if (
+      selection === undefined ||
+      recovery.originalSelection.appId !== selection.appId ||
+      recovery.originalSelection.dataHistoryId !== selection.dataHistoryId
+    ) {
+      yield* error(
+        "Unavailable",
+        "This recovery record belongs to another application data history.",
+        id,
+      );
+      return;
+    }
+    const rows = yield* ownerRows(recovery.invocationId).pipe(Effect.orDie);
+    if (rows[0] === undefined || !owns(rows[0], recovery.originalSelection)) {
+      yield* error("SessionExpired", "This session does not own the mutation recovery record.", id);
+      return;
+    }
+    const result = yield* replays.lookup(recovery.invocationId).pipe(Effect.orDie);
+    yield* send({
+      type: "MutationOutcome",
+      id,
+      identity: recovery,
+      outcome: result === undefined ? { type: "Uncertain" } : { type: "Settled", result },
+    });
+  });
+  const deliver = Effect.fn("ManagedLocalSync.deliver")(function* (message: ManagedServerMessage) {
+    if (!(yield* checkSelection()) || !(yield* checkIdentity())) return;
+    yield* send(message);
+  });
+  yield* Effect.addFinalizer(() =>
+    Effect.forEach(preparations, (id) => files.releasePreparation(id)),
+  );
+  yield* socket
+    .runString((text) =>
+      messages.withPermits(1)(
+        Effect.gen(function* () {
+          const message = yield* Schema.decodeEffect(Schema.fromJsonString(ManagedClientMessage))(
+            text,
+          ).pipe(
+            Effect.catch(() =>
+              error("InvalidMessage", "The frame is not valid managed sync JSON."),
+            ),
+          );
+          if (message === undefined) return;
+          if (message.type === "Connect") {
+            if (selection !== undefined)
+              return yield* error("InvalidMessage", "Connect has already been accepted.");
+            const current = options.selection();
+            if (
+              message.protocolVersion !== 1 ||
+              !sameExecutionSelection(message.selection, current)
+            ) {
+              yield* send({ type: "UpgradeRequired", selection: current });
+              return;
+            }
+            if (!(yield* checkIdentity())) return;
+            selection = current;
+            clientSessionId = message.clientSessionId;
+            session = yield* createLocalSession(current, identity, deliver);
+            yield* send({
+              type: "Handshake",
+              protocolVersion: 1,
+              selection,
+              session: identity,
+              serverTime: yield* Clock.currentTimeMillis,
+            });
+            return;
+          }
+          if (selection === undefined || session === undefined)
+            return yield* error("InvalidMessage", "Connect must be accepted first.");
+          if (expired || !(yield* checkSelection())) return;
+          if (!(yield* checkIdentity())) return;
+          if (message.type === "RecoverMutation")
+            return yield* outcome(message.id, message.identity);
+          if (message.type === "Invoke" || message.type === "Prepare") {
+            const input = canonicalInvocationInput(
+              selection.versionId,
+              "Mutation",
+              message.function,
+              message.args,
+              identity.sessionEpoch,
+            );
+            const rows = yield* ownerRows(message.invocationId).pipe(Effect.orDie);
+            if (rows[0] !== undefined && (!owns(rows[0], selection) || rows[0].input !== input))
+              return yield* error(
+                "InvocationIdConflict",
+                "This invocation belongs to another input, selection or session.",
+                message.invocationId,
+              );
+            if (
+              rows[0] === undefined &&
+              (yield* replays.lookup(message.invocationId).pipe(Effect.orDie)) !== undefined
+            )
+              return yield* error(
+                "InvocationIdConflict",
+                "This invocation already exists outside this managed session.",
+                message.invocationId,
+              );
+            const encodedSelection = yield* Schema.encodeEffect(
+              Schema.fromJsonString(ExecutionSelection),
+            )(selection).pipe(Effect.orDie);
+            const inserted =
+              yield* sql`INSERT OR IGNORE INTO managed_invocation_owners (id, input, prepared, clientSessionId, sessionEpoch, selection) VALUES (${message.invocationId}, ${input}, ${message.type === "Prepare" ? 1 : 0}, ${clientSessionId!}, ${identity.sessionEpoch}, ${encodedSelection}) RETURNING id`.pipe(
+                Effect.orDie,
+              );
+            const admitted = yield* ownerRows(message.invocationId).pipe(Effect.orDie);
+            if (
+              admitted[0] === undefined ||
+              admitted[0].input !== input ||
+              !owns(admitted[0], selection)
+            )
+              return yield* error(
+                "InvocationIdConflict",
+                "This invocation belongs to another session.",
+                message.invocationId,
+              );
+            if (inserted.length === 0) {
+              if (admitted[0].prepared === 0)
+                return yield* outcome(message.invocationId, {
+                  invocationId: message.invocationId,
+                  originalSelection: selection,
+                });
+              if (message.type === "Invoke") {
+                const claimed =
+                  yield* sql`UPDATE managed_invocation_owners SET prepared = 0 WHERE id = ${message.invocationId} AND prepared = 1 RETURNING id`.pipe(
+                    Effect.orDie,
+                  );
+                if (claimed.length === 0)
+                  return yield* outcome(message.invocationId, {
+                    invocationId: message.invocationId,
+                    originalSelection: selection,
+                  });
+              }
+            }
+            preparations.add(message.invocationId);
+          }
+          yield* session.handle(message);
+        }),
+      ),
+    )
+    .pipe(Effect.raceFirst(Deferred.await(shutdown)));
+}, Effect.scoped);

package/src/dev-runtime/managed-websocket.ts

@@ -0,0 +1,71 @@
+// @effect-diagnostics-next-line nodeBuiltinImport:off Vite supplies Node HTTP upgrade requests.
+import type { IncomingMessage } from "node:http";
+// @effect-diagnostics-next-line nodeBuiltinImport:off Vite supplies the raw Node upgrade socket.
+import type { Duplex } from "node:stream";
+import { NodeSocket } from "@effect/platform-node";
+import { Cause, Context, Effect, FiberSet, Function, Layer } from "effect";
+import * as Socket from "effect/unstable/socket/Socket";
+
+/** Owns upgraded sessions without sending an HTTP response when a session ends. */
+const makeManagedWebSocketUpgradeHandler = Effect.fn("ManagedWebSocket.makeUpgradeHandler")(
+  function* <E, R>(
+    server: NodeSocket.NodeWS.WebSocketServer,
+    handle: (socket: Socket.Socket, request: IncomingMessage) => Effect.Effect<void, E, R>,
+  ) {
+    const run = yield* FiberSet.makeRuntime<R>();
+    return (request: IncomingMessage, raw: Duplex, head: Buffer): void => {
+      const session = Effect.gen(function* () {
+        const socket = yield* Socket.fromWebSocket(
+          Effect.acquireRelease(
+            Effect.callback<globalThis.WebSocket>((resume) => {
+              server.handleUpgrade(request, raw, head, (webSocket) => {
+                // SAFETY: Effect's NodeSocket layer uses this same NodeWS/DOM bridge. Socket.fromWebSocket consumes compatible events, send and close methods.
+                // eslint-disable-next-line anti-slop/no-chained-type-assertions
+                resume(Effect.succeed(webSocket as unknown as globalThis.WebSocket));
+              });
+            }),
+            (webSocket) => Effect.sync(() => webSocket.close()),
+          ),
+          { closeCodeIsError: Function.constFalse },
+        );
+        yield* handle(socket, request);
+      }).pipe(
+        Effect.scoped,
+        Effect.catchCause((cause) =>
+          Cause.hasInterruptsOnly(cause)
+            ? Effect.void
+            : Effect.logError("A managed local WebSocket session failed.").pipe(
+                Effect.annotateLogs({ cause }),
+              ),
+        ),
+      );
+      const fiber = run(session);
+      const onClose = () => fiber.interruptUnsafe();
+      raw.on("error", Function.constVoid);
+      raw.once("close", onClose);
+      fiber.addObserver(() => {
+        raw.off("error", Function.constVoid);
+        raw.off("close", onClose);
+      });
+    };
+  },
+);
+
+export class ManagedWebSocket extends Context.Service<
+  ManagedWebSocket,
+  {
+    readonly upgrade: (request: IncomingMessage, socket: Duplex, head: Buffer) => void;
+  }
+>()("ignotum/dev-runtime/managed-websocket/ManagedWebSocket") {
+  static layer<E, R>(
+    server: NodeSocket.NodeWS.WebSocketServer,
+    handle: (socket: Socket.Socket, request: IncomingMessage) => Effect.Effect<void, E, R>,
+  ) {
+    return Layer.effect(
+      ManagedWebSocket,
+      makeManagedWebSocketUpgradeHandler(server, handle).pipe(
+        Effect.map((upgrade) => ManagedWebSocket.of({ upgrade })),
+      ),
+    );
+  }
+}

package/src/dev-runtime/migrations.ts

@@ -88,10 +88,30 @@ const addApplicationFiles = Effect.gen(function* () {
   `;
 });
 
+const addSchemaState = Effect.gen(function* () {
+  const sql = yield* SqlClient.SqlClient;
+  yield* sql`CREATE TABLE schema_state (
+    singleton INTEGER PRIMARY KEY NOT NULL CHECK (singleton = 1),
+    snapshot TEXT NOT NULL CHECK (json_valid(snapshot))
+  ) STRICT`;
+});
+
 export const developmentMigrationLoader = Migrator.fromRecord({
   "0001_initial_development_schema": initialDevelopmentSchema,
   "0002_application_indexes": addDevelopmentIndexes,
   "0003_application_files": addApplicationFiles,
+  "0004_schema_state": addSchemaState,
+  "0005_managed_invocation_owners": Effect.gen(function* () {
+    const sql = yield* SqlClient.SqlClient;
+    yield* sql`CREATE TABLE managed_invocation_owners (
+      id TEXT PRIMARY KEY NOT NULL,
+      input TEXT NOT NULL,
+      prepared INTEGER NOT NULL DEFAULT 0 CHECK (prepared IN (0, 1)),
+      clientSessionId TEXT NOT NULL,
+      sessionEpoch TEXT NOT NULL,
+      selection TEXT NOT NULL CHECK (json_valid(selection))
+    ) STRICT`;
+  }),
 });
 
 interface DevelopmentDatabaseService {