@graftland/plugin-remote 0.3.0 → 0.3.2

package/dist/{websocketServer-MXcCJx0v.js → websocketServer-NQhODlEt.js}

@@ -1,11 +1,13 @@
-import { c as TransportError } from "./Errors-oPsTLY7l.js";
-import { a as payloadLimit, s as protocol, t as fromSocket } from "./socketChannel-KmtzF-9G.js";
+import { u as TransportError } from "./Errors-DYhsGZcZ.js";
+import { a as payloadLimit, s as protocol, t as fromSocket } from "./socketChannel-CJvL2DiB.js";
 import { Array, Cause, Deferred, Effect, Option, Redacted, Scope, String } from "effect";
 import { NodeHttpServer, NodeHttpServerRequest } from "@effect/platform-node";
 import { HttpServerRequest, HttpServerResponse } from "effect/http";
 import { TLSSocket } from "node:tls";
 // packages/remote/src/internal/websocketServer.ts
-const rejection = (error) => Effect.logWarning("Remote host authentication failed", { reason: error.reason }, ...error.cause === void 0 ? [] : [error.cause]).pipe(Effect.as(HttpServerResponse.empty({
+const rejection = (error) => error._tag === "AuthenticatorUnavailable" ? unavailable(error) : unauthorized(error);
+const unavailable = (error) => Effect.logError("Remote host authenticator is unavailable", error.cause).pipe(Effect.as(HttpServerResponse.empty({ status: 503 })));
+const unauthorized = (error) => Effect.logWarning("Remote host authentication failed", { reason: error.reason }, ...error.cause === void 0 ? [] : [error.cause]).pipe(Effect.as(HttpServerResponse.empty({
 	status: 401,
 	headers: error.challenge === void 0 ? {} : { "www-authenticate": error.challenge }
 })));

package/dist/{workerChannel-P82YdNjh.js → workerChannel-C8hhBJzA.js}

@@ -1,4 +1,4 @@
-import { c as TransportError } from "./Errors-oPsTLY7l.js";
+import { u as TransportError } from "./Errors-DYhsGZcZ.js";
 import { Cause, Effect, FiberSet, Queue, Schema, Sink, Stream } from "effect";
 // packages/remote/src/internal/workerBootstrap.ts
 const Bootstrap = Schema.Struct({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graftland/plugin-remote",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "type": "module",
   "description": "Local and authenticated network execution for Graft plugins",
   "license": "Apache-2.0",
@@ -49,9 +49,9 @@
     "effect": "4.1.*"
   },
   "dependencies": {
-    "@graftland/graft": "0.3.0",
+    "@graftland/graft": "0.3.2",
     "@effect/platform-node": "4.1.2",
-    "@graftland/loader": "0.3.0",
+    "@graftland/loader": "0.3.2",
     "pkijs": "4.0.1",
     "asn1js": "4.0.0",
     "ws": "8.22.1"

package/src/Auth.ts

@@ -1,7 +1,11 @@
 /** Credentials and authenticated identities shared by transport plugins. */
 import { Context } from "effect"
 import type { Effect, Redacted, Option, Scope } from "effect"
-import type { AuthenticationFailed, CredentialsError } from "./Errors"
+import type {
+	AuthenticationFailed,
+	AuthenticatorUnavailable,
+	CredentialsError,
+} from "./Errors"
 
 export interface ClientCertificate {
 	readonly cert: string
@@ -42,7 +46,10 @@ export type AuthenticatorApi =
 			readonly issuer?: string
 			readonly authenticate: (
 				header: Option.Option<Redacted.Redacted<string>>,
-			) => Effect.Effect<string, AuthenticationFailed>
+			) => Effect.Effect<
+				string,
+				AuthenticationFailed | AuthenticatorUnavailable
+			>
 	  }
 	| {
 			readonly _tag: "Mtls"

package/src/Contract.ts

@@ -1,38 +1,79 @@
-import { ChildFailure } from "./internal/childErrors"
-export { ChildFailure }
-import { Array, Cause, Predicate, Schema } from "effect"
-
-import type { Service } from "./internal/services"
+import { Array, Predicate, Schema } from "effect"
+import type { Context, Effect, Scope } from "effect"
+import type { Graft } from "@graftland/graft"
+import type { Rpc, RpcClient, RpcGroup, RpcServer } from "effect/rpc"
 import * as Control from "./internal/control"
 export { service } from "./internal/services"
 
 const TypeId = "~@graftland/plugin-remote/Contract"
 
-/** An undeclared failure still crosses the boundary, with its diagnostic value. */
-export class UndeclaredFailure extends Schema.TaggedError<
-	UndeclaredFailure,
-	{ readonly brand: unique symbol }
->()("UndeclaredFailure", { original: Schema.Defect({ includeStack: true }) }) {}
+/** RPC types stay inside the descriptor; Graft supplies its dynamic activation context. */
+export interface Service<R = never, ClientR = never> {
+	readonly key: Context.Key<unknown, unknown>
+	readonly group: Pick<RpcGroup.RpcGroup<Rpc.Any>, "requests">
+	readonly serve: (port: {
+		readonly serverProtocol: (endpoint: string) => RpcServer.Protocol["Service"]
+	}) => Effect.Effect<never, never, R>
+	readonly publish: (port: {
+		readonly clientProtocol: (endpoint: string) => RpcClient.Protocol["Service"]
+	}) => Effect.Effect<
+		void,
+		Graft.ServiceConflict,
+		Graft.Graft | Scope.Scope | ClientR
+	>
+}
 
-/** Pure metadata shared by the host and the executable runner bootstrap. */
-export const make = <
-	S extends Schema.Top & {
-		readonly Encoded: Schema.Json
-		readonly DecodingServices: never
-		readonly EncodingServices: never
-	},
-	E extends Schema.Top & {
-		readonly DecodingServices: never
-		readonly EncodingServices: never
-	},
->(options: {
+/** A self-contained configuration schema that encodes as JSON. */
+export type ConfigSchema = Schema.Top & {
+	readonly Encoded: Schema.Json
+	readonly DecodingServices: never
+	readonly EncodingServices: never
+}
+/** A self-contained schema for declared failures. */
+export type ErrorSchema = Schema.Top & {
+	readonly DecodingServices: never
+	readonly EncodingServices: never
+}
+
+/** The shared configuration and service declarations for one remote plugin. */
+export interface Contract<
+	S extends ConfigSchema,
+	E extends ErrorSchema = typeof Schema.Never,
+> {
 	readonly name: string
 	readonly config: S
 	readonly error: E
 	readonly module: string
+	readonly inject: ReadonlyArray<Service>
+	readonly provides: ReadonlyArray<Service>
+	readonly [TypeId]: typeof TypeId
+}
+/** Configuration accepted by make; omitted errors default to Never. */
+export interface Options<S extends ConfigSchema, E extends ErrorSchema> {
+	readonly name: string
+	readonly config: S
+	readonly error?: E
+	readonly module: string
 	readonly inject?: ReadonlyArray<Service>
 	readonly provides?: ReadonlyArray<Service>
-}) => {
+}
+
+/** An undeclared failure still crosses the boundary, with its diagnostic value. */
+export class UndeclaredFailure extends Schema.TaggedError<
+	UndeclaredFailure,
+	{ readonly brand: unique symbol }
+>()("UndeclaredFailure", { original: Schema.Defect({ includeStack: true }) }) {}
+
+/** Pure metadata shared by the host and the executable runner bootstrap. */
+export function make<S extends ConfigSchema, E extends ErrorSchema>(
+	options: Options<S, E> & { readonly error: E },
+): Contract<S, E>
+export function make<S extends ConfigSchema>(
+	options: Options<S, typeof Schema.Never>,
+): Contract<S>
+export function make<S extends ConfigSchema, E extends ErrorSchema>(
+	options: Options<S, E>,
+): Contract<S, E | typeof Schema.Never> {
 	// Keys are runtime strings; tuple types cannot distinguish independently created keys.
 	const keys = Array.map(
 		[...(options.inject ?? []), ...(options.provides ?? [])],
@@ -45,42 +86,17 @@ export const make = <
 		throw new Error(
 			"Service keys must be unique within a remote contract and must not use the control endpoint",
 		)
-	const failure = Schema.Union([options.error, 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 : UndeclaredFailure.make({ original: error }),
-		)
+
 	return {
 		...options,
-		control: Control.make(codec),
-		normalizeCause,
+		error: options.error ?? Schema.Never,
 		inject: options.inject ?? [],
 		provides: options.provides ?? [],
 		[TypeId]: TypeId,
-		encodeCause: (cause: Cause.Cause<unknown>) =>
-			normalizeCause(cause).pipe(Schema.encodeEffect(codec)),
-		decodeCause: Schema.decodeUnknownEffect(codec),
 	}
 }
 
-/** The shared config, error codecs, and service declarations for one remote plugin. */
-export type Contract<
-	S extends Schema.Top & {
-		readonly Encoded: Schema.Json
-		readonly DecodingServices: never
-		readonly EncodingServices: never
-	},
-	E extends Schema.Top & {
-		readonly DecodingServices: never
-		readonly EncodingServices: never
-	},
-> = ReturnType<typeof make<S, E>>
-
-/** Dynamic imports retain the control server and cause normalization; hosts retain the declared error type. */
+/** A contract whose schemas are discovered through a dynamic import. */
 export type RunnerContract = Contract<
 	Schema.Codec<unknown, Schema.Json>,
 	Schema.Codec<unknown>

package/src/Errors.ts

@@ -80,3 +80,26 @@ export class AuthenticationFailed extends Schema.TaggedError<
 	challenge: Schema.optionalKey(Schema.String),
 	cause: Schema.optionalKey(Schema.Cause(Schema.Unknown, Schema.Unknown)),
 }) {}
+
+/** The authenticator could not reach what it needs to decide, such as its key set; the credential may still be valid. */
+export class AuthenticatorUnavailable extends Schema.TaggedError<
+	AuthenticatorUnavailable,
+	{ readonly brand: unique symbol }
+>()("AuthenticatorUnavailable", {
+	cause: Schema.Cause(Schema.Unknown, Schema.Unknown),
+}) {}
+
+/** A remote entry could not be resolved or configured at the indicated field. */
+export class RemoteEntryError extends Schema.TaggedError<
+	RemoteEntryError,
+	{ 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}`
+	}
+}

package/src/Testing.ts

@@ -1,6 +1,7 @@
 import type { Plugin } from "@graftland/graft"
 import {
 	Array,
+	Cause,
 	Equivalence,
 	Deferred,
 	Effect,
@@ -9,13 +10,17 @@ import {
 	String,
 	Schema,
 } from "effect"
+import type { TransportError } from "./Errors"
 import type { Channel } from "./Transport"
 import * as Framing from "./internal/runner/Framing"
 
 export class ConformanceError extends Schema.TaggedError<
 	ConformanceError,
 	{ readonly brand: unique symbol }
->()("ConformanceError", { message: Schema.String }) {}
+>()("ConformanceError", {
+	message: Schema.String,
+	cause: Schema.optionalKey(Schema.Cause(Schema.Unknown, Schema.Unknown)),
+}) {}
 const check = (condition: boolean, message: string) =>
 	condition ? Effect.void : Effect.fail(ConformanceError.make({ message }))
 export interface Capabilities {
@@ -88,7 +93,16 @@ export const transport = <E, R>(
 				),
 				"The channel changed byte order across split or coalesced chunks",
 			)
-		}),
+		}).pipe(
+			Effect.mapError((error): E | ConformanceError | TransportError =>
+				Schema.is(Framing.FrameError)(error)
+					? ConformanceError.make({
+							message: error.message,
+							cause: Cause.fail(error),
+						})
+					: error,
+			),
+		),
 		eof: Effect.gen(function* () {
 			const channel = yield* connect
 			yield* Stream.empty.pipe(Stream.run(channel.output))

package/src/Transport.ts

@@ -1,7 +1,11 @@
 /** Execution and byte-channel capabilities; implementations live in host plugins. */
 import { Context } from "effect"
 import type { Effect, Option, Scope, Stream, Sink, Redacted } from "effect"
-import type { AuthenticationFailed, TransportError } from "./Errors"
+import type {
+	AuthenticationFailed,
+	AuthenticatorUnavailable,
+	TransportError,
+} from "./Errors"
 import type { Prepared, VerifiedCertificate, TlsPolicy } from "./Auth"
 /** Ordered reliable bytes. Chunk boundaries have no meaning; EOF is not exit confirmation. */
 export interface Channel {
@@ -24,7 +28,7 @@ export type Session = (
 ) => Effect.Effect<void, TransportError, Scope.Scope>
 export type Accept = (
 	handshake: Handshake,
-) => Effect.Effect<Session, AuthenticationFailed>
+) => Effect.Effect<Session, AuthenticationFailed | AuthenticatorUnavailable>
 export interface Serving {
 	/** Completes after serve has registered its accept loop, not merely after bind. */
 	readonly ready: Effect.Effect<void>

package/src/bin.ts

@@ -68,24 +68,23 @@ const child = Command.make(
 			Argument.withSchema(Schema.fromJsonString(Bootstrap)),
 		),
 	},
-	({ contract, session, bootstrap }) =>
-		Effect.gen(function* () {
-			const watchdog = yield* Watchdog.start
-			// The executable owns stdin; it must not retain the process after a supervisor stop.
-			yield* Effect.addFinalizer(() =>
-				Effect.sync(() => {
-					process.stdin.destroy()
-				}),
-			)
-			const begin = yield* Effect.raceFirst(
-				watchdog.begin.pipe(Effect.as(true)),
-				watchdog.stop.pipe(Effect.as(false)),
-			)
-			if (!begin) return
-			const definition = yield* load(pathToFileURL(contract).href)
-			const channel = yield* bytes
-			return yield* run(definition, channel, session, bootstrap, watchdog.stop)
-		}),
+	Effect.fnUntraced(function* ({ contract, session, bootstrap }) {
+		const watchdog = yield* Watchdog.start
+		// The executable owns stdin; it must not retain the process after a supervisor stop.
+		yield* Effect.addFinalizer(() =>
+			Effect.sync(() => {
+				process.stdin.destroy()
+			}),
+		)
+		const begin = yield* Effect.raceFirst(
+			watchdog.begin.pipe(Effect.as(true)),
+			watchdog.stop.pipe(Effect.as(false)),
+		)
+		if (!begin) return
+		const definition = yield* load(pathToFileURL(contract).href)
+		const channel = yield* bytes
+		return yield* run(definition, channel, session, bootstrap, watchdog.stop)
+	}),
 )
 const cli = Command.make(
 	"graft-remote",
@@ -93,18 +92,17 @@ const cli = Command.make(
 		contract: Argument.String("contract").pipe(Argument.optional),
 		session: Argument.String("session").pipe(Argument.withDefault("local")),
 	},
-	({ contract, session }) =>
-		Effect.gen(function* () {
-			if (Option.isNone(contract))
-				return yield* CliError.UserError.make({
-					cause: "Missing contract module",
-					userMessage:
-						"A contract module or the child/serve/certificates subcommand is required",
-				})
-			const definition = yield* load(contract.value)
-			const channel = yield* bytes
-			return yield* run(definition, channel, session)
-		}),
+	Effect.fnUntraced(function* ({ contract, session }) {
+		if (Option.isNone(contract))
+			return yield* CliError.UserError.make({
+				cause: "Missing contract module",
+				userMessage:
+					"A contract module or the child/serve/certificates subcommand is required",
+			})
+		const definition = yield* load(contract.value)
+		const channel = yield* bytes
+		return yield* run(definition, channel, session)
+	}),
 ).pipe(Command.withSubcommands([child, serve, certificates]))
 
 NodeRuntime.runMain(

package/src/host/auth/bearer.ts

@@ -1,10 +1,5 @@
-import type { Graft, Plugin } from "@graftland/graft"
 import { Config, plugin } from "../../internal/auth/tokenCredentials"
 export { Config }
 
-const capability: Plugin.Plugin<
-	typeof Config.Type,
-	typeof Config.Encoded,
-	Graft.ServiceConflict
-> = plugin("remote-bearer-credentials")
+const capability = plugin("remote-bearer-credentials")
 export default capability

package/src/host/auth/jwt.ts

@@ -1,10 +1,5 @@
-import type { Graft, Plugin } from "@graftland/graft"
 import { Config, plugin } from "../../internal/auth/tokenCredentials"
 export { Config }
 
-const capability: Plugin.Plugin<
-	typeof Config.Type,
-	typeof Config.Encoded,
-	Graft.ServiceConflict
-> = plugin("remote-jwt-credentials")
+const capability = plugin("remote-jwt-credentials")
 export default capability

package/src/host/command.ts

@@ -1,3 +1,5 @@
+/** Options for the command connector. */
+export type { CommandOptions as Options } from "../internal/transportOptions"
 import type { CommandOptions } from "../internal/transportOptions"
 import { Plugin, Graft } from "@graftland/graft"
 import {

package/src/host/local.ts

@@ -1,4 +1,4 @@
-import { Plugin, type Graft } from "@graftland/graft"
+import { Plugin } from "@graftland/graft"
 import { Array, Effect, Scope } from "effect"
 import { ChildProcess, ChildProcessSpawner } from "effect/process"
 import { LocalTransport } from "../internal/directTransport"
@@ -29,13 +29,9 @@ const make = Effect.map(ChildProcessSpawner.ChildProcessSpawner, (spawner) =>
 		}),
 	}),
 )
-const plugin: Plugin.Plugin<void, void, Graft.ServiceConflict> = Plugin.service(
-	LocalTransport,
-	make,
-	{
-		name: "remote-local-transport",
-		inject: [ChildProcessSpawner.ChildProcessSpawner],
-	},
-)
+const plugin = Plugin.service(LocalTransport, make, {
+	name: "remote-local-transport",
+	inject: [ChildProcessSpawner.ChildProcessSpawner],
+})
 
 export default plugin

package/src/host/unix.ts

@@ -1,3 +1,5 @@
+/** Options for the unix connector. */
+export type { UnixOptions as Options } from "../internal/transportOptions"
 import type { UnixOptions } from "../internal/transportOptions"
 import { Plugin, Graft } from "@graftland/graft"
 import { ConfigDirectory } from "@graftland/loader"

package/src/host/websocket.ts

@@ -1,3 +1,5 @@
+/** Options for the websocket connector. */
+export type { WebsocketOptions as Options } from "../internal/transportOptions"
 import type { WebsocketOptions } from "../internal/transportOptions"
 import { Plugin, Graft } from "@graftland/graft"
 import { Cause, Effect, FileSystem, Option, Path, Schema } from "effect"

package/src/host/worker.ts

@@ -1,4 +1,4 @@
-import { Plugin, type Graft } from "@graftland/graft"
+import { Plugin } from "@graftland/graft"
 import { Cause, Deferred, Effect, FiberSet, Option, Schema } from "effect"
 import { Worker } from "node:worker_threads"
 import { WorkerTransport } from "../internal/directTransport"
@@ -82,9 +82,7 @@ const start: typeof WorkerTransport.Service.start = Effect.fnUntraced(
 		}
 	},
 )
-const plugin: Plugin.Plugin<void, void, Graft.ServiceConflict> = Plugin.service(
-	WorkerTransport,
-	Effect.succeed({ start }),
-	{ name: "remote-thread-transport" },
-)
+const plugin = Plugin.service(WorkerTransport, Effect.succeed({ start }), {
+	name: "remote-thread-transport",
+})
 export default plugin

package/src/index.ts

@@ -16,9 +16,11 @@ export { Contract }
 export { Instance } from "./Instance"
 export { RemoteTerminationUnconfirmed } from "./internal/runner/model"
 export { RemoteError, RemoteWithdrawn, MissingInstance } from "./Errors"
-export { UndeclaredFailure, ChildFailure } from "./Contract"
+export { UndeclaredFailure } from "./Contract"
 export type {
 	Connect,
+	Authentication,
+	Token as CredentialToken,
 	Source as CredentialSource,
 } from "./internal/credentials"
 
@@ -90,8 +92,8 @@ export const plugin = <
 			ChildProcessSpawner.ChildProcessSpawner,
 		],
 		retry: options.retry,
-		apply: () =>
-			Effect.gen(function* () {
+		apply: Effect.fnUntraced(
+			function* () {
 				const input = yield* Schema.decodeUnknownEffect(Configuration.Host)({
 					contract: options.contractModule,
 					connect: options.connect,
@@ -110,6 +112,8 @@ export const plugin = <
 				yield* follow(child, (cause) =>
 					Effect.failCause(publicCause(contract.error, cause)),
 				)
-			}).pipe(Effect.mapError((error) => publicError(contract.error, error))),
+			},
+			Effect.mapError((error) => publicError(contract.error, error)),
+		),
 	})
 export { host as default } from "./internal/entry"

package/src/internal/Certificates.ts

@@ -241,20 +241,17 @@ export const write = Effect.fn("Certificates.write")(function* (
 	force: boolean = false,
 ) {
 	const fs = yield* FileSystem.FileSystem
-	yield* fs
-		.writeFileString(base + ".key", Redacted.value(pair.privateKey), {
-			flag: force ? "w" : "wx",
-			mode: 0o600,
-		})
-		.pipe(Effect.uninterruptible)
+	yield* fs.writeFileString(base + ".key", Redacted.value(pair.privateKey), {
+		flag: force ? "w" : "wx",
+		mode: 0o600,
+	})
 	// Opening an existing file does not change its permissions when renewing it.
-	yield* fs.chmod(base + ".key", 0o600).pipe(Effect.uninterruptible)
-	yield* fs
-		.writeFileString(base + ".crt", pair.certificate, {
-			flag: force ? "w" : "wx",
-		})
-		.pipe(Effect.uninterruptible)
-})
+	yield* fs.chmod(base + ".key", 0o600)
+	yield* fs.writeFileString(base + ".crt", pair.certificate, {
+		flag: force ? "w" : "wx",
+	})
+	// One region for the pair: an interruption between the files would leave a key without its certificate.
+}, Effect.uninterruptible)
 
 export interface Options {
 	readonly out: string