@graftland/plugin-remote 0.0.0-stage → 0.3.0

package/src/internal/workerChannel.ts

@@ -0,0 +1,54 @@
+import { Cause, Effect, FiberSet, Queue, Sink, Stream } from "effect"
+import { TransportError } from "../Errors"
+import type { Channel } from "./port"
+
+/** Both ends send owned ArrayBuffers; null is the byte stream's EOF. */
+export interface Endpoint {
+	readonly postMessage: (
+		value: ArrayBuffer | null,
+		transferList: ArrayBuffer[],
+	) => void
+	readonly on: (
+		event: "message",
+		listener: (value: ArrayBuffer | null) => void,
+	) => unknown
+	readonly off: (
+		event: "message",
+		listener: (value: ArrayBuffer | null) => void,
+	) => unknown
+}
+export const make = Effect.fnUntraced(function* (endpoint: Endpoint) {
+	// Port owns admission and RPC chunk backpressure; this queue only bridges message events.
+	const input = yield* Queue.unbounded<Uint8Array, Cause.Done>()
+	const callbacks = yield* FiberSet.make()
+	const run = yield* FiberSet.runtime(callbacks)()
+	const receive = (value: ArrayBuffer | null) =>
+		run(
+			value === null
+				? Queue.end(input)
+				: Queue.offer(input, new Uint8Array(value)),
+		)
+	yield* Effect.acquireRelease(
+		Effect.sync(() => endpoint.on("message", receive)),
+		() =>
+			Effect.sync(() => endpoint.off("message", receive)).pipe(
+				Effect.andThen(Queue.shutdown(input)),
+			),
+	)
+	const send = (bytes: Uint8Array | null) =>
+		Effect.try({
+			try: () => {
+				// Copy even Buffer slices: only this fresh, exact-sized backing store is transferable.
+				const buffer = bytes === null ? null : new Uint8Array(bytes).buffer
+				endpoint.postMessage(buffer, buffer === null ? [] : [buffer])
+			},
+			catch: (cause) => TransportError.make({ cause: Cause.die(cause) }),
+		})
+	return {
+		input: Stream.fromQueue(input),
+		output: Sink.forEach((bytes: Uint8Array) => send(bytes)).pipe(
+			// Closing the output half always sends EOF, including when its writer is interrupted.
+			Sink.ensuring(send(null)),
+		),
+	} satisfies Channel
+})

package/src/internal/workerMain.ts

@@ -0,0 +1,23 @@
+/** Executable entry for a direct worker; platform services belong to this thread. */
+import { Graft } from "@graftland/graft"
+import { NodeRuntime } from "@effect/platform-node"
+import { Effect, Layer, Schema } from "effect"
+import { parentPort, workerData } from "node:worker_threads"
+import { load, run } from "./childRuntime"
+import { Bootstrap } from "./workerBootstrap"
+import * as Channel from "./workerChannel"
+import { platform } from "./platform"
+
+const main = Effect.scoped(
+	Effect.gen(function* () {
+		const port = yield* Effect.fromNullishOr(parentPort)
+		yield* Effect.addFinalizer(() => Effect.sync(() => port.close()))
+		const bootstrap = yield* Schema.decodeUnknownEffect(Bootstrap)(workerData)
+		const channel = yield* Channel.make(port)
+		const contract = yield* load(bootstrap.contractModule)
+		yield* run(contract, channel, bootstrap.session)
+	}),
+)
+NodeRuntime.runMain(
+	main.pipe(Effect.provide(Graft.layer.pipe(Layer.provide(platform)))),
+)

package/src/runner/auth/bearer.ts

@@ -0,0 +1,66 @@
+import { Option } from "effect"
+import { Graft, Plugin } from "@graftland/graft"
+import {
+	Array,
+	Effect,
+	FileSystem,
+	Path,
+	Record,
+	Redacted,
+	Schema,
+} from "effect"
+import { Digest } from "effect/crypto"
+import { Hex } from "effect/encoding"
+// @effect-diagnostics-next-line nodeBuiltinImport:off -- Token digests use Node's constant-time comparison
+import { timingSafeEqual } from "node:crypto"
+import { Authenticator } from "../../Auth"
+import { ConfigDirectory } from "@graftland/loader"
+import * as Token from "../../internal/auth/token"
+
+export const Config = Schema.Struct({ tokens: Schema.String })
+const Tokens = Schema.fromJsonString(
+	Schema.Record(
+		Schema.String.check(Schema.isPattern(/^[0-9a-fA-F]{64}$/)),
+		Schema.NonEmptyString,
+	),
+)
+export default Plugin.make({
+	name: "remote-bearer-authenticator",
+	config: Config,
+	inject: [FileSystem.FileSystem, Path.Path, Digest.Digest],
+	apply: Effect.fnUntraced(function* (config) {
+		const fs = yield* FileSystem.FileSystem
+		const path = yield* Path.Path
+		const directory = yield* ConfigDirectory.pipe(
+			Effect.map(Option.getOrElse(() => ".")),
+		)
+		const digest = yield* Digest.Digest
+		const file = yield* fs.readFileString(
+			path.resolve(directory, config.tokens),
+		)
+		const mapping = yield* Schema.decodeEffect(Tokens)(file)
+		const tokens = yield* Effect.forEach(
+			Record.toEntries(mapping),
+			([hex, identity]) =>
+				Effect.fromResult(Hex.decode(hex)).pipe(
+					Effect.map((hash) => ({ hash, identity })),
+				),
+		)
+		yield* Graft.provide(Authenticator, {
+			_tag: "Header",
+			authenticate: Effect.fnUntraced(function* (authorization) {
+				const token = yield* Token.read(authorization)
+				const hash = yield* digest.digest(
+					Digest.sha256,
+					new TextEncoder().encode(Redacted.value(token)),
+				)
+				const found = Array.findFirst(tokens, (entry) =>
+					timingSafeEqual(hash, entry.hash),
+				)
+				return yield* Effect.fromOption(found, Token.invalid).pipe(
+					Effect.map((entry) => entry.identity),
+				)
+			}),
+		})
+	}),
+})

package/src/runner/auth/jwt.ts

@@ -0,0 +1,114 @@
+import { Option } from "effect"
+import { Graft, Plugin } from "@graftland/graft"
+import {
+	Cause,
+	Duration,
+	Effect,
+	FileSystem,
+	Layer,
+	Path,
+	Schema,
+} from "effect"
+import { Jwk, Jwks, Jwt } from "effect/jose"
+import { Signature } from "effect/crypto"
+import { HttpClient } from "effect/http"
+import { Authenticator } from "../../Auth"
+import { ConfigDirectory } from "@graftland/loader"
+import { AuthenticationFailed } from "../../Errors"
+import * as Token from "../../internal/auth/token"
+
+export const ClockTolerance = Schema.DurationFromString.check(
+	Schema.makeFilter(
+		(duration) =>
+			Duration.isFinite(duration) && Duration.toMillis(duration) >= 0,
+		{ expected: "a finite, non-negative duration" },
+	),
+)
+export const Config = Schema.Struct({
+	issuer: Schema.NonEmptyString,
+	audience: Schema.NonEmptyArray(Schema.NonEmptyString),
+	algorithms: Schema.NonEmptyArray(Jwk.AsymmetricAlgorithm),
+	identityClaim: Schema.NonEmptyString.pipe(
+		Schema.withDecodingDefaultKey(Effect.succeed("sub")),
+	),
+	clockTolerance: ClockTolerance.pipe(
+		Schema.withDecodingDefaultKey(Effect.succeed("5 seconds")),
+	),
+	keys: Schema.Union([
+		Schema.Struct({
+			jwksUrl: Schema.String,
+			publicKey: Schema.optionalKey(Schema.Never),
+		}),
+		Schema.Struct({
+			publicKey: Schema.String,
+			jwksUrl: Schema.optionalKey(Schema.Never),
+		}),
+	]),
+})
+const keys = Effect.fnUntraced(function* (config: typeof Config.Type) {
+	if (config.keys.jwksUrl !== undefined)
+		return Jwks.layerRemote({ url: config.keys.jwksUrl })
+	const fs = yield* FileSystem.FileSystem
+	const path = yield* Path.Path
+	const directory = yield* ConfigDirectory.pipe(
+		Effect.map(Option.getOrElse(() => ".")),
+	)
+	const pem = yield* fs.readFileString(
+		path.resolve(directory, config.keys.publicKey),
+	)
+	// A single PEM must support the allowed algorithms; use JWKS for multiple key types.
+	const keys = yield* Effect.forEach(config.algorithms, (algorithm) =>
+		Jwk.importSpki(pem, algorithm).pipe(Effect.flatMap(Jwk.exportPublic)),
+	)
+	return Jwks.layerLocal({ keys })
+})
+export default Plugin.make({
+	name: "remote-jwt-authenticator",
+	config: Config,
+	inject: [
+		FileSystem.FileSystem,
+		Path.Path,
+		Signature.Signature,
+		HttpClient.HttpClient,
+	],
+	apply: Effect.fnUntraced(function* (config) {
+		const keySet = yield* keys(config)
+		const services = yield* Layer.build(keySet)
+		const signature = yield* Signature.Signature
+		yield* Graft.provide(Authenticator, {
+			_tag: "Header",
+			issuer: config.issuer,
+			authenticate: (authorization) =>
+				Token.read(authorization).pipe(
+					Effect.flatMap((token) =>
+						Jwt.verifyWithKeySet(
+							Schema.Record(Schema.String, Schema.Unknown),
+							token,
+							{
+								issuer: config.issuer,
+								audience: config.audience,
+								algorithms: config.algorithms,
+								clockTolerance: config.clockTolerance,
+								requiredClaims: ["exp"],
+							},
+						).pipe(
+							Effect.flatMap((verified) =>
+								Schema.decodeUnknownEffect(Schema.NonEmptyString)(
+									verified.claims[config.identityClaim],
+								),
+							),
+							Effect.mapError((error) =>
+								AuthenticationFailed.make({
+									reason: "invalid",
+									challenge: 'Bearer error="invalid_token"',
+									cause: Cause.fail(error),
+								}),
+							),
+							Effect.provideService(Signature.Signature, signature),
+							Effect.provideContext(services),
+						),
+					),
+				),
+		})
+	}),
+})

package/src/runner/auth/mtls.ts

@@ -0,0 +1,37 @@
+import { Graft, Plugin } from "@graftland/graft"
+import { Effect, FileSystem, Option, Path, Schema } from "effect"
+import { Authenticator, type AuthenticatorApi } from "../../Auth"
+import { ConfigDirectory } from "@graftland/loader"
+import { identityFromSubjectAltName } from "../../internal/auth/mtls"
+
+export const Config = Schema.Struct({ ca: Schema.String })
+const read = Effect.fnUntraced(function* (ca: string) {
+	const fs = yield* FileSystem.FileSystem
+	const path = yield* Path.Path
+	const directory = yield* ConfigDirectory.pipe(
+		Effect.map(Option.getOrElse(() => ".")),
+	)
+	return yield* fs.readFileString(path.resolve(directory, ca))
+})
+export const make = (
+	ca: string,
+): Extract<AuthenticatorApi, { readonly _tag: "Mtls" }> => ({
+	_tag: "Mtls",
+	tls: {
+		ca: [ca],
+		minVersion: "TLSv1.3",
+		requestCert: true,
+		rejectUnauthorized: true,
+	},
+	authenticate: (peer) =>
+		identityFromSubjectAltName(Option.getOrUndefined(peer.subjectAltName)),
+})
+export default Plugin.make({
+	name: "remote-certificate-authenticator",
+	config: Config,
+	inject: [FileSystem.FileSystem, Path.Path],
+	apply: ({ ca }) =>
+		read(ca).pipe(
+			Effect.flatMap((ca) => Graft.provide(Authenticator, make(ca))),
+		),
+})

package/src/runner/auth/none.ts

@@ -0,0 +1,13 @@
+import { Graft, Plugin } from "@graftland/graft"
+import { Effect, Schema } from "effect"
+import { Authenticator } from "../../Auth"
+
+export default Plugin.make({
+	name: "remote-none-authenticator",
+	config: Schema.Struct({
+		identity: Schema.String.pipe(
+			Schema.withDecodingDefaultKey(Effect.succeed("anonymous")),
+		),
+	}),
+	apply: (config) => Graft.provide(Authenticator, { _tag: "None", ...config }),
+})

package/src/runner/index.ts

@@ -0,0 +1,97 @@
+import { Graft, Plugin } from "@graftland/graft"
+import { SecureRandom } from "effect/crypto"
+import { Path } from "effect"
+import { ModuleResolver } from "@graftland/loader"
+import { Deferred, Effect, Schema, Stream } from "effect"
+import * as Configuration from "../internal/entryConfig"
+import { boundary, resolve } from "../internal/entry"
+import * as Assembly from "../internal/assembly"
+import * as Startup from "../internal/listenerStartup"
+import { follow } from "../internal/follow"
+import { Supervisor } from "../internal/Supervisor"
+import supervisor, {
+	Config as SupervisorConfig,
+} from "../internal/supervisorPlugin"
+
+const startListener = Effect.fnUntraced(function* (
+	input: Configuration.Listen,
+	index: number,
+	begin: Deferred.Deferred<void>,
+) {
+	const field = `listen[${index}]`
+	const transport = yield* resolve(
+		Configuration.runnerTransport(input),
+		field + ".transport",
+	)
+	const auth = yield* resolve(
+		Configuration.runnerAuthentication(input),
+		field + ".auth",
+	)
+	const signals = yield* Startup.signals
+	const consumer = Assembly.makeListenerConsumer(
+		(properties, auth) =>
+			Assembly.directAuth(properties, input.auth !== undefined).pipe(
+				Effect.andThen(
+					Deferred.succeed(signals.description, { properties, auth }),
+				),
+				Effect.andThen(Deferred.await(begin)),
+			),
+		Deferred.succeed(signals.ready, undefined).pipe(Effect.asVoid),
+	)
+	const fork = yield* Assembly.runner({ transport, auth }, consumer)
+	return { fork, signals, field }
+})
+
+const owner = Plugin.make({
+	name: "remote-supervised-runtime",
+	config: Configuration.Runner,
+	inject: [ModuleResolver.ModuleResolver, Path.Path, SecureRandom.SecureRandom],
+	apply: Effect.fnUntraced(function* (config) {
+		const options = yield* Schema.encodeEffect(SupervisorConfig)(config)
+		const engine = yield* Graft.plugin(supervisor, options)
+		const fail = yield* boundary("supervisor")
+		yield* follow(engine, fail)
+		const begin = yield* Deferred.make<void>()
+		const listeners = yield* Effect.forEach(config.listen, (input, index) =>
+			startListener(input, index, begin),
+		)
+		const descriptions = yield* Effect.forEach(
+			listeners,
+			({ fork, signals }) => Startup.wait(fork, signals.description),
+			{ concurrency: "unbounded" },
+		)
+		yield* Startup.validate(descriptions)
+		yield* Deferred.succeed(begin, undefined)
+		yield* Effect.forEach(
+			listeners,
+			({ fork, signals }) => Startup.wait(fork, signals.ready),
+			{ concurrency: "unbounded" },
+		)
+		yield* Effect.forEach(
+			listeners,
+			({ fork, field }) =>
+				Plugin.fork(
+					fork.state.pipe(
+						Stream.runForEach((state) =>
+							state._tag === "Failed"
+								? Effect.logWarning("Remote listener failed", state.cause).pipe(
+										Effect.annotateLogs({ "remote.listener": field }),
+									)
+								: Effect.void,
+						),
+					),
+				),
+			{ discard: true },
+		)
+	}),
+})
+export default Plugin.make({
+	name: "remote-server",
+	config: Configuration.Runner,
+	apply: Effect.fnUntraced(function* (config) {
+		const encoded = yield* Schema.encodeEffect(Configuration.Runner)(config)
+		const fork = yield* Graft.plugin(owner, encoded, { isolate: [Supervisor] })
+		const fail = yield* boundary("runner")
+		yield* follow(fork, fail)
+	}),
+})

package/src/runner/stdio.ts

@@ -0,0 +1,76 @@
+import { Graft, Plugin } from "@graftland/graft"
+import {
+	Cause,
+	Deferred,
+	Effect,
+	Exit,
+	Option,
+	Schema,
+	Sink,
+	Stdio,
+	Stream,
+} from "effect"
+import { Listener, type Accept } from "../Transport"
+import { TransportError } from "../Errors"
+import * as Release from "../internal/release"
+
+export const Config = Schema.Struct({ auth: Schema.optionalKey(Schema.Never) })
+export default Plugin.make({
+	name: "remote-stdio-listener",
+	config: Config,
+	inject: [Stdio.Stdio],
+	apply: Effect.fnUntraced(function* () {
+		const stdio = yield* Stdio.Stdio
+		yield* Graft.provide(Listener, {
+			properties: {
+				protocol: "stdio",
+				encrypted: false,
+				network: false,
+				carries: [],
+			},
+			bind: Effect.fnUntraced(function* () {
+				const ready = yield* Deferred.make<void>()
+				const eof = yield* Deferred.make<void>()
+				const channel = {
+					input: stdio.stdin.pipe(
+						Stream.onExit((exit) =>
+							Exit.isSuccess(exit)
+								? Deferred.succeed(eof, undefined)
+								: Effect.void,
+						),
+						Stream.mapError((error) =>
+							TransportError.make({ cause: Cause.fail(error) }),
+						),
+					),
+					output: stdio
+						.stdout({ endOnDone: false })
+						.pipe(
+							Sink.mapError((error) =>
+								TransportError.make({ cause: Cause.fail(error) }),
+							),
+						),
+				}
+				return {
+					ready: Deferred.await(ready),
+					serve: (accept: Accept) =>
+						accept({
+							authorization: Option.none(),
+							certificate: Option.none(),
+						}).pipe(
+							Effect.mapError((error) =>
+								TransportError.make({ cause: Cause.fail(error) }),
+							),
+							Effect.flatMap((session) =>
+								Deferred.succeed(ready, undefined).pipe(
+									Effect.andThen(session(channel)),
+								),
+							),
+							Release.scoped,
+							// Successful session completion alone is not EOF.
+							Effect.andThen(Deferred.await(eof)),
+						),
+				}
+			}),
+		})
+	}),
+})

package/src/runner/unix.ts

@@ -0,0 +1,53 @@
+import { Graft, Plugin } from "@graftland/graft"
+import { ConfigDirectory } from "@graftland/loader"
+import { Cause, Console, Effect, Option, Path, Schema } from "effect"
+// @effect-diagnostics-next-line nodeBuiltinImport:off -- NodeHttpServer takes a factory for an HTTP/1.1 server on the Unix socket
+import { createServer } from "node:http"
+import { Listener } from "../Transport"
+import { TransportError } from "../Errors"
+import * as Server from "../internal/websocketServer"
+
+export const Config = Schema.Struct({ path: Schema.String })
+const Listening = Schema.fromJsonString(
+	Schema.Struct({ event: Schema.Literal("Listening"), path: Schema.String }),
+)
+export default Plugin.make({
+	name: "remote-unix-listener",
+	config: Config,
+	inject: [Path.Path],
+	apply: Effect.fnUntraced(function* (config) {
+		const path = yield* Path.Path
+		const directory = yield* ConfigDirectory
+		const socket = path.resolve(
+			Option.getOrElse(directory, () => "."),
+			config.path,
+		)
+		yield* Graft.provide(Listener, {
+			properties: {
+				protocol: "unix",
+				encrypted: false,
+				network: false,
+				carries: ["header"],
+			},
+			// Node rejects an occupied path and removes its own socket file when the server closes.
+			bind: () =>
+				Server.bind(createServer, { path: socket }).pipe(
+					Effect.mapBoth({
+						onSuccess: (server) => ({
+							serve: server.serve,
+							ready: server.ready.pipe(
+								Effect.andThen(
+									Schema.encodeEffect(Listening)({
+										event: "Listening",
+										path: socket,
+									}).pipe(Effect.orDie, Effect.flatMap(Console.log)),
+								),
+							),
+						}),
+						onFailure: (error) =>
+							TransportError.make({ cause: Cause.fail(error) }),
+					}),
+				),
+		})
+	}),
+})

package/src/runner/websocket.ts

@@ -0,0 +1,143 @@
+import { Graft, Plugin } from "@graftland/graft"
+import {
+	Cause,
+	Console,
+	Effect,
+	FileSystem,
+	Option,
+	Path,
+	Schema,
+	String,
+} from "effect"
+import { ConfigDirectory } from "@graftland/loader"
+import { createSecureServer } from "node:http2"
+import { Url, path as upgradePath } from "../internal/websocket"
+import { Listener } from "../Transport"
+import type { TlsPolicy } from "../Auth"
+import { TransportError } from "../Errors"
+import * as Server from "../internal/websocketServer"
+import { properties } from "../internal/websocket"
+// @effect-diagnostics-next-line nodeBuiltinImport:off -- NodeHttpServer takes a factory for an HTTP/1.1 upgrade server
+import { createServer } from "node:http"
+
+const url = (protocol: "ws:" | "wss:") =>
+	Url.check(
+		Schema.makeFilter((url) => url.protocol === protocol, {
+			expected: protocol + "//",
+		}),
+		Schema.makeFilter(
+			(url) => url.pathname === "/" || url.pathname === upgradePath,
+			{
+				expected: "a listener URL with no path or /graft",
+			},
+		),
+	)
+const ws = {
+	auth: Schema.optionalKey(Schema.Never),
+	url: url("ws:"),
+	cert: Schema.optionalKey(Schema.Never),
+	key: Schema.optionalKey(Schema.Never),
+}
+const wss = {
+	auth: Schema.optionalKey(Schema.Never),
+	url: url("wss:"),
+	cert: Schema.String,
+	key: Schema.String,
+}
+export const Config = Schema.Union([
+	Schema.Struct({
+		...ws,
+	}).pipe(
+		Schema.extendTo(
+			{ _tag: Schema.Literal("ws") },
+			{ _tag: () => Option.some<"ws">("ws") },
+		),
+	),
+	Schema.Struct({
+		...wss,
+	}).pipe(
+		Schema.extendTo(
+			{ _tag: Schema.Literal("wss") },
+			{ _tag: () => Option.some<"wss">("wss") },
+		),
+	),
+])
+
+const factory = Effect.fnUntraced(function* (
+	config: typeof Config.Type,
+	tls: Option.Option<TlsPolicy>,
+) {
+	if (config._tag === "ws") return createServer
+	const fs = yield* FileSystem.FileSystem
+	const path = yield* Path.Path
+	const directory = yield* ConfigDirectory.pipe(
+		Effect.map(Option.getOrElse(() => ".")),
+	)
+	const cert = yield* fs.readFileString(path.resolve(directory, config.cert))
+	const key = yield* fs.readFileString(path.resolve(directory, config.key))
+	return () =>
+		createSecureServer({
+			allowHTTP1: true,
+			cert,
+			key,
+			minVersion: "TLSv1.3",
+			...Option.match(tls, {
+				onNone: () => ({}),
+				onSome: (tls) => ({ ...tls, ca: [...tls.ca] }),
+			}),
+		})
+})
+/** Configured Listener; authentication is supplied to bind, never injected here. */
+export default Plugin.make({
+	name: "remote-websocket-capability",
+	config: Config,
+	inject: [FileSystem.FileSystem, Path.Path],
+	apply: Effect.fnUntraced(function* (config) {
+		const fs = yield* FileSystem.FileSystem
+		const path = yield* Path.Path
+		const directory = yield* ConfigDirectory.pipe(
+			Effect.map(Option.getOrElse(() => ".")),
+		)
+		yield* Graft.provide(Listener, {
+			properties: properties(config.url),
+			bind: (tls) =>
+				factory(config, tls).pipe(
+					Effect.provideService(FileSystem.FileSystem, fs),
+					Effect.provideService(Path.Path, path),
+					Effect.provideService(ConfigDirectory, Option.some(directory)),
+					Effect.flatMap((server) =>
+						Server.bind(server, {
+							host: String.replace(/^\[|\]$/g, "")(config.url.hostname),
+							port: Number(
+								config.url.port || (config._tag === "wss" ? 443 : 80),
+							),
+						}),
+					),
+					Effect.mapBoth({
+						onSuccess: (server) => ({
+							ready: server.ready.pipe(
+								Effect.andThen(
+									Schema.encodeEffect(Listening)({
+										event: "Listening",
+										port:
+											server.address._tag === "UnixPathAddress"
+												? null
+												: server.address.port,
+									}).pipe(Effect.orDie, Effect.flatMap(Console.log)),
+								),
+							),
+							serve: server.serve,
+						}),
+						onFailure: (error) =>
+							TransportError.make({ cause: Cause.fail(error) }),
+					}),
+				),
+		})
+	}),
+})
+const Listening = Schema.fromJsonString(
+	Schema.Struct({
+		event: Schema.Literal("Listening"),
+		port: Schema.NullOr(Schema.Int),
+	}),
+)