Support host-owned Node embedding without an HTTP listener

[igorsheg-wix]

Problem

Some Node hosts own the HTTP listener, request admission, process lifecycle, and shutdown ordering. In that environment Flue needs to run as an in-process Fetch application rather than as the process entrypoint.

The generated Node artifact already contains the useful lower-level API:

const application = await loadFlueNodeApplication({ env });
await application.fetch(request);
await application.stop();

However, flue build --target node appends an unconditional top-level call to startFlueNodeServer(...) and installs signal handlers. Importing server.mjs therefore starts a second listener. A host application currently has to post-process generated output to remove that startup tail. That is intentionally brittle and cannot be a supported production integration.

There is a related composition problem: authored app.ts, db.ts, channel, and agent modules are part of the generated module graph and may evaluate before application-specific dependencies can be supplied to loadFlueNodeApplication. A host that creates its database connection, bounded HTTP transport, logger, and application services must currently expose those process-lifetime dependencies through environment variables or an ambient global.

Requested API

Could Flue support a first-class host-owned Node embedding mode with both:

1. A no-listen build artifact that exports loadFlueNodeApplication without top-level startup or signal handlers. This might be a build option, or an application.mjs artifact plus the current thin standalone server.mjs wrapper.
2. Application dependency injection during load, so statically composed authored modules can consume host-created process-lifetime bindings without environment/global indirection or importing Flue internals.

Illustrative shape only:

const flue = await loadFlueNodeApplication({
  env,
  bindings: {
    db,
    logger,
    http,
  },
});

host.post('/events', request => flue.fetch(request));
await flue.stop(25_000);

The exact mechanism could instead be a generated factory or a typed authored-module context. The important properties are:

• loading the artifact never opens a socket;
• the host remains the sole owner of startup and shutdown;
• dependencies are explicit and available when authored modules are composed;
• standalone node server.mjs and flue dev behavior remain unchanged;
• the public artifact includes the application fetch/stop types, without requiring imports from @flue/runtime/internal.

This is for process-lifetime dependencies only. Per-turn principals, credentials, or ephemeral capabilities should remain separately scoped rather than becoming ambient application bindings.

Tested against @flue/cli / @flue/runtime 1.0.0-beta.9.

[FredKSchott]

Thanks for the detailed writeup. Good news: on 2.0 (current nightlies), the core of this already exists. vite build on the Node target emits two entries: the self-starting dist/server.mjs, and a non-listening dist/app.mjs chunk it imports. Importing app.mjs never opens a socket or installs signal handlers — it exports loadFlueNodeApplication({ env }), which returns fetch(request), pauseAdmissions(), and stop(timeoutMs), so the host owns the listener, admission, and shutdown ordering. This is the documented embedding surface (see the Node target guide) and is what vite preview itself uses. Note the build command changed in 2.0: builds are vite build with the flue() plugin; there is no flue build.

For non-HTTP programmatic embedding with explicit dependency injection (db, providers), start() from @flue/runtime/node covers that today, though it composes agents directly rather than loading your built app.ts.

Two parts of your request are real gaps we're treating as open questions rather than bugs: exported TypeScript types for the app.mjs surface, and host-supplied process-lifetime dependencies visible to authored modules (db.ts etc.) at load time. The second cuts against the current composition model, where db.ts module-scope construction is the seam and env is the injection channel — so it needs design, not a patch. Converting this to a Discussion to carry those two.