@graftland/plugin-remote 0.0.0-stage → 0.3.0

package/src/internal/host/local.ts

@@ -0,0 +1,53 @@
+import { Cause, Effect, Fiber, Option, Sink, Stream } from "effect"
+import type { ChildProcessSpawner } from "effect/process"
+import { ProcessExited, TransportError } from "../../Errors"
+import * as ProcessObservation from "../runner/ProcessObservation"
+
+export const observe = Effect.fnUntraced(function* (
+	child: ChildProcessSpawner.ChildProcessHandle,
+) {
+	const observation = yield* ProcessObservation.observe(child)
+	const exited = yield* observation.exited.pipe(
+		Effect.mapBoth({
+			onFailure: (error) => TransportError.make({ cause: Cause.fail(error) }),
+			onSuccess: (status) =>
+				ProcessExited.make({
+					pid: Option.some(child.pid),
+					exitCode: status.code,
+					stderr: status.stderr,
+					statusCause: status.cause,
+				}),
+		}),
+		Effect.forkScoped,
+	)
+	return {
+		pid: Option.some(child.pid),
+		exited: Fiber.join(exited),
+		failure: observation.failure.pipe(
+			Effect.mapError((error) =>
+				TransportError.make({ cause: Cause.fail(error) }),
+			),
+		),
+		channel: {
+			input: child.getOutputFd(3).pipe(
+				// EOF can precede Node's exit event; prefer complete process diagnostics.
+				Stream.concat(
+					Stream.fromEffect(
+						Fiber.join(exited).pipe(
+							Effect.timeoutOption("1 second"),
+							Effect.asVoid,
+						),
+					).pipe(Stream.drain),
+				),
+				Stream.mapError((error) =>
+					TransportError.make({ cause: Cause.fail(error) }),
+				),
+			),
+			output: child.stdin.pipe(
+				Sink.mapError((error) =>
+					TransportError.make({ cause: Cause.fail(error) }),
+				),
+			),
+		},
+	}
+})

package/src/internal/host/runner.ts

@@ -0,0 +1,187 @@
+import * as FailureGroup from "../FailureGroup"
+import {
+	Cause,
+	Effect,
+	Duration,
+	Exit,
+	Fiber,
+	Option,
+	Ref,
+	Scope,
+} from "effect"
+import { RpcClient } from "effect/rpc"
+import { connectWith as connectCapability } from "../assembly"
+import type { ConfiguredRunner, Connected } from "../runner/Connection"
+import { ProcessExited, TransportError } from "../../Errors"
+import { cleanupCause } from "../cleanup"
+import * as Port from "../port"
+import * as Multiplex from "../runner/Multiplex"
+import * as Packages from "../runner/Packages"
+import * as Wire from "../runner/Wire"
+import { awaitTermination, defaults, childOf } from "../runner/model"
+export const connect = (
+	target: ConfiguredRunner,
+	contractModule: string,
+	options: Port.Options,
+	resources: Scope.Scope,
+	processScope: Scope.Scope,
+) =>
+	Effect.gen(function* () {
+		const instance = target.instance
+
+		const margin = Duration.toMillis(target.margin ?? "5 seconds")
+		const channel = yield* connectCapability(target.explicitAuth).pipe(
+			Scope.provide(processScope),
+		)
+		const mux = yield* Multiplex.make(channel).pipe(Scope.provide(resources))
+		const control = yield* Port.make(Wire.channel(mux, 0), {
+			session: "session-v1",
+			serve: {},
+			call: { session: Wire.Session },
+		}).pipe(Scope.provide(resources))
+		const session = yield* RpcClient.make(Wire.Session).pipe(
+			Effect.provideService(
+				RpcClient.Protocol,
+				control.clientProtocol("session"),
+			),
+			Scope.provide(resources),
+		)
+		const expectedGeneration = yield* session.HighWater({ instance })
+		const record = yield* session.Open({
+			instance,
+			expectedGeneration,
+			requestId: options.session,
+			limits: defaults,
+			...(target.lease === undefined
+				? {}
+				: {
+						leaseMillis: Duration.toMillis(target.lease),
+					}),
+		})
+		const failures = yield* FailureGroup.make<TransportError>().pipe(
+			Scope.provide(resources),
+		)
+		const finishStarted = yield* Ref.make(false)
+		const terminate = yield* Effect.cached(
+			Effect.gen(function* () {
+				yield* Ref.set(finishStarted, true)
+				yield* failures.close
+				const result = yield* awaitTermination(
+					record.handle,
+					session.Dispose(record.handle),
+					record.leaseMillis,
+					margin,
+				)
+				const { code, signal, stderr, cause } = result.exit
+				yield* Effect.logInfo("Remote execution terminated", {
+					code,
+					...(signal === null ? {} : { signal }),
+					...(stderr === undefined || stderr === "" ? {} : { stderr }),
+					...(cause === undefined || cause.reasons.length === 0
+						? {}
+						: { cause }),
+				}).pipe(
+					Effect.annotateLogs({
+						"remote.instance": record.handle.key.instance,
+						"remote.generation": record.handle.generation,
+						"remote.termination": result.kind,
+					}),
+				)
+				if (result.cause.reasons.length > 0)
+					return yield* Effect.failCause(cleanupCause(result.cause))
+			}),
+		)
+		yield* Scope.addFinalizer(
+			processScope,
+			Effect.gen(function* () {
+				if (!(yield* Ref.get(finishStarted)))
+					yield* terminate.pipe(
+						Effect.catchCause((cause) => Effect.failCause(cleanupCause(cause))),
+					)
+			}),
+		)
+		const renewed = yield* Effect.forever(
+			Effect.sleep(record.leaseMillis / 3).pipe(
+				Effect.andThen(session.Renew(record.handle)),
+			),
+		).pipe(Effect.forkIn(resources))
+		const code = yield* session.Load({
+			handle: record.handle,
+			specifier: contractModule,
+			digest: target.expect?.digest !== undefined,
+		})
+		yield* Packages.verify(code, target.expect)
+		const loaded = yield* session.Status(record.handle)
+		const peer = yield* Port.make(Wire.channel(mux, 1), {
+			...options,
+			session: record.handle.token,
+			limits: record.limits,
+		}).pipe(Scope.provide(resources))
+		// RPC forwarding cancellation is expected; resource cleanup is collected by Connection's scopes.
+		const report = (cause: Cause.Cause<unknown>) =>
+			Cause.hasInterruptsOnly(cause)
+				? Effect.void
+				: failures.failCause(
+						Cause.map(cause, (error) =>
+							TransportError.make({ cause: Cause.fail(error) }),
+						),
+					)
+		yield* failures.await.pipe(
+			Effect.catchCause((cause) =>
+				Cause.hasInterruptsOnly(cause)
+					? Effect.void
+					: peer.fail(TransportError.make({ cause })),
+			),
+			Effect.forkIn(resources),
+		)
+
+		yield* failures.run(
+			Fiber.join(renewed).pipe(
+				Effect.catchCause((cause) =>
+					Effect.gen(function* () {
+						if (Cause.hasInterruptsOnly(cause)) return
+						const status = yield* Effect.exit(
+							session.Status(record.handle).pipe(Effect.timeout("5 seconds")),
+						)
+						if (Exit.isSuccess(status) && status.value.phase === "Stopped") {
+							const exit = status.value.termination.exit
+							yield* report(
+								Cause.combine(
+									cause,
+									Cause.fail(
+										ProcessExited.make({
+											pid: Option.map(childOf(loaded), (child) => child.pid),
+											exitCode: exit.code,
+											stderr: exit.stderr ?? "",
+											statusCause: exit.cause ?? Cause.empty,
+										}),
+									),
+								),
+							)
+						} else
+							yield* report(
+								Exit.isFailure(status)
+									? Cause.combine(cause, status.cause)
+									: cause,
+							)
+					}),
+				),
+			),
+		)
+		return {
+			resources,
+			pid: Option.map(childOf(loaded), (child) => child.pid),
+			diagnostics: failures.cause,
+			terminate: () =>
+				Effect.gen(function* () {
+					// No renewal may extend a disconnected session while termination waits out its lease.
+					yield* Fiber.interrupt(renewed)
+					yield* terminate
+				}),
+			transport: {
+				...peer,
+				failure: peer.await,
+				report,
+			},
+		} satisfies Connected
+	})

package/src/internal/host.ts

@@ -0,0 +1,209 @@
+import * as FailureGroup from "./FailureGroup"
+import * as ContractModule from "../Contract"
+import {
+	Cause,
+	Array,
+	Deferred,
+	Effect,
+	Ref,
+	Option,
+	Schema,
+	Scope,
+	Stream,
+} from "effect"
+import { RpcClient, type RpcClientError } from "effect/rpc"
+import { RemoteWithdrawn } from "../Errors"
+import * as Control from "./control"
+import { cleanupCause } from "./cleanup"
+import { Connection } from "./runner/Connection"
+import type { Service } from "./services"
+
+type ErrorSchema = Schema.Top & {
+	readonly DecodingServices: never
+	readonly EncodingServices: never
+}
+type ControlGroup<E extends ErrorSchema> = ContractModule.Contract<
+	Schema.Codec<unknown, Schema.Json>,
+	E
+>["control"]
+interface Contract<E extends ErrorSchema> {
+	readonly control: ControlGroup<E>
+	readonly inject: ReadonlyArray<Service>
+	readonly decodeCause: (
+		input: unknown,
+	) => Effect.Effect<
+		Cause.Cause<
+			E["Type"] | ContractModule.UndeclaredFailure | ContractModule.ChildFailure
+		>,
+		Schema.SchemaError
+	>
+}
+type Client<E extends ErrorSchema> = RpcClient.FromGroup<
+	ControlGroup<E>,
+	RpcClientError.RpcClientError
+>
+const race = <A, E, R>(
+	connection: Connection["Service"],
+	effect: Effect.Effect<A, E, R>,
+) => Effect.raceFirst(effect, connection.transport.failure)
+
+const forwardEvents = <E extends ErrorSchema>(
+	contract: Contract<E>,
+	client: Client<E>,
+	connection: Connection["Service"],
+) =>
+	Effect.gen(function* () {
+		const stopped = yield* Deferred.make<void>()
+		const remoteFailure = yield* FailureGroup.make<
+			| E["Type"]
+			| ContractModule.UndeclaredFailure
+			| ContractModule.ChildFailure
+			| RemoteWithdrawn
+		>()
+		const events = yield* race(
+			connection,
+			client.Events().pipe(
+				Stream.runForEach((event) => {
+					switch (event._tag) {
+						case "Stopped":
+							return Deferred.succeed(stopped, undefined)
+						case "Withdrawing":
+							return remoteFailure.fail(RemoteWithdrawn.make({}))
+						case "Failed":
+							return contract
+								.decodeCause(event.cause)
+								.pipe(Effect.flatMap((cause) => remoteFailure.failCause(cause)))
+					}
+				}),
+			),
+		).pipe(
+			Effect.tapCause(connection.transport.report),
+			Effect.forkIn(connection.resources),
+		)
+		return { stopped, remoteFailure, events }
+	})
+const forwardLogs = <E extends ErrorSchema>(
+	contract: Contract<E>,
+	client: Client<E>,
+	connection: Connection["Service"],
+) =>
+	Effect.gen(function* () {
+		const logsEnded = yield* Deferred.make<void>()
+		const reportedDrops = yield* Ref.make(0)
+		yield* race(
+			connection,
+			client.Logs().pipe(
+				Stream.runForEach((event) =>
+					Effect.gen(function* () {
+						const previous = yield* Ref.getAndSet(reportedDrops, event.dropped)
+						if (event.dropped > previous)
+							yield* Effect.logWarning("Remote logs were dropped").pipe(
+								Effect.annotateLogs({
+									...(Option.isSome(connection.pid)
+										? { "remote.pid": connection.pid.value }
+										: {}),
+									"remote.logs.dropped": event.dropped - previous,
+									"remote.logs.droppedTotal": event.dropped,
+								}),
+							)
+						if (event._tag === "LogsEnded") {
+							yield* Deferred.succeed(logsEnded, undefined)
+							return
+						}
+						const entry = event.entry
+						const cause = yield* contract.decodeCause(entry.cause)
+						yield* Effect.logWithLevel(
+							entry.level === "All" || entry.level === "None"
+								? "Info"
+								: entry.level,
+						)(
+							...(Array.isArray(entry.message)
+								? entry.message
+								: [entry.message]),
+							cause,
+						).pipe(
+							Effect.annotateLogs({
+								...(Option.isSome(connection.pid)
+									? { "remote.pid": connection.pid.value }
+									: {}),
+								...(connection.threadId === undefined
+									? {}
+									: { "remote.threadId": connection.threadId }),
+								"remote.annotations": entry.annotations,
+							}),
+						)
+					}),
+				),
+			),
+		).pipe(
+			Effect.tapCause(connection.transport.report),
+			Effect.forkIn(connection.resources),
+		)
+		return logsEnded
+	})
+export const initialize = <E extends ErrorSchema>(contract: Contract<E>) =>
+	Effect.gen(function* () {
+		const connection = yield* Connection
+		const client = yield* RpcClient.make(contract.control).pipe(
+			Effect.provideService(
+				RpcClient.Protocol,
+				connection.transport.clientProtocol(Control.endpoint),
+			),
+			Scope.provide(connection.resources),
+		)
+		for (const service of contract.inject)
+			yield* service
+				.serve(connection.transport)
+				.pipe(
+					Effect.tapCause(connection.transport.report),
+					Effect.forkIn(connection.resources),
+				)
+		const events = yield* forwardEvents(contract, client, connection)
+		const logsEnded = yield* forwardLogs(contract, client, connection)
+		return { connection, client, ...events, logsEnded }
+	})
+type Active<E extends ErrorSchema> = Effect.Success<
+	ReturnType<typeof initialize<E>>
+>
+export const load = <E extends ErrorSchema>(
+	active: Active<E>,
+	input: Schema.Json,
+) =>
+	race(
+		active.connection,
+		Effect.raceFirst(
+			active.client
+				.Load({ input })
+				.pipe(
+					Effect.catchIf(
+						(
+							cause,
+						): cause is Cause.Cause<
+							| E["Type"]
+							| ContractModule.UndeclaredFailure
+							| ContractModule.ChildFailure
+						> => Cause.isCause(cause),
+						Effect.failCause,
+					),
+				),
+			active.remoteFailure.await,
+		),
+	)
+export const dispose = <E extends ErrorSchema>(active: Active<E>) =>
+	Effect.gen(function* () {
+		const result = yield* race(
+			active.connection,
+			active.client
+				.Dispose()
+				.pipe(Effect.catchIf(Cause.isCause, Effect.succeed)),
+		)
+		const cause = Cause.isCause(result) ? result : Cause.empty
+		// A remote cleanup failure still permits the bounded event and log tail to drain.
+		yield* race(
+			active.connection,
+			Deferred.await(active.stopped).pipe(
+				Effect.andThen(Deferred.await(active.logsEnded)),
+			),
+		).pipe(Effect.onError(() => Effect.failCause(cleanupCause(cause))))
+		return cause
+	})

package/src/internal/importer.ts

@@ -0,0 +1,27 @@
+import { Effect, Path, String } from "effect"
+import { SecureRandom } from "effect/crypto"
+import { registerHooks } from "node:module"
+
+/** Bare names resolve from the application; imported dependencies keep their own parent URLs. */
+export const make = Effect.fnUntraced(function* (directory: string) {
+	const path = yield* Path.Path
+	const base = yield* path.toFileUrl(path.join(directory, "graft.yml"))
+	const random = yield* SecureRandom.SecureRandom
+	const id = yield* random.uuidV4()
+	const prefix = `graft-remote-${id}:`
+	yield* Effect.acquireRelease(
+		Effect.sync(() =>
+			registerHooks({
+				resolve: (specifier, context, next) =>
+					String.startsWith(prefix)(specifier)
+						? next(String.slice(prefix.length)(specifier), {
+								...context,
+								parentURL: base.href,
+							})
+						: next(specifier, context),
+			}),
+		),
+		(hooks) => Effect.sync(() => hooks.deregister()),
+	)
+	return (specifier: string): Promise<unknown> => import(prefix + specifier)
+})

package/src/internal/listenerStartup.ts

@@ -0,0 +1,55 @@
+import type { Fork } from "@graftland/graft"
+import { Array, Deferred, Effect, HashSet, Option, Stream } from "effect"
+import type { AuthenticatorApi } from "../Auth"
+import type { Properties } from "../Transport"
+import { CapabilityCombinationError, CapabilityFailed } from "./assembly"
+
+export interface Description {
+	readonly properties: Properties
+	readonly auth: AuthenticatorApi
+}
+export const signals = Effect.all({
+	description: Deferred.make<Description>(),
+	ready: Deferred.make<void>(),
+})
+/** A startup signal races its assembly's failure; no runtime failure is promoted to the owner. */
+export const wait = <A>(fork: Fork.Fork, signal: Deferred.Deferred<A>) =>
+	Deferred.await(signal).pipe(
+		Effect.raceFirst(
+			fork.state.pipe(
+				Stream.runForEach((state) =>
+					state._tag === "Failed"
+						? Effect.fail(CapabilityFailed.make({ cause: state.cause }))
+						: Effect.void,
+				),
+				Effect.andThen(Effect.never),
+			),
+		),
+	)
+export const validate = (listeners: ReadonlyArray<Description>) => {
+	if (
+		listeners.length !== 1 &&
+		Array.some(listeners, ({ properties }) => properties.protocol === "stdio")
+	)
+		return Effect.fail(
+			CapabilityCombinationError.make({
+				detail: "A stdio listener must be the only listener in serve",
+			}),
+		)
+	const issuers = HashSet.fromIterable(
+		Array.getSomes(
+			Array.map(listeners, ({ auth }) =>
+				auth._tag === "Header"
+					? Option.fromUndefinedOr(auth.issuer)
+					: Option.none(),
+			),
+		),
+	)
+	return HashSet.size(issuers) > 1
+		? Effect.fail(
+				CapabilityCombinationError.make({
+					detail: "A runner must use a single authentication issuer",
+				}),
+			)
+		: Effect.void
+}

package/src/internal/loadModule.ts

@@ -0,0 +1,23 @@
+import { Cause, Effect } from "effect"
+import { ModuleImportFailed } from "./childErrors"
+
+/** Native imports cannot be cancelled; late rejection still belongs to the importing context. */
+export const loadModule = Effect.fn("Remote.loadModule")(function* (
+	module: string,
+) {
+	const context = yield* Effect.context<never>()
+	return yield* Effect.tryPromise({
+		try: (signal) =>
+			import(module).catch((cause) => {
+				if (signal.aborted)
+					Effect.runSyncWith(context)(
+						Effect.logError(
+							"Module import failed after cancellation",
+							Cause.die(cause),
+						).pipe(Effect.annotateLogs({ module })),
+					)
+				throw cause
+			}),
+		catch: (cause) => ModuleImportFailed.make({ module, cause }),
+	})
+})

package/src/internal/platform.ts

@@ -0,0 +1,12 @@
+import { NodeServices } from "@effect/platform-node"
+import { Layer } from "effect"
+import { Digest, SecureRandom, Signature } from "effect/crypto"
+import { FetchHttpClient } from "effect/http"
+
+export const platform = Layer.mergeAll(
+	NodeServices.layer,
+	FetchHttpClient.layer,
+	Digest.layerWebCrypto,
+	SecureRandom.layerWebCrypto,
+	Signature.layerWebCrypto.pipe(Layer.provide(SecureRandom.layerWebCrypto)),
+)