@jk2908/solas 0.14.0 → 0.15.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.15.1
+
+### Fixes
+
+- The README separates build adapters from runtime helpers, so the Node runtime is no longer presented as an adapter.
+
+## 0.15.0
+
+### Features
+
+- `@jk2908/solas/runtime/node` exports `createHttpRequestListener` for caller-owned `http` and `https` servers and `createHttp2RequestListener` for `http2` compatibility servers, with an exported `Http2RequestListener` type. HTTP/2 pseudo-headers are filtered out of the forwarded fetch `Request`, and `:authority` is used when there is no `host` header.
+
+### Changed
+
+- Internal asset-store and MIME helpers moved from `internal/runtimes` to `internal/assets.ts` and `internal/mime.ts`. The public `runtime/*` entries are unchanged.
+
 ## 0.14.0
 
 ### Breaking

package/README.md

@@ -566,7 +566,11 @@ export default defineConfig({
 })
 ```
 
-## Cloudflare
+## Adapters
+
+Adapters run at build time. Pass one to `solas({ adapter })`; it configures the build output for a platform.
+
+### Cloudflare
 
 Solas ships a Cloudflare adapter that runs the RSC server as a Worker and serves prerender artifacts and client assets through the Cloudflare assets binding.
 
@@ -608,7 +612,7 @@ export default defineConfig({
 
 > `cloudflare.config.ts` is an open beta and must be loaded with Node 22.18+ (Bun is not supported), so the Cloudflare build and deploy commands run under Node. See the [`cf` documentation](https://developers.cloudflare.com/cf/) for the format and the `cf dev` / `cf build` / `cf deploy` commands.
 
-### Bindings
+#### Bindings
 
 Bindings are declared in `cloudflare.config.ts` and read with the standard Cloudflare global. The adapter does not manage them:
 
@@ -654,17 +658,38 @@ The adapter:
 
 `htmlHandling: none` stops the asset layer serving a prerendered document at its route path. That matters because the asset layer ignores `Accept`, so an RSC navigation (`Accept: text/x-component`) to a fully-prerendered route would otherwise receive HTML and fail to parse. Routing documents through the Worker lets Solas serve the prerender for `text/html` and render RSC otherwise, while non-HTML assets (JS, CSS, fonts, images) are still served straight from the asset layer.
 
-Because workers have no filesystem, the Worker reads its own output through the `ASSETS` binding. Reads use logical namespaces rather than filesystem paths: `client` maps onto asset-root URLs, and `static` (prerenders) and `artifact` (manifest, ppr) map onto the artifact prefix. During the build-time prerender pass the Worker is invoked without bindings, so the Node asset store is used and reads/writes artifacts on disk.
+`cloudflare()` forwards its `cloudflare` option to `@cloudflare/vite-plugin`.
 
-`cloudflare()` forwards its `cloudflare` option to `@cloudflare/vite-plugin`. To build a Worker manually, `createWorker` composes the entry behaviour, and `createCloudflareAssets` builds the store directly:
+### Static
+
+The static adapter sets `prerender: 'full'` so every route is rendered to HTML at build time, then assembles a directory any static host can serve. There is no server.
 
 ```ts
-import { createCloudflareAssets } from '@jk2908/solas/runtime/cloudflare'
+// vite.config.ts
+import { defineConfig } from 'vite'
 
-const assets = createCloudflareAssets(env)
+import solas from '@jk2908/solas'
+import staticAdapter from '@jk2908/solas/adapters/static'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+	plugins: [solas({ adapter: staticAdapter() }), react()],
+})
 ```
 
-## Node
+`vite build` writes the site to `build/` (override with `outDir`): the client assets, each route as `<route>.html` (or `<route>/index.html` under `trailingSlash: 'always'`), its RSC payload as `<route>.rsc.txt`, plus `sitemap.xml` and `robots.txt`. Serve that directory with anything — `npx serve build`, GitHub Pages, Netlify, an S3 bucket, nginx.
+
+Client-side navigation works with no server: the browser router fetches each route's `<route>.rsc.txt` payload instead of asking a server for `text/x-component`.
+
+Because it forces full prerendering, routes that need a server are not a fit: per-route PPR or SSR opt-ins and dynamic routes without `params()`.
+
+Server actions and runtime endpoints also need a server, so the build warns when the graph contains any (a `'use server'` module or a `+endpoint` file).
+
+## Runtime helpers
+
+Runtime helpers run at request time. They live under `@jk2908/solas/runtime/*` and are never passed to `solas({ adapter })`.
+
+### Node
 
 `vite dev` and `vite preview` already run the built handler in Node (via `@vitejs/plugin-rsc`'s default server handler), so nothing extra is needed locally. For a production Node server, use `@jk2908/solas/runtime/node`:
 
@@ -679,14 +704,47 @@ await serve()
 {
 	"scripts": {
 		"build": "vite build",
-		"start": "node server.ts"
+		"start": "NODE_ENV=production node server.ts"
 	}
 }
 ```
 
+Set `NODE_ENV=production` before starting. React reads it when the built handler loads; without it the server renders development payloads, which include debug data and are noticeably larger.
+
 `serve()` loads the built RSC entry (`dist/rsc/index.js` by default) and forwards requests to its fetch handler, which already serves prerendered routes, client assets, and RSC/SSR responses. Options: `port` (defaults to `PORT` or `3000`), `host`, `outDir`, and `entry`. Run from the project root so the handler can resolve `dist`.
 
-`serve` is a runtime helper, not a build adapter: it starts an HTTP server and returns it, so it belongs in `server.ts`. Do not pass it to `solas({ adapter })`; that option expects an `Adapter` with `name` and `plugins`, such as `cloudflare()` or the static adapter.
+Set `precompress: true` in the Solas config to emit brotli variants of client and prerendered assets at build time. `serve()` negotiates them when the client sends `accept-encoding: br` and falls back to the original file otherwise. Dynamic HTML and RSC responses are streamed per request and are not precompressed, so compress those at a proxy or CDN if you need it.
+
+For TLS, mount the handler on your own `https` server:
+
+```ts
+import { createServer } from 'node:https'
+
+import { createHttpRequestListener } from '@jk2908/solas/runtime/node'
+
+import handler from './dist/rsc/index.js'
+
+createServer({ key, cert }, createHttpRequestListener(handler)).listen(443)
+```
+
+For HTTP/2, use `createHttp2RequestListener` with the compatibility API. Browsers only negotiate HTTP/2 over TLS, and `allowHTTP1` keeps clients that do not speak it working:
+
+```ts
+import http2 from 'node:http2'
+
+import { createHttp2RequestListener } from '@jk2908/solas/runtime/node'
+
+import handler from './dist/rsc/index.js'
+
+http2
+	.createSecureServer(
+		{ key, cert, allowHTTP1: true },
+		createHttp2RequestListener(handler),
+	)
+	.listen(443)
+```
+
+`serve()` itself is HTTP/1.1. TLS and HTTP/2 termination still belong at your proxy or CDN when you have one; these listeners are for deployments that terminate at Node.
 
 Bun and Deno do not need the helper. Their native servers pass the handler a `Request` directly and expect a `Response`, so the Node-specific HTTP-to-Fetch bridging (streams, `duplex`, backpressure) is not needed:
 
@@ -706,32 +764,19 @@ Deno.serve(request => handler.fetch(request))
 
 The handler reads `dist` through `node:fs`, which Bun and Deno (2.x, via Node compat) provide. Run from the project root. Bun can also run `@jk2908/solas/runtime/node` as-is, since it implements `node:http`.
 
-## Static
+### Cloudflare runtime
 
-The static adapter sets `prerender: 'full'` so every route is rendered to HTML at build time, then assembles a directory any static host can serve. There is no server.
+Because workers have no filesystem, the Worker reads its own output through the `ASSETS` binding. Reads use logical namespaces rather than filesystem paths: `client` maps onto asset-root URLs, and `static` (prerenders) and `artifact` (manifest, ppr) map onto the artifact prefix. During the build-time prerender pass the Worker is invoked without bindings, so the Node asset store is used and reads/writes artifacts on disk.
 
-```ts
-// vite.config.ts
-import { defineConfig } from 'vite'
+To build a Worker manually, `createWorker` composes the entry behaviour, and `createCloudflareAssets` builds the store directly:
 
-import solas from '@jk2908/solas'
-import staticAdapter from '@jk2908/solas/adapters/static'
-import react from '@vitejs/plugin-react'
+```ts
+import { createCloudflareAssets } from '@jk2908/solas/runtime/cloudflare'
 
-export default defineConfig({
-	plugins: [solas({ adapter: staticAdapter() }), react()],
-})
+const assets = createCloudflareAssets(env)
 ```
 
-`vite build` writes the site to `build/` (override with `outDir`): the client assets, each route as `<route>.html` (or `<route>/index.html` under `trailingSlash: 'always'`), its RSC payload as `<route>.rsc.txt`, plus `sitemap.xml` and `robots.txt`. Serve that directory with anything — `npx serve build`, GitHub Pages, Netlify, an S3 bucket, nginx.
-
-Client-side navigation works with no server: the browser router fetches each route's `<route>.rsc.txt` payload instead of asking a server for `text/x-component`.
-
-Because it forces full prerendering, routes that need a server are not a fit: per-route PPR or SSR opt-ins and dynamic routes without `params()`.
-
-Server actions and runtime endpoints also need a server, so the build warns when the graph contains any (a `'use server'` module or a `+endpoint` file).
-
-## Runtime
+### Asset store
 
 At request time Solas reads its output through an `Assets` interface (`exists`/`readText`/`readBuffer`/`mimeType`) injected into `createHandler`, defaulting to the Node standard library (which Bun runs natively). References are logical (`{ namespace, path }`), where the namespaces are `client` (Vite client output), `static` (full prerenders), and `artifact` (runtime manifest and ppr files). Platforms without a filesystem provide their own store; `@jk2908/solas/runtime/cloudflare` builds one around the `ASSETS` binding via `createWorker`. Build-time reads and writes use `node:fs` directly and are not abstracted.
 

package/dist/internal/{runtimes/assets.js → assets.js}

@@ -1,6 +1,6 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import * as Config from '../../config.js';
+import * as Config from '../config.js';
 import { getMimeTypeFromPath } from './mime.js';
 const NAMESPACE_DIRS = {
     client: 'client',

package/dist/internal/env/rsc.d.ts

@@ -1,10 +1,10 @@
 import type { ReactFormState } from 'react-dom/client';
 import type { ImportMap, Manifest, RuntimeConfig } from '../../types.js';
-import type { Assets } from '../runtimes/assets.js';
+import type { Assets } from '../assets.js';
 import * as RuntimeManifest from '../../manifest.js';
 import { Metadata } from '../metadata.js';
 export { loadManifest } from '../../manifest.js';
-export type { Assets } from '../runtimes/assets.js';
+export type { Assets } from '../assets.js';
 export type HandlerOptions = {
     /**
      * Static asset store used to serve prerendered HTML, PPR artifacts, and

package/dist/internal/env/rsc.js

@@ -4,6 +4,7 @@ import { applyBasePath, normaliseBasePath, stripBasePath } from '../../utils/bas
 import { Logger } from '../../utils/logger.js';
 import * as Config from '../../config.js';
 import * as RuntimeManifest from '../../manifest.js';
+import { nodeAssets } from '../assets.js';
 import { createHttpRouter } from '../http-router/create-http-router.js';
 import { HttpRouter } from '../http-router/router.js';
 import { isRscRequest, normaliseTrailingSlash, resolveRequestPath, } from '../http-router/utils.js';
@@ -13,7 +14,6 @@ import { isRedirect, toRedirect } from '../navigation/redirect.js';
 import * as Prerender from '../prerender.js';
 import { Tree } from '../render/tree.js';
 import { Resolver } from '../resolver.js';
-import { nodeAssets } from '../runtimes/assets.js';
 import { processActionRequest } from '../server/actions.js';
 import DefaultErr from '../ui/defaults/error.js';
 import { RequestContext } from './request-context.js';

package/dist/internal/http-router/router.d.ts

@@ -1,5 +1,5 @@
 import type { PluginConfig, SolasRequest } from '../../types.js';
-import type { AssetRef, Assets } from '../runtimes/assets.js';
+import type { AssetRef, Assets } from '../assets.js';
 import { CsrfConfig } from '../server/csrf.js';
 export declare namespace HttpRouter {
     type Params = Record<string, string | string[]>;

package/dist/internal/prerender.d.ts

@@ -1,5 +1,5 @@
 import type { BuildContext } from '../types.js';
-import type { Assets } from './runtimes/assets.js';
+import type { Assets } from './assets.js';
 export type Mode = 'full' | 'ppr';
 export type File = 'html' | 'prelude' | 'postponed' | 'metadata';
 export type Value = {

package/dist/internal/prerender.js

@@ -4,8 +4,8 @@ import { applyBasePath } from '../utils/base-path.js';
 import { Logger } from '../utils/logger.js';
 import * as Config from '../config.js';
 import * as Solas from '../solas.js';
+import { nodeAssets } from './assets.js';
 import { toPathPattern } from './http-router/utils.js';
-import { nodeAssets } from './runtimes/assets.js';
 const logger = new Logger();
 const DEFAULT_CONCURRENCY = 4;
 /**

package/dist/manifest.d.ts

@@ -1,4 +1,4 @@
-import type { Assets } from './internal/runtimes/assets.js';
+import type { Assets } from './internal/assets.js';
 import * as Prerender from './internal/prerender.js';
 export type Manifest = {
     artifacts: Prerender.ArtifactManifest;

package/dist/manifest.js

@@ -1,5 +1,5 @@
 import * as Config from './config.js';
-import { nodeAssets } from './internal/runtimes/assets.js';
+import { nodeAssets } from './internal/assets.js';
 export function getManifestPath(outDir) {
     return [outDir, Config.GENERATED_DIR, Config.RUNTIME_MANIFEST]
         .map((part, index) => {

package/dist/runtime/cloudflare/assets.d.ts

@@ -1,4 +1,4 @@
-import type { AssetNamespace, Assets } from '../../internal/runtimes/assets.js';
+import type { AssetNamespace, Assets } from '../../internal/assets.js';
 /**
  * The subset of the Cloudflare `assets` Fetcher binding that Solas needs.
  */

package/dist/runtime/cloudflare/assets.js

@@ -1,4 +1,4 @@
-import { getMimeTypeFromPath } from '../../internal/runtimes/mime.js';
+import { getMimeTypeFromPath } from '../../internal/mime.js';
 /**
  * Path prefix the adapter copies `dist/.solas` artifacts under in the asset
  * output.

package/dist/runtime/cloudflare/worker.js

@@ -1,5 +1,5 @@
+import { nodeAssets } from '../../internal/assets.js';
 import { createRuntimeHandler } from '../../internal/env/rsc.js';
-import { nodeAssets } from '../../internal/runtimes/assets.js';
 import { createCloudflareAssets } from './assets.js';
 /**
  * Build a Cloudflare Worker around Solas's RSC handler.

package/dist/runtime/node.d.ts

@@ -1,3 +1,4 @@
+import type { Http2ServerRequest, Http2ServerResponse } from 'node:http2';
 import http from 'node:http';
 export type ServeOptions = {
     /**
@@ -26,6 +27,48 @@ export type ServeOptions = {
     }) => void;
 };
 export type Server = http.Server & AsyncDisposable;
+export type FetchHandler = {
+    fetch: (request: Request) => Response | Promise<Response>;
+};
+/**
+ * A request listener for an `http2` compatibility server.
+ */
+export type Http2RequestListener = (req: Http2ServerRequest, res: Http2ServerResponse) => void;
+/**
+ * Create a request listener for a built fetch handler on an `http` or `https`
+ * server.
+ *
+ * `serve` uses this internally. Exporting it lets you terminate TLS yourself:
+ *
+ * ```ts
+ * import { createServer } from 'node:https'
+ * import { createHttpRequestListener } from '@jk2908/solas/runtime/node'
+ * import handler from './dist/rsc/index.js'
+ *
+ * createServer({ key, cert }, createHttpRequestListener(handler)).listen(443)
+ * ```
+ */
+declare function createHttpRequestListener(handler: FetchHandler): http.RequestListener;
+/**
+ * Create a request listener for a built fetch handler on an `http2`
+ * compatibility server.
+ *
+ * Browsers only negotiate HTTP/2 over TLS, so use
+ * `http2.createSecureServer({ allowHTTP1: true }, listener)`. `allowHTTP1`
+ * keeps clients that do not speak HTTP/2 working:
+ *
+ * ```ts
+ * import http2 from 'node:http2'
+ * import { createHttp2RequestListener } from '@jk2908/solas/runtime/node'
+ * import handler from './dist/rsc/index.js'
+ *
+ * http2.createSecureServer(
+ * 	{ key, cert, allowHTTP1: true },
+ * 	createHttp2RequestListener(handler),
+ * ).listen(443)
+ * ```
+ */
+declare function createHttp2RequestListener(handler: FetchHandler): Http2RequestListener;
 /**
  * Start a production HTTP server for a Node (or Bun) deployment.
  *
@@ -35,10 +78,12 @@ export type Server = http.Server & AsyncDisposable;
  * handler can resolve `dist`. The returned server is `AsyncDisposable`, so it
  * can be released with `await using`.
  *
- * Deno and Bun do not need this helper: use `Deno.serve(handler.fetch)` or
+ * For TLS or HTTP/2, mount `createHttpRequestListener(handler)` or
+ * `createHttp2RequestListener(handler)` on your own server instead. Deno and Bun
+ * do not need this helper: use `Deno.serve(handler.fetch)` or
  * `Bun.serve({ fetch: handler.fetch })` directly.
  */
 declare function serve(options?: ServeOptions): Promise<http.Server<typeof http.IncomingMessage, typeof http.ServerResponse> & {
     [Symbol.asyncDispose](): Promise<void>;
 }>;
-export { serve };
+export { createHttp2RequestListener, createHttpRequestListener, serve };

package/dist/runtime/node.js

@@ -90,9 +90,16 @@ async function webToNode(stream, res) {
  * Convert a Node request into a fetch `Request`, streaming the body when present.
  */
 function toRequest(req, signal) {
-    const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+    // HTTP/2's compatibility API also exposes pseudo-headers such as `:path` and
+    // `:authority`. Fetch `Headers` rejects names starting with `:`, and the
+    // authority replaces the HTTP/1 `host` header, so normalise both here
+    const authority = req.headers[':authority'];
+    const host = req.headers.host ?? (Array.isArray(authority) ? authority[0] : authority);
+    const url = new URL(req.url ?? '/', `http://${host ?? 'localhost'}`);
     const headers = new Headers();
     for (const [key, value] of Object.entries(req.headers)) {
+        if (key.startsWith(':'))
+            continue;
         if (Array.isArray(value)) {
             for (const item of value)
                 headers.append(key, item);
@@ -134,11 +141,84 @@ async function sendResponse(res, response) {
     }
     // send headers now so a delayed first chunk (SSE, slow streams) does not
     // leave the client waiting with no response
-    res.flushHeaders();
+    res.flushHeaders?.();
     await webToNode(response.body, res);
     if (!res.destroyed)
         res.end();
 }
+/**
+ * Handle one Node request by forwarding it to the fetch handler.
+ */
+async function handleRequest(req, res, handler) {
+    const abort = new AbortController();
+    // `close` before the response has finished means the client went away;
+    // surface that through `req.signal` so long-lived work can stop
+    function onClose() {
+        if (!res.writableEnded)
+            abort.abort(new Error('client disconnected'));
+    }
+    res.once('close', onClose);
+    try {
+        const response = await handler.fetch(toRequest(req, abort.signal));
+        await sendResponse(res, response);
+    }
+    catch (err) {
+        console.error('[solas] request failed', err);
+        if (res.headersSent) {
+            res.destroy();
+            return;
+        }
+        res.statusCode = 500;
+        res.setHeader('content-type', 'text/plain; charset=utf-8');
+        res.end('Internal Server Error');
+    }
+    finally {
+        res.off('close', onClose);
+    }
+}
+/**
+ * Create a request listener for a built fetch handler on an `http` or `https`
+ * server.
+ *
+ * `serve` uses this internally. Exporting it lets you terminate TLS yourself:
+ *
+ * ```ts
+ * import { createServer } from 'node:https'
+ * import { createHttpRequestListener } from '@jk2908/solas/runtime/node'
+ * import handler from './dist/rsc/index.js'
+ *
+ * createServer({ key, cert }, createHttpRequestListener(handler)).listen(443)
+ * ```
+ */
+function createHttpRequestListener(handler) {
+    return (req, res) => {
+        void handleRequest(req, res, handler);
+    };
+}
+/**
+ * Create a request listener for a built fetch handler on an `http2`
+ * compatibility server.
+ *
+ * Browsers only negotiate HTTP/2 over TLS, so use
+ * `http2.createSecureServer({ allowHTTP1: true }, listener)`. `allowHTTP1`
+ * keeps clients that do not speak HTTP/2 working:
+ *
+ * ```ts
+ * import http2 from 'node:http2'
+ * import { createHttp2RequestListener } from '@jk2908/solas/runtime/node'
+ * import handler from './dist/rsc/index.js'
+ *
+ * http2.createSecureServer(
+ * 	{ key, cert, allowHTTP1: true },
+ * 	createHttp2RequestListener(handler),
+ * ).listen(443)
+ * ```
+ */
+function createHttp2RequestListener(handler) {
+    return (req, res) => {
+        void handleRequest(req, res, handler);
+    };
+}
 /**
  * Start a production HTTP server for a Node (or Bun) deployment.
  *
@@ -148,7 +228,9 @@ async function sendResponse(res, response) {
  * handler can resolve `dist`. The returned server is `AsyncDisposable`, so it
  * can be released with `await using`.
  *
- * Deno and Bun do not need this helper: use `Deno.serve(handler.fetch)` or
+ * For TLS or HTTP/2, mount `createHttpRequestListener(handler)` or
+ * `createHttp2RequestListener(handler)` on your own server instead. Deno and Bun
+ * do not need this helper: use `Deno.serve(handler.fetch)` or
  * `Bun.serve({ fetch: handler.fetch })` directly.
  */
 async function serve(options = {}) {
@@ -157,33 +239,7 @@ async function serve(options = {}) {
     const port = options.port ?? (Number(process.env.PORT) || 3000);
     const host = options.host ?? '0.0.0.0';
     const handler = await loadHandler(entry);
-    const server = http.createServer(async (req, res) => {
-        const abort = new AbortController();
-        // `close` before the response has finished means the client went away;
-        // surface that through `req.signal` so long-lived work can stop
-        function onClose() {
-            if (!res.writableEnded)
-                abort.abort(new Error('client disconnected'));
-        }
-        res.once('close', onClose);
-        try {
-            const response = await handler.fetch(toRequest(req, abort.signal));
-            await sendResponse(res, response);
-        }
-        catch (err) {
-            console.error('[solas] request failed', err);
-            if (res.headersSent) {
-                res.destroy();
-                return;
-            }
-            res.statusCode = 500;
-            res.setHeader('content-type', 'text/plain; charset=utf-8');
-            res.end('Internal Server Error');
-        }
-        finally {
-            res.off('close', onClose);
-        }
-    });
+    const server = http.createServer(createHttpRequestListener(handler));
     await new Promise(resolve => server.listen(port, host, resolve));
     options.onListen?.({ port, host });
     return Object.assign(server, {
@@ -194,4 +250,4 @@ async function serve(options = {}) {
         },
     });
 }
-export { serve };
+export { createHttp2RequestListener, createHttpRequestListener, serve };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@jk2908/solas",
-	"version": "0.14.0",
+	"version": "0.15.1",
 	"description": "A Vite + React meta-framework exploring streaming, Server Components, and partial prerendering. Designed for simplicity and lightness",
 	"keywords": [
 		"framework",