@hraness/slopcamera 3.2.4

package/apps/desktop/code/worker-protocol.ts

@@ -0,0 +1,211 @@
+import { z } from "zod";
+
+import { ApplicationError } from "../application/errors";
+import {
+  ComputeKeySchema,
+  JsonValueSchema,
+  NodeKeySchema,
+  OperationDiscoverySchema,
+} from "./contracts";
+
+export const CODE_WORKER_PROTOCOL = "slopcamera.code-worker/v5";
+export const MAX_CODE_WORKER_FRAME_BYTES = 4 * 1024 * 1024;
+
+const IdentifierSchema = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u);
+const DigestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
+
+export const CodeWorkerHelloSchema = z.strictObject({
+  bunRevision: z.string().regex(/^[a-f0-9]{40}$/u),
+  bunVersion: z.string().min(1).max(128),
+  bundleSha256: DigestSchema,
+  generation: z.number().int().safe().positive(),
+  kind: z.literal("hello"),
+  protocol: z.literal(CODE_WORKER_PROTOCOL),
+  workerEntrySha256: DigestSchema,
+});
+
+export const CodeWorkerRequestSchema = z.discriminatedUnion("action", [
+  z.strictObject({
+    action: z.literal("build"),
+    generation: z.number().int().safe().positive(),
+    inputMode: z.enum(["raw", "parsed"]),
+    kind: z.literal("request"),
+    protocol: z.literal(CODE_WORKER_PROTOCOL),
+    registry: z.array(OperationDiscoverySchema).max(1_024),
+    requestId: IdentifierSchema,
+    workflowInput: JsonValueSchema,
+  }),
+  z.strictObject({
+    action: z.literal("compute"),
+    computeKey: ComputeKeySchema,
+    generation: z.number().int().safe().positive(),
+    input: JsonValueSchema,
+    kind: z.literal("request"),
+    nodeKey: NodeKeySchema,
+    protocol: z.literal(CODE_WORKER_PROTOCOL),
+    replayAcknowledged: z.boolean(),
+    requestId: IdentifierSchema,
+  }),
+  z.strictObject({
+    action: z.literal("cancel"),
+    generation: z.number().int().safe().positive(),
+    kind: z.literal("request"),
+    protocol: z.literal(CODE_WORKER_PROTOCOL),
+    requestId: IdentifierSchema,
+    targetRequestId: IdentifierSchema,
+  }),
+  z.strictObject({
+    action: z.literal("shutdown"),
+    generation: z.number().int().safe().positive(),
+    kind: z.literal("request"),
+    protocol: z.literal(CODE_WORKER_PROTOCOL),
+    requestId: IdentifierSchema,
+  }),
+]);
+
+const CodeWorkerErrorSchema = z.strictObject({
+  code: z.enum(["invalid-request", "invalid-output", "unknown-compute", "execution", "cancelled", "internal"]),
+  message: z.string().min(1).max(2_000),
+});
+
+export const CodeWorkerResponseSchema = z.discriminatedUnion("status", [
+  z.strictObject({
+    diagnosticBarrier: IdentifierSchema,
+    generation: z.number().int().safe().positive(),
+    kind: z.literal("response"),
+    output: JsonValueSchema,
+    protocol: z.literal(CODE_WORKER_PROTOCOL),
+    requestId: IdentifierSchema,
+    status: z.literal("ok"),
+  }),
+  z.strictObject({
+    diagnosticBarrier: IdentifierSchema,
+    error: CodeWorkerErrorSchema,
+    generation: z.number().int().safe().positive(),
+    kind: z.literal("response"),
+    protocol: z.literal(CODE_WORKER_PROTOCOL),
+    requestId: IdentifierSchema,
+    status: z.literal("error"),
+  }),
+]);
+
+export const CodeWorkerMessageSchema = z.union([
+  CodeWorkerHelloSchema,
+  CodeWorkerRequestSchema,
+  CodeWorkerResponseSchema,
+]);
+
+export type CodeWorkerRequest = z.infer<typeof CodeWorkerRequestSchema>;
+export type CodeWorkerResponse = z.infer<typeof CodeWorkerResponseSchema>;
+export type CodeWorkerMessage = z.infer<typeof CodeWorkerMessageSchema>;
+
+export type CodeWorkerDiagnosticStream = "stderr" | "stdout";
+
+export function encodeCodeWorkerDiagnosticBarrier(
+  barrier: string,
+  stream: CodeWorkerDiagnosticStream,
+): Uint8Array {
+  const identifier = IdentifierSchema.parse(barrier);
+  return new TextEncoder().encode(
+    `\n\u001e${CODE_WORKER_PROTOCOL}:diagnostics:${stream}:${identifier}\u001f\n`,
+  );
+}
+
+export const MAX_CODE_WORKER_DIAGNOSTIC_BARRIER_BYTES = Math.max(
+  encodeCodeWorkerDiagnosticBarrier(`a${"a".repeat(127)}`, "stderr").byteLength,
+  encodeCodeWorkerDiagnosticBarrier(`a${"a".repeat(127)}`, "stdout").byteLength,
+);
+
+function maximumFrameBytes(input: number | undefined): number {
+  const value = input ?? MAX_CODE_WORKER_FRAME_BYTES;
+  if (!Number.isSafeInteger(value) || value < 1 || value > MAX_CODE_WORKER_FRAME_BYTES) {
+    throw new ApplicationError(
+      "usage",
+      `Worker frame limit must be from 1 through ${String(MAX_CODE_WORKER_FRAME_BYTES)} bytes.`,
+    );
+  }
+  return value;
+}
+
+export function encodeWorkerFrame(
+  input: unknown,
+  maximumBytes?: number,
+): Uint8Array {
+  const message = CodeWorkerMessageSchema.parse(input);
+  const body = new TextEncoder().encode(JSON.stringify(message));
+  const limit = maximumFrameBytes(maximumBytes);
+  if (body.byteLength > limit) {
+    throw new ApplicationError("invalid-data", `Worker frame exceeds ${String(limit)} bytes.`);
+  }
+  const frame = new Uint8Array(4 + body.byteLength);
+  new DataView(frame.buffer).setUint32(0, body.byteLength, false);
+  frame.set(body, 4);
+  return frame;
+}
+
+export class WorkerFrameDecoder {
+  readonly #bodyDecoder = new TextDecoder("utf-8", { fatal: true });
+  readonly #header = new Uint8Array(4);
+  readonly #maximumBytes: number;
+  #body: Uint8Array | undefined;
+  #bodyOffset = 0;
+  #headerOffset = 0;
+
+  constructor(maximumBytes?: number) {
+    this.#maximumBytes = maximumFrameBytes(maximumBytes);
+  }
+
+  push(chunk: Uint8Array): readonly CodeWorkerMessage[] {
+    const messages: CodeWorkerMessage[] = [];
+    let offset = 0;
+    while (offset < chunk.byteLength) {
+      if (this.#body === undefined) {
+        const headerRemaining = 4 - this.#headerOffset;
+        const copied = Math.min(headerRemaining, chunk.byteLength - offset);
+        this.#header.set(chunk.subarray(offset, offset + copied), this.#headerOffset);
+        this.#headerOffset += copied;
+        offset += copied;
+        if (this.#headerOffset < 4) continue;
+        const length = new DataView(
+          this.#header.buffer,
+          this.#header.byteOffset,
+          this.#header.byteLength,
+        ).getUint32(0, false);
+        this.#headerOffset = 0;
+        if (length === 0 || length > this.#maximumBytes) {
+          throw new ApplicationError(
+            "invalid-data",
+            `Worker frame declares ${String(length)} bytes; limit is ${String(this.#maximumBytes)}.`,
+          );
+        }
+        this.#body = new Uint8Array(length);
+        this.#bodyOffset = 0;
+      }
+      const body = this.#body;
+      const bodyRemaining = body.byteLength - this.#bodyOffset;
+      const copied = Math.min(bodyRemaining, chunk.byteLength - offset);
+      body.set(chunk.subarray(offset, offset + copied), this.#bodyOffset);
+      this.#bodyOffset += copied;
+      offset += copied;
+      if (this.#bodyOffset !== body.byteLength) continue;
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(this.#bodyDecoder.decode(body));
+      } catch (error) {
+        this.#body = undefined;
+        this.#bodyOffset = 0;
+        throw new ApplicationError("invalid-data", `Worker frame is not strict UTF-8 JSON: ${String(error)}`);
+      }
+      this.#body = undefined;
+      this.#bodyOffset = 0;
+      messages.push(CodeWorkerMessageSchema.parse(parsed));
+    }
+    return Object.freeze(messages);
+  }
+
+  finish(): void {
+    if (this.#headerOffset !== 0 || this.#body !== undefined) {
+      throw new ApplicationError("invalid-data", "Worker protocol ended with a truncated frame.");
+    }
+  }
+}

package/apps/desktop/code/workflow-effects.ts

@@ -0,0 +1,132 @@
+import { Cause, Context, Deferred, Effect, Exit, Fiber, FiberId, Layer, ManagedRuntime, Ref, Scope } from "effect";
+
+export type WorkflowFailurePhase = "admission" | "authority" | "compute" | "operation" | "monitor" | "cleanup";
+export type WorkflowFailure = Readonly<{
+  _tag: "WorkflowBoundaryFailure";
+  phase: WorkflowFailurePhase;
+  cause: unknown;
+}>;
+
+export function workflowBoundary<A>(
+  phase: WorkflowFailurePhase,
+  execute: () => A | Promise<A>,
+): Effect.Effect<A, WorkflowFailure> {
+  return Effect.tryPromise({
+    try: async () => await execute(),
+    catch: (cause): WorkflowFailure => ({ _tag: "WorkflowBoundaryFailure", phase, cause }),
+  });
+}
+
+export function workflowValidation<A>(phase: WorkflowFailurePhase, evaluate: () => A): Effect.Effect<A, WorkflowFailure> {
+  return Effect.try({ try: evaluate, catch: (cause): WorkflowFailure => ({ _tag: "WorkflowBoundaryFailure", phase, cause }) });
+}
+
+export function workflowFailure(cause: unknown, phase: WorkflowFailurePhase = "authority"): WorkflowFailure {
+  return { _tag: "WorkflowBoundaryFailure", phase, cause };
+}
+
+export function workflowExitValue<A>(exit: Exit.Exit<A, WorkflowFailure>): A {
+  if (Exit.isSuccess(exit)) return exit.value;
+  const failures = [
+    ...Array.from(Cause.failures(exit.cause), failure => failure.cause),
+    ...Cause.defects(exit.cause),
+  ];
+  if (failures.length === 1) throw failures[0];
+  if (failures.length > 1) throw new AggregateError(failures, "Workflow execution and cleanup failed.");
+  throw Cause.squash(exit.cause);
+}
+
+class WorkflowCleanup extends Context.Tag("@slopcamera/local/WorkflowCleanup")<
+  WorkflowCleanup, Ref.Ref<Cause.Cause<WorkflowFailure>>
+>() { }
+
+export function workflowResource<A>(
+  acquire: Effect.Effect<A, WorkflowFailure>,
+  release: (value: A) => Effect.Effect<void, WorkflowFailure>,
+): Effect.Effect<A, WorkflowFailure, Scope.Scope | WorkflowCleanup> {
+  return Effect.gen(function*() {
+    const cleanup = yield* WorkflowCleanup;
+    return yield* Effect.acquireRelease(acquire, value => Effect.flatMap(
+      Effect.exit(release(value)),
+      exit => Exit.isFailure(exit)
+        ? Ref.update(cleanup, cause => Cause.parallel(cause, exit.cause))
+        : Effect.void,
+    ));
+  });
+}
+
+export function workflowScoped<A>(
+  program: Effect.Effect<A, WorkflowFailure, Scope.Scope | WorkflowCleanup>,
+): Effect.Effect<A, WorkflowFailure> {
+  return Effect.gen(function*() {
+    const failures = yield* Ref.make<Cause.Cause<WorkflowFailure>>(Cause.empty);
+    const result = yield* Effect.exit(Effect.scoped(Effect.provideService(program, WorkflowCleanup, failures)));
+    const cleanup = yield* Ref.get(failures);
+    return yield* Exit.zipLeft(result, Cause.isEmpty(cleanup) ? Exit.void : Exit.failCause(cleanup));
+  });
+}
+
+/** One owner per run. Observer cancellation never serves as foreign-custody proof. */
+export class WorkflowEffectRuntime {
+  readonly #runtime = ManagedRuntime.make(Layer.empty);
+  readonly #watchers = new Map<Fiber.RuntimeFiber<void, never>, boolean>();
+  #custody = 0;
+  #closing = false;
+  #disposing: Promise<void> | undefined;
+
+  async run<A>(program: Effect.Effect<A, WorkflowFailure>): Promise<A> {
+    return workflowExitValue(await this.#runtime.runPromiseExit(program));
+  }
+
+  deferred<A, E>(): Deferred.Deferred<A, E> {
+    return Deferred.unsafeMake<A, E>(FiberId.none);
+  }
+
+  watch(program: Effect.Effect<void>, retainUntilSettled = false): () => Promise<void> {
+    const fiber = this.#runtime.runFork(program);
+    this.#watchers.set(fiber, retainUntilSettled);
+    fiber.addObserver(() => { this.#watchers.delete(fiber); });
+    return async () => { await this.#runtime.runPromise(Effect.asVoid(Fiber.interrupt(fiber))); };
+  }
+
+  fork<A, E>(program: Effect.Effect<A, E>): Fiber.RuntimeFiber<A, E> {
+    this.#custody += 1;
+    const fiber = this.#runtime.runFork(program);
+    fiber.addObserver(() => {
+      this.#custody -= 1;
+      this.#disposeWhenQuiescent();
+    });
+    return fiber;
+  }
+
+  /** Native host callbacks retain their own kernel/publication leases until actual settlement. */
+  async custody<A>(program: Effect.Effect<A, WorkflowFailure>): Promise<A> {
+    this.#custody += 1;
+    try {
+      return workflowExitValue(await this.#runtime.runPromiseExit(Effect.uninterruptible(program)));
+    } finally {
+      this.#custody -= 1;
+      this.#disposeWhenQuiescent();
+    }
+  }
+
+  async stop(): Promise<void> {
+    await this.#runtime.runPromise(Effect.forEach(
+      [...this.#watchers].filter(([, retain]) => !retain), ([fiber]) => Effect.asVoid(Fiber.interrupt(fiber)),
+      { concurrency: "unbounded", discard: true },
+    ));
+    this.#closing = true;
+    this.#disposeWhenQuiescent();
+    // A timed-out foreign callback may still hold a publication or kernel lease.
+    // Its continuation, not this observer shutdown, closes the runtime.
+    if (this.#custody === 0) await this.#disposing;
+  }
+
+  #disposeWhenQuiescent(): void {
+    if (this.#closing && this.#custody === 0 && this.#disposing === undefined) {
+      this.#disposing = this.#runtime.dispose();
+      // Layer.empty has no failing finalizers. Observe detached disposal anyway.
+      void this.#disposing.catch(() => undefined);
+    }
+  }
+}