@graftland/plugin-remote 0.0.0-stage → 0.3.0

package/src/internal/child.ts

@@ -0,0 +1,323 @@
+import { loadModule } from "./loadModule"
+import { AlreadyLoaded, ActivationFailed } from "./childErrors"
+import { Graft, Plugin, type Fork } from "@graftland/graft"
+import {
+	Array,
+	Cause,
+	Data,
+	Deferred,
+	Effect,
+	Exit,
+	Fiber,
+	Logger,
+	MutableRef,
+	Option,
+	Queue,
+	Ref,
+	References,
+	Scope,
+	Stream,
+	SynchronizedRef,
+} from "effect"
+import type { Schema } from "effect"
+import { type RunnerContract } from "../Contract"
+import { Instance, type Identity } from "../Instance"
+import type * as Port from "./port"
+import type { Event, Log, LogEvent } from "./control"
+
+type Peer = Port.Port
+type ChildEvent = Data.TaggedEnum<{
+	Failed: { readonly cause: Cause.Cause<unknown> }
+	Withdrawing: {}
+	Stopped: {}
+}>
+const ChildEvent = Data.taggedEnum<ChildEvent>()
+type LogEntry = Omit<typeof Log.Type, "cause"> & {
+	readonly cause: Cause.Cause<unknown>
+}
+
+/** Queue data; serialization belongs to the RPC consumer, outside synchronous logger callbacks. */
+export const telemetry = (contract: RunnerContract) =>
+	Effect.gen(function* () {
+		const events = yield* Queue.bounded<ChildEvent>(2)
+		const logs = yield* Queue.dropping<LogEntry, Cause.Done>(128)
+		const dropped = MutableRef.make(0)
+		const encode = (cause: Cause.Cause<unknown>) =>
+			contract.encodeCause(cause).pipe(Effect.orDie)
+		const logger = Logger.make((entry) => {
+			// Logger callbacks are synchronous; a dropping offer and loss counter cannot suspend.
+			const accepted = Queue.offerUnsafe(logs, {
+				level: entry.logLevel,
+				message: entry.message,
+				cause: entry.cause,
+				annotations: entry.fiber.getRef(References.CurrentLogAnnotations),
+			})
+			if (!accepted) MutableRef.increment(dropped)
+		})
+		return {
+			events,
+			logs,
+			logger,
+			eventStream: Stream.fromQueue(events).pipe(
+				Stream.mapEffect((event): Effect.Effect<typeof Event.Type> =>
+					event._tag === "Failed"
+						? encode(event.cause).pipe(
+								Effect.map(
+									(cause) =>
+										({
+											_tag: "Failed",
+											cause,
+										}) satisfies typeof Event.Type,
+								),
+							)
+						: Effect.succeed(event),
+				),
+			),
+			logStream: Stream.fromQueue(logs).pipe(
+				Stream.mapEffect((entry) =>
+					encode(entry.cause).pipe(
+						Effect.map((cause): typeof LogEvent.Type => ({
+							_tag: "Log",
+							entry: { ...entry, cause },
+							dropped: MutableRef.get(dropped),
+						})),
+					),
+				),
+				Stream.concat(
+					Stream.sync((): typeof LogEvent.Type => ({
+						_tag: "LogsEnded",
+						dropped: MutableRef.get(dropped),
+					})),
+				),
+			),
+		}
+	})
+type Telemetry = Effect.Success<ReturnType<typeof telemetry>>
+interface Running {
+	readonly fork: Pick<Fork.Fork<never, unknown>, "dispose" | "state">
+	readonly bridge: Pick<Fork.Fork<never, never>, "dispose" | "state">
+	readonly observation: Fiber.Fiber<void>
+	readonly observedFailure: Ref.Ref<Cause.Cause<unknown>>
+}
+type Lifecycle = Data.TaggedEnum<{
+	Idle: {}
+	Loading: {}
+	Running: { readonly running: Running }
+	Withdrawing: { readonly running: Option.Option<Running> }
+	Disposing: { readonly running: Option.Option<Running> }
+}>
+const Lifecycle = Data.taggedEnum<Lifecycle>()
+const runningOf = (state: Lifecycle): Option.Option<Running> =>
+	state._tag === "Running"
+		? Option.some(state.running)
+		: state._tag === "Withdrawing" || state._tag === "Disposing"
+			? state.running
+			: Option.none()
+
+const cleanup = (running: Running, retired: boolean) =>
+	Effect.gen(function* () {
+		const pluginExit = yield* Effect.exit(running.fork.dispose)
+		const bridgeExit = yield* Effect.exit(running.bridge.dispose)
+		yield* Fiber.join(running.observation)
+		const failed = yield* Ref.get(running.observedFailure)
+		return Array.reduce(
+			[bridgeExit, pluginExit],
+			retired ? failed : Cause.empty,
+			(cause, exit) =>
+				Exit.isFailure(exit)
+					? Cause.combine(
+							cause,
+							Cause.fromReasons(
+								Array.flatMap(exit.cause.reasons, (reason) =>
+									reason._tag === "Fail"
+										? reason.error.cause.reasons
+										: [reason],
+								),
+							),
+						)
+					: cause,
+		)
+	})
+
+export const lifecycle = (
+	contract: RunnerContract,
+	peer: Peer,
+	identity: typeof Identity.Type,
+	telemetry: Telemetry,
+) =>
+	Effect.gen(function* () {
+		const scope = yield* Effect.scope
+		const instanceScope = yield* Scope.fork(scope)
+		const releaseExports = yield* Deferred.make<void>()
+		const state = yield* SynchronizedRef.make<Lifecycle>(Lifecycle.Idle())
+		// This gate represents host consumers draining, not a second lifecycle state.
+		const release = SynchronizedRef.update(state, (current) =>
+			Lifecycle.Disposing({ running: runningOf(current) }),
+		).pipe(Effect.andThen(Deferred.succeed(releaseExports, undefined)))
+
+		const exportBridge = Graft.plugin(
+			Plugin.make({
+				name: `${contract.name}/exports`,
+				inject: Array.map(contract.provides, (service) => service.key),
+				apply: () =>
+					Effect.gen(function* () {
+						for (const service of contract.provides)
+							yield* service.serve(peer).pipe(
+								Effect.tapCause((cause) =>
+									Cause.hasInterruptsOnly(cause)
+										? Effect.void
+										: Queue.offer(
+												telemetry.events,
+												ChildEvent.Failed({ cause }),
+											),
+								),
+								Effect.forkScoped,
+							)
+						yield* Effect.addFinalizer(() =>
+							Effect.gen(function* () {
+								const withdrawing = yield* SynchronizedRef.modify(
+									state,
+									(current) =>
+										current._tag === "Disposing"
+											? [false, current]
+											: [
+													true,
+													Lifecycle.Withdrawing({
+														running: runningOf(current),
+													}),
+												],
+								)
+								if (withdrawing)
+									yield* Queue.offer(telemetry.events, ChildEvent.Withdrawing())
+								yield* Deferred.await(releaseExports)
+							}),
+						)
+					}),
+			}),
+		).pipe(Scope.provide(instanceScope))
+
+		const start = (input: Schema.Json) =>
+			Effect.gen(function* () {
+				// Imported clients outlive Load and remain available during plugin cleanup.
+				for (const service of contract.inject)
+					yield* service.publish(peer).pipe(
+						Scope.provide(scope),
+						Effect.mapError((error) =>
+							ActivationFailed.make({
+								detail: "Publishing imported services failed",
+								cause: Cause.fail(error),
+							}),
+						),
+					)
+				const module = yield* loadModule(contract.module)
+				const plugin = Plugin.fromModule(module)
+				if (Option.isNone(plugin))
+					return yield* ActivationFailed.make({
+						detail: "The implementation module exports no plugin",
+					})
+				const fork = yield* Graft.plugin(
+					{ ...plugin.value, retry: undefined },
+					input,
+				).pipe(
+					Effect.provideService(Instance, identity),
+					Scope.provide(instanceScope),
+				)
+				const observedFailure = yield* Ref.make<Cause.Cause<unknown>>(
+					Cause.empty,
+				)
+				const observation = yield* fork.state.pipe(
+					Stream.runForEach((state) =>
+						state._tag === "Failed"
+							? Ref.set(observedFailure, state.cause)
+							: Effect.void,
+					),
+					Effect.forkIn(instanceScope),
+				)
+				const bridge = yield* exportBridge
+				return { fork, bridge, observedFailure, observation } satisfies Running
+			})
+		const awaitActive = (running: Running) =>
+			Effect.gen(function* () {
+				const first = yield* running.fork.state.pipe(
+					Stream.filter((state) => state._tag !== "Loading"),
+					Stream.runHead,
+				)
+				if (Option.isNone(first))
+					return yield* ActivationFailed.make({
+						detail: "The remote fork disappeared during startup",
+					})
+				if (first.value._tag === "Failed")
+					return yield* Effect.fail(contract.normalizeCause(first.value.cause))
+				if (first.value._tag !== "Active")
+					return yield* ActivationFailed.make({
+						detail:
+							"The remote plugin did not become active; check its declared dependencies",
+					})
+				yield* running.fork.state.pipe(
+					Stream.runForEach((state) =>
+						state._tag === "Failed"
+							? Queue.offer(
+									telemetry.events,
+									ChildEvent.Failed({ cause: state.cause }),
+								)
+							: Effect.void,
+					),
+					Effect.forkIn(instanceScope),
+				)
+				const exported = yield* running.bridge.state.pipe(
+					Stream.filter(
+						(state) =>
+							state._tag === "Active" ||
+							state._tag === "Failed" ||
+							state._tag === "Disposed",
+					),
+					Stream.runHead,
+				)
+				if (Option.isSome(exported) && exported.value._tag === "Failed")
+					return yield* ActivationFailed.make({
+						detail: "The remote export bridge failed during startup",
+						cause: exported.value.cause,
+					})
+				if (Option.isNone(exported) || exported.value._tag !== "Active")
+					return yield* ActivationFailed.make({
+						detail: "The remote export bridge stopped during startup",
+					})
+			})
+		const load = (input: Schema.Json) =>
+			Effect.gen(function* () {
+				yield* SynchronizedRef.updateEffect(state, (current) =>
+					current._tag === "Idle"
+						? Effect.succeed(Lifecycle.Loading())
+						: Effect.fail(AlreadyLoaded.make({})),
+				)
+				const running = yield* start(input)
+				yield* SynchronizedRef.update(state, (current) =>
+					current._tag === "Withdrawing"
+						? Lifecycle.Withdrawing({ running: Option.some(running) })
+						: current._tag === "Disposing"
+							? Lifecycle.Disposing({ running: Option.some(running) })
+							: Lifecycle.Running({ running }),
+				)
+				yield* awaitActive(running)
+			}).pipe(
+				Effect.mapError((error) =>
+					Cause.isCause(error)
+						? error
+						: contract.normalizeCause(Cause.fail(error)),
+				),
+			)
+		const dispose = Effect.gen(function* () {
+			const previous = yield* SynchronizedRef.get(state)
+			yield* release
+			const current = runningOf(previous)
+			const retired = previous._tag === "Withdrawing"
+			const cause = Option.isSome(current)
+				? yield* cleanup(current.value, retired)
+				: Cause.empty
+			yield* Queue.offer(telemetry.events, ChildEvent.Stopped())
+			yield* Queue.end(telemetry.logs)
+			if (cause.reasons.length > 0)
+				return yield* Effect.fail(contract.normalizeCause(cause))
+		})
+		return { load, dispose, release }
+	})

package/src/internal/childErrors.ts

@@ -0,0 +1,44 @@
+import { Schema } from "effect"
+
+export class AlreadyLoaded extends Schema.TaggedError<
+	AlreadyLoaded,
+	{ readonly brand: unique symbol }
+>()("AlreadyLoaded", {}) {}
+export class ContractNotFound extends Schema.TaggedError<
+	ContractNotFound,
+	{ readonly brand: unique symbol }
+>()("ContractNotFound", { module: Schema.String }) {
+	override get message() {
+		return `No remote contract exported by ${this.module}`
+	}
+}
+export class ModuleImportFailed extends Schema.TaggedError<
+	ModuleImportFailed,
+	{ readonly brand: unique symbol }
+>()("ModuleImportFailed", {
+	module: Schema.String,
+	cause: Schema.Defect({ includeStack: true }),
+}) {}
+export class ActivationFailed extends Schema.TaggedError<
+	ActivationFailed,
+	{ readonly brand: unique symbol }
+>()("ActivationFailed", {
+	detail: Schema.String,
+	cause: Schema.optionalKey(
+		Schema.Cause(
+			Schema.Defect({ includeStack: true }),
+			Schema.Defect({ includeStack: true }),
+		),
+	),
+}) {
+	override get message() {
+		return this.detail
+	}
+}
+export const ChildFailure = Schema.Union([
+	AlreadyLoaded,
+	ContractNotFound,
+	ModuleImportFailed,
+	ActivationFailed,
+])
+export type ChildFailure = typeof ChildFailure.Type

package/src/internal/childRuntime.ts

@@ -0,0 +1,111 @@
+import { loadModule } from "./loadModule"
+import { ContractNotFound } from "./childErrors"
+import type { Graft } from "@graftland/graft"
+import { Effect, Logger, Option } from "effect"
+import { RpcServer } from "effect/rpc"
+import { fromModule, type RunnerContract } from "../Contract"
+import * as Port from "./port"
+import * as Services from "./services"
+import * as Child from "./child"
+import * as Multiplex from "./runner/Multiplex"
+import * as Wire from "./runner/Wire"
+import type { Bootstrap } from "./runner/Bootstrap"
+import { ExecutionError } from "./runner/model"
+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
+	})
+
+const connect = (
+	contract: RunnerContract,
+	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 }),
+			},
+		)
+	})
+
+/** One execution unit; the executable supplies the platform and Graft services. */
+export const run = (
+	contract: RunnerContract,
+	channel: Port.Channel,
+	session = "local",
+	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),
+				)
+			}).pipe(
+				Effect.provideService(
+					Logger.CurrentLoggers,
+					new Set([...loggers, telemetry.logger]),
+				),
+			)
+		}),
+	)

package/src/internal/cleanup.ts

@@ -0,0 +1,34 @@
+import { Fork } from "@graftland/graft"
+import { Array, Cause, Effect, Schema, Scope } from "effect"
+import * as Release from "./release"
+
+/** Finalizers have no typed failure channel. Keep reasons and their annotations flat. */
+export const cleanupCause = (cause: Cause.Cause<unknown>): Cause.Cause<never> =>
+	Cause.fromReasons(
+		Array.flatMap(cause.reasons, (reason) => {
+			const error =
+				reason._tag === "Fail"
+					? reason.error
+					: reason._tag === "Die"
+						? reason.defect
+						: undefined
+			if (Schema.is(Fork.CleanupError)(error))
+				return Array.map(cleanupCause(error.cause).reasons, (inner) =>
+					inner.annotate(Cause.reasonAnnotations(reason)),
+				)
+			return [
+				reason._tag === "Fail"
+					? Cause.makeDieReason(reason.error).annotate(
+							Cause.reasonAnnotations(reason),
+						)
+					: reason,
+			]
+		}),
+	)
+
+/** Assembly children close before the entry reports their cleanup as its own result. */
+export const children = Effect.acquireRelease(Scope.make(), (scope, exit) =>
+	Release.close(scope, exit).pipe(
+		Effect.catchCause((cause) => Effect.failCause(cleanupCause(cause))),
+	),
+)

package/src/internal/config.ts

@@ -0,0 +1,8 @@
+import { Duration, Schema } from "effect"
+
+export const PositiveDuration = Schema.DurationFromString.check(
+	Schema.makeFilter(
+		(value) => Duration.isFinite(value) && Duration.toMillis(value) > 0,
+		{ expected: "a finite, positive duration" },
+	),
+)

package/src/internal/control.ts

@@ -0,0 +1,49 @@
+import { Schema } from "effect"
+import { Rpc, RpcGroup } from "effect/rpc"
+
+import { Priority } from "./port"
+
+export const Log = Schema.Struct({
+	level: Schema.Literals([
+		"Fatal",
+		"Error",
+		"Warn",
+		"Info",
+		"Debug",
+		"Trace",
+		"All",
+		"None",
+	]),
+	message: Schema.Defect({ includeStack: true }),
+	cause: Schema.Json,
+	annotations: Schema.Record(
+		Schema.String,
+		Schema.Defect({ includeStack: true }),
+	),
+})
+export const Event = Schema.Union([
+	Schema.TaggedStruct("Failed", { cause: Schema.Json }),
+	Schema.TaggedStruct("Stopped", {}),
+	Schema.TaggedStruct("Withdrawing", {}),
+])
+export const LogEvent = Schema.Union([
+	Schema.TaggedStruct("Log", { entry: Log, dropped: Schema.Int }),
+	Schema.TaggedStruct("LogsEnded", { dropped: Schema.Int }),
+])
+export const endpoint = "@graftland/plugin-remote/control"
+export const make = <C extends Schema.Top>(cause: C) =>
+	RpcGroup.make(
+		Rpc.make("Load", {
+			payload: { input: Schema.Json },
+			error: cause,
+		}),
+		Rpc.make("Events", { success: Event, stream: true }),
+		Rpc.make("Dispose", { error: cause }),
+	)
+		.annotateRpcs(Priority, "control")
+		.add(
+			Rpc.make("Logs", { success: LogEvent, stream: true }).annotate(
+				Priority,
+				"log",
+			),
+		)

package/src/internal/credentials.ts

@@ -0,0 +1,112 @@
+import { Graft, Plugin } from "@graftland/graft"
+import { Cause, Context, Effect, Redacted, Scope } from "effect"
+import { Credentials, type ClientCertificate, type Prepared } from "../Auth"
+import { CredentialsError } from "../Errors"
+import { prepare } from "./auth/token"
+import type * as Configuration from "./entryConfig"
+
+export type Source<A, D extends ReadonlyArray<Plugin.Dependency>, E = unknown> =
+	| Effect.Effect<A, E, Scope.Scope>
+	| {
+			readonly inject: D
+			readonly read: Effect.Effect<
+				A,
+				unknown,
+				NoInfer<Plugin.Required<D>> | Scope.Scope
+			>
+	  }
+type Token<D extends ReadonlyArray<Plugin.Dependency>> =
+	string | { readonly file: string } | Source<Redacted.Redacted<string>, D>
+type Authentication<D extends ReadonlyArray<Plugin.Dependency>> =
+	| { readonly name: string; readonly config?: unknown }
+	| { readonly none: { readonly identity?: string } }
+	| {
+			readonly mtls:
+				| { readonly cert: string; readonly key: string }
+				| Source<ClientCertificate, D>
+	  }
+	| { 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>
+
+const provider = <A, E, D extends ReadonlyArray<Plugin.Dependency>>(
+	source: Source<A, D, E>,
+	encode: (
+		read: Effect.Effect<A, CredentialsError, Scope.Scope>,
+	) => typeof Credentials.Service,
+) => {
+	const input = Effect.isEffect(source) ? { inject: [], read: source } : source
+	return Plugin.make({
+		name: "remote-effect-credentials",
+		inject: input.inject,
+		apply: Effect.fnUntraced(function* () {
+			// Restore the provider's context without replacing each read's owning scope.
+			const context = yield* Effect.context<
+				Plugin.Required<D> | Scope.Scope
+			>().pipe(Effect.map(Context.omit(Scope.Scope)))
+			const read = input.read.pipe(
+				Effect.provideContext(context),
+				Effect.mapError((error) =>
+					CredentialsError.make({ cause: Cause.fail(error) }),
+				),
+			)
+			yield* Graft.provide(Credentials, encode(read))
+		}),
+	})
+}
+export const invocation = <D extends ReadonlyArray<Plugin.Dependency>>(
+	connect: Connect<D>,
+) => {
+	const auth = connect.auth
+	if (auth === undefined) return undefined
+	if ("mtls" in auth) {
+		const source = auth.mtls
+		if (Effect.isEffect(source) || "read" in source)
+			return {
+				plugin: provider(source, (read) => ({
+					kind: "Certificate",
+					read: read.pipe(
+						Effect.map(
+							(value): Extract<Prepared, { readonly _tag: "Certificate" }> => ({
+								_tag: "Certificate",
+								value,
+							}),
+						),
+					),
+				})),
+				config: undefined,
+			}
+	}
+	if ("bearer" in auth || "jwt" in auth) {
+		const source = "bearer" in auth ? auth.bearer.token : auth.jwt.token
+		if (
+			typeof source !== "string" &&
+			(Effect.isEffect(source) || "read" in source)
+		)
+			return {
+				plugin: provider(source, (read) => ({
+					kind: "Authorization",
+					read: read.pipe(
+						Effect.flatMap(prepare),
+						Effect.map(
+							(
+								value,
+							): Extract<Prepared, { readonly _tag: "Authorization" }> => ({
+								_tag: "Authorization",
+								value,
+							}),
+						),
+					),
+				})),
+				config: undefined,
+			}
+	}
+	return undefined
+}