@graftland/plugin-remote 0.0.0-stage → 0.3.0

package/src/internal/directTransport.ts

@@ -0,0 +1,38 @@
+import { Context } from "effect"
+import type { Effect, Option, Scope, PlatformError } from "effect"
+import type { ProcessExited, TransportError } from "../Errors"
+import type { Channel } from "../Transport"
+export interface LocalOptions {
+	readonly command?: readonly [string, ...string[]]
+	readonly contractModule: string
+	readonly session: string
+}
+export interface Execution {
+	readonly channel: Channel
+	readonly pid: Option.Option<number>
+	readonly threadId?: number
+	readonly exited: Effect.Effect<ProcessExited, TransportError>
+	readonly failure: Effect.Effect<never, TransportError>
+}
+export class LocalTransport extends Context.Service<
+	LocalTransport,
+	{
+		readonly start: (
+			options: LocalOptions,
+		) => Effect.Effect<Execution, PlatformError.PlatformError, Scope.Scope>
+	}
+>()("@graftland/plugin-remote/internal/directTransport/LocalTransport") {}
+
+export interface WorkerOptions {
+	readonly execArgv?: ReadonlyArray<string>
+	readonly contractModule: string
+	readonly session: string
+}
+export class WorkerTransport extends Context.Service<
+	WorkerTransport,
+	{
+		readonly start: (
+			options: WorkerOptions,
+		) => Effect.Effect<Execution, TransportError, Scope.Scope>
+	}
+>()("@graftland/plugin-remote/internal/directTransport/WorkerTransport") {}

package/src/internal/entry.ts

@@ -0,0 +1,288 @@
+import { Graft, Plugin, type Fork } from "@graftland/graft"
+import { ConfigDirectory, Entry, ModuleResolver } from "@graftland/loader"
+import {
+	Cause,
+	Effect,
+	Option,
+	Path,
+	Schema,
+	References,
+	Scope,
+	String,
+} from "effect"
+import { ChildProcessSpawner } from "effect/process"
+import * as Contract from "../Contract"
+import { MissingInstance } from "../Errors"
+import { LocalTransport, WorkerTransport } from "./directTransport"
+import * as Configuration from "./entryConfig"
+import * as Assembly from "./assembly"
+import { executionPlugin } from "./execution"
+import { follow } from "./follow"
+import { children } from "./cleanup"
+import { resolveEntry } from "./runner/Packages"
+import type { LocalTarget, WorkerTarget } from "./runner/Connection"
+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
+	return (cause: Cause.Cause<unknown>) =>
+		Effect.fail(EntryError.make({ entry, directory, field, cause }))
+})
+export const resolve = Effect.fnUntraced(function* (
+	reference: Configuration.Reference,
+	field: string,
+) {
+	const existing = yield* Effect.serviceOption(ModuleResolver.ModuleResolver)
+	const path = yield* Path.Path
+	const source = yield* ConfigDirectory
+	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),
+				})
+			}),
+	})
+	const fail = yield* boundary(field)
+	const plugin = yield* resolver
+		.resolve(reference.name)
+		.pipe(Effect.catchCause(fail))
+	return { plugin, config: reference.config }
+})
+export const loadContract = Effect.fnUntraced(function* (specifier: string) {
+	const resolver = yield* ModuleResolver.ModuleResolver
+	const fail = yield* boundary("contract")
+	return yield* resolver.importModule(specifier).pipe(
+		Effect.flatMap((module) =>
+			Effect.fromOption(Contract.fromModule(module), () =>
+				ModuleResolver.ModuleInvalid.make({
+					specifier,
+					cause: "Expected a default or named remote contract",
+				}),
+			),
+		),
+		Effect.catchCause(fail),
+	)
+})
+
+/** Direct execution installs only its execution capability in a private realm. */
+export const direct = (
+	provider: Plugin.Plugin,
+	consumer: Plugin.Plugin,
+	input: Schema.Json,
+	key: typeof LocalTransport | typeof WorkerTransport,
+): Effect.Effect<Fork.Fork<never, unknown>, never, Graft.Graft | Scope.Scope> =>
+	Graft.plugin(
+		Plugin.make({
+			name: "remote-direct",
+			apply: Effect.fnUntraced(function* () {
+				const capability = yield* Graft.plugin(provider)
+				yield* follow(capability, (cause) =>
+					Effect.fail(Assembly.CapabilityFailed.make({ cause })),
+				)
+				const execution = yield* Graft.plugin(consumer, input)
+				yield* follow(execution, (cause) =>
+					Effect.fail(Assembly.CapabilityFailed.make({ cause })),
+				)
+			}),
+		}),
+		undefined,
+		{ isolate: [key] },
+	)
+
+type Annotations = Readonly<Record<string, unknown>>
+const directTarget = Effect.fnUntraced(function* <
+	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>,
+	input: typeof Configuration.Host.Type,
+	selected: LocalTarget | WorkerTarget,
+	annotations: Annotations,
+	options: ExecutionOptions,
+) {
+	const path = yield* Path.Path
+	const source = yield* ConfigDirectory
+	const directory = path.resolve(Option.getOrElse(source, () => "."))
+	const module = String.startsWith("file:")(input.contract)
+		? input.contract
+		: yield* resolveEntry(directory, input.contract)
+	const capability = yield* resolve(
+		{
+			name:
+				selected._tag === "Local"
+					? "@graftland/plugin-remote/host/local"
+					: "@graftland/plugin-remote/host/worker",
+		},
+		"connect",
+	)
+	return yield* direct(
+		capability.plugin,
+		executionPlugin(
+			contract,
+			{ ...options, contractModule: module },
+			selected,
+			annotations,
+		),
+		input.config,
+		selected._tag === "Local" ? LocalTransport : WorkerTransport,
+	)
+})
+const runnerTarget = Effect.fnUntraced(function* <
+	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>,
+	input: typeof Configuration.Host.Type,
+	target: Exclude<
+		Configuration.Connect,
+		{ readonly local: object } | { readonly worker: object }
+	>,
+	annotations: Annotations,
+	options: ExecutionOptions,
+	authOverride: typeof Assembly.Invocation.Type | undefined,
+) {
+	const instance =
+		target.instance === undefined
+			? yield* Entry.CurrentId
+			: Option.some(target.instance)
+	if (Option.isNone(instance)) return yield* MissingInstance.make({})
+	const transport = yield* resolve(
+		Configuration.hostTransport(target),
+		"connect.transport",
+	)
+	const auth =
+		authOverride ??
+		(yield* resolve(
+			Configuration.authentication("host", target.auth),
+			"connect.auth",
+		))
+	const consumer = executionPlugin(
+		contract,
+		options,
+		{
+			_tag: "Connector",
+			explicitAuth: target.auth !== undefined,
+			instance: instance.value,
+			...(target.lease === undefined ? {} : { lease: target.lease }),
+			...(target.margin === undefined ? {} : { margin: target.margin }),
+			...(target.expect === undefined ? {} : { expect: target.expect }),
+		},
+		annotations,
+	)
+	return yield* Assembly.host({
+		transport,
+		auth,
+		consumer,
+		input: input.config,
+	})
+})
+
+export const launch = Effect.fnUntraced(function* <
+	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>,
+	input: typeof Configuration.Host.Type,
+	options: ExecutionOptions,
+	authOverride?: typeof Assembly.Invocation.Type,
+) {
+	const annotations = yield* References.CurrentLogAnnotations
+	const connect = input.connect
+	const scope = yield* children
+	return yield* Effect.gen(function* () {
+		if (connect.local !== undefined)
+			return yield* directTarget(
+				contract,
+				input,
+				{ _tag: "Local", ...connect.local },
+				annotations,
+				options,
+			)
+		if (connect.worker !== undefined)
+			return yield* directTarget(
+				contract,
+				input,
+				{ _tag: "Worker", ...connect.worker },
+				annotations,
+				options,
+			)
+		return yield* runnerTarget(
+			contract,
+			input,
+			connect,
+			annotations,
+			options,
+			authOverride,
+		)
+	}).pipe(Scope.provide(scope))
+})
+const load = Effect.fnUntraced(function* (
+	input: typeof Configuration.Host.Type,
+) {
+	const contract = yield* loadContract(input.contract)
+	const failConfig = yield* boundary("config")
+	yield* Schema.decodeEffect(contract.config)(input.config).pipe(
+		Effect.catchCause(failConfig),
+	)
+	const failConnect = yield* boundary("connect")
+	const fork = yield* launch(contract, input, {
+		contractModule: input.contract,
+	}).pipe(Effect.catchCause(failConnect))
+	yield* follow(fork, failConnect)
+})
+export const host = Plugin.make({
+	name: "remote",
+	config: Configuration.Host,
+	inject: [
+		SecureRandom.SecureRandom,
+		ModuleResolver.ModuleResolver,
+		Path.Path,
+		ChildProcessSpawner.ChildProcessSpawner,
+	],
+	apply: load,
+})

package/src/internal/entryConfig.ts

@@ -0,0 +1,190 @@
+import { Effect, Schema } from "effect"
+import { PositiveDuration } from "./config"
+
+export const Reference = Schema.Struct({
+	name: Schema.String,
+	config: Schema.optionalKey(Schema.Unknown),
+})
+export type Reference = typeof Reference.Type
+const absent = Schema.optionalKey(Schema.Never)
+const authFields = {
+	name: absent,
+	config: absent,
+	mtls: absent,
+	bearer: absent,
+	jwt: absent,
+	none: absent,
+}
+export const Authentication = Schema.Union([
+	Schema.Struct({
+		...authFields,
+		name: Schema.String,
+		config: Schema.optionalKey(Schema.Unknown),
+	}),
+	Schema.Struct({ ...authFields, mtls: Schema.Unknown }),
+	Schema.Struct({ ...authFields, bearer: Schema.Unknown }),
+	Schema.Struct({ ...authFields, jwt: Schema.Unknown }),
+	Schema.Struct({ ...authFields, none: Schema.Unknown }),
+])
+const transportFields = {
+	url: absent,
+	unix: absent,
+	command: absent,
+	stdio: absent,
+	local: absent,
+	worker: absent,
+	transport: absent,
+}
+const auth = Schema.optionalKey(Authentication)
+const common = {
+	instance: Schema.optionalKey(Schema.String),
+	lease: Schema.optionalKey(PositiveDuration),
+	margin: Schema.optionalKey(PositiveDuration),
+	expect: Schema.optionalKey(
+		Schema.Struct({
+			version: Schema.optionalKey(Schema.String),
+			digest: Schema.optionalKey(Schema.String),
+		}),
+	),
+}
+const network = {
+	...transportFields,
+	...common,
+	auth,
+	url: Schema.String,
+	ca: Schema.optionalKey(Schema.String),
+	servername: Schema.optionalKey(Schema.String),
+}
+export const Connect = Schema.Union([
+	Schema.Struct(network),
+	Schema.Struct({ ...transportFields, ...common, auth, unix: Schema.String }),
+	Schema.Struct({
+		...transportFields,
+		...common,
+		command: Schema.NonEmptyArray(Schema.String),
+		auth: Schema.optionalKey(
+			Schema.Never.annotate({
+				message: "Direct and stdio transports do not accept auth",
+			}),
+		),
+		cwd: Schema.optionalKey(Schema.String),
+		env: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)),
+	}),
+	Schema.Struct({
+		...transportFields,
+		auth: Schema.optionalKey(
+			Schema.Never.annotate({
+				message: "Direct and stdio transports do not accept auth",
+			}),
+		),
+		local: Schema.Struct({
+			command: Schema.optionalKey(Schema.NonEmptyArray(Schema.String)),
+		}),
+	}),
+	Schema.Struct({
+		...transportFields,
+		auth: Schema.optionalKey(
+			Schema.Never.annotate({
+				message: "Direct and stdio transports do not accept auth",
+			}),
+		),
+		worker: Schema.Struct({
+			execArgv: Schema.optionalKey(Schema.Array(Schema.String)),
+		}),
+	}),
+	Schema.Struct({ ...transportFields, ...common, auth, transport: Reference }),
+])
+export type Connect = typeof Connect.Type
+export const Listen = Schema.Union([
+	Schema.Struct({
+		...transportFields,
+		auth,
+		url: Schema.String,
+		cert: Schema.optionalKey(Schema.String),
+		key: Schema.optionalKey(Schema.String),
+	}),
+	Schema.Struct({ ...transportFields, auth, unix: Schema.String }),
+	Schema.Struct({
+		...transportFields,
+		stdio: Schema.Literal(true),
+		auth: Schema.optionalKey(
+			Schema.Never.annotate({
+				message: "Direct and stdio transports do not accept auth",
+			}),
+		),
+		identity: Schema.optionalKey(Schema.String),
+	}),
+	Schema.Struct({ ...transportFields, auth, transport: Reference }),
+])
+export type Listen = typeof Listen.Type
+const capability = (
+	side: "host" | "runner",
+	name: string,
+	config: unknown,
+): Reference => ({ name: `@graftland/plugin-remote/${side}/${name}`, config })
+export const authentication = (
+	side: "host" | "runner",
+	input: typeof Authentication.Type | undefined,
+): Reference => {
+	if (input === undefined) return capability(side, "auth/none", {})
+	if (input.name !== undefined) return input
+	if (input.mtls !== undefined) return capability(side, "auth/mtls", input.mtls)
+	if (input.bearer !== undefined)
+		return capability(side, "auth/bearer", input.bearer)
+	if (input.jwt !== undefined) return capability(side, "auth/jwt", input.jwt)
+	return capability(side, "auth/none", input.none)
+}
+export const hostTransport = (
+	input: Exclude<
+		Connect,
+		{ readonly local: object } | { readonly worker: object }
+	>,
+): Reference => {
+	if (input.transport !== undefined) return input.transport
+	if (input.url !== undefined)
+		return capability("host", "websocket", {
+			url: input.url,
+			...(input.ca === undefined ? {} : { ca: input.ca }),
+			...(input.servername === undefined
+				? {}
+				: { servername: input.servername }),
+		})
+	if (input.unix !== undefined)
+		return capability("host", "unix", { path: input.unix })
+	return capability("host", "command", {
+		argv: input.command,
+		...("cwd" in input && input.cwd !== undefined ? { cwd: input.cwd } : {}),
+		...("env" in input && input.env !== undefined ? { env: input.env } : {}),
+	})
+}
+export const runnerTransport = (input: Listen): Reference => {
+	if (input.transport !== undefined) return input.transport
+	if (input.url !== undefined)
+		return capability("runner", "websocket", {
+			url: input.url,
+			...(input.cert === undefined ? {} : { cert: input.cert }),
+			...(input.key === undefined ? {} : { key: input.key }),
+		})
+	if (input.unix !== undefined)
+		return capability("runner", "unix", { path: input.unix })
+	return capability("runner", "stdio", {})
+}
+export const Host = Schema.Struct({
+	contract: Schema.String,
+	connect: Connect,
+	config: Schema.Json.pipe(Schema.withDecodingDefaultKey(Effect.succeed({}))),
+})
+export const Runner = Schema.Struct({
+	root: Schema.String,
+	state: Schema.String,
+	lease: Schema.optionalKey(PositiveDuration),
+	grace: Schema.optionalKey(PositiveDuration),
+	listen: Schema.Array(Listen),
+})
+
+export const runnerAuthentication = (input: Listen): Reference =>
+	input.stdio !== undefined
+		? capability("runner", "auth/none", {
+				identity: input.identity ?? "anonymous",
+			})
+		: authentication("runner", input.auth)

package/src/internal/execution.ts

@@ -0,0 +1,121 @@
+import { Plugin } from "@graftland/graft"
+import { Array, Cause, Effect, Fiber, Schema, Scope } from "effect"
+import { SecureRandom } from "effect/crypto"
+import type {
+	LocalTarget as Local,
+	WorkerTarget as Worker,
+} from "./runner/Connection"
+import { Connector } from "../Transport"
+import { LocalTransport, WorkerTransport } from "./directTransport"
+import { Credentials } from "../Auth"
+import type { Duration } from "effect"
+import * as Connection from "./runner/Connection"
+import * as Services from "./services"
+import * as Host from "./host"
+import { RemoteWithdrawn, RemoteError, MissingInstance } from "../Errors"
+import * as Contract from "../Contract"
+import * as Control from "./control"
+
+export interface ExecutionOptions {
+	readonly contractModule: string
+	readonly shutdownTimeout?: Duration.Input | undefined
+}
+
+const dependencies = (
+	target: Local | Worker | Connection.ConfiguredRunner,
+): ReadonlyArray<Plugin.Dependency> =>
+	target._tag === "Connector"
+		? [Connector, Credentials]
+		: target._tag === "Local"
+			? [LocalTransport]
+			: [WorkerTransport]
+
+/** One owned execution per activation, with explicitly mapped services. */
+export const executionPlugin = <
+	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>,
+	options: ExecutionOptions,
+	configured: Local | Worker | Connection.ConfiguredRunner,
+	annotations: Readonly<Record<string, unknown>> = {},
+): Plugin.Plugin<
+	S["Encoded"],
+	S["Encoded"],
+	| E["Type"]
+	| Contract.UndeclaredFailure
+	| RemoteError
+	| RemoteWithdrawn
+	| MissingInstance
+> =>
+	Plugin.make({
+		name: contract.name,
+		inject: [
+			SecureRandom.SecureRandom,
+			...dependencies(configured),
+			...Array.map(contract.inject, (service) => service.key),
+		],
+		config: Schema.toEncoded(contract.config),
+		apply: (input) =>
+			Effect.gen(function* () {
+				const random = yield* SecureRandom.SecureRandom
+				const session = yield* random.uuidV4()
+				const active = yield* Connection.acquire(
+					configured,
+					options.contractModule,
+					{
+						session,
+						serve: Services.endpoints(contract.inject),
+						call: {
+							...Services.endpoints(contract.provides),
+							[Control.endpoint]: contract.control,
+						},
+					},
+					Host.initialize(contract),
+					Host.dispose,
+					options.shutdownTimeout ?? "5 seconds",
+				)
+				yield* Host.load(active, input)
+				for (const service of contract.provides)
+					yield* service
+						.publish(active.connection.transport)
+						.pipe(Scope.provide(active.connection.resources))
+				yield* Plugin.fork(
+					Effect.raceFirst(
+						Fiber.join(active.events),
+						active.remoteFailure.await,
+					).pipe(
+						Effect.mapError((error) => publicError(contract.error, error)),
+					),
+				)
+				return () => Effect.succeed(false)
+			}).pipe(
+				Effect.annotateLogs(annotations),
+				Effect.mapError((error) => publicError(contract.error, error)),
+			),
+	})
+
+export const publicError = <E extends Schema.Top>(
+	declared: E,
+	error: unknown,
+):
+	| E["Type"]
+	| Contract.UndeclaredFailure
+	| RemoteWithdrawn
+	| RemoteError
+	| MissingInstance =>
+	Schema.is(declared)(error)
+		? error
+		: Schema.is(Contract.UndeclaredFailure)(error) ||
+			  Schema.is(RemoteWithdrawn)(error) ||
+			  Schema.is(RemoteError)(error) ||
+			  Schema.is(MissingInstance)(error)
+			? error
+			: RemoteError.make({ cause: Cause.fail(error) })

package/src/internal/follow.ts

@@ -0,0 +1,17 @@
+import { Plugin, type Fork, type Graft } from "@graftland/graft"
+import { Effect, Stream, type Cause, type Schema } from "effect"
+
+/** Follow startup and later failures without changing the caller's error boundary. */
+export const follow = Effect.fnUntraced(function* <I, E, F>(
+	fork: Fork.Fork<I, E>,
+	fail: (cause: Cause.Cause<E | Schema.SchemaError>) => Effect.Effect<never, F>,
+): Effect.fn.Return<void, F, Graft.Graft | Plugin.Tasks<F>> {
+	yield* fork.await.pipe(Effect.catchCause(fail))
+	yield* Plugin.fork(
+		fork.state.pipe(
+			Stream.runForEach((state) =>
+				state._tag === "Failed" ? fail(state.cause) : Effect.void,
+			),
+		),
+	)
+})

package/src/internal/forkTree.ts

@@ -0,0 +1,13 @@
+import type { Fork } from "@graftland/graft"
+import { Array, Option } from "effect"
+
+export const findSubtree = (
+	trees: ReadonlyArray<Fork.ForkTree>,
+	id: number,
+): Option.Option<Fork.ForkTree> =>
+	Array.findFirst(trees, (tree) =>
+		tree.id === id ? Option.some(tree) : findSubtree(tree.children, id),
+	)
+
+export const isSubtreeActive = (tree: Fork.ForkTree): boolean =>
+	tree.state._tag === "Active" && Array.every(tree.children, isSubtreeActive)