@graftland/plugin-remote 0.3.1 → 0.3.2

package/src/internal/childRuntime.ts

@@ -16,98 +16,99 @@ import { closedNormally } from "./runner/connectionEnded"
 import { endpoint } from "./control"
 
 /** Import a contract in the runner installation; importing this module performs no I/O. */
-export const load = (specifier: string) =>
-	Effect.gen(function* () {
-		const module = yield* loadModule(specifier)
-		const contract = fromModule(module)
-		if (Option.isNone(contract))
-			return yield* ContractNotFound.make({ module: specifier })
-		return contract.value
-	})
+export const load = Effect.fnUntraced(function* (specifier: string) {
+	const module = yield* loadModule(specifier)
+	const contract = fromModule(module)
+	if (Option.isNone(contract))
+		return yield* ContractNotFound.make({ module: specifier })
+	return contract.value
+})
 
-const connect = (
+const connect = Effect.fnUntraced(function* (
 	contract: PreparedContract,
 	channel: Port.Channel,
 	session: string,
 	bootstrap: Bootstrap | undefined,
-) =>
-	Effect.gen(function* () {
-		const mux =
-			bootstrap === undefined ? undefined : yield* Multiplex.make(channel)
-		return yield* Port.make(
-			mux === undefined ? channel : Wire.channel(mux, 1),
-			{
-				session,
-				serve: {
-					...Services.endpoints(contract.provides),
-					[endpoint]: contract.control,
-				},
-				call: Services.endpoints(contract.inject),
-				...(bootstrap === undefined ? {} : { limits: bootstrap.limits }),
-			},
-		)
+) {
+	const mux =
+		bootstrap === undefined ? undefined : yield* Multiplex.make(channel)
+	return yield* Port.make(mux === undefined ? channel : Wire.channel(mux, 1), {
+		session,
+		serve: {
+			...Services.endpoints(contract.provides),
+			[endpoint]: contract.control,
+		},
+		call: Services.endpoints(contract.inject),
+		...(bootstrap === undefined ? {} : { limits: bootstrap.limits }),
 	})
+})
 
 /** One execution unit; the executable supplies the platform and Graft services. */
-export const run = (
+export const run: (
 	descriptor: RunnerContract,
 	channel: Port.Channel,
-	session = "local",
+	session?: string,
 	bootstrap?: Bootstrap,
-	stop: Effect.Effect<unknown, ExecutionError> = Effect.never,
-): Effect.Effect<void, ExecutionError, Graft.Graft> =>
-	Effect.scoped(
-		Effect.gen(function* () {
-			const contract = prepare(descriptor)
-			const telemetry = yield* Child.telemetry(contract)
-			const loggers = yield* Logger.CurrentLoggers
-			yield* Effect.gen(function* () {
-				const peer = yield* connect(contract, channel, session, bootstrap)
-				const instance = yield* Child.lifecycle(
-					contract,
-					peer,
-					bootstrap?.identity ?? { id: session, generation: 1 },
-					telemetry,
-				)
-				const handlers = yield* contract.control.toHandlers({
-					Load: ({ input }) => instance.load(input),
-					Dispose: () => instance.dispose,
-					Events: () => telemetry.eventStream,
-					Logs: () => telemetry.logStream,
-				})
-				yield* RpcServer.make(contract.control, {
-					disableFatalDefects: true,
-				}).pipe(
-					Effect.provideContext(handlers),
-					Effect.provideService(
-						RpcServer.Protocol,
-						peer.serverProtocol(endpoint),
-					),
-					Effect.forkScoped,
-				)
-				yield* Effect.raceFirst(
-					peer.await.pipe(
-						Effect.catchIf(
-							(error) => closedNormally(error.cause),
-							() => Effect.void,
-						),
-						Effect.mapError((error) =>
-							ExecutionError.make({
-								detail: "Child transport failed",
-								cause: error.cause,
-							}),
-						),
-					),
-					stop,
-				).pipe(
-					// Release exports before closing the instance scope, including on interruption.
-					Effect.ensuring(instance.release),
-				)
+	stop?: Effect.Effect<unknown, ExecutionError>,
+) => Effect.Effect<void, ExecutionError, Graft.Graft> = Effect.fnUntraced(
+	function* (
+		descriptor: RunnerContract,
+		channel: Port.Channel,
+		session: string = "local",
+		bootstrap?: Bootstrap,
+		stop: Effect.Effect<unknown, ExecutionError> = Effect.never,
+	) {
+		const contract = prepare(descriptor)
+		const telemetry = yield* Child.telemetry(contract)
+		const loggers = yield* Logger.CurrentLoggers
+		yield* Effect.gen(function* () {
+			const peer = yield* connect(contract, channel, session, bootstrap)
+			const instance = yield* Child.lifecycle(
+				contract,
+				peer,
+				bootstrap?.identity ?? { id: session, generation: 1 },
+				telemetry,
+			)
+			const handlers = yield* contract.control.toHandlers({
+				Load: ({ input }) => instance.load(input),
+				Dispose: () => instance.dispose,
+				Events: () => telemetry.eventStream,
+				Logs: () => telemetry.logStream,
+			})
+			yield* RpcServer.make(contract.control, {
+				disableFatalDefects: true,
 			}).pipe(
+				Effect.provideContext(handlers),
 				Effect.provideService(
-					Logger.CurrentLoggers,
-					new Set([...loggers, telemetry.logger]),
+					RpcServer.Protocol,
+					peer.serverProtocol(endpoint),
 				),
+				Effect.forkScoped,
 			)
-		}),
-	)
+			yield* Effect.raceFirst(
+				peer.await.pipe(
+					Effect.catchIf(
+						(error) => closedNormally(error.cause),
+						() => Effect.void,
+					),
+					Effect.mapError((error) =>
+						ExecutionError.make({
+							detail: "Child transport failed",
+							cause: error.cause,
+						}),
+					),
+				),
+				stop,
+			).pipe(
+				// Release exports before closing the instance scope, including on interruption.
+				Effect.ensuring(instance.release),
+			)
+		}).pipe(
+			Effect.provideService(
+				Logger.CurrentLoggers,
+				new Set([...loggers, telemetry.logger]),
+			),
+		)
+	},
+	Effect.scoped,
+)

package/src/internal/entry.ts

@@ -41,17 +41,16 @@ export const resolve = Effect.fnUntraced(function* (
 	const directory = path.resolve(Option.getOrElse(source, () => "."))
 	const resolver = yield* Option.match(existing, {
 		onSome: Effect.succeed,
-		onNone: () =>
-			Effect.gen(function* () {
-				const importer = yield* Importer.make(directory)
-				return yield* ModuleResolver.make({
-					base: directory,
-					importer: (specifier) =>
-						String.startsWith("@graftland/plugin-remote/")(specifier)
-							? import(specifier)
-							: importer(specifier),
-				})
-			}),
+		onNone: Effect.fnUntraced(function* () {
+			const importer = yield* Importer.make(directory)
+			return yield* ModuleResolver.make({
+				base: directory,
+				importer: (specifier) =>
+					String.startsWith("@graftland/plugin-remote/")(specifier)
+						? import(specifier)
+						: importer(specifier),
+			})
+		}),
 	})
 	const fail = yield* boundary(field)
 	const plugin = yield* resolver

package/src/internal/execution.ts

@@ -1,6 +1,15 @@
 import { Plugin } from "@graftland/graft"
-import { Array, Cause, Effect, Fiber, Schema, Scope } from "effect"
+import {
+	Array,
+	Cause,
+	Effect,
+	Fiber,
+	PlatformError,
+	Schema,
+	Scope,
+} from "effect"
 import { SecureRandom } from "effect/crypto"
+import { RpcClientError } from "effect/rpc"
 import type {
 	LocalTarget as Local,
 	WorkerTarget as Worker,
@@ -12,7 +21,12 @@ import type { Duration } from "effect"
 import * as Connection from "./runner/Connection"
 import * as Services from "./services"
 import * as Host from "./host"
+import * as Errors from "../Errors"
 import { RemoteWithdrawn, RemoteError, MissingInstance } from "../Errors"
+import * as ChildErrors from "./childErrors"
+import * as Assembly from "./assembly"
+import * as Model from "./runner/model"
+import { ReleaseInterrupted } from "./release"
 import * as Contract from "../Contract"
 import * as Control from "./control"
 import { prepare } from "./contract"
@@ -64,8 +78,8 @@ export const executionPlugin = <
 			...Array.map(contract.inject, (service) => service.key),
 		],
 		config: Schema.toEncoded(contract.config),
-		apply: (input) =>
-			Effect.gen(function* () {
+		apply: Effect.fnUntraced(
+			function* (input: Schema.Json) {
 				const prepared = prepare(contract)
 				const random = yield* SecureRandom.SecureRandom
 				const session = yield* random.uuidV4()
@@ -98,12 +112,57 @@ export const executionPlugin = <
 					),
 				)
 				return () => Effect.succeed(false)
-			}).pipe(
-				Effect.annotateLogs(annotations),
-				Effect.mapError((error) => publicError(contract.error, error)),
-			),
+			},
+			Effect.annotateLogs(annotations),
+			Effect.mapError((error) => publicError(contract.error, error)),
+		),
 	})
 
+/** Failures raised by the host machinery; a permissive declared schema must not claim them. */
+const internalErrors: ReadonlyArray<abstract new (...args: never) => unknown> =
+	[
+		Errors.ProcessExited,
+		Errors.TransportError,
+		Errors.LocalTerminationTimeout,
+		Errors.CredentialsError,
+		Errors.AuthenticationFailed,
+		Errors.RemoteEntryError,
+		ChildErrors.AlreadyLoaded,
+		ChildErrors.ContractNotFound,
+		ChildErrors.ModuleImportFailed,
+		ChildErrors.ActivationFailed,
+		Model.PackageError,
+		Model.SessionAccessDenied,
+		Model.StaleSession,
+		Model.LeaseExpired,
+		Model.SessionStopped,
+		Model.SessionConflict,
+		Model.StateStorageError,
+		Model.ExecutionError,
+		Model.TerminationUnconfirmed,
+		Model.RunnerClosing,
+		Model.StateDirectoryLocked,
+		Model.RemoteTerminationUnconfirmed,
+		ReleaseInterrupted,
+		RpcClientError.RpcClientError,
+		...Assembly.errors,
+	]
+const isInternal = (error: unknown) =>
+	Schema.isSchemaError(error) ||
+	PlatformError.isPlatformError(error) ||
+	Array.some(internalErrors, (Class) => error instanceof Class)
+const isPublic = (
+	error: unknown,
+): error is
+	| Contract.UndeclaredFailure
+	| RemoteWithdrawn
+	| RemoteError
+	| MissingInstance =>
+	Schema.is(Contract.UndeclaredFailure)(error) ||
+	Schema.is(RemoteWithdrawn)(error) ||
+	Schema.is(RemoteError)(error) ||
+	Schema.is(MissingInstance)(error)
+
 export const publicError = <E extends Schema.Top>(
 	declared: E,
 	error: unknown,
@@ -113,11 +172,9 @@ export const publicError = <E extends Schema.Top>(
 	| RemoteWithdrawn
 	| RemoteError
 	| MissingInstance =>
-	Schema.is(declared)(error)
+	isPublic(error)
 		? error
-		: Schema.is(Contract.UndeclaredFailure)(error) ||
-			  Schema.is(RemoteWithdrawn)(error) ||
-			  Schema.is(RemoteError)(error) ||
-			  Schema.is(MissingInstance)(error)
+		: // Classify host failures before the declared schema, which may be structural.
+			!isInternal(error) && Schema.is(declared)(error)
 			? error
 			: RemoteError.make({ cause: Cause.fail(error) })

package/src/internal/host/runner.ts

@@ -19,169 +19,169 @@ 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 = (
+export const connect = Effect.fnUntraced(function* (
 	target: ConfiguredRunner,
 	contractModule: string,
 	options: Port.Options,
 	resources: Scope.Scope,
 	processScope: Scope.Scope,
-) =>
-	Effect.gen(function* () {
-		const instance = target.instance
+) {
+	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 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)
+			// A failed close must not skip Dispose; both outcomes are reported together below.
+			const closed = yield* Effect.exit(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,
+				}),
+			)
+			const failure = Exit.isFailure(closed)
+				? Cause.combine(closed.cause, result.cause)
+				: result.cause
+			if (failure.reasons.length > 0)
+				return yield* Effect.failCause(cleanupCause(failure))
+		}),
+	)
+	yield* Scope.addFinalizer(
+		processScope,
+		Effect.gen(function* () {
+			if (!(yield* Ref.get(finishStarted)))
+				yield* terminate.pipe(
+					Effect.catchCause((cause) => Effect.failCause(cleanupCause(cause))),
 				)
-				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,
-					}),
+		}),
+	)
+	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) }),
+					),
 				)
-				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>) =>
+	yield* failures.await.pipe(
+		Effect.catchCause((cause) =>
 			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),
-		)
+				: 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,
-										}),
-									),
+	yield* failures.run(
+		Fiber.join(renewed).pipe(
+			Effect.catchCause(
+				Effect.fnUntraced(function* (cause) {
+					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
+							),
+						)
+					} else
+						yield* report(
+							Exit.isFailure(status)
+								? Cause.combine(cause, status.cause)
+								: cause,
+						)
 				}),
-			transport: {
-				...peer,
-				failure: peer.await,
-				report,
-			},
-		} satisfies Connected
-	})
+			),
+		),
+	)
+	return {
+		resources,
+		pid: Option.map(childOf(loaded), (child) => child.pid),
+		diagnostics: failures.cause,
+		terminate: Effect.fnUntraced(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
+})