@roj-ai/standalone-server 0.1.36 → 0.2.2

package/src/preview-proxy.ts

@@ -9,7 +9,7 @@
  * pick a more specific code if needed.
  */
 
-import type { Logger, SessionManager } from '@roj-ai/sdk'
+import type { Logger, RuntimeLeaseRelease, SessionState } from '@roj-ai/sdk'
 import { selectPluginState } from '@roj-ai/sdk'
 
 interface ServiceEntry {
@@ -17,23 +17,50 @@ interface ServiceEntry {
 	status?: string
 }
 
-export async function resolveServicePort(
-	sessionManager: SessionManager,
+/** The slice of a session runtime this proxy needs — `Session` satisfies it. */
+export interface PreviewSession {
+	readonly state: SessionState
+	tryAcquireRuntimeLease(reason: string): RuntimeLeaseRelease | null
+}
+
+/** The slice of the manager this proxy needs — `SessionManager` satisfies it. */
+export interface PreviewSessionSource {
+	listResidentSessions(): Promise<PreviewSession[]>
+}
+
+export interface PreviewTarget {
+	port: number
+	/** Runtime lease held for this request — release it once the response is done. */
+	release: RuntimeLeaseRelease
+}
+
+/**
+ * Find a resident session running `serviceType` and lease its runtime.
+ *
+ * Resident runtimes only: a session is not kept resident by a healthy service any
+ * more, and loading one here would let a proxied asset GET resurrect an evicted
+ * session and reset every runtime's idle clock.
+ *
+ * The lease is what keeps the service alive for the request. Without it, idle
+ * eviction stops the dev server mid-response — an HMR or SSE stream outlives the
+ * idle window on its own, since it never produces a new request to refresh it.
+ */
+export async function acquirePreviewTarget(
+	sessions: PreviewSessionSource,
 	serviceType: string,
-): Promise<number | null> {
-	const stats = await sessionManager.getStats()
-	for (const { id } of stats.sessions) {
-		const result = await sessionManager.getSession(id)
-		if (!result.ok) continue
-		const services = selectPluginState<Map<string, ServiceEntry>>(result.value.state, 'services')
+): Promise<PreviewTarget | null> {
+	for (const session of await sessions.listResidentSessions()) {
+		const services = selectPluginState<Map<string, ServiceEntry>>(session.state, 'services')
 		const entry = services?.get(serviceType)
 		// Accept any non-failed status as long as a port is assigned. The
 		// services plugin emits `ready` (not `running`); the state projection
 		// can also briefly lag the WS `serviceStatus` broadcast that clients
 		// use to decide when to render the preview iframe.
-		if (entry?.port && entry.status !== 'failed' && entry.status !== 'stopped') {
-			return entry.port
-		}
+		if (!entry?.port || entry.status === 'failed' || entry.status === 'stopped') continue
+		// Losing the race with an eviction that already started is normal — skip
+		// that session rather than serving a port that is about to close.
+		const release = session.tryAcquireRuntimeLease(`preview:${serviceType}`)
+		if (release) return { port: entry.port, release }
 	}
 	return null
 }
@@ -41,7 +68,7 @@ export async function resolveServicePort(
 export async function proxyPreview(
 	req: Request,
 	prefix: string,
-	sessionManager: SessionManager,
+	sessions: PreviewSessionSource,
 	logger: Logger,
 ): Promise<Response> {
 	const url = new URL(req.url)
@@ -52,13 +79,22 @@ export async function proxyPreview(
 		return new Response('preview code required', { status: 404 })
 	}
 
-	const port = await resolveServicePort(sessionManager, code)
-	if (!port) {
+	const target = await acquirePreviewTarget(sessions, code)
+	if (!target) {
 		return new Response(`No service running for code "${code}"`, { status: 503 })
 	}
 
+	let released = false
+	const release = () => {
+		if (released) return
+		released = true
+		target.release()
+	}
+	// A client that walks away mid-stream never reaches the flush below.
+	req.signal.addEventListener('abort', release, { once: true })
+
 	const targetPath = '/' + restParts.join('/')
-	const targetUrl = `http://127.0.0.1:${port}${targetPath}${url.search}`
+	const targetUrl = `http://127.0.0.1:${target.port}${targetPath}${url.search}`
 
 	const headers = new Headers(req.headers)
 	headers.delete('host')
@@ -70,15 +106,47 @@ export async function proxyPreview(
 			body: req.method === 'GET' || req.method === 'HEAD' ? undefined : req.body,
 			redirect: 'manual',
 		})
-		return new Response(upstream.body, {
+		if (!upstream.body) {
+			release()
+			return new Response(null, {
+				status: upstream.status,
+				statusText: upstream.statusText,
+				headers: upstream.headers,
+			})
+		}
+		// Pump manually so the lease is released on every ending the body can have:
+		// last chunk, upstream failure, or a consumer that walks away.
+		const reader = upstream.body.getReader()
+		const tracked = new ReadableStream<Uint8Array>({
+			async pull(controller) {
+				try {
+					const { done, value } = await reader.read()
+					if (done) {
+						controller.close()
+						release()
+						return
+					}
+					controller.enqueue(value)
+				} catch (error) {
+					controller.error(error)
+					release()
+				}
+			},
+			cancel(reason) {
+				release()
+				return reader.cancel(reason)
+			},
+		})
+		return new Response(tracked, {
 			status: upstream.status,
 			statusText: upstream.statusText,
 			headers: upstream.headers,
 		})
 	} catch (err) {
+		release()
 		logger.warn('Preview proxy upstream failed', {
 			code,
-			port,
+			port: target.port,
 			error: err instanceof Error ? err.message : String(err),
 		})
 		return new Response('Preview upstream unreachable', { status: 502 })

package/src/server.ts

@@ -12,11 +12,11 @@
  *   GET  /health                                  — health check
  */
 
-import type { Config, LLMMiddleware, LocalResource, Logger, Preset, SessionId, SessionManager } from '@roj-ai/sdk'
+import type { Config, LLMMiddleware, LocalResource, Logger, SessionDefaults, SessionId, SessionManager } from '@roj-ai/sdk'
 import { bootstrap, createSystemFromServices, loadConfig, validateConfig } from '@roj-ai/sdk'
 import { createApp } from '@roj-ai/sdk/transport/http/app'
 import { createAgentTransport, ServerAdapter } from '@roj-ai/sdk/transport/adapter'
-import { createBunPlatform } from '@roj-ai/sdk/bun-platform'
+import { createBunPlatform, createServerLifecycle, runServerStartup, shutdownFromSignal } from '@roj-ai/sdk/bun-platform'
 import { createBunWebSocketHandlers } from '@roj-ai/transport/bun'
 import { Hono } from 'hono'
 import { cors } from 'hono/cors'
@@ -29,8 +29,7 @@ import { proxyPreview } from './preview-proxy.js'
 import { createSessionFileRoute } from './session-file-route.js'
 import { generateTokenSecret } from './signed-token.js'
 
-export interface StartStandaloneOptions {
-	presets: Preset[]
+export interface StartStandaloneOptions extends SessionDefaults {
 	config?: Partial<Config>
 	instanceId?: string
 	instanceName?: string
@@ -56,24 +55,39 @@ export interface StandaloneHandle {
 	shutdown(): Promise<void>
 }
 
+/** Evict a session runtime after this long idle. Override with SESSION_IDLE_TIMEOUT_MS. */
+const DEFAULT_SESSION_IDLE_TIMEOUT_MS = 600_000
+
 export async function startStandaloneServer(options: StartStandaloneOptions): Promise<StandaloneHandle> {
 	const envConfig = loadConfig()
-	const config: Config = options.config ? { ...envConfig, ...options.config } : envConfig
+	const config: Config = {
+		...envConfig,
+		...options.config,
+		host: resolveStandaloneHost(options.config?.host, process.env.HOST),
+		// Standalone is a long-lived single-instance runtime, so it evicts idle
+		// session runtimes by default. SESSION_IDLE_TIMEOUT_MS=0 turns it off.
+		sessionIdleTimeoutMs: options.config?.sessionIdleTimeoutMs
+			?? envConfig.sessionIdleTimeoutMs
+			?? DEFAULT_SESSION_IDLE_TIMEOUT_MS,
+	}
 
 	const errors = validateConfig(config)
 	if (errors.length > 0) {
 		throw new Error(`Configuration errors:\n${errors.map(e => `  - ${e}`).join('\n')}`)
 	}
 
-	const presets = options.llmMiddleware?.length
+	const llmMiddleware = options.llmMiddleware
+	const presets = llmMiddleware?.length
 		? options.presets.map(p => ({
 			...p,
-			llmMiddleware: [...options.llmMiddleware!, ...(p.llmMiddleware ?? [])],
+			llmMiddleware: [...llmMiddleware, ...(p.llmMiddleware ?? [])],
 		}))
 		: options.presets
 
-	const services = bootstrap(config, { presets }, createBunPlatform())
+	// Forwarded whole: bootstrap folds the SessionDefaults, so nothing is dropped here.
+	const services = bootstrap(config, { ...options, presets }, createBunPlatform())
 	const { logger } = services
+	warnIfStandaloneExposed(config.host, logger)
 
 	// Reap service processes left behind by a previous agent, before any session can load
 	// and start its own. At boot this agent owns nothing, so every survivor is an orphan.
@@ -103,8 +117,8 @@ export async function startStandaloneServer(options: StartStandaloneOptions): Pr
 	})
 
 	const tokenSecret = generateTokenSecret()
-	const publicHost = config.host === '0.0.0.0' ? 'localhost' : config.host
-	const publicBaseUrl = `http://${publicHost}:${config.port}`
+	let publicPort = config.port
+	const getPublicBaseUrl = () => `http://${formatPublicHost(config.host)}:${publicPort}`
 
 	const registry = new LocalRegistry(config.dataPath, logger)
 	await registry.init()
@@ -123,7 +137,7 @@ export async function startStandaloneServer(options: StartStandaloneOptions): Pr
 		registry,
 		gitFs,
 		tokenSecret,
-		publicBaseUrl,
+		getPublicBaseUrl,
 	})
 
 	const outerApp = new Hono()
@@ -168,44 +182,74 @@ export async function startStandaloneServer(options: StartStandaloneOptions): Pr
 	})
 
 	const server = startBunServer(config, outerApp, serverAdapter)
-
-	try {
-		await sessionManager.loadAllSessions()
-	} catch (err) {
-		logger.error('Failed to load persisted sessions', err instanceof Error ? err : new Error(String(err)))
+	publicPort = server.port ?? config.port
+	let transportStopPromise: Promise<void> | undefined
+	let transportStopErrorReported = false
+	const stopTransportOnce = async () => {
+		transportStopPromise ??= Promise.resolve().then(() => transport.stop())
+		try {
+			await transportStopPromise
+		} catch (error) {
+			if (transportStopErrorReported) return
+			transportStopErrorReported = true
+			throw error
+		}
 	}
 
-	try {
-		await transport.start()
-	} catch (err) {
-		logger.error('Transport start failed', err instanceof Error ? err : new Error(String(err)))
-	}
+	const lifecycle = createServerLifecycle({
+		stopIngress: () => server.stop(true),
+		cleanupSteps: [
+			...options.onShutdown ? [options.onShutdown] : [],
+			() => sessionManager.shutdown(),
+			stopTransportOnce,
+		],
+		runSignalShutdown: shutdown => {
+			void shutdownFromSignal(shutdown)
+		},
+	})
+
+	await runServerStartup(lifecycle, [
+		{ run: () => sessionManager.loadAllSessions() },
+		// A pending connection is canceled before the remaining ordered cleanup.
+		{ run: () => transport.start(), cancel: stopTransportOnce },
+	])
 
 	logger.info('Standalone server started', {
 		host: config.host,
-		port: config.port,
+		port: publicPort,
 		instanceId: instance.id,
-		url: `http://${config.host === '0.0.0.0' ? 'localhost' : config.host}:${config.port}`,
+		url: getPublicBaseUrl(),
 	})
 
-	const shutdown = async () => {
-		logger.info('Shutting down standalone server...')
-		if (options.onShutdown) {
-			await options.onShutdown()
-		}
-		await sessionManager.shutdown()
-		await transport.stop()
-		server.stop()
-	}
+	return { config, logger, instance, port: publicPort, sessionManager, shutdown: lifecycle.shutdown }
+}
 
-	process.on('SIGINT', () => {
-		void shutdown().then(() => process.exit(0))
-	})
-	process.on('SIGTERM', () => {
-		void shutdown().then(() => process.exit(0))
+export function resolveStandaloneHost(configHost: string | undefined, envHost: string | undefined): string {
+	return configHost ?? envHost ?? '127.0.0.1'
+}
+
+export function isLoopbackHost(host: string): boolean {
+	const normalized = host.toLowerCase().replace(/^\[|\]$/g, '')
+	if (normalized === 'localhost' || normalized === '::1' || normalized === '0:0:0:0:0:0:0:1') return true
+	if (normalized.startsWith('::ffff:')) return isLoopbackHost(normalized.slice('::ffff:'.length))
+	const ipv4 = normalized.split('.')
+	return ipv4.length === 4
+		&& ipv4.every(part => /^\d{1,3}$/.test(part) && Number(part) <= 255)
+		&& ipv4[0] === '127'
+}
+
+export function warnIfStandaloneExposed(host: string, logger: Pick<Logger, 'warn'>): void {
+	if (isLoopbackHost(host)) return
+	logger.warn('Standalone server is listening on a non-loopback host without authentication', {
+		host,
+		action: 'Bind to 127.0.0.1 unless network access is intentional and protected externally',
 	})
+}
 
-	return { config, logger, instance, port: server.port ?? config.port, sessionManager, shutdown }
+function formatPublicHost(host: string): string {
+	if (host === '0.0.0.0' || host === '::' || host === '[::]') return 'localhost'
+	const unwrapped = host.replace(/^\[|\]$/g, '')
+	return unwrapped.includes(':') ? `[${unwrapped}]` : unwrapped
 }
 
 interface WSData {
@@ -251,4 +295,3 @@ function startBunServer(
 		websocket: wsHandlers ?? { open() {}, close() {}, message() {} },
 	})
 }
-

package/src/user-config-loader.ts

@@ -6,7 +6,7 @@
  */
 
 import type { LocalResource, Preset, RojConfig } from '@roj-ai/sdk'
-import { validatePreset } from '@roj-ai/sdk'
+import { parseExtraBinds, validatePreset } from '@roj-ai/sdk'
 import { existsSync } from 'node:fs'
 import { dirname, isAbsolute, resolve } from 'node:path'
 
@@ -70,6 +70,7 @@ export async function loadUserConfig(configPath: string): Promise<RojConfig> {
 		presets,
 		sandboxed: typedConfig.sandboxed as boolean | undefined,
 		snapshotter: typedConfig.snapshotter as RojConfig['snapshotter'],
+		extraBinds: parseExtraBinds(typedConfig.extraBinds, configDir, absolutePath),
 		localResources,
 	}
 }