@xoong/server 0.0.0-stage → 0.0.35

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Duong Tran Xuan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,26 @@
-# Temporary Holding Version
+# @xoong/server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The server behind `xoong dev` and `xoong build`: one `(Request) => Response` handler for static files, an API proxy and TypeScript type stripping, with a Node adapter. Never shipped to the browser.
+
+## Install
+
+```bash
+npm install @xoong/server
+```
+
+## Use
+
+```js
+import { createHandler } from '@xoong/server';
+import { serve } from '@xoong/server/node';
+```
+See the docs for the options.
+
+## More
+
+* Documentation and demos: https://github.com/fpt-duongtx/xoong#readme
+* Source: https://github.com/fpt-duongtx/xoong/tree/main/packages/server
+* All packages share one version number and are released together: https://github.com/fpt-duongtx/xoong/releases
+* xoong is a working prototype (0.0.x): the HTML syntax is still Draft.
+
+MIT licence.

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@xoong/server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.35",
+  "description": "xoong server: one (Request) => Response handler for static files, an API proxy and TypeScript type stripping, plus a Node adapter. Dev and optional production use; never shipped to the browser.",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js",
+    "./node": "./src/node.js"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "amaro": "^1.3.0"
+  },
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "xoong",
+    "web-framework",
+    "openapi",
+    "custom-elements"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "author": "Duong Tran Xuan <duongtx1505@icloud.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fpt-duongtx/xoong.git",
+    "directory": "packages/server"
+  },
+  "bugs": {
+    "url": "https://github.com/fpt-duongtx/xoong/issues"
+  },
+  "homepage": "https://github.com/fpt-duongtx/xoong#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/handler.js

@@ -0,0 +1,167 @@
+// @ts-check
+/**
+ * One web-standard handler: (Request) => Promise<Response>.
+ * It runs anywhere a Fetch-API runtime exists. File access is injected, so this file imports no Node module.
+ *
+ *   createHandler({
+ *     files:    async (path) => ({ body: Uint8Array|string, type?: string }) | null,
+ *     proxy:    { '/api': 'https://backend.internal' },   // prefix -> upstream origin
+ *     packages: { '@xoong/core': { prefix: '/@xoong/core', exports: {...} } }, // served to the browser via an import map
+ *     transform: { '.ts': (code, path) => javascript },     // e.g. strip TypeScript types
+ *   })
+ */
+
+const TYPES = {
+  '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.mjs': 'text/javascript; charset=utf-8',
+  '.ts': 'text/javascript; charset=utf-8', '.css': 'text/css; charset=utf-8', '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml', '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif',
+  '.webp': 'image/webp', '.avif': 'image/avif', '.ico': 'image/x-icon', '.woff': 'font/woff', '.woff2': 'font/woff2', '.ttf': 'font/ttf', '.otf': 'font/otf',
+  '.txt': 'text/plain; charset=utf-8', '.md': 'text/markdown; charset=utf-8', '.xml': 'application/xml', '.pdf': 'application/pdf', '.wasm': 'application/wasm',
+  '.map': 'application/json', '.webmanifest': 'application/manifest+json', '.mp4': 'video/mp4', '.webm': 'video/webm', '.mp3': 'audio/mpeg',
+};
+const extOf = (p) => { const i = p.lastIndexOf('.'); return i < 0 ? '' : p.slice(i).toLowerCase(); };
+
+/** Headers that describe one hop and must not be copied through a proxy. */
+const HOP = new Set(['connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization', 'te', 'trailer', 'transfer-encoding', 'upgrade', 'host', 'content-length']);
+
+/**
+ * Build the import map for the packages the page may import (bare specifiers like "@xoong/core").
+ * @param {Record<string, { prefix: string, exports: Record<string, string> | string }>} packages
+ */
+export function buildImportMap(packages) {
+  /** @type {Record<string, string>} */
+  const imports = {};
+  for (const [name, { prefix, exports }] of Object.entries(packages)) {
+    const map = typeof exports === 'string' ? { '.': exports } : exports;
+    for (const [sub, target] of Object.entries(map)) {
+      const file = typeof target === 'string' ? target : target?.default ?? target?.import;
+      if (typeof file !== 'string') continue;
+      imports[sub === '.' ? name : `${name}/${sub.replace(/^\.\//, '')}`] = `${prefix}/${file.replace(/^\.\//, '')}`;
+    }
+  }
+  return { imports };
+}
+
+/** Insert an import map before the first <script> (or at the end of <head>) unless the page has one. */
+export function injectImportMap(html, importMap) {
+  if (/<script[^>]+type\s*=\s*["']importmap["']/i.test(html)) return html;
+  const tag = `<script type="importmap">${JSON.stringify(importMap).replace(/</g, '\\u003c')}</script>`;
+  const script = html.search(/<script\b/i);
+  if (script >= 0) return html.slice(0, script) + tag + '\n' + html.slice(script);
+  const head = html.search(/<\/head>/i);
+  if (head >= 0) return html.slice(0, head) + tag + '\n' + html.slice(head);
+  return tag + '\n' + html;
+}
+
+/**
+ * @param {{
+ *   files?: (path: string) => Promise<{ body: Uint8Array | string, type?: string } | null>,
+ *   proxy?: Record<string, string>,
+ *   packages?: Record<string, { prefix: string, exports: Record<string, any> | string }>,
+ *   transform?: Record<string, (code: string, path: string) => string | Promise<string>>,
+ *   fetch?: typeof fetch,
+ *   spa?: boolean,
+ *   headers?: Record<string, string>,
+ *   onError?: (error: unknown, request: Request) => void,
+ * }} options
+ */
+export function createHandler(options = {}) {
+  const { files, proxy = {}, packages = {}, transform = {}, spa = false, headers: extra = {}, onError } = options;
+  const upstreamFetch = options.fetch ?? globalThis.fetch;
+  const importMap = Object.keys(packages).length ? buildImportMap(packages) : null;
+  // Longest prefix first so "/api/v2" wins over "/api".
+  const proxies = Object.entries(proxy).sort((a, b) => b[0].length - a[0].length);
+  for (const [prefix, target] of proxies) {
+    if (!prefix.startsWith('/')) throw new Error(`xoong server: proxy prefix "${prefix}" must start with "/"`);
+    try { new URL(target); } catch { throw new Error(`xoong server: proxy target for "${prefix}" is not a valid URL: ${target}`); }
+  }
+
+  /** path -> { code, out }: an unchanged source file is not transformed again on every reload. */
+  const transformed = new Map();
+  const text = (status, message) => new Response(message, { status, headers: { 'content-type': 'text/plain; charset=utf-8', ...extra } });
+
+  /** The part of the (still percent-encoded) path below `prefix`, or null when the path is not under it. */
+  function below(rawPath, prefix) {
+    if (prefix === '/') return rawPath;
+    if (rawPath === prefix) return '';
+    return rawPath.startsWith(prefix + '/') ? rawPath.slice(prefix.length) : null; // "/apix" is not under "/api"
+  }
+
+  /** @param {Request} request @param {URL} url @param {string} rest @param {string} target */
+  async function forward(request, url, rest, target) {
+    const upstream = new URL(target);
+    upstream.pathname = upstream.pathname.replace(/\/$/, '') + (rest || '/');
+    upstream.search = url.search;
+    const out = new Headers();
+    for (const [k, v] of request.headers) if (!HOP.has(k.toLowerCase())) out.set(k, v);
+    out.set('x-forwarded-host', url.host);
+    out.set('x-forwarded-proto', url.protocol.replace(':', ''));
+    const hasBody = !['GET', 'HEAD'].includes(request.method);
+    try {
+      const res = await upstreamFetch(upstream, { method: request.method, headers: out, body: hasBody ? request.body : undefined, redirect: 'manual', ...(hasBody ? { duplex: 'half' } : {}) });
+      const back = new Headers();
+      for (const [k, v] of res.headers) if (!HOP.has(k.toLowerCase()) && k.toLowerCase() !== 'content-encoding') back.append(k, v); // append: several Set-Cookie headers must all survive
+      // fetch() already decoded the body, so the encoding header would now be wrong.
+      return new Response(res.body, { status: res.status, statusText: res.statusText, headers: back });
+    } catch (error) {
+      onError?.(error, request);
+      return text(502, `xoong server: could not reach ${upstream.origin} (${/** @type {Error} */ (error)?.message ?? error})`);
+    }
+  }
+
+  /** Serve a file, applying transforms and the import map. */
+  async function serveFile(path, request) {
+    const found = await files?.(path);
+    if (!found) return null;
+    const ext = extOf(path);
+    let body = found.body;
+    if (transform[ext]) {
+      const code = typeof body === 'string' ? body : new TextDecoder().decode(body);
+      try {
+        const hit = transformed.get(path);
+        if (hit && hit.code === code) body = hit.out;
+        else { body = await transform[ext](code, path); transformed.set(path, { code, out: /** @type {string} */ (body) }); }
+      } catch (error) {
+        onError?.(error, request);
+        return text(500, `xoong server: could not transform ${path}\n${/** @type {Error} */ (error)?.message ?? error}`);
+      }
+    }
+    if (ext === '.html' && importMap) body = injectImportMap(typeof body === 'string' ? body : new TextDecoder().decode(body), importMap);
+    const h = { 'content-type': found.type ?? TYPES[ext] ?? 'application/octet-stream', 'cache-control': 'no-cache', ...extra };
+    return new Response(request.method === 'HEAD' ? null : /** @type {BodyInit} */ (body), { status: 200, headers: h });
+  }
+
+  return async function handle(/** @type {Request} */ request) {
+    const url = new URL(request.url);
+    let pathname;
+    try { pathname = decodeURIComponent(url.pathname); } catch { return text(400, 'Bad request'); }
+    if (pathname.includes('\0') || pathname.split('/').includes('..')) return text(400, 'Bad request');
+
+    // Match on the encoded path so the forwarded path is sliced from the same string that was matched.
+    for (const [prefix, target] of proxies) {
+      const rest = below(url.pathname, prefix);
+      if (rest !== null) return forward(request, url, rest, target);
+    }
+    if (request.method !== 'GET' && request.method !== 'HEAD') return text(405, 'Method not allowed');
+
+    // Files provided by installed packages (served under their prefix; the import map points here).
+    for (const pkg of Object.values(packages)) {
+      if (pathname.startsWith(pkg.prefix + '/')) {
+        const res = await serveFile(pathname, request);
+        if (res) return res;
+        return text(404, 'Not found');
+      }
+    }
+
+    const candidates = pathname.endsWith('/') ? [pathname + 'index.html'] : [pathname];
+    for (const path of candidates) {
+      const res = await serveFile(path, request);
+      if (res) return res;
+    }
+    if (spa && !extOf(pathname)) {
+      const res = await serveFile('/index.html', request);
+      if (res) return res;
+    }
+    return text(404, 'Not found');
+  };
+}

package/src/index.js

@@ -0,0 +1 @@
+export { createHandler, buildImportMap, injectImportMap } from './handler.js';

package/src/node.js

@@ -0,0 +1,179 @@
+// @ts-check
+/** Node adapters for @xoong/server: a file reader rooted at a folder, TypeScript stripping, and an http server. */
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import { createRequire } from 'node:module';
+import { dirname, join, normalize, resolve, sep } from 'node:path';
+import { Readable } from 'node:stream';
+import { createHandler } from './handler.js';
+
+/**
+ * Read files under `root` only. Paths that escape the root (via .., symlink-free check) are refused.
+ * @param {string} root
+ */
+export function nodeFiles(root) {
+  const base = resolve(root);
+  return async (/** @type {string} */ path) => {
+    const file = resolve(join(base, normalize('.' + path)));
+    if (file !== base && !file.startsWith(base + sep)) return null;
+    try {
+      if (!(await stat(file)).isFile()) return null;
+      return { body: await readFile(file) };
+    } catch { return null; }
+  };
+}
+
+/** Strip TypeScript types (erasable syntax only: no enum, namespace or parameter properties). */
+export async function stripTypes(/** @type {string} */ code, /** @type {string} */ path) {
+  const { transformSync } = await import('amaro');
+  try { return transformSync(code, { mode: 'strip-only' }).code; } catch (error) {
+    throw new Error(`${path}: ${/** @type {Error} */ (error).message}\nxoong only strips types; use erasable TypeScript (no enum/namespace/parameter properties)`);
+  }
+}
+
+/** Walk up from a resolved entry file to the package.json of the package called `name`. */
+async function packageDirOf(entry, name) {
+  for (let dir = dirname(entry); dir !== dirname(dir); dir = dirname(dir)) {
+    try {
+      const pkg = JSON.parse(await readFile(join(dir, 'package.json'), 'utf8'));
+      if (pkg.name === name) return { dir, pkg };
+    } catch { /* keep walking */ }
+  }
+  return null;
+}
+
+/**
+ * Find installed @xoong/* packages from `from` and describe how to serve them to the browser.
+ * URL prefixes: @xoong/core -> /@xoong/core; the unscoped umbrella `xoong` -> /vendor/xoong.
+ * @param {string} from  a folder inside the project
+ * @param {string[]} names
+ */
+export async function findPackages(from, names = ['@xoong/core', '@xoong/data', '@xoong/forms', '@xoong/i18n', '@xoong/controls', '@xoong/richtext', '@xoong/ui', 'xoong'], extra = []) {
+  const require = createRequire(join(resolve(from), 'noop.js'));
+  const xoong = new Set(names);
+  names = [...names, ...extra.filter((n) => !xoong.has(n))];
+  /** @type {Record<string, { prefix: string, exports: any, dir: string }>} */
+  const out = {};
+  for (const name of names) {
+    let found = null;
+    try { found = await packageDirOf(require.resolve(name), name); } catch { /* not installed */ }
+    if (!found) continue;
+    const own = !xoong.has(name); // a package named in the project's config: its exports map is expanded (wildcards) so an import map can list every entry
+    out[name] = { prefix: name.startsWith('@') ? `/${name}` : own ? `/@${name}` : `/vendor/${name}`, exports: own ? await expandExports(found.dir, found.pkg.exports ?? found.pkg.main ?? './src/index.js') : found.pkg.exports ?? found.pkg.main ?? './src/index.js', dir: found.dir };
+  }
+  return out;
+}
+
+/** Entries that only Node can use: never given to the browser. */
+const NODE_ONLY = /^\.\/server(\/|$)/;
+
+/**
+ * An `exports` map as a flat { "./sub": "./file" }: conditions resolved (browser, import, default), wildcards ("./widgets/*": "./src/widgets/*.js")
+ * expanded against the files of the package, and Node-only entries ("./server") left out.
+ */
+export async function expandExports(dir, exports) {
+  const map = typeof exports === 'string' ? { '.': exports } : exports;
+  const pick = (t) => typeof t === 'string' ? t : t && typeof t === 'object' ? pick(t.browser ?? t.import ?? t.default) : undefined;
+  /** @type {Record<string, string>} */ const out = {};
+  for (const [key, target] of Object.entries(map)) {
+    const file = pick(target);
+    if (typeof file !== 'string' || NODE_ONLY.test(key)) continue;
+    if (!key.includes('*')) { out[key] = file; continue; }
+    const [keyHead, keyTail] = key.split('*');
+    const [fileHead, fileTail] = file.split('*');
+    const head = fileHead.replace(/^\.\//, '');
+    const folder = head.slice(0, head.lastIndexOf('/') + 1); // the part of the pattern that is a folder
+    const base = join(dir, folder);
+    let names;
+    try { names = await readdir(base, { recursive: true }); } catch { continue; }
+    for (const n of names.map((x) => x.split(sep).join('/'))) {
+      const rel = folder + n;
+      if (!rel.startsWith(head) || !rel.endsWith(fileTail) || rel.length < head.length + fileTail.length) continue;
+      const star = rel.slice(head.length, rel.length - fileTail.length);
+      if (star) out[`${keyHead}${star}${keyTail}`] = `${fileHead}${star}${fileTail}`;
+    }
+  }
+  return out;
+}
+
+/** The file a URL under a package prefix stands for: an exports subpath ("/theme.css") maps to its target, anything else is the path itself. */
+export const packagePath = (exports, rest) => (typeof exports === 'object' && exports && typeof exports[`.${rest}`] === 'string' ? exports[`.${rest}`].replace(/^\./, '') : rest);
+
+/**
+ * Dev handler: serves `root`, the installed @xoong packages (with an import map), strips .ts on the fly and proxies APIs.
+ * @param {{ root?: string, resolveFrom?: string, proxy?: Record<string,string>, spa?: boolean, onError?: (e: unknown, r: Request) => void }} [options]
+ *   `resolveFrom`: folder to look for installed @xoong packages from (default: `root`).
+ */
+/** Dot-folders a page may read: generated tables and the standard well-known folder. Everything else (.env, .git, ...) is refused. */
+const ALLOWED_DOT = new Set(['.xoong', '.well-known']);
+export const isHidden = (/** @type {string} */ path) => path.split('/').some((seg) => seg.startsWith('.') && !ALLOWED_DOT.has(seg) && seg !== '');
+
+export async function createDevHandler({ root = '.', resolveFrom = root, proxy = {}, spa = false, onError, packages: extraPackages = [] } = {}) {
+  const pkgs = await findPackages(resolveFrom, undefined, extraPackages);
+  const projectFiles = nodeFiles(root);
+  const exportsOf = Object.fromEntries(Object.values(pkgs).map((p) => [p.prefix, p.exports]));
+  const pkgFiles = Object.fromEntries(Object.values(pkgs).map((p) => [p.prefix, nodeFiles(p.dir)]));
+  const files = async (/** @type {string} */ path) => {
+    if (isHidden(path)) return null;
+    for (const [prefix, read] of Object.entries(pkgFiles)) if (path.startsWith(prefix + '/')) return read(packagePath(exportsOf[prefix], path.slice(prefix.length)));
+    return projectFiles(path);
+  };
+  const packages = Object.fromEntries(Object.entries(pkgs).map(([name, p]) => [name, { prefix: p.prefix, exports: p.exports }]));
+  return createHandler({ files, packages, proxy, spa, onError, transform: { '.ts': stripTypes } });
+}
+
+/** The host name in a Host header: "[::1]:5173" -> "::1", "Localhost:80" -> "localhost". */
+export function hostName(header) {
+  const h = header.trim().toLowerCase();
+  if (h.startsWith('[')) return h.slice(1, h.indexOf(']') > 0 ? h.indexOf(']') : undefined);
+  return h.replace(/:\d+$/, '');
+}
+
+/**
+ * Adapt a Fetch-API handler to node:http.
+ * @param {(request: Request) => Promise<Response>} handler
+ * @param {{ port?: number, host?: string, allowedHosts?: string[] }} [options]
+ *   `allowedHosts`: Host header names accepted besides localhost, 127.0.0.1 and [::1] (blocks DNS-rebinding pages).
+ */
+export function serve(handler, { port = 5173, host = '127.0.0.1', allowedHosts = [] } = {}) {
+  const allowed = new Set(['localhost', '127.0.0.1', '::1', host, ...allowedHosts].map((h) => h.toLowerCase()));
+  const server = createServer(async (req, res) => {
+    try {
+      const name = hostName(String(req.headers.host ?? ''));
+      if (!allowed.has(name)) {
+        res.writeHead(403, { 'content-type': 'text/plain' });
+        return res.end(`xoong server: host "${name}" is not allowed (add it to allowedHosts if this is intended)`);
+      }
+      const origin = `http://${req.headers.host ?? `${host}:${port}`}`;
+      const hasBody = req.method !== 'GET' && req.method !== 'HEAD';
+      const request = new Request(new URL(req.url ?? '/', origin), {
+        method: req.method,
+        headers: /** @type {any} */ (req.headers),
+        body: hasBody ? /** @type {any} */ (Readable.toWeb(req)) : undefined,
+        ...(hasBody ? { duplex: 'half' } : {}),
+      });
+      const response = await handler(request);
+      const out = {};
+      for (const [k, v] of response.headers) if (k !== 'set-cookie') out[k] = v;
+      const cookies = response.headers.getSetCookie();
+      if (cookies.length) out['set-cookie'] = cookies; // several cookies must stay separate headers
+      res.writeHead(response.status, out);
+      if (!response.body) return res.end();
+      const stream = Readable.fromWeb(/** @type {any} */ (response.body));
+      stream.on('error', () => res.destroy());
+      res.on('close', () => stream.destroy()); // a closed SSE connection must stop the upstream read
+      stream.pipe(res);
+    } catch (error) {
+      if (!res.headersSent) res.writeHead(500, { 'content-type': 'text/plain' });
+      res.end('xoong server: internal error');
+      console.error(error);
+    }
+  });
+  return new Promise((resolveListen, reject) => {
+    server.once('error', reject);
+    server.listen(port, host, () => {
+      const address = /** @type {import('node:net').AddressInfo} */ (server.address());
+      resolveListen({ server, port: address.port, url: `http://${host}:${address.port}`, close: () => new Promise((r) => { server.closeAllConnections?.(); server.close(() => r(undefined)); }) });
+    });
+  });
+}