hadars 0.1.35 → 0.1.37

package/src/lambda.ts

@@ -0,0 +1,287 @@
+/**
+ * AWS Lambda adapter for hadars.
+ *
+ * After running `hadars build`, import this in your Lambda entry file:
+ *
+ *   // lambda.ts
+ *   import { createLambdaHandler } from 'hadars/lambda';
+ *   import config from './hadars.config';
+ *   export const handler = createLambdaHandler(config);
+ *
+ * The returned handler speaks the API Gateway HTTP API (v2) payload format.
+ * API Gateway REST API (v1) events are also accepted.
+ *
+ * Static assets (JS, CSS, fonts) are served directly from the bundled
+ * `.hadars/static/` directory. For production use, front the Lambda with
+ * CloudFront and route static paths to an S3 origin instead.
+ */
+
+import React from 'react';
+import pathMod from 'node:path';
+import { pathToFileURL } from 'node:url';
+import fs from 'node:fs/promises';
+import { createProxyHandler } from './utils/proxyHandler';
+import { parseRequest } from './utils/request';
+import { tryServeFile } from './utils/staticFile';
+import { getReactResponse } from './utils/response';
+import { buildSsrResponse, buildSsrHtml, makePrecontentHtmlGetter, createRenderCache } from './utils/ssrHandler';
+import type { HadarsOptions, HadarsEntryModule, HadarsProps } from './types/hadars';
+
+// ── Lambda event / response types ────────────────────────────────────────────
+
+/** API Gateway HTTP API (v2) event. */
+export interface APIGatewayV2Event {
+    version: '2.0';
+    routeKey: string;
+    rawPath: string;
+    rawQueryString: string;
+    cookies?: string[];
+    headers: Record<string, string>;
+    requestContext: {
+        http: { method: string };
+        domainName: string;
+    };
+    body?: string;
+    isBase64Encoded: boolean;
+}
+
+/** API Gateway REST API (v1) event. */
+export interface APIGatewayV1Event {
+    httpMethod: string;
+    path: string;
+    queryStringParameters?: Record<string, string> | null;
+    headers?: Record<string, string> | null;
+    body?: string | null;
+    isBase64Encoded: boolean;
+}
+
+export type APIGatewayEvent = APIGatewayV2Event | APIGatewayV1Event;
+
+export interface LambdaResponse {
+    statusCode: number;
+    headers: Record<string, string>;
+    body: string;
+    isBase64Encoded: boolean;
+}
+
+export type LambdaHandler = (event: APIGatewayEvent) => Promise<LambdaResponse>;
+
+// ── Event → Request ───────────────────────────────────────────────────────────
+
+function eventToRequest(event: APIGatewayEvent): Request {
+    let method: string;
+    let path: string;
+    let queryString: string;
+    let headers: Record<string, string>;
+    let rawBody: string | undefined | null;
+    let isBase64: boolean;
+    let host: string;
+
+    if ('version' in event && event.version === '2.0') {
+        method      = event.requestContext.http.method;
+        path        = event.rawPath;
+        queryString = event.rawQueryString;
+        headers     = { ...event.headers };
+        // v2 puts cookies in a separate array; merge them back into the header
+        if (event.cookies?.length) headers['cookie'] = event.cookies.join('; ');
+        rawBody     = event.body;
+        isBase64    = event.isBase64Encoded;
+        host        = event.requestContext.domainName;
+    } else {
+        const e  = event as APIGatewayV1Event;
+        method      = e.httpMethod;
+        path        = e.path;
+        const qs    = e.queryStringParameters;
+        queryString = qs ? new URLSearchParams(qs as Record<string, string>).toString() : '';
+        headers     = (e.headers as Record<string, string>) ?? {};
+        rawBody     = e.body;
+        isBase64    = e.isBase64Encoded;
+        host        = headers['host'] ?? 'lambda';
+    }
+
+    const url  = `https://${host}${path}${queryString ? '?' + queryString : ''}`;
+    let body: BodyInit | undefined;
+    if (rawBody) body = isBase64 ? Buffer.from(rawBody, 'base64') : rawBody;
+
+    return new Request(url, {
+        method,
+        headers,
+        body: ['GET', 'HEAD'].includes(method) ? undefined : body,
+    });
+}
+
+// ── Response → Lambda ─────────────────────────────────────────────────────────
+
+const TEXT_RE = /\b(?:text\/|application\/(?:json|javascript|xml)|image\/svg\+xml)/;
+
+async function responseToLambda(response: Response): Promise<LambdaResponse> {
+    const headers: Record<string, string> = {};
+    response.headers.forEach((v, k) => { headers[k] = v; });
+
+    const contentType = response.headers.get('Content-Type') ?? '';
+    if (TEXT_RE.test(contentType)) {
+        return {
+            statusCode: response.status,
+            headers,
+            body: await response.text(),
+            isBase64Encoded: false,
+        };
+    }
+
+    // Binary response (images, fonts, pre-compressed assets, etc.)
+    return {
+        statusCode: response.status,
+        headers,
+        body: Buffer.from(await response.arrayBuffer()).toString('base64'),
+        isBase64Encoded: true,
+    };
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+const HadarsFolder = './.hadars';
+const StaticPath   = `${HadarsFolder}/static`;
+const SSR_FILENAME = 'index.ssr.js';
+const noopCtx      = { upgrade: () => false };
+
+/**
+ * Pre-loaded module and HTML for single-file Lambda bundles created by
+ * `hadars export lambda`. Passing this bypasses all runtime file I/O so
+ * the handler works without a `.hadars/` directory on disk.
+ */
+export interface LambdaBundled {
+    /** The compiled SSR module — import it statically in your entry shim. */
+    ssrModule: HadarsEntryModule<any>;
+    /**
+     * The contents of `.hadars/static/out.html` — load it as a text string
+     * at build time (esbuild's `--loader:.html=text` does this automatically
+     * when `hadars export lambda` runs).
+     */
+    outHtml: string;
+}
+
+/**
+ * Creates an AWS Lambda handler from a hadars config.
+ *
+ * Must be called after `hadars build` has produced the `.hadars/` output
+ * directory. The handler is stateless — Lambda can reuse the same instance
+ * across invocations; the SSR module and HTML template are cached in memory
+ * after the first warm invocation.
+ *
+ * Pass a {@link LambdaBundled} object as the second argument when using
+ * `hadars export lambda` to produce a single-file bundle — in that mode all
+ * I/O is eliminated and the handler is fully self-contained.
+ *
+ * @example — standard (file-based) deployment
+ * export const handler = createLambdaHandler(config);
+ *
+ * @example — single-file bundle (generated entry shim)
+ * import * as ssrModule from './.hadars/index.ssr.js';
+ * import outHtml from './.hadars/static/out.html';
+ * export const handler = createLambdaHandler(config, { ssrModule, outHtml });
+ */
+export function createLambdaHandler(options: HadarsOptions, bundled?: LambdaBundled): LambdaHandler {
+    const cwd          = process.cwd();
+    const fetchHandler = options.fetch;
+    const handleProxy  = createProxyHandler(options);
+
+    const getPrecontentHtml = bundled
+        ? makePrecontentHtmlGetter(Promise.resolve(bundled.outHtml))
+        : makePrecontentHtmlGetter(fs.readFile(pathMod.join(cwd, StaticPath, 'out.html'), 'utf-8'));
+
+    // Hoist the SSR module reference so it is resolved once, not on every
+    // request. In bundled mode the module is already in-memory; in file-based
+    // mode we lazily import it and cache the promise so Node's module cache is
+    // only consulted once.
+    let ssrModulePromise: Promise<HadarsEntryModule<any>> | null = null;
+    const getSsrModule = (): Promise<HadarsEntryModule<any>> => {
+        if (bundled) return Promise.resolve(bundled.ssrModule);
+        if (!ssrModulePromise) {
+            ssrModulePromise = import(
+                pathToFileURL(pathMod.resolve(cwd, HadarsFolder, SSR_FILENAME)).href
+            ) as Promise<HadarsEntryModule<any>>;
+        }
+        return ssrModulePromise;
+    };
+
+    const runHandler = async (req: Request): Promise<Response> => {
+        const request = parseRequest(req);
+
+        if (fetchHandler) {
+            const res = await fetchHandler(request);
+            if (res) return res;
+        }
+
+        const proxied = await handleProxy(request);
+        if (proxied) return proxied;
+
+        const urlPath = new URL(request.url).pathname;
+
+        if (!bundled) {
+            // File-based deployment: serve static assets from disk.
+            const staticRes = await tryServeFile(pathMod.join(cwd, StaticPath, urlPath));
+            if (staticRes) return staticRes;
+
+            const projectStaticPath = pathMod.resolve(cwd, 'static');
+            const projectRes = await tryServeFile(pathMod.join(projectStaticPath, urlPath));
+            if (projectRes) return projectRes;
+
+            const routeClean = urlPath.replace(/(^\/|\/$)/g, '');
+            if (routeClean) {
+                const routeRes = await tryServeFile(
+                    pathMod.join(cwd, StaticPath, routeClean, 'index.html'),
+                );
+                if (routeRes) return routeRes;
+            }
+        }
+        // bundled mode: static assets are not served from Lambda — route them to S3/CDN.
+
+        try {
+            const {
+                default: Component,
+                getInitProps,
+                getAfterRenderProps,
+                getFinalProps,
+            } = await getSsrModule();
+
+            const { bodyHtml, clientProps, status, headHtml } = await getReactResponse(request, {
+                document: {
+                    body: Component as React.FC<HadarsProps<object>>,
+                    lang: 'en',
+                    getInitProps,
+                    getAfterRenderProps,
+                    getFinalProps,
+                },
+            });
+
+            if (request.headers.get('Accept') === 'application/json') {
+                const serverData = (clientProps as any).__serverData ?? {};
+                return new Response(JSON.stringify({ serverData }), {
+                    status,
+                    headers: { 'Content-Type': 'application/json; charset=utf-8' },
+                });
+            }
+
+            // Build the HTML string directly — avoids creating a ReadableStream
+            // that would immediately be drained by the Lambda response serialiser.
+            const html = await buildSsrHtml(bodyHtml, clientProps, headHtml, getPrecontentHtml);
+            return new Response(html, {
+                status,
+                headers: { 'Content-Type': 'text/html; charset=utf-8' },
+            });
+        } catch (err: any) {
+            console.error('[hadars] SSR render error:', err);
+            return new Response('Internal Server Error', { status: 500 });
+        }
+    };
+
+    const finalHandler: (req: Request, ctx: any) => Promise<Response | undefined> = options.cache
+        ? createRenderCache(options.cache, (req) => runHandler(req))
+        : (req: Request) => runHandler(req);
+
+    return async (event: APIGatewayEvent): Promise<LambdaResponse> => {
+        const req      = eventToRequest(event);
+        const response = (await finalHandler(req, noopCtx)) ?? new Response('Not Found', { status: 404 });
+        return responseToLambda(response);
+    };
+}

package/src/types/hadars.ts

@@ -142,6 +142,16 @@ export interface HadarsOptions {
      * ]
      */
     moduleRules?: Record<string, any>[];
+    /**
+     * Additional rspack/webpack-compatible plugins applied to both the client
+     * and SSR bundles. Any object that implements the `apply(compiler)` method
+     * (the standard webpack/rspack plugin interface) is accepted.
+     *
+     * @example
+     * import { SubresourceIntegrityPlugin } from 'webpack-subresource-integrity';
+     * plugins: [new SubresourceIntegrityPlugin()]
+     */
+    plugins?: Array<{ apply(compiler: any): void }>;
     /**
      * SSR response cache for `run()` mode. Has no effect in `dev()` mode.
      *

package/src/utils/Head.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import type { AppContext, AppUnsuspend, LinkProps, MetaProps, ScriptProps, StyleProps } from '../types/hadars'
+import type { AppContext as HadarsAppContext, AppUnsuspend, LinkProps, MetaProps, ScriptProps, StyleProps } from '../types/hadars'
 
 interface InnerContext {
     setTitle: (title: string) => void;
@@ -31,7 +31,7 @@ const AppContext = React.createContext<InnerContext>({
 
 export const AppProviderSSR: React.FC<{
     children: React.ReactNode,
-    context: AppContext,
+    context: HadarsAppContext,
 }> = React.memo( ({ children, context }) => {
 
     const { head } = context;

package/src/utils/rspack.ts

@@ -136,6 +136,8 @@ interface EntryOptions {
     optimization?: Record<string, unknown>;
     // additional module rules appended after the built-in rules
     moduleRules?: Record<string, any>[];
+    // additional rspack/webpack-compatible plugins (applied after built-in plugins)
+    plugins?: Array<{ apply(compiler: any): void }>;
     // force React runtime mode independently of build mode (client only)
     reactMode?: 'development' | 'production';
 }
@@ -264,6 +266,30 @@ const buildCompilerConfig = (
     }
 
     const extraPlugins: any[] = [];
+
+    // Built-in plugin: force classic chunk loading for web worker sub-compilations.
+    // Without this, worker child compilers inherit the parent's outputModule:true context
+    // and may emit ES module chunks that cannot be loaded inside classic workers
+    // via importScripts. Applied to client builds only — SSR doesn't spawn workers.
+    if (!isServerBuild) {
+        extraPlugins.push({
+            apply(compiler: any) {
+                compiler.hooks.compilation.tap('HadarsWorkerChunkLoading', (compilation: any) => {
+                    compilation.hooks.childCompiler.tap(
+                        'HadarsWorkerChunkLoading',
+                        (childCompiler: any) => {
+                            if (childCompiler.options?.output) {
+                                childCompiler.options.output.chunkLoading = 'import-scripts';
+                            }
+                            if (childCompiler.options?.experiments) {
+                                childCompiler.options.experiments.outputModule = false;
+                            }
+                        },
+                    );
+                });
+            },
+        });
+    }
     const defineValues: Record<string, string> = { ...(opts.define ?? {}) };
     // When reactMode overrides the React runtime we must also set process.env.NODE_ENV
     // so React picks its dev/prod bundle, independently of the rspack build mode.
@@ -352,6 +378,7 @@ const buildCompilerConfig = (
             isDev && !isServerBuild && new ReactRefreshPlugin(),
             includeHotPlugin && isDev && !isServerBuild && new rspack.HotModuleReplacementPlugin(),
             ...extraPlugins,
+            ...(opts.plugins ?? []),
         ],
         ...localConfig,
         // Merge base resolve (modules, tsConfig, extensions) with per-build resolve

package/src/utils/ssrHandler.ts

@@ -0,0 +1,185 @@
+import { parseRequest } from './request';
+import type { HadarsOptions } from '../types/hadars';
+
+export const HEAD_MARKER = '<meta name="HADARS_HEAD">';
+export const BODY_MARKER = '<meta name="HADARS_BODY">';
+
+const encoder = new TextEncoder();
+
+// ── HTML response assembly ────────────────────────────────────────────────────
+
+export async function buildSsrResponse(
+    bodyHtml: string,
+    clientProps: Record<string, unknown>,
+    headHtml: string,
+    status: number,
+    getPrecontentHtml: (headHtml: string) => Promise<[string, string]>,
+): Promise<Response> {
+    const responseStream = new ReadableStream({
+        async start(controller) {
+            const [precontentHtml, postContent] = await getPrecontentHtml(headHtml);
+            // Flush the shell (precontentHtml) immediately so the browser can
+            // start loading CSS/fonts before the body is assembled.
+            controller.enqueue(encoder.encode(precontentHtml));
+
+            const scriptContent = JSON.stringify({ hadars: { props: clientProps } }).replace(/</g, '\\u003c');
+            controller.enqueue(encoder.encode(
+                `<div id="app">${bodyHtml}</div><script id="hadars" type="application/json">${scriptContent}</script>` + postContent,
+            ));
+            controller.close();
+        },
+    });
+
+    return new Response(responseStream, {
+        headers: { 'Content-Type': 'text/html; charset=utf-8' },
+        status,
+    });
+}
+
+/**
+ * Like {@link buildSsrResponse} but returns the complete HTML string directly
+ * instead of wrapping it in a streaming Response. Use this in environments
+ * where streaming is not beneficial (e.g. AWS Lambda) to avoid the
+ * ReadableStream allocation and the subsequent `.text()` drain overhead.
+ */
+export async function buildSsrHtml(
+    bodyHtml: string,
+    clientProps: Record<string, unknown>,
+    headHtml: string,
+    getPrecontentHtml: (headHtml: string) => Promise<[string, string]>,
+): Promise<string> {
+    const [precontentHtml, postContent] = await getPrecontentHtml(headHtml);
+    const scriptContent = JSON.stringify({ hadars: { props: clientProps } }).replace(/</g, '\\u003c');
+    return (
+        precontentHtml +
+        `<div id="app">${bodyHtml}</div><script id="hadars" type="application/json">${scriptContent}</script>` +
+        postContent
+    );
+}
+
+/**
+ * Returns a function that parses `out.html` into pre-head, post-head, and
+ * post-content segments and caches the result. Call the returned function with
+ * the per-request headHtml to produce the full HTML prefix and suffix.
+ */
+export const makePrecontentHtmlGetter = (htmlFilePromise: Promise<string>) => {
+    let preHead: string | null = null;
+    let postHead: string | null = null;
+    let postContent: string | null = null;
+    return async (headHtml: string): Promise<[string, string]> => {
+        if (preHead === null || postHead === null || postContent === null) {
+            const html = await htmlFilePromise;
+            const headEnd = html.indexOf(HEAD_MARKER);
+            const contentStart = html.indexOf(BODY_MARKER);
+            preHead = html.slice(0, headEnd);
+            postHead = html.slice(headEnd + HEAD_MARKER.length, contentStart);
+            postContent = html.slice(contentStart + BODY_MARKER.length);
+        }
+        return [preHead! + headHtml + postHead!, postContent!];
+    };
+};
+
+// ── SSR response cache ────────────────────────────────────────────────────────
+
+export interface CacheEntry {
+    /** Gzip-compressed response body. */
+    body: Uint8Array;
+    status: number;
+    /** Headers with Content-Encoding: gzip already set. */
+    headers: [string, string][];
+    expiresAt: number | null;
+}
+
+export type CacheFetchHandler = (req: Request, ctx: any) => Promise<Response | undefined>;
+
+async function transformStream(
+    data: Uint8Array,
+    stream: { writable: WritableStream; readable: ReadableStream<Uint8Array> },
+): Promise<Uint8Array> {
+    const writer = stream.writable.getWriter();
+    writer.write(data);
+    writer.close();
+    const chunks: Uint8Array[] = [];
+    const reader = stream.readable.getReader();
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        chunks.push(value);
+    }
+    const total = chunks.reduce((n, c) => n + c.length, 0);
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const c of chunks) { out.set(c, offset); offset += c.length; }
+    return out;
+}
+
+export const gzipCompress   = (d: Uint8Array) => transformStream(d, new (globalThis as any).CompressionStream('gzip'));
+export const gzipDecompress = (d: Uint8Array) => transformStream(d, new (globalThis as any).DecompressionStream('gzip'));
+
+export async function buildCacheEntry(res: Response, ttl: number | undefined): Promise<CacheEntry> {
+    const buf = await res.arrayBuffer();
+    const body = await gzipCompress(new Uint8Array(buf));
+    const headers: [string, string][] = [];
+    res.headers.forEach((v, k) => {
+        if (k.toLowerCase() !== 'content-encoding' && k.toLowerCase() !== 'content-length') {
+            headers.push([k, v]);
+        }
+    });
+    headers.push(['content-encoding', 'gzip']);
+    return { body, status: res.status, headers, expiresAt: ttl != null ? Date.now() + ttl : null };
+}
+
+export async function serveFromEntry(entry: CacheEntry, req: Request): Promise<Response> {
+    const accept = req.headers.get('Accept-Encoding') ?? '';
+    if (accept.includes('gzip')) {
+        return new Response(entry.body.buffer as ArrayBuffer, { status: entry.status, headers: entry.headers });
+    }
+    const plain = await gzipDecompress(entry.body);
+    const headers = entry.headers.filter(([k]) => k.toLowerCase() !== 'content-encoding');
+    return new Response(plain.buffer as ArrayBuffer, { status: entry.status, headers });
+}
+
+export function createRenderCache(
+    opts: NonNullable<HadarsOptions['cache']>,
+    handler: CacheFetchHandler,
+): CacheFetchHandler {
+    const store    = new Map<string, CacheEntry>();
+    const inFlight = new Map<string, Promise<CacheEntry | null>>();
+
+    return async (req, ctx) => {
+        const hadarsReq = parseRequest(req);
+        const cacheOpts = await opts(hadarsReq);
+        const key = cacheOpts?.key ?? null;
+
+        if (key != null) {
+            const entry = store.get(key);
+            if (entry) {
+                const expired = entry.expiresAt != null && Date.now() >= entry.expiresAt;
+                if (!expired) return serveFromEntry(entry, req);
+                store.delete(key);
+            }
+
+            let flight = inFlight.get(key);
+            if (!flight) {
+                const ttl = cacheOpts?.ttl;
+                flight = handler(new Request(req), ctx)
+                    .then(async (res) => {
+                        if (!res || res.status < 200 || res.status >= 300 || res.headers.has('set-cookie')) {
+                            return null;
+                        }
+                        const newEntry = await buildCacheEntry(res, ttl);
+                        store.set(key, newEntry);
+                        return newEntry;
+                    })
+                    .catch(() => null)
+                    .finally(() => inFlight.delete(key));
+                inFlight.set(key, flight);
+            }
+
+            const newEntry = await flight;
+            if (newEntry) return serveFromEntry(newEntry, req);
+        }
+
+        return handler(req, ctx);
+    };
+}