@graftland/plugin-remote 0.0.0-stage → 0.2.0-beta.2

package/src/internal/runner/Connection.ts

@@ -0,0 +1,184 @@
+import {
+	LocalTransport,
+	WorkerTransport,
+	type Execution,
+} from "../directTransport"
+import * as RunnerConnection from "../host/runner"
+import {
+	Array,
+	Cause,
+	Context,
+	Effect,
+	Duration,
+	Exit,
+	Option,
+	Scope,
+} from "effect"
+import * as Release from "../release"
+import type { RpcClientError } from "effect/rpc"
+import type { Schema, PlatformError } from "effect"
+import type { RemoteTerminationUnconfirmed } from "./model"
+import type { Expected } from "./Packages"
+
+import {
+	LocalTerminationTimeout,
+	ProcessExited,
+	TransportError,
+} from "../../Errors"
+import { cleanupCause } from "../cleanup"
+import * as Port from "../port"
+import * as LocalProcess from "./Local"
+import * as Wire from "./Wire"
+
+export interface LocalTarget {
+	readonly _tag: "Local"
+	readonly command?: readonly [string, ...string[]]
+}
+export interface WorkerTarget {
+	readonly _tag: "Worker"
+	readonly execArgv?: ReadonlyArray<string>
+}
+
+export interface ConfiguredRunner {
+	readonly instance: string
+	readonly lease?: Duration.Input
+	readonly margin?: Duration.Input
+	readonly expect?: Expected
+	readonly _tag: "Connector"
+	readonly explicitAuth?: boolean
+}
+export type Target = LocalTarget | WorkerTarget | ConfiguredRunner
+
+type Peer = Port.Port
+export interface Connected {
+	readonly resources: Scope.Scope
+	readonly pid: Option.Option<number>
+	readonly threadId?: number
+	readonly diagnostics: Effect.Effect<Cause.Cause<unknown>>
+	readonly terminate: (
+		graceful: boolean,
+	) => Effect.Effect<
+		void,
+		| ProcessExited
+		| LocalTerminationTimeout
+		| TransportError
+		| Schema.SchemaError
+		| Wire.SessionError
+		| RemoteTerminationUnconfirmed
+		| RpcClientError.RpcClientError
+	>
+	readonly transport: {
+		readonly clientProtocol: Peer["clientProtocol"]
+		readonly serverProtocol: Peer["serverProtocol"]
+		readonly failure: Effect.Effect<never, ProcessExited | TransportError>
+		readonly report: (cause: Cause.Cause<unknown>) => Effect.Effect<void>
+	}
+}
+export class Connection extends Context.Service<Connection, Connected>()(
+	"@graftland/plugin-remote/internal/runner/Connection",
+) {}
+const connected = Connection.of
+
+const Local = Effect.fnUntraced(function* (
+	target: LocalTarget | WorkerTarget,
+	contractModule: string,
+	options: Port.Options,
+	resources: Scope.Scope,
+	processScope: Scope.Scope,
+) {
+	const transport = yield* target._tag === "Local"
+		? LocalTransport
+		: WorkerTransport
+	const started: Effect.Effect<
+		Execution,
+		PlatformError.PlatformError | TransportError,
+		Scope.Scope
+	> = transport.start({ ...target, contractModule, session: options.session })
+	const execution = yield* started.pipe(Scope.provide(processScope))
+	return yield* LocalProcess.connect(execution, options).pipe(
+		Scope.provide(resources),
+	)
+})
+
+const reason = <A, E>(exit: Exit.Exit<A, E>) =>
+	Exit.isFailure(exit) ? exit.cause : Cause.empty
+const finish = (causes: ReadonlyArray<Cause.Cause<unknown>>) => {
+	const cause = Array.reduce(causes, Cause.empty, Cause.combine)
+	return cause.reasons.length === 0
+		? Effect.void
+		: Effect.failCause(cleanupCause(cause))
+}
+
+/** Close partially acquired resources too; the normal release observes exit before stopping readers. */
+const scopes = Effect.acquireRelease(
+	Effect.all({ resources: Scope.make(), process: Scope.make() }),
+	(scopes, exit) =>
+		Effect.gen(function* () {
+			const process = yield* Effect.exit(Release.close(scopes.process, exit))
+			const resources = yield* Effect.exit(
+				Release.close(scopes.resources, exit),
+			)
+			yield* finish([reason(process), reason(resources)])
+		}),
+)
+
+/** Setup supplies a concrete control lifecycle; release never reads a later-installed effect. */
+export const acquire = <A, E, R, D, DR>(
+	target: Target,
+	contractModule: string,
+	options: Port.Options,
+	setup: Effect.Effect<A, E, R | Connection>,
+	dispose: (value: A) => Effect.Effect<Cause.Cause<unknown>, D, DR>,
+	timeout: Duration.Input,
+) =>
+	Effect.gen(function* () {
+		const owned = yield* scopes
+		const connection = yield* Effect.acquireRelease(
+			Effect.gen(function* () {
+				return target._tag === "Local" || target._tag === "Worker"
+					? yield* Local(
+							target,
+							contractModule,
+							options,
+							owned.resources,
+							owned.process,
+						).pipe(Effect.map(connected))
+					: yield* RunnerConnection.connect(
+							target,
+							contractModule,
+							options,
+							owned.resources,
+							owned.process,
+						)
+			}).pipe(Effect.interruptible),
+			(connection, exit) =>
+				Effect.gen(function* () {
+					const process = yield* Effect.exit(Release.close(owned.process, exit))
+					// Wait for exit while readers are alive; collect their final cause after resources close.
+					yield* connection.diagnostics
+					const resources = yield* Effect.exit(
+						Release.close(owned.resources, exit),
+					)
+					const diagnostics = yield* connection.diagnostics
+					yield* finish([reason(process), reason(resources), diagnostics])
+				}),
+		)
+		return yield* Effect.acquireRelease(
+			setup.pipe(Effect.provideService(Connection, connection)),
+			(value) =>
+				Effect.gen(function* () {
+					const graceful = yield* dispose(value).pipe(
+						Effect.interruptible,
+						Effect.timeout(timeout),
+						Effect.exit,
+					)
+					const terminated = yield* Effect.exit(
+						connection.terminate(Exit.isSuccess(graceful)),
+					)
+					yield* finish([
+						Exit.isSuccess(graceful) ? graceful.value : graceful.cause,
+						reason(terminated),
+					])
+				}),
+		)
+	})

package/src/internal/runner/Execution.ts

@@ -0,0 +1,244 @@
+import * as ProcessObservation from "./ProcessObservation"
+import * as FailureGroup from "../FailureGroup"
+import { Command, CommandJson } from "./WatchdogProtocol"
+import {
+	Array,
+	Cause,
+	FileSystem,
+	Path,
+	Schema,
+	Context,
+	Effect,
+	HashMap,
+	HashSet,
+	Queue,
+	Ref,
+	Sink,
+	Stream,
+	Layer,
+	Scope,
+} from "effect"
+import { ChildProcess, ChildProcessSpawner } from "effect/process"
+import { TransportError } from "../../Errors"
+import * as Multiplex from "./Multiplex"
+import * as Packages from "./Packages"
+import * as Processes from "./Processes"
+import {
+	Execution,
+	ExecutionError,
+	SessionConflict,
+	SessionStopped,
+} from "./model"
+import { Bootstrap } from "./Bootstrap"
+import { command } from "./command"
+
+export class Channels extends Context.Service<
+	Channels,
+	{
+		readonly peer: (
+			token: string,
+		) => Effect.Effect<
+			Multiplex.Peer,
+			SessionStopped | SessionConflict,
+			Scope.Scope
+		>
+	}
+>()("@graftland/plugin-remote/internal/runner/Execution/Channels") {}
+
+export const make = (root: string) =>
+	Effect.gen(function* () {
+		const spawner = yield* ChildProcessSpawner.ChildProcessSpawner
+		const fs = yield* FileSystem.FileSystem
+		const path = yield* Path.Path
+		const platform = Context.make(
+			ChildProcessSpawner.ChildProcessSpawner,
+			spawner,
+		).pipe(Context.add(FileSystem.FileSystem, fs), Context.add(Path.Path, path))
+
+		const peers = yield* Ref.make(HashMap.empty<string, Multiplex.Peer>())
+		const claimed = yield* Ref.make(HashSet.empty<string>())
+		const driver = Execution.of({
+			recover: (child) =>
+				Processes.recover(child).pipe(Effect.provideContext(platform)),
+			spawn: (handle, request, limits) =>
+				Effect.gen(function* () {
+					const resolved = yield* Packages.resolve(
+						root,
+						request.specifier,
+						request.digest,
+					)
+					const argv = yield* command()
+					const child = yield* spawner.spawn(
+						ChildProcess.make(
+							argv[0],
+							[
+								...Array.drop(argv, 1),
+								"child",
+								resolved.entry,
+								handle.token,
+								yield* Schema.encodeEffect(Schema.fromJsonString(Bootstrap))({
+									identity: {
+										id: handle.key.instance,
+										generation: handle.generation,
+									},
+									limits,
+								}),
+							],
+							{
+								stdin: "pipe",
+								stdout: "pipe",
+								stderr: "pipe",
+								additionalFds: {
+									fd3: { type: "output" },
+									fd4: { type: "input" },
+								},
+								forceKillAfter: "1 second",
+							},
+						),
+					)
+					const observation = yield* ProcessObservation.observe(child)
+					const exited = observation.exited.pipe(
+						Effect.mapError((error) =>
+							ExecutionError.make({
+								detail: "Observing child exit failed",
+								cause: Cause.fail(error),
+							}),
+						),
+					)
+					const failures = yield* FailureGroup.make<ExecutionError>()
+					yield* failures.run(
+						observation.failure.pipe(
+							Effect.mapError((error) =>
+								ExecutionError.make({
+									detail: "Reading child output failed",
+									cause: Cause.fail(error),
+								}),
+							),
+						),
+					)
+					const controls = yield* Queue.bounded<string>(4)
+
+					yield* failures.run(
+						Stream.fromQueue(controls).pipe(
+							Stream.map((line) => new TextEncoder().encode(line + "\n")),
+							Stream.run(child.getInputFd(4)),
+							Effect.mapError((error) =>
+								ExecutionError.make({
+									detail: "Child supervision channel failed",
+									cause: Cause.fail(error),
+								}),
+							),
+						),
+					)
+					const send = (value: typeof Command.Type) =>
+						Effect.raceFirst(
+							Schema.encodeEffect(CommandJson)(value).pipe(
+								Effect.flatMap((line) => Queue.offer(controls, line)),
+								Effect.asVoid,
+								Effect.mapError((error) =>
+									ExecutionError.make({
+										detail: "Encoding watchdog command failed",
+										cause: Cause.fail(error),
+									}),
+								),
+							),
+							failures.await,
+						)
+					const peer = yield* Multiplex.make({
+						input: child
+							.getOutputFd(3)
+							.pipe(
+								Stream.mapError((error) =>
+									TransportError.make({ cause: Cause.fail(error) }),
+								),
+							),
+						output: child.stdin.pipe(
+							Sink.mapError((error) =>
+								TransportError.make({ cause: Cause.fail(error) }),
+							),
+						),
+					})
+					const identity = yield* Processes.identity(child.pid)
+					yield* Ref.update(peers, HashMap.set(handle.token, peer))
+					yield* Effect.addFinalizer(() =>
+						Ref.update(peers, HashMap.remove(handle.token)),
+					)
+					return {
+						code: resolved.identity,
+						start: send({ kind: "start" }),
+						identity,
+						exited,
+						interrupt: send({ kind: "stop" }),
+						kill: child.kill({ killSignal: "SIGKILL" }).pipe(
+							Effect.mapError((error) =>
+								ExecutionError.make({
+									detail: "Killing the child failed",
+									cause: Cause.fail(error),
+								}),
+							),
+						),
+						renew: (millis: number) => send({ kind: "renew", millis }),
+					}
+				}).pipe(
+					Effect.provideContext(platform),
+					Effect.catchTags({
+						PlatformError: (error) =>
+							Effect.fail(
+								ExecutionError.make({
+									detail: "Starting the child failed",
+									cause: Cause.fail(error),
+								}),
+							),
+						SchemaError: (error) =>
+							Effect.fail(
+								ExecutionError.make({
+									detail: "Encoding child bootstrap failed",
+									cause: Cause.fail(error),
+								}),
+							),
+					}),
+				),
+		})
+		return {
+			driver,
+			peer: (token: string) =>
+				Effect.acquireRelease(
+					Effect.gen(function* () {
+						const peer = yield* Ref.get(peers).pipe(
+							Effect.flatMap((all) => {
+								const peer = HashMap.get(all, token)
+								return peer._tag === "Some"
+									? Effect.succeed(peer.value)
+									: Effect.fail(
+											SessionStopped.make({
+												detail: "The execution channel is no longer available",
+											}),
+										)
+							}),
+						)
+						const occupied = yield* Ref.modify(
+							claimed,
+							(all) =>
+								[HashSet.has(all, token), HashSet.add(all, token)] as const,
+						)
+						if (occupied)
+							return yield* SessionConflict.make({
+								detail: "The instance channel is already attached",
+							})
+						return peer
+					}),
+					() => Ref.update(claimed, HashSet.remove(token)),
+				),
+		}
+	})
+
+export const layer = (root: string) =>
+	Layer.effectContext(
+		make(root).pipe(
+			Effect.map((execution) =>
+				Context.make(Execution, execution.driver).pipe(
+					Context.add(Channels, { peer: execution.peer }),
+				),
+			),
+		),
+	)

package/src/internal/runner/Framing.ts

@@ -0,0 +1,122 @@
+import { Array, Effect, MutableRef, Option, Result, Schema } from "effect"
+
+export class FrameError extends Schema.TaggedError<
+	FrameError,
+	{ readonly brand: unique symbol }
+>()("FrameError", { detail: Schema.String }) {
+	override get message() {
+		return this.detail
+	}
+}
+/** A complete byte stream ended; malformed trailing bytes remain FrameError. */
+export class EndOfStream extends Schema.TaggedError<
+	EndOfStream,
+	{ readonly brand: unique symbol }
+>()("RunnerEndOfStream", {}) {
+	override get message() {
+		return "Runner byte channel ended"
+	}
+}
+export type Channel = 0 | 1
+export interface Frame {
+	readonly channel: Channel
+	readonly payload: Uint8Array
+}
+export const headerSize = 8
+export const maxPayload = 1024 * 1024
+const invalid = (detail: string) => FrameError.make({ detail })
+
+/** Version 2 carries only channel and length; request admission belongs to port. */
+export const encode = (frame: Frame) =>
+	Effect.gen(function* () {
+		if (frame.payload.byteLength > maxPayload)
+			return yield* invalid("Runner frame exceeds the payload limit")
+		const bytes = new Uint8Array(headerSize + frame.payload.byteLength)
+		bytes.set([2, frame.channel, 0, 0])
+		new DataView(bytes.buffer).setUint32(4, frame.payload.byteLength)
+		bytes.set(frame.payload, headerSize)
+		return bytes
+	})
+
+/** Check a message boundary; the decoder still validates the frame's contents. */
+export const isCompleteFrame = (bytes: Uint8Array): boolean =>
+	bytes.byteLength >= headerSize &&
+	new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(
+		4,
+	) ===
+		bytes.byteLength - headerSize
+
+/** The decoder owns its byte buffer. Results expose malformed frames without throwing through a generator. */
+export const decoder = () => {
+	const pending = MutableRef.make<Result.Result<Uint8Array, FrameError>>(
+		Result.succeed(new Uint8Array(0)),
+	)
+	const decode = (
+		chunk: Uint8Array,
+	): Result.Result<ReadonlyArray<Frame>, FrameError> =>
+		Result.flatMap(MutableRef.get(pending), (previous) => {
+			const bytes = new Uint8Array(previous.length + chunk.length)
+			bytes.set(previous)
+			bytes.set(chunk, previous.length)
+			const frames = Array.unfold(
+				0,
+				(
+					offset,
+				): Option.Option<
+					readonly [Result.Result<Frame, FrameError>, number]
+				> => {
+					if (bytes.length - offset < headerSize) return Option.none()
+					const header = new DataView(bytes.buffer, offset, headerSize)
+					const channel = header.getUint8(1)
+					const length = header.getUint32(4)
+					if (
+						header.getUint8(0) !== 2 ||
+						(channel !== 0 && channel !== 1) ||
+						header.getUint16(2) !== 0 ||
+						length > maxPayload
+					)
+						return Option.some([
+							Result.fail(
+								invalid("Invalid runner frame header or payload length"),
+							),
+							bytes.length,
+						])
+					const end = offset + headerSize + length
+					if (end > bytes.length) return Option.none()
+					return Option.some([
+						Result.succeed({
+							channel,
+							payload: bytes.subarray(offset + headerSize, end),
+						}),
+						end,
+					])
+				},
+			)
+			const result = Result.all(frames)
+			MutableRef.set(
+				pending,
+				Result.map(result, (frames) =>
+					bytes.subarray(
+						Array.reduce(
+							frames,
+							0,
+							(used, frame) => used + headerSize + frame.payload.length,
+						),
+					),
+				),
+			)
+			return result
+		})
+	return {
+		decode,
+		finish: Effect.suspend(() =>
+			Effect.fromResult(
+				Result.flatMap(MutableRef.get(pending), (bytes) =>
+					bytes.length === 0
+						? Result.succeed(undefined)
+						: Result.fail(invalid("Runner connection ended inside a frame")),
+				),
+			),
+		),
+	}
+}

package/src/internal/runner/Local.ts

@@ -0,0 +1,73 @@
+import { Cause, Effect, Fiber, Option } from "effect"
+import type { Execution } from "../directTransport"
+import * as FailureGroup from "../FailureGroup"
+import {
+	LocalTerminationTimeout,
+	ProcessExited,
+	TransportError,
+} from "../../Errors"
+import * as Port from "../port"
+import { stdinExitTimeout } from "./ProcessObservation"
+
+/** Direct execution observers stay alive until exit, including forced cleanup. */
+export const connect = Effect.fnUntraced(function* (
+	execution: Execution,
+	options: Port.Options,
+) {
+	const failures = yield* FailureGroup.make<ProcessExited | TransportError>()
+	const exited = yield* execution.exited.pipe(Effect.forkScoped)
+	const peer = yield* Port.make(execution.channel, options)
+	yield* failures.run(
+		Effect.raceFirst(
+			peer.await,
+			Fiber.join(exited).pipe(Effect.flatMap(Effect.fail)),
+		),
+	)
+	const report = (cause: Cause.Cause<unknown>) =>
+		Cause.hasInterruptsOnly(cause)
+			? Effect.void
+			: failures
+					.fail(TransportError.make({ cause }))
+					.pipe(Effect.andThen(peer.fail(TransportError.make({ cause }))))
+	yield* failures.run(execution.failure)
+
+	return {
+		...peer,
+		pid: execution.pid,
+		...(execution.threadId === undefined
+			? {}
+			: { threadId: execution.threadId }),
+		exited,
+		resources: yield* Effect.scope,
+		transport: { ...peer, failure: failures.await, report },
+		diagnostics: Fiber.await(exited).pipe(Effect.andThen(failures.cause)),
+		terminate: (graceful: boolean) =>
+			Effect.gen(function* () {
+				// Stop observation before intentionally ending stdin or killing the process.
+				yield* failures.close
+				if (!graceful) return
+				// If this fails, the execution scope forces termination and waits for exit.
+				const status = yield* peer.end.pipe(
+					// Peer EOF can interrupt the writer as its output ends. Still confirm the unit's exit.
+					Effect.catchCauseIf(Cause.hasInterruptsOnly, () => Effect.void),
+					Effect.andThen(Fiber.join(exited)),
+					Effect.interruptible,
+					Effect.timeoutOrElse({
+						duration: stdinExitTimeout,
+						orElse: () =>
+							LocalTerminationTimeout.make({
+								...Option.match(execution.pid, {
+									onNone: () => ({}),
+									onSome: (pid) => ({ pid }),
+								}),
+								...(execution.threadId === undefined
+									? {}
+									: { threadId: execution.threadId }),
+							}),
+					}),
+				)
+				if (status.exitCode !== 0 || status.statusCause.reasons.length > 0)
+					return yield* status
+			}),
+	}
+})

package/src/internal/runner/Lock.ts

@@ -0,0 +1,29 @@
+import { Cause, Effect, FileSystem, Path } from "effect"
+import { StateDirectoryLocked } from "./model"
+
+/** SQLite owns the local directory lock for the enclosing scope, including failed startup. */
+export const acquire = (directory: string) =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem
+		const path = yield* Path.Path
+		yield* fs
+			.makeDirectory(directory, { recursive: true })
+			.pipe(Effect.uninterruptible)
+		const { DatabaseSync } = yield* Effect.promise(
+			() => import("node:sqlite"),
+		).pipe(Effect.uninterruptible)
+		const locked = (cause: unknown) =>
+			StateDirectoryLocked.make({
+				detail:
+					"The runner state directory is already owned or cannot be locked",
+				cause: Cause.die(cause),
+			})
+		const db = yield* Effect.acquireRelease(
+			Effect.try({
+				try: () => new DatabaseSync(path.join(directory, "owner.sqlite")),
+				catch: locked,
+			}),
+			(db) => Effect.sync(() => db.close()),
+		)
+		yield* Effect.try({ try: () => db.exec("BEGIN EXCLUSIVE"), catch: locked })
+	})