@harperfast/vite 1.0.0

package/dist/auth.js

@@ -0,0 +1,174 @@
+import { databases } from 'harper';
+import { isDevMode } from "./options.js";
+/**
+ * Harper's canonical "is this a super_user" check. Matches how Harper itself gates privileged paths
+ * (e.g. impersonation, token minting): the resolved user carries `role.permission.super_user === true`.
+ */
+export function isSuperUser(user) {
+    return user?.role?.permission?.super_user === true;
+}
+/**
+ * A Connect middleware that restricts the chain behind it (the Vite dev server) to Harper `super_user`s,
+ * authenticated via HTTP Basic auth. It runs the check itself against Harper's APIs:
+ *
+ * - A super_user Harper already resolved (`req.user`, bridged onto the node request by `registerHttp` —
+ *   e.g. an authenticated admin) passes straight through.
+ * - A loopback peer under `authorizeLocal` (the default in `harper dev`) also passes, authorized here the
+ *   same way the HMR WebSocket gate does it (`isUpgradeAuthorized`): Harper applies `authorizeLocal` to
+ *   MQTT (and its Bun HTTP inject path) but NOT the Node HTTP middleware layer this runs in, so `req.user`
+ *   is unset for a plain loopback `harper dev` request — we trust the real socket peer ourselves rather
+ *   than relying on Harper to pre-set it. So local development passes straight through with no prompt.
+ * - Otherwise we validate an `Authorization: Basic` header directly with `server.authenticateUser` and, on
+ *   failure, reply `401` with a `WWW-Authenticate: Basic` header so a browser prompts for credentials.
+ *
+ * NOTE: this guards the HTTP surface — the Vite dev server's asset, module-transform and `/@fs/`
+ * (arbitrary file read) endpoints, which is the dangerous part. Vite's HMR *WebSocket* runs on its own
+ * port and is not routed through here; keep it bound to localhost (or otherwise unexposed) in any
+ * non-local deployment.
+ */
+export function superUserAuth(scope, realm) {
+    return (req, res, next) => {
+        // Fast path: a super_user Harper already resolved (any scheme), or a loopback peer under
+        // authorizeLocal — authorized here the same way the HMR WebSocket gate is (see isUpgradeAuthorized),
+        // because Harper doesn't resolve authorizeLocal for the Node HTTP middleware layer this runs in.
+        if (isSuperUser(req.user) || authorizeLocalAllows(req))
+            return next();
+        authenticateBasic(scope, req)
+            .then((user) => {
+            if (isSuperUser(user)) {
+                req.user = user; // surface the authenticated user to the rest of the chain
+                return next();
+            }
+            challenge(res, realm);
+        })
+            .catch(next);
+    };
+}
+/** Validate an `Authorization: Basic` header against Harper's user store; `undefined` when absent/invalid. */
+async function authenticateBasic(scope, req) {
+    const header = req.headers?.authorization;
+    if (typeof header !== 'string' || !header.startsWith('Basic '))
+        return undefined;
+    const decoded = Buffer.from(header.slice('Basic '.length), 'base64').toString('utf8');
+    const separator = decoded.indexOf(':');
+    if (separator === -1)
+        return undefined; // malformed — no `username:password` pair
+    const username = decoded.slice(0, separator);
+    const password = decoded.slice(separator + 1);
+    try {
+        // `authenticateUser` always validates the password. (`getUser` skips it for a null password — the
+        // certificate-auth path — so it must not be used here.) The third arg is the request, which Harper
+        // uses only for contextual strategies (mTLS, etc.); it's unused for direct credential validation.
+        // Bad credentials throw or resolve to a non-super_user; either way the caller falls through to the
+        // 401 challenge.
+        return await scope.server?.authenticateUser?.(username, password, req);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Whether a WebSocket upgrade request may reach the Vite dev server — i.e. whether it represents a Harper
+ * `super_user`.
+ *
+ * The HMR WebSocket is served on Harper's own port (see `setupDevelopment`), so the same super_user gate as
+ * the HTTP surface should apply. But Harper runs its auth layer on the HTTP request chain, NOT the upgrade
+ * chain — `req.user` is unset here — so we authorize the raw upgrade ourselves, from the three signals a real
+ * client carries on a same-origin upgrade, cheapest first:
+ *
+ *   1. A loopback peer under `authorizeLocal` — mirrors how Harper trusts localhost for the HTTP surface, so
+ *      plain `harper dev` works with no prompt (the upgrade carries neither a Basic header nor a cookie, and
+ *      `authorizeLocal` sets no cookie). We trust the real socket peer, not a spoofable `X-Forwarded-For`.
+ *   2. An `Authorization: Basic` header, validated exactly like the HTTP gate. Browsers seldom attach this to
+ *      a WebSocket handshake, but CLI clients (and some browsers) do.
+ *   3. The `hdb-session` cookie Harper sets after any successful login (sessions are on by default). Cookies
+ *      ARE reliably sent on a same-origin upgrade, so this is the path that carries a logged-in admin's
+ *      identity from the page to a remotely-exposed HMR socket.
+ *
+ * Best-effort and fails closed: a missing global, store, or lookup error yields `false` (the upgrade is then
+ * refused), never an unauthenticated pass.
+ */
+export async function isUpgradeAuthorized(scope, req) {
+    if (authorizeLocalAllows(req))
+        return true;
+    if (isSuperUser(await authenticateBasic(scope, req)))
+        return true;
+    if (isSuperUser(await authenticateSessionCookie(scope, req)))
+        return true;
+    return false;
+}
+/** True when the upgrade's real socket peer is loopback and Harper's `authorizeLocal` trust is in effect. */
+function authorizeLocalAllows(req) {
+    if (!authorizeLocalEnabled())
+        return false;
+    const ip = req?.socket?.remoteAddress ?? '';
+    // Match Harper's own loopback test (covers `127.0.0.1`, IPv4-mapped `::ffff:127.0.0.1`, and IPv6 `::1`).
+    return ip.includes('127.0.0.') || ip === '::1';
+}
+/**
+ * Mirror the env-visible part of Harper's `authorizeLocal` resolution: an explicit `AUTHENTICATION_AUTHORIZELOCAL`
+ * override wins, otherwise it defaults to dev mode (what `harper dev` sets). Harper also consults its config
+ * file, which a plugin can't read here — so a config-file-only override isn't reflected; document accordingly.
+ */
+function authorizeLocalEnabled() {
+    const explicit = process.env.AUTHENTICATION_AUTHORIZELOCAL;
+    if (explicit != null)
+        return explicit !== 'false' && explicit !== '0' && explicit !== '';
+    return isDevMode();
+}
+/**
+ * Resolve the user named by a Harper `hdb-session` cookie on the request, or `undefined`. Harper stores
+ * sessions in `system.hdb_session` keyed by the id carried in the cookie; the cookie NAME is origin-prefixed
+ * (e.g. `localhost_9926-hdb-session`), so we match any cookie whose name ends in `hdb-session` rather than
+ * reconstructing Harper's exact prefix. Resolving a user from a session id needs no password — the id is the
+ * proof — which is why this uses `getUser` (and why `authenticateBasic`, validating a password, must not).
+ */
+async function authenticateSessionCookie(scope, req) {
+    const cookieHeader = req?.headers?.cookie;
+    if (typeof cookieHeader !== 'string' || cookieHeader.length === 0)
+        return undefined;
+    // `system.hdb_session` is an internal Harper table; feature-detect it so this stays a no-op outside Harper
+    // (unit tests) or on a host that doesn't expose it.
+    const sessionStore = databases?.system?.hdb_session;
+    if (typeof sessionStore?.get !== 'function')
+        return undefined;
+    for (const id of sessionIds(cookieHeader)) {
+        try {
+            const session = await sessionStore.get(id);
+            const username = session?.user;
+            if (typeof username !== 'string' || username.length === 0)
+                continue;
+            const user = await scope.server?.getUser?.(username, null, req);
+            if (isSuperUser(user))
+                return user;
+        }
+        catch {
+            // Unreadable session / store error — try the next candidate, else fall through to undefined.
+        }
+    }
+    return undefined;
+}
+/** Session ids from every `*hdb-session` cookie in a Cookie header (a request can carry more than one). */
+function sessionIds(cookieHeader) {
+    const ids = [];
+    for (const pair of cookieHeader.split(/;\s*/)) {
+        const eq = pair.indexOf('=');
+        if (eq === -1)
+            continue;
+        const name = pair.slice(0, eq).trim();
+        if (name === 'hdb-session' || name.endsWith('-hdb-session')) {
+            const value = pair.slice(eq + 1).trim();
+            if (value)
+                ids.push(value);
+        }
+    }
+    return ids;
+}
+/** Send a `401` asking the browser to collect Basic credentials. */
+function challenge(res, realm) {
+    res.statusCode = 401;
+    res.setHeader('WWW-Authenticate', `Basic realm="${realm}", charset="UTF-8"`);
+    res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+    res.end('401 Unauthorized — super_user credentials required.\n');
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}

package/dist/buildLock.d.ts

@@ -0,0 +1,10 @@
+import { type Scope } from 'harper';
+/**
+ * Run `build` once across the workers sharing this app's build-info record. The worker that claims the
+ * record runs the build; others wait until it finishes and return without building. Resolves once the
+ * build is complete (whether performed by this worker or another), so callers can safely refresh from the
+ * output afterward.
+ *
+ * Outside Harper (no `databases` global), it simply runs `build`.
+ */
+export declare function withBuildLock(scope: Scope, build: () => Promise<void>): Promise<void>;

package/dist/buildLock.js

@@ -0,0 +1,58 @@
+import { databases } from 'harper';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { log } from "./log.js";
+// Harper runs `handleApplication` in every worker thread, so without coordination each worker would run
+// its own `vite build` concurrently into the same output directory. We coordinate with a shared Harper
+// table (defined in schema.graphql): a worker claims the per-app record with status "building" before
+// compiling, and other workers see it and wait rather than building in parallel. This mirrors the
+// `@harperfast/nextjs` build-info pattern and works across threads and processes that share the database.
+const DATABASE = 'harperfast_vite';
+const TABLE = 'vite_build_info';
+const STALE_MS = 5 * 60 * 1000; // a "building" record older than this is treated as abandoned (crashed build)
+const POLL_MS = 150;
+const WAIT_TIMEOUT_MS = 5 * 60 * 1000;
+/** The build-info table, or undefined when running outside Harper (e.g. unit tests). */
+function buildInfoTable() {
+    return databases?.[DATABASE]?.[TABLE];
+}
+/** True while another worker holds a fresh "building" claim on this app. */
+function heldByOther(info) {
+    return info?.status === 'building' && Date.now() - info.getUpdatedTime() < STALE_MS;
+}
+/**
+ * Run `build` once across the workers sharing this app's build-info record. The worker that claims the
+ * record runs the build; others wait until it finishes and return without building. Resolves once the
+ * build is complete (whether performed by this worker or another), so callers can safely refresh from the
+ * output afterward.
+ *
+ * Outside Harper (no `databases` global), it simply runs `build`.
+ */
+export async function withBuildLock(scope, build) {
+    const table = buildInfoTable();
+    if (!table) {
+        await build();
+        return;
+    }
+    const key = scope.appName;
+    // If another worker is already building, wait for it to finish and then skip — it produced the output.
+    if (heldByOther(await table.get(key))) {
+        log(scope, 'debug', 'another worker is building; waiting for it to finish');
+        const start = Date.now();
+        while (Date.now() - start < WAIT_TIMEOUT_MS) {
+            await sleep(POLL_MS);
+            if (!heldByOther(await table.get(key)))
+                return;
+        }
+        log(scope, 'warn', 'timed out waiting for another worker to finish building');
+        return;
+    }
+    // Claim the build. Other workers will observe "building" and wait above.
+    await table.put(key, { status: 'building' });
+    try {
+        await build();
+    }
+    finally {
+        await table.put(key, { status: 'idle' });
+    }
+}
+//# sourceMappingURL=buildLock.js.map

package/dist/buildLock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildLock.js","sourceRoot":"","sources":["../src/buildLock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAc,MAAM,QAAQ,CAAC;AAC/C,OAAO,EAAE,UAAU,IAAI,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAE/B,wGAAwG;AACxG,uGAAuG;AACvG,sGAAsG;AACtG,kGAAkG;AAClG,0GAA0G;AAE1G,MAAM,QAAQ,GAAG,iBAAiB,CAAC;AACnC,MAAM,KAAK,GAAG,iBAAiB,CAAC;AAChC,MAAM,QAAQ,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,8EAA8E;AAC9G,MAAM,OAAO,GAAG,GAAG,CAAC;AACpB,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AAEtC,wFAAwF;AACxF,SAAS,cAAc;IACtB,OAAO,SAAS,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;AACvC,CAAC;AAED,4EAA4E;AAC5E,SAAS,WAAW,CAAC,IAAS;IAC7B,OAAO,IAAI,EAAE,MAAM,KAAK,UAAU,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,cAAc,EAAE,GAAG,QAAQ,CAAC;AACrF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,KAAY,EAAE,KAA0B;IAC3E,MAAM,KAAK,GAAG,cAAc,EAAE,CAAC;IAC/B,IAAI,CAAC,KAAK,EAAE,CAAC;QACZ,MAAM,KAAK,EAAE,CAAC;QACd,OAAO;IACR,CAAC;IAED,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC;IAE1B,uGAAuG;IACvG,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;QACvC,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,sDAAsD,CAAC,CAAC;QAC5E,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,GAAG,eAAe,EAAE,CAAC;YAC7C,MAAM,KAAK,CAAC,OAAO,CAAC,CAAC;YACrB,IAAI,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBAAE,OAAO;QAChD,CAAC;QACD,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,yDAAyD,CAAC,CAAC;QAC9E,OAAO;IACR,CAAC;IAED,yEAAyE;IACzE,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;IAC7C,IAAI,CAAC;QACJ,MAAM,KAAK,EAAE,CAAC;IACf,CAAC;YAAS,CAAC;QACV,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC1C,CAAC;AACF,CAAC"}

package/dist/development.d.ts

@@ -0,0 +1,8 @@
+import type { Scope } from 'harper';
+export declare const HMR_PATH = "/@harper-vite-hmr";
+/**
+ * Development mode: a Vite dev server in middleware mode with HMR.
+ * - SPA: Vite serves `index.html` and assets; everything else falls through to Harper.
+ * - SSR: Vite serves assets; HTML navigations are rendered on the fly via `ssrLoadModule`.
+ */
+export declare function setupDevelopment(scope: Scope, ssrEntry?: string): Promise<void>;

package/dist/development.js

@@ -0,0 +1,139 @@
+import { createServer as createBridgeServer } from 'node:http';
+import { join } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { viteWrapper } from "./wrappers.js";
+import { acceptsHtml, chain, registerHttp, registerShutdown } from "./http.js";
+import { superUserAuth, isUpgradeAuthorized } from "./auth.js";
+import { log } from "./log.js";
+// The HMR WebSocket is served on this path on Harper's own port (not Vite's default standalone port 24678),
+// so the whole dev surface — assets, module transforms, AND the HMR socket — sits on one origin behind one
+// super_user gate. Both our upgrade gate and Vite key off this path; any other upgrade falls through to
+// Harper untouched. The `@`-prefix mirrors Vite's own internal route convention (`/@fs`, `/@vite`).
+export const HMR_PATH = '/@harper-vite-hmr';
+/**
+ * Development mode: a Vite dev server in middleware mode with HMR.
+ * - SPA: Vite serves `index.html` and assets; everything else falls through to Harper.
+ * - SSR: Vite serves assets; HTML navigations are rendered on the fly via `ssrLoadModule`.
+ */
+export async function setupDevelopment(scope, ssrEntry) {
+    const root = scope.directory;
+    // Prefer routing HMR through Harper's port so the WebSocket is gated like everything else (below). That
+    // needs Harper's `upgrade` hook (Harper >= 5). If the host is older, fall back to Vite's own WebSocket on
+    // a separate port — still functional, but ungated, so it must be kept on localhost.
+    const canGateWebSocket = typeof scope.server?.upgrade === 'function';
+    // A never-listening HTTP server used purely as the target Vite attaches its WebSocket upgrade handler to
+    // (`hmr.server`). Our gate forwards authenticated upgrades to it; it opens no port of its own.
+    const hmrBridge = canGateWebSocket ? createBridgeServer() : undefined;
+    const server = await viteWrapper.createServer({
+        root,
+        // Omit `configFile` so Vite auto-resolves vite.config.{js,ts,mjs,...} from the root.
+        server: {
+            middlewareMode: true,
+            hmr: hmrBridge ? { server: hmrBridge, path: HMR_PATH } : true,
+            // Every request to the dev server — HTTP and the HMR upgrade — is gated as super_user, so Vite's
+            // Host-header allowlist (a DNS-rebinding defense) is redundant here. Allowing all hosts is what lets
+            // HMR be enabled against a deployed instance (e.g. a cloud IDE) where Host isn't localhost; local
+            // dev is unchanged.
+            allowedHosts: true,
+        },
+        appType: ssrEntry ? 'custom' : 'spa',
+    });
+    // The Vite dev server exposes powerful endpoints (on-the-fly module transforms, arbitrary file reads
+    // via `/@fs/`). Run a super_user Basic-auth check ahead of it in the middleware chain so HMR can't be
+    // reached by unauthenticated clients if the dev server is ever exposed beyond localhost. Local dev is
+    // unaffected: Harper auto-authorizes loopback requests as super_user under `authorizeLocal`.
+    const authenticate = superUserAuth(scope, 'Harper Vite dev server (HMR)');
+    const vite = ssrEntry
+        ? renderSsr(server, root, ssrEntry.startsWith('/') ? ssrEntry : `/${ssrEntry}`)
+        : (req, res, next) => server.middlewares(req, res, next);
+    registerHttp(scope, chain(authenticate, vite));
+    if (hmrBridge) {
+        gateHmrWebSocket(scope, hmrBridge);
+    }
+    else {
+        log(scope, 'warn', 'host Harper exposes no WebSocket upgrade hook; HMR uses a separate, ungated port — keep it bound to localhost');
+    }
+    registerShutdown(scope, () => server.close());
+    log(scope, 'info', `dev server started with HMR (${ssrEntry ? 'SSR' : 'SPA'}); super_user auth required${hmrBridge ? ' for HTTP + WebSocket' : ''}`);
+}
+/**
+ * Gate the HMR WebSocket behind the same super_user check as the HTTP surface.
+ *
+ * Registered as a run-first Harper `upgrade` handler, it claims only upgrades on `HMR_PATH` and lets every
+ * other upgrade fall through to Harper. Harper does not run its auth layer on the upgrade chain, so we
+ * authenticate the raw request ourselves (see `authenticateUpgrade`); an authenticated super_user's upgrade
+ * is handed to Vite via the bridge, and anyone else gets a `401` and the socket closed.
+ *
+ * Harper only wires its upgrade chain to the socket once some WebSocket consumer is registered, so we also
+ * register a pass-through `ws` handler to guarantee the chain is active even when the app has no other one
+ * (e.g. no `rest`). It forwards every (non-HMR) connection on to the real handlers untouched.
+ */
+function gateHmrWebSocket(scope, hmrBridge) {
+    const server = scope.server;
+    server.upgrade(async (request, socket, head, next) => {
+        // On the upgrade chain `request` is the raw Node IncomingMessage (carrying `.url`/`.headers`);
+        // tolerate a Harper Request wrapper too.
+        const req = request?._nodeRequest ?? request;
+        const path = String(req?.url ?? '').split('?', 1)[0];
+        if (path !== HMR_PATH)
+            return next(request, socket, head); // not an HMR upgrade — leave it for Harper
+        try {
+            if (await isUpgradeAuthorized(scope, req)) {
+                // Hand the authorized upgrade to Vite's listener (attached to the bridge via `hmr.server`),
+                // which performs the handshake. We do NOT call `next`, so Harper won't also upgrade this socket.
+                hmrBridge.emit('upgrade', req, socket, head);
+                return;
+            }
+        }
+        catch (e) {
+            log(scope, 'debug', 'HMR WebSocket auth error; refusing upgrade:', e);
+        }
+        refuseUpgrade(socket);
+    }, { runFirst: true });
+    // Ensure Harper actually wires its upgrade chain to the socket (it only does so once a `ws` consumer
+    // exists). Pure pass-through: forward every connection to the next handler so `rest`/`mqtt` are unaffected.
+    // (`next` is a 4th argument Harper passes at runtime that its published types omit, hence optional + any.)
+    server.ws?.((ws, request, completion, next) => next?.(ws, request, completion), {
+        subProtocol: 'harper-vite-hmr',
+    });
+}
+/** Refuse a WebSocket upgrade: emit a minimal `401` and close the socket. */
+function refuseUpgrade(socket) {
+    try {
+        socket.write('HTTP/1.1 401 Unauthorized\r\nConnection: close\r\nContent-Length: 0\r\n\r\n');
+    }
+    catch {
+        // The socket may already be gone.
+    }
+    socket.destroy?.();
+}
+/**
+ * SSR middleware: Vite serves assets; for HTML navigations it transforms `index.html`, loads the server
+ * entry via `ssrLoadModule` (so edits are reflected immediately) and injects the render into the outlet.
+ */
+function renderSsr(server, root, ssrUrl) {
+    return (req, res, next) => {
+        server.middlewares(req, res, async (err) => {
+            if (err)
+                return next(err);
+            if (!acceptsHtml(req))
+                return next();
+            try {
+                const raw = readFileSync(join(root, 'index.html'), 'utf-8');
+                const template = await server.transformIndexHtml(req.url, raw);
+                const { render } = await server.ssrLoadModule(ssrUrl);
+                const appHtml = await render(req.url);
+                res.statusCode = 200;
+                res.setHeader('Content-Type', 'text/html');
+                // Function replacer: a literal string would let `$&`/`$\``/`$'`/`$$` sequences in the
+                // rendered markup be interpreted as replacement patterns and corrupt the document.
+                res.end(template.replace('<!--ssr-outlet-->', () => appHtml));
+            }
+            catch (e) {
+                server.ssrFixStacktrace(e);
+                next(e);
+            }
+        });
+    };
+}
+//# sourceMappingURL=development.js.map

package/dist/development.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"development.js","sourceRoot":"","sources":["../src/development.ts"],"names":[],"mappings":"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"}

package/dist/http.d.ts

@@ -0,0 +1,18 @@
+import type { Scope } from 'harper';
+/** A Connect-style middleware: forwards to `next()` when it does not handle the request. */
+export type Middleware = (req: any, res: any, next: (err?: unknown) => void) => void;
+/**
+ * Compose Connect middlewares into one. Each runs only after the previous calls `next()` without an
+ * error; the first to handle the response (by not calling `next`) ends the chain. When all fall through,
+ * the composed middleware calls its own `next`. Lets us run, say, an auth check ahead of Vite.
+ */
+export declare function chain(...middlewares: Middleware[]): Middleware;
+/** A request that should receive an HTML document (SPA shell / SSR render) rather than falling through. */
+export declare function acceptsHtml(req: any): boolean;
+/**
+ * Register an HTTP handler with Harper that runs `middleware` first and, for any request the middleware
+ * does not handle, falls through to the next Harper layer (e.g. `rest: true` resources) via `nextLayer`.
+ */
+export declare function registerHttp(scope: Scope, middleware: Middleware, options?: Record<string, unknown>): void;
+/** Close the given instance both when the scope closes and when Harper broadcasts a shutdown message. */
+export declare function registerShutdown(scope: Scope, close: () => unknown): void;

package/dist/http.js

@@ -0,0 +1,87 @@
+import { parentPort } from 'node:worker_threads';
+/**
+ * Compose Connect middlewares into one. Each runs only after the previous calls `next()` without an
+ * error; the first to handle the response (by not calling `next`) ends the chain. When all fall through,
+ * the composed middleware calls its own `next`. Lets us run, say, an auth check ahead of Vite.
+ */
+export function chain(...middlewares) {
+    return (req, res, next) => {
+        let i = 0;
+        const advance = (err) => {
+            if (err)
+                return next(err);
+            const middleware = middlewares[i++];
+            if (!middleware)
+                return next();
+            middleware(req, res, advance);
+        };
+        advance();
+    };
+}
+/** A request that should receive an HTML document (SPA shell / SSR render) rather than falling through. */
+export function acceptsHtml(req) {
+    const method = req.method ?? 'GET';
+    if (method !== 'GET' && method !== 'HEAD')
+        return false;
+    return String(req.headers?.accept ?? '').includes('text/html');
+}
+/**
+ * Register an HTTP handler with Harper that runs `middleware` first and, for any request the middleware
+ * does not handle, falls through to the next Harper layer (e.g. `rest: true` resources) via `nextLayer`.
+ */
+export function registerHttp(scope, middleware, options) {
+    scope.server?.http?.((request, nextLayer) => new Promise((resolve, reject) => {
+        const res = request._nodeResponse;
+        // A middleware that handles the request writes the response directly and never calls `next`.
+        // Resolve once the response completes so Harper's awaited handler doesn't accumulate a pending
+        // promise (and its captured req/res) per handled request — a leak under load. Resolving
+        // `undefined` is exactly the "already handled via the node response" signal Harper looks for,
+        // so it won't double-send; the fall-through path below resolves with the next layer instead.
+        const onComplete = () => {
+            cleanup();
+            resolve(undefined);
+        };
+        const cleanup = () => {
+            res?.removeListener?.('finish', onComplete);
+            res?.removeListener?.('close', onComplete);
+        };
+        res?.on?.('finish', onComplete);
+        res?.on?.('close', onComplete);
+        // Bridge Harper's resolved identity onto the node request so a node-level middleware can run
+        // its own auth check (e.g. the dev server's super_user gate). Harper itself does this for
+        // fall-through requests (`request._nodeRequest.user = request.user`); we do it up front.
+        request._nodeRequest.user = request.user;
+        middleware(request._nodeRequest, res, (err) => {
+            cleanup();
+            if (err)
+                return reject(err);
+            try {
+                resolve(nextLayer(request));
+            }
+            catch (e) {
+                reject(e);
+            }
+        });
+    }), options);
+}
+/** Close the given instance both when the scope closes and when Harper broadcasts a shutdown message. */
+export function registerShutdown(scope, close) {
+    // `scope`'s `close` event and a Harper `shutdown` message can both fire; run `close` exactly once and
+    // memoize its promise so every caller awaits the *same* teardown. Returning that promise from the
+    // `close` listener lets Harper's `scope.close()` await Vite's `server.close()` — i.e. wait for the
+    // rolldown dev-server runtime to be fully disposed before the worker exits. That ordering matters:
+    // tearing the worker down (exit or terminate) while rolldown's native runtime is still live crashes
+    // the whole process. The `shutdown` message starts the teardown as early as possible.
+    let closing;
+    const closeOnce = () => (closing ??= (async () => close())());
+    const shutdownHandler = (msg) => {
+        if (msg?.type === 'shutdown')
+            void closeOnce();
+    };
+    scope.on('close', () => {
+        parentPort?.off('message', shutdownHandler);
+        return closeOnce();
+    });
+    parentPort?.on('message', shutdownHandler);
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import type { Scope } from 'harper';
+export { viteWrapper } from './wrappers.ts';
+/**
+ * Harper extension entry point. Runs the Vite dev server (HMR) or the hybrid-production build based on the
+ * `hmr` option (defaulting to Harper's `DEV_MODE`), then hands off to the matching setup. SSR is enabled
+ * when the `ssr` option points at a server entry.
+ */
+export declare function handleApplication(scope: Scope): Promise<void>;

package/dist/index.js

@@ -0,0 +1,23 @@
+import { normalizeSsrEntry, resolveHmr } from "./options.js";
+import { setupDevelopment } from "./development.js";
+import { setupProduction } from "./production.js";
+import { log } from "./log.js";
+// Re-export the mockable wrappers so tests (and consumers) can reach them from the entry point.
+export { viteWrapper } from "./wrappers.js";
+/**
+ * Harper extension entry point. Runs the Vite dev server (HMR) or the hybrid-production build based on the
+ * `hmr` option (defaulting to Harper's `DEV_MODE`), then hands off to the matching setup. SSR is enabled
+ * when the `ssr` option points at a server entry.
+ */
+export async function handleApplication(scope) {
+    const ssrEntry = normalizeSsrEntry(scope.options?.get?.(['ssr']));
+    const hmr = resolveHmr(scope.options?.get?.(['hmr']));
+    log(scope, 'info', `handling '${scope.appName}' in ${hmr ? 'development (HMR)' : 'production'} mode`);
+    if (hmr) {
+        await setupDevelopment(scope, ssrEntry);
+    }
+    else {
+        await setupProduction(scope, ssrEntry);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAE/B,gGAAgG;AAChG,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,KAAY;IACnD,MAAM,QAAQ,GAAG,iBAAiB,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAClE,MAAM,GAAG,GAAG,UAAU,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAEtD,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,KAAK,CAAC,OAAO,QAAQ,GAAG,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,YAAY,OAAO,CAAC,CAAC;IAEtG,IAAI,GAAG,EAAE,CAAC;QACT,MAAM,gBAAgB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACzC,CAAC;SAAM,CAAC;QACP,MAAM,eAAe,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACxC,CAAC;AACF,CAAC"}

package/dist/log.d.ts

@@ -0,0 +1,9 @@
+import type { Scope } from 'harper';
+type Level = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Log through Harper's scoped logger with a consistent prefix. Logger methods are optional, so this is a
+ * no-op for any level the host logger doesn't implement. Note Harper's default log level is `warn`, so
+ * set `logging.level` to `info` (or `debug`) to see build/rebuild diagnostics.
+ */
+export declare function log(scope: Scope, level: Level, message: string, ...args: unknown[]): void;
+export {};

package/dist/log.js

@@ -0,0 +1,10 @@
+const PREFIX = '[@harperfast/vite]';
+/**
+ * Log through Harper's scoped logger with a consistent prefix. Logger methods are optional, so this is a
+ * no-op for any level the host logger doesn't implement. Note Harper's default log level is `warn`, so
+ * set `logging.level` to `info` (or `debug`) to see build/rebuild diagnostics.
+ */
+export function log(scope, level, message, ...args) {
+    scope.logger[level]?.(`${PREFIX} ${message}`, ...args);
+}
+//# sourceMappingURL=log.js.map

package/dist/log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.js","sourceRoot":"","sources":["../src/log.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,GAAG,oBAAoB,CAAC;AAIpC;;;;GAIG;AACH,MAAM,UAAU,GAAG,CAAC,KAAY,EAAE,KAAY,EAAE,OAAe,EAAE,GAAG,IAAe;IAClF,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,MAAM,IAAI,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,CAAC;AACxD,CAAC"}

package/dist/options.d.ts

@@ -0,0 +1,19 @@
+/** Harper sets `DEV_MODE` when started with `harper dev`. */
+export declare function isDevMode(): boolean;
+/**
+ * Whether to run the Vite dev server with HMR (vs. the hybrid production build).
+ *
+ * Controlled by the `hmr` option when it's an explicit boolean; otherwise defaults to Harper's dev mode
+ * (the `DEV_MODE` env, set by `harper dev`).
+ */
+export declare function resolveHmr(hmrOption: unknown): boolean;
+/** Normalize the optional `ssr` config value (path to the server entry) to a non-empty string or undefined. */
+export declare function normalizeSsrEntry(value: unknown): string | undefined;
+/**
+ * The build output directory (the `output` option), relative to the app root. This is where the plugin
+ * builds the client and what the `static` plugin should serve. Defaults to `dist` (matching Vite's own
+ * default), with any trailing slash trimmed.
+ */
+export declare function resolveOutput(value: unknown): string;
+/** True when `files` is configured (string, non-empty array, or object), meaning we should watch for rebuilds. */
+export declare function hasFilesOption(value: unknown): boolean;