@graftland/plugin-remote 0.3.0 → 0.3.2

package/src/internal/childRuntime.ts

@@ -5,6 +5,7 @@ import { Effect, Logger, Option } from "effect"
 import { RpcServer } from "effect/rpc"
 import { fromModule, type RunnerContract } from "../Contract"
 import * as Port from "./port"
+import { prepare, type RunnerContract as PreparedContract } from "./contract"
 import * as Services from "./services"
 import * as Child from "./child"
 import * as Multiplex from "./runner/Multiplex"
@@ -15,97 +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 = (
-	contract: RunnerContract,
+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 = (
-	contract: RunnerContract,
+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 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/contract.ts

@@ -0,0 +1,47 @@
+import { Cause, Schema } from "effect"
+import * as Contract from "../Contract"
+import { ChildFailure } from "./childErrors"
+import * as Control from "./control"
+
+/** Control RPCs and child failures belong to the execution protocol, not the public descriptor. */
+export const prepare = <
+	S extends Schema.Top & {
+		readonly Encoded: Schema.Json
+		readonly DecodingServices: never
+		readonly EncodingServices: never
+	},
+	E extends Schema.Top & {
+		readonly DecodingServices: never
+		readonly EncodingServices: never
+	},
+>(
+	contract: Contract.Contract<S, E>,
+) => {
+	const failure = Schema.Union([
+		contract.error,
+		Contract.UndeclaredFailure,
+		ChildFailure,
+	])
+	const codec = Schema.toCodecJson(
+		Schema.Cause(failure, Schema.Defect({ includeStack: true })),
+	)
+	const declared = Schema.is(failure)
+	const normalizeCause = (cause: Cause.Cause<unknown>) =>
+		Cause.map(cause, (error) =>
+			declared(error)
+				? error
+				: Contract.UndeclaredFailure.make({ original: error }),
+		)
+	return {
+		...contract,
+		control: Control.make(codec),
+		normalizeCause,
+		encodeCause: (cause: Cause.Cause<unknown>) =>
+			normalizeCause(cause).pipe(Schema.encodeEffect(codec)),
+		decodeCause: Schema.decodeUnknownEffect(codec),
+	}
+}
+
+export type RunnerContract = ReturnType<
+	typeof prepare<Schema.Codec<unknown, Schema.Json>, Schema.Codec<unknown>>
+>

package/src/internal/credentials.ts

@@ -15,9 +15,11 @@ export type Source<A, D extends ReadonlyArray<Plugin.Dependency>, E = unknown> =
 				NoInfer<Plugin.Required<D>> | Scope.Scope
 			>
 	  }
-type Token<D extends ReadonlyArray<Plugin.Dependency>> =
+/** A token value, a file, or a credential effect with declared dependencies. */
+export type Token<D extends ReadonlyArray<Plugin.Dependency>> =
 	string | { readonly file: string } | Source<Redacted.Redacted<string>, D>
-type Authentication<D extends ReadonlyArray<Plugin.Dependency>> =
+/** Authentication configuration shared by TypeScript connection descriptions. */
+export type Authentication<D extends ReadonlyArray<Plugin.Dependency>> =
 	| { readonly name: string; readonly config?: unknown }
 	| { readonly none: { readonly identity?: string } }
 	| {
@@ -27,14 +29,15 @@ type Authentication<D extends ReadonlyArray<Plugin.Dependency>> =
 	  }
 	| { readonly bearer: { readonly token: Token<D> } }
 	| { readonly jwt: { readonly token: Token<D> } }
-type WithCredentials<C, D extends ReadonlyArray<Plugin.Dependency>> = C extends
-	| { readonly local: object }
-	| { readonly worker: object }
-	| { readonly command: ReadonlyArray<string> }
-	? C
-	: Omit<C, "auth"> & { readonly auth?: Authentication<D> }
 export type Connect<D extends ReadonlyArray<Plugin.Dependency> = readonly []> =
-	WithCredentials<typeof Configuration.Connect.Encoded, D>
+	typeof Configuration.Connect.Encoded extends infer C
+		? C extends
+				| { readonly local: object }
+				| { readonly worker: object }
+				| { readonly command: ReadonlyArray<string> }
+			? C
+			: Omit<C, "auth"> & { readonly auth?: Authentication<D> }
+		: never
 
 const provider = <A, E, D extends ReadonlyArray<Plugin.Dependency>>(
 	source: Source<A, D, E>,

package/src/internal/entry.ts

@@ -12,7 +12,7 @@ import {
 } from "effect"
 import { ChildProcessSpawner } from "effect/process"
 import * as Contract from "../Contract"
-import { MissingInstance } from "../Errors"
+import { MissingInstance, RemoteEntryError as EntryError } from "../Errors"
 import { LocalTransport, WorkerTransport } from "./directTransport"
 import * as Configuration from "./entryConfig"
 import * as Assembly from "./assembly"
@@ -25,19 +25,6 @@ import type { ExecutionOptions } from "./execution"
 import * as Importer from "./importer"
 import { SecureRandom } from "effect/crypto"
 
-export class EntryError extends Schema.TaggedError<
-	EntryError,
-	{ readonly brand: unique symbol }
->()("RemoteEntryError", {
-	entry: Schema.Option(Schema.String),
-	directory: Schema.Option(Schema.String),
-	field: Schema.String,
-	cause: Schema.Cause(Schema.Unknown, Schema.Unknown),
-}) {
-	override get message() {
-		return `Remote entry ${Option.getOrElse(this.entry, () => "<programmatic>")} failed at ${this.field}`
-	}
-}
 export const boundary = Effect.fnUntraced(function* (field: string) {
 	const entry = yield* Entry.CurrentId
 	const directory = yield* ConfigDirectory
@@ -54,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,9 +21,15 @@ 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"
 
 export interface ExecutionOptions {
 	readonly contractModule: string
@@ -63,8 +78,9 @@ 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()
 				const active = yield* Connection.acquire(
@@ -75,10 +91,10 @@ export const executionPlugin = <
 						serve: Services.endpoints(contract.inject),
 						call: {
 							...Services.endpoints(contract.provides),
-							[Control.endpoint]: contract.control,
+							[Control.endpoint]: prepared.control,
 						},
 					},
-					Host.initialize(contract),
+					Host.initialize(prepared),
 					Host.dispose,
 					options.shutdownTimeout ?? "5 seconds",
 				)
@@ -96,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,
@@ -111,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) })