@graftland/plugin-remote 0.3.3 → 0.4.1

package/src/Auth.ts

@@ -1,6 +1,12 @@
 /** Credentials and authenticated identities shared by transport plugins. */
-import { Context } from "effect"
-import type { Effect, Redacted, Option, Scope } from "effect"
+import {
+	Context,
+	type Effect,
+	type Option,
+	type Redacted,
+	type Scope,
+} from "effect"
+
 import type {
 	AuthenticationFailed,
 	AuthenticatorUnavailable,

package/src/Config.ts

@@ -0,0 +1,196 @@
+/** Configuration schemas for remote entries and their built-in capabilities. */
+import { Effect, JsonSchema, Schema } from "effect"
+
+import * as Auth from "./internal/auth/config"
+import { PositiveDuration } from "./internal/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,
+}
+const authentication = <
+	M extends Schema.Top,
+	B extends Schema.Top,
+	J extends Schema.Top,
+	N extends Schema.Top,
+>(schemas: {
+	readonly mtls: M
+	readonly bearer: B
+	readonly jwt: J
+	readonly none: N
+}) =>
+	Schema.Union([
+		Schema.Struct({
+			...authFields,
+			name: Schema.String,
+			config: Schema.optionalKey(Schema.Unknown),
+		}),
+		Schema.Struct({ ...authFields, mtls: schemas.mtls }),
+		Schema.Struct({ ...authFields, bearer: schemas.bearer }),
+		Schema.Struct({ ...authFields, jwt: schemas.jwt }),
+		Schema.Struct({ ...authFields, none: schemas.none }),
+	])
+export const Authentication = authentication({
+	mtls: Auth.Certificate,
+	bearer: Auth.Token,
+	jwt: Auth.Token,
+	none: Auth.None,
+})
+export const RunnerAuthentication = authentication({
+	mtls: Auth.Mtls,
+	bearer: Auth.Bearer,
+	jwt: Schema.toEncoded(Auth.Jwt),
+	none: Auth.None,
+})
+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: Schema.optionalKey(RunnerAuthentication),
+		url: Schema.String.check(Schema.isStartingWith("ws://")),
+		cert: absent,
+		key: absent,
+	}),
+	Schema.Struct({
+		...transportFields,
+		auth: Schema.optionalKey(RunnerAuthentication),
+		url: Schema.String.check(Schema.isStartingWith("wss://")),
+		cert: Schema.String,
+		key: Schema.String,
+	}),
+	Schema.Struct({
+		...transportFields,
+		auth: Schema.optionalKey(RunnerAuthentication),
+		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: Schema.optionalKey(RunnerAuthentication),
+		transport: Reference,
+	}),
+])
+export type Listen = typeof Listen.Type
+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),
+})
+
+/** The command plugin has no business configuration. */
+export const Cli = Schema.Struct({})
+/** Editor registrations, with inline schemas so consumers can compose them without reference collisions. */
+export const entries = () => [
+	{
+		names: ["remote", "@graftland/plugin-remote"],
+		schema: json(Host),
+		required: true,
+	},
+	{
+		names: ["remote/runner", "@graftland/plugin-remote/runner"],
+		schema: json(Runner),
+		required: true,
+	},
+	{ names: ["remote/cli", "@graftland/plugin-remote/cli"], schema: json(Cli) },
+]
+const json = (schema: Schema.Top) =>
+	JsonSchema.toDocumentDraft07(
+		Schema.toJsonSchemaDocument(schema, {
+			referencePolicy: () => undefined,
+			onExcessProperty: "error",
+		}),
+	).schema

package/src/Contract.ts

@@ -1,8 +1,17 @@
-import { Array, Predicate, Schema } from "effect"
-import type { Context, Effect, Scope } from "effect"
-import type { Graft } from "@graftland/graft"
+import {
+	Array,
+	Predicate,
+	Schema,
+	type Context,
+	type Effect,
+	type Scope,
+} from "effect"
 import type { Rpc, RpcClient, RpcGroup, RpcServer } from "effect/rpc"
+
+import type { Graft } from "@graftland/graft"
+
 import * as Control from "./internal/control"
+
 export { service } from "./internal/services"
 
 const TypeId = "~@graftland/plugin-remote/Contract"

package/src/Instance.ts

@@ -1,4 +1,5 @@
 import { Context, Schema } from "effect"
+
 export const Identity = Schema.Struct({
 	id: Schema.String,
 	generation: Schema.Int,

package/src/Testing.ts

@@ -1,18 +1,20 @@
-import type { Plugin } from "@graftland/graft"
 import {
 	Array,
 	Cause,
-	Equivalence,
 	Deferred,
 	Effect,
+	Equivalence,
 	Fiber,
+	Schema,
 	Stream,
 	String,
-	Schema,
 } from "effect"
+
+import type { Plugin } from "@graftland/graft"
+
 import type { TransportError } from "./Errors"
-import type { Channel } from "./Transport"
 import * as Framing from "./internal/runner/Framing"
+import type { Channel } from "./Transport"
 
 export class ConformanceError extends Schema.TaggedError<
 	ConformanceError,

package/src/Transport.ts

@@ -1,12 +1,21 @@
 /** 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 {
+	Context,
+	type Effect,
+	type Option,
+	type Redacted,
+	type Scope,
+	type Sink,
+	type Stream,
+} from "effect"
+
+import type { Prepared, TlsPolicy, VerifiedCertificate } from "./Auth"
 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 {
 	readonly input: Stream.Stream<Uint8Array, TransportError>

package/src/cli.ts

@@ -0,0 +1,60 @@
+import { Console, Effect } from "effect"
+import { CliError, Command, Flag } from "effect/cli"
+
+import { platform } from "@graftland/cli/Application"
+import { Commands } from "@graftland/cli/Commands"
+import { Plugin } from "@graftland/graft"
+
+const certificates = Command.make(
+	"certificates",
+	{
+		out: Flag.String("out").pipe(
+			Flag.withDescription("Directory for the CA and issued certificates"),
+		),
+		server: Flag.String("server").pipe(
+			Flag.atLeast(0),
+			Flag.withDescription(
+				"Runner DNS name or IP address; repeat for additional SANs",
+			),
+		),
+		identity: Flag.String("identity").pipe(
+			Flag.atLeast(0),
+			Flag.withDescription(
+				"Host identity; repeat to issue multiple client certificates",
+			),
+		),
+		days: Flag.Int("days").pipe(
+			Flag.withDefault(365),
+			Flag.filter(
+				(days) => days > 0,
+				() => "Days must be a positive integer",
+			),
+		),
+		force: Flag.Boolean("force").pipe(
+			Flag.withDefault(false),
+			Flag.withDescription(
+				"Replace requested leaf certificates, keeping the existing CA",
+			),
+		),
+	},
+	(options) =>
+		Effect.promise(() => import("./internal/Certificates")).pipe(
+			Effect.uninterruptible,
+			Effect.flatMap((Certificates) => Certificates.generate(options)),
+			Effect.andThen(Console.log(`Certificates written to ${options.out}`)),
+			Effect.mapError((error) =>
+				CliError.UserError.make({ cause: error, userMessage: String(error) }),
+			),
+		),
+)
+
+const command = Command.make("remote").pipe(
+	Command.withSubcommands([certificates]),
+	Command.provide(platform),
+)
+export default Plugin.make({
+	name: "remote-commands",
+	inject: [Commands],
+	apply: () =>
+		Effect.flatMap(Commands, (commands) => commands.register(command)),
+})

package/src/host/auth/bearer.ts

@@ -1,4 +1,5 @@
 import { Config, plugin } from "../../internal/auth/tokenCredentials"
+
 export { Config }
 
 const capability = plugin("remote-bearer-credentials")

package/src/host/auth/jwt.ts

@@ -1,4 +1,5 @@
 import { Config, plugin } from "../../internal/auth/tokenCredentials"
+
 export { Config }
 
 const capability = plugin("remote-jwt-credentials")

package/src/host/auth/mtls.ts

@@ -1,18 +1,13 @@
-import { Plugin, Graft } from "@graftland/graft"
-import {
-	Cause,
-	Effect,
-	FileSystem,
-	Option,
-	Path,
-	Redacted,
-	Schema,
-} from "effect"
-import { CredentialsError } from "../../Errors"
+import { Cause, Effect, FileSystem, Option, Path, Redacted } from "effect"
+
+import { Graft, Plugin } from "@graftland/graft"
 import { ConfigDirectory } from "@graftland/loader"
+
 import { Credentials, type Prepared } from "../../Auth"
+import { CredentialsError } from "../../Errors"
+import { Certificate as Config } from "../../internal/auth/config"
 
-export const Config = Schema.Struct({ cert: Schema.String, key: Schema.String })
+export { Config }
 export default Plugin.make({
 	name: "remote-certificate-credentials",
 	config: Config,

package/src/host/auth/none.ts

@@ -1,5 +1,7 @@
-import { Plugin, Graft } from "@graftland/graft"
 import { Effect, Schema } from "effect"
+
+import { Graft, Plugin } from "@graftland/graft"
+
 import { Credentials } from "../../Auth"
 
 export default Plugin.make({

package/src/host/command.ts

@@ -1,7 +1,3 @@
-/** 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 {
 	Array,
 	Cause,
@@ -14,11 +10,18 @@ import {
 	Stream,
 } from "effect"
 import { ChildProcess, ChildProcessSpawner } from "effect/process"
-import { Connector } from "../Transport"
+
+import { Graft, Plugin } from "@graftland/graft"
 import { ConfigDirectory } from "@graftland/loader"
+
 import { TransportError } from "../Errors"
 import { cleanupCause } from "../internal/cleanup"
 import * as ProcessObservation from "../internal/runner/ProcessObservation"
+import type { CommandOptions } from "../internal/transportOptions"
+import { Connector } from "../Transport"
+
+/** Options for the command connector. */
+export type { CommandOptions as Options } from "../internal/transportOptions"
 
 export class CommandExited extends Schema.TaggedError<
 	CommandExited,

package/src/host/local.ts

@@ -1,9 +1,11 @@
-import { Plugin } from "@graftland/graft"
 import { Array, Effect, Scope } from "effect"
 import { ChildProcess, ChildProcessSpawner } from "effect/process"
+
+import { Plugin } from "@graftland/graft"
+
 import { LocalTransport } from "../internal/directTransport"
-import { command } from "../internal/runner/command"
 import * as Local from "../internal/host/local"
+import { command } from "../internal/runner/command"
 
 const make = Effect.map(ChildProcessSpawner.ChildProcessSpawner, (spawner) =>
 	LocalTransport.of({

package/src/host/unix.ts

@@ -1,16 +1,20 @@
-/** 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"
 import { Cause, Effect, Layer, Option, Path, Redacted, Schema } from "effect"
 import { Socket } from "effect/socket"
+
+import { Graft, Plugin } from "@graftland/graft"
+import { ConfigDirectory } from "@graftland/loader"
+
 import WS from "ws"
+
 import type { Prepared } from "../Auth"
-import { Connector, type ConnectorApi } from "../Transport"
 import { TransportError } from "../Errors"
-import { path, protocol, payloadLimit } from "../internal/websocket"
 import * as Channel from "../internal/socketChannel"
+import type { UnixOptions } from "../internal/transportOptions"
+import { path, payloadLimit, protocol } from "../internal/websocket"
+import { Connector, type ConnectorApi } from "../Transport"
+
+/** Options for the unix connector. */
+export type { UnixOptions as Options } from "../internal/transportOptions"
 
 export const properties: ConnectorApi["properties"] = {
 	protocol: "unix",

package/src/host/websocket.ts

@@ -1,13 +1,16 @@
-/** 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"
-import { Connector, type ConnectorApi } from "../Transport"
-import { TransportError } from "../Errors"
+
+import { Graft, Plugin } from "@graftland/graft"
 import { ConfigDirectory } from "@graftland/loader"
-import * as Websocket from "../internal/websocket"
+
+import { TransportError } from "../Errors"
 import * as Channel from "../internal/socketChannel"
+import type { WebsocketOptions } from "../internal/transportOptions"
+import * as Websocket from "../internal/websocket"
+import { Connector, type ConnectorApi } from "../Transport"
+
+/** Options for the websocket connector. */
+export type { WebsocketOptions as Options } from "../internal/transportOptions"
 
 /** Configured Connector; certificate paths belong to the enclosing configuration. */
 export const Config = Schema.Struct({

package/src/host/worker.ts

@@ -1,12 +1,15 @@
-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"
+
+import { Cause, Deferred, Effect, FiberSet, Option, Schema } from "effect"
+
+import { Plugin } from "@graftland/graft"
+
 import { ProcessExited, TransportError } from "../Errors"
-import * as Channel from "../internal/workerChannel"
+import { cleanupCause } from "../internal/cleanup"
+import { WorkerTransport } from "../internal/directTransport"
 import * as FailureGroup from "../internal/FailureGroup"
 import { Bootstrap } from "../internal/workerBootstrap"
-import { cleanupCause } from "../internal/cleanup"
+import * as Channel from "../internal/workerChannel"
 
 const start: typeof WorkerTransport.Service.start = Effect.fnUntraced(
 	function* (options) {

package/src/index.ts

@@ -1,21 +1,31 @@
-import { Plugin } from "@graftland/graft"
-import { ModuleResolver } from "@graftland/loader"
-import { Array, Cause, Effect, Path, Schema } from "effect"
-import type { Duration, Schedule } from "effect"
+import {
+	Array,
+	Cause,
+	Effect,
+	Path,
+	Schema,
+	type Duration,
+	type Schedule,
+} from "effect"
 import { SecureRandom } from "effect/crypto"
 import { ChildProcessSpawner } from "effect/process"
-import { launch } from "./internal/entry"
-import { follow } from "./internal/follow"
+
+import { Plugin } from "@graftland/graft"
+import { ModuleResolver } from "@graftland/loader"
+
+import * as Contract from "./Contract"
+import { MissingInstance, RemoteError, RemoteWithdrawn } from "./Errors"
 import { CapabilityFailed } from "./internal/assembly"
-import { publicError } from "./internal/execution"
-import * as Configuration from "./internal/entryConfig"
 import * as Credential from "./internal/credentials"
-import { RemoteWithdrawn, RemoteError, MissingInstance } from "./Errors"
-import * as Contract from "./Contract"
+import { launch } from "./internal/entry"
+import * as Configuration from "./internal/entryConfig"
+import { publicError } from "./internal/execution"
+import { follow } from "./internal/follow"
+
 export { Contract }
 export { Instance } from "./Instance"
 export { RemoteTerminationUnconfirmed } from "./internal/runner/model"
-export { RemoteError, RemoteWithdrawn, MissingInstance } from "./Errors"
+export * from "./Errors"
 export { UndeclaredFailure } from "./Contract"
 export type {
 	Connect,
@@ -30,7 +40,6 @@ export interface Options<
 	readonly connect: Credential.Connect<D>
 	/** Contract module resolved independently in each execution environment. */
 	readonly contractModule: string
-	readonly config?: Schema.Json
 	readonly retry?: Schedule.Schedule<unknown, unknown> | undefined
 	readonly shutdownTimeout?: Duration.Input | undefined
 }
@@ -60,6 +69,7 @@ const publicCause = <E extends Schema.Top>(
 		}),
 	)
 
+/** Fixes deployment options; business config is plugin input, and updates restart the execution unit. */
 export const plugin = <
 	S extends Schema.Top & {
 		readonly Encoded: Schema.Json
@@ -73,10 +83,10 @@ export const plugin = <
 	const D extends ReadonlyArray<Plugin.Dependency> = readonly [],
 >(
 	contract: Contract.Contract<S, E>,
-	options: Options<D> & { readonly config?: S["Encoded"] },
+	options: Options<D>,
 ): Plugin.Plugin<
-	void,
-	void,
+	S["Encoded"],
+	S["Encoded"],
 	| E["Type"]
 	| Contract.UndeclaredFailure
 	| RemoteError
@@ -92,12 +102,17 @@ export const plugin = <
 			ChildProcessSpawner.ChildProcessSpawner,
 		],
 		retry: options.retry,
-		apply: Effect.fnUntraced(
-			function* () {
+		config: Schema.toEncoded(contract.config),
+		apply: (config) =>
+			Effect.gen(function* () {
+				const auth = Credential.invocation(options.connect)
 				const input = yield* Schema.decodeUnknownEffect(Configuration.Host)({
 					contract: options.contractModule,
-					connect: options.connect,
-					config: options.config === undefined ? {} : options.config,
+					connect:
+						auth === undefined
+							? options.connect
+							: { ...options.connect, auth: { name: "effect-credentials" } },
+					config,
 				})
 				yield* Schema.decodeEffect(contract.config)(input.config)
 				const child = yield* launch(
@@ -107,13 +122,11 @@ export const plugin = <
 						contractModule: options.contractModule,
 						shutdownTimeout: options.shutdownTimeout,
 					},
-					Credential.invocation(options.connect),
+					auth,
 				)
 				yield* follow(child, (cause) =>
 					Effect.failCause(publicCause(contract.error, cause)),
 				)
-			},
-			Effect.mapError((error) => publicError(contract.error, error)),
-		),
+			}).pipe(Effect.mapError((error) => publicError(contract.error, error))),
 	})
 export { host as default } from "./internal/entry"

package/src/internal/Certificates.ts

@@ -12,6 +12,7 @@ import {
 import { SecureRandom, WebCrypto } from "effect/crypto"
 import { Base64 } from "effect/encoding"
 import { NetAddress } from "effect/net"
+
 import * as asn1js from "asn1js"
 import * as pki from "pkijs"
 

package/src/internal/FailureGroup.ts

@@ -1,18 +1,20 @@
 import {
 	Array,
 	Cause,
-	Fiber,
 	Data,
 	Deferred,
 	Effect,
 	Exit,
+	Fiber,
 	FiberSet,
 	Ref,
-	Scope,
 	Schema,
+	Scope,
 	TxRef,
 } from "effect"
-import * as Release from "./release"
+
+import * as Release from "@graftland/graft/Release"
+
 import { cleanupCause } from "./cleanup"
 
 type State<E> = Data.TaggedEnum<{

package/src/internal/Peer.ts

@@ -1,4 +1,5 @@
 import { Context } from "effect"
+
 export class Peer extends Context.Service<Peer, string>()(
 	"@graftland/plugin-remote/internal/Peer",
 ) {}