asljs-server 0.2.0 → 0.2.2

package/README.md

@@ -26,10 +26,19 @@ Or without installing:
   - `asljs-server --port 8080`
   - `asljs-server --host 0.0.0.0 --port 8080`
 
-## JSON API
+- Map a folder under a virtual path:
+  - `asljs-server --map assets=../Assets`
+  - Serves `../Assets/logo.png` as `/assets/logo.png`
 
-- `GET /api/json?file=name[.json]` returns the JSON file
-- `PUT|POST /api/json?file=name[.json]` writes JSON (pretty-printed)
+## File API
+
+- `GET /api/file?path=path` returns the file contents
+- `PUT|POST /api/file?path=path` writes the file
+- `GET /api/files?path=path` lists all files in the directory
+
+Folder mappings apply to the File API too. For example, with `--map assets=../Assets`:
+
+- `GET /api/file?path=assets/logo.png`
 
 ## Live reload
 

package/cli.js

@@ -1,3 +1,3 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 import './dist/cli.js';

package/dist/cli.js

@@ -6,10 +6,12 @@ function printHelp() {
     process.stdout.write(`asljs-server
 
 Usage:
-  asljs-server [--root <dir>] [--port <number>] [--host <name>]
+  asljs-server [--root <dir>] [--port <number>] [--host <name>] [--map <virtual>=<dir>]
 
 Options:
   --root <dir>     Root directory to serve (default: .)
+  --map <spec>     Map a folder under a virtual path (repeatable)
+                   Spec: <virtual>=<dir> (example: assets=../Assets)
   --port <number>  Port to listen on (default: 3000)
   --host <name>    Host/interface to bind (default: localhost)
   --help           Show this help
@@ -26,7 +28,25 @@ function readVersion() {
 function parseArgs(argv) {
     const options = { root: '.',
         port: 3000,
-        host: 'localhost' };
+        host: 'localhost',
+        mounts: {} };
+    const addMount = (spec) => {
+        // Use '=' to avoid Windows drive-letter ambiguity.
+        const separatorIndex = spec.indexOf('=');
+        if (separatorIndex <= 0
+            || separatorIndex >= spec.length - 1) {
+            throw new TypeError('Invalid --map spec. Use <virtual>=<dir>');
+        }
+        const virtual = spec.slice(0, separatorIndex);
+        const dir = spec.slice(separatorIndex + 1);
+        if (!/^[a-zA-Z0-9._/-]+$/.test(virtual)
+            || virtual.startsWith('/')
+            || virtual.includes('\\')
+            || virtual.split('/').some(p => !p || p === '.' || p === '..')) {
+            throw new TypeError('Invalid virtual path in --map spec');
+        }
+        options.mounts[virtual] = dir;
+    };
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         if (arg === '--help'
@@ -66,6 +86,16 @@ function parseArgs(argv) {
             options.host = value;
             continue;
         }
+        if (arg === '--map'
+            || arg === '--mount'
+            || arg === '-m') {
+            const value = argv[++i];
+            if (!value) {
+                throw new TypeError('Missing value for --map');
+            }
+            addMount(value);
+            continue;
+        }
         if (arg.startsWith('-')) {
             throw new TypeError(`Unknown option: ${arg}`);
         }

package/dist/send.d.ts

@@ -1,13 +1,65 @@
+/**
+ * Functions for sending HTTP responses.
+ *
+ * Exported helpers:
+ *
+ * - `options(ServerResponse, OutgoingHttpHeaders): void`
+ * - `api(ServerResponse, unknown): void`
+ * - `apiError(ServerResponse, unknown): void`
+ * - `json(ServerResponse, number, unknown): void`
+ * - `html(ServerResponse, string): void`
+ * - `badRequest(ServerResponse, string?): void`
+ * - `forbidden(ServerResponse, string?): void`
+ * - `notFound(ServerResponse, string?): void`
+ * - `methodNotAllowed(ServerResponse, string?): void`
+ * - `error(ServerResponse, unknown): void`
+ * - `file(ServerResponse, string): Promise<void>`
+ */
 import type { OutgoingHttpHeaders } from 'node:http';
 import type { ServerResponse } from 'node:http';
+/**
+ * Sends an empty response to the client for an OPTIONS request.
+ * Typically used for CORS preflight requests.
+ */
 export declare function options(response: ServerResponse, headers: OutgoingHttpHeaders): void;
+/**
+ * Sends a JSON API response with status 200.
+ */
 export declare function api(response: ServerResponse, payload: unknown): void;
+/**
+ * Sends an API error message to the response with status 500.
+ */
 export declare function apiError(response: ServerResponse, error: unknown): void;
+/**
+ * Sends a JSON string to the response with the specified status.
+ */
 export declare function json(response: ServerResponse, status: number, jsonString: unknown): void;
+/**
+ * Sends an HTML string to the response with status 200.
+ */
 export declare function html(response: ServerResponse, htmlString: string): void;
+/**
+ * Sends a "Bad request" error message to the response with status 400.
+ */
 export declare function badRequest(response: ServerResponse, message?: string): void;
+/**
+ * Sends a "Forbidden" error message to the response with status 403.
+ */
 export declare function forbidden(response: ServerResponse, message?: string): void;
+/**
+ * Sends a "Not found" error message to the response with status 404.
+ */
 export declare function notFound(response: ServerResponse, message?: string): void;
+/**
+ * Sends a "Method not allowed" error message to the response with status 405.
+ */
 export declare function methodNotAllowed(response: ServerResponse, allowed?: string): void;
+/**
+ * Sends an error message to the response with status 500.
+ */
 export declare function error(response: ServerResponse, err: unknown): void;
+/**
+ * Sends a static file, specified by `filePath`, to the response,
+ * asynchronously.
+ */
 export declare function file(response: ServerResponse, filePath: string): Promise<void>;

package/dist/send.js

@@ -1,6 +1,25 @@
+/**
+ * Functions for sending HTTP responses.
+ *
+ * Exported helpers:
+ *
+ * - `options(ServerResponse, OutgoingHttpHeaders): void`
+ * - `api(ServerResponse, unknown): void`
+ * - `apiError(ServerResponse, unknown): void`
+ * - `json(ServerResponse, number, unknown): void`
+ * - `html(ServerResponse, string): void`
+ * - `badRequest(ServerResponse, string?): void`
+ * - `forbidden(ServerResponse, string?): void`
+ * - `notFound(ServerResponse, string?): void`
+ * - `methodNotAllowed(ServerResponse, string?): void`
+ * - `error(ServerResponse, unknown): void`
+ * - `file(ServerResponse, string): Promise<void>`
+ */
 import fs from 'node:fs';
 import fsp from 'node:fs/promises';
 import path from 'node:path';
+// Map of file extensions to content types.
+// Used by `file()` to set the Content-Type header.
 const CONTENT_TYPES = new Map([['.html', 'text/html; charset=utf-8'],
     ['.htm', 'text/html; charset=utf-8'],
     ['.js', 'text/javascript; charset=utf-8'],
@@ -23,14 +42,24 @@ function contentTypeFor(filePath) {
     return CONTENT_TYPES.get(ext)
         || 'application/octet-stream';
 }
+/**
+ * Sends an empty response to the client for an OPTIONS request.
+ * Typically used for CORS preflight requests.
+ */
 export function options(response, headers) {
     response.writeHead(204, headers);
     response.end();
 }
+/**
+ * Sends a JSON API response with status 200.
+ */
 export function api(response, payload) {
     response.writeHead(200, { 'content-type': 'application/json; charset=utf-8' });
     response.end(JSON.stringify(payload));
 }
+/**
+ * Sends an API error message to the response with status 500.
+ */
 export function apiError(response, error) {
     response.writeHead(500, { 'content-type': 'application/json; charset=utf-8' });
     const message = (error && typeof error === 'object' && 'message' in error)
@@ -38,33 +67,54 @@ export function apiError(response, error) {
         : String(error);
     response.end(JSON.stringify({ error: message }));
 }
+/**
+ * Sends a JSON string to the response with the specified status.
+ */
 export function json(response, status, jsonString) {
     response.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
     response.end(typeof jsonString === 'string'
         ? jsonString
         : JSON.stringify(jsonString));
 }
+/**
+ * Sends an HTML string to the response with status 200.
+ */
 export function html(response, htmlString) {
     response.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
     response.end(htmlString);
 }
+/**
+ * Sends a "Bad request" error message to the response with status 400.
+ */
 export function badRequest(response, message = 'Bad request') {
     response.writeHead(400, { 'content-type': 'text/plain; charset=utf-8' });
     response.end(message);
 }
+/**
+ * Sends a "Forbidden" error message to the response with status 403.
+ */
 export function forbidden(response, message = 'Forbidden') {
     response.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' });
     response.end(message);
 }
+/**
+ * Sends a "Not found" error message to the response with status 404.
+ */
 export function notFound(response, message = 'Not found') {
     response.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
     response.end(message);
 }
+/**
+ * Sends a "Method not allowed" error message to the response with status 405.
+ */
 export function methodNotAllowed(response, allowed = 'GET') {
     response.writeHead(405, { 'content-type': 'text/plain; charset=utf-8',
         'allow': allowed });
     response.end('Method not allowed');
 }
+/**
+ * Sends an error message to the response with status 500.
+ */
 export function error(response, err) {
     response.writeHead(500, { 'content-type': 'text/plain; charset=utf-8' });
     const message = (err && typeof err === 'object' && 'stack' in err)
@@ -74,6 +124,10 @@ export function error(response, err) {
             : String(err);
     response.end(message);
 }
+/**
+ * Sends a static file, specified by `filePath`, to the response,
+ * asynchronously.
+ */
 export async function file(response, filePath) {
     try {
         const stat = await fsp.stat(filePath);

package/dist/server.d.ts

@@ -8,5 +8,6 @@ export type StartServerOptions = {
     port?: number;
     host?: string;
     logger?: ServerLogger;
+    mounts?: Record<string, string>;
 };
-export declare function startServer({ root, port, host, logger }?: StartServerOptions): Server;
+export declare function startServer({ root, port, host, logger, mounts }?: StartServerOptions): Server;

package/dist/server.js

@@ -4,22 +4,10 @@ import path from 'node:path';
 import { URL, pathToFileURL } from 'node:url';
 import * as send from './send.js';
 import { watchStaticTree } from './watch.js';
-function isPathInside(child, parent) {
-    const resolved = path.resolve(child);
-    return resolved === parent
-        || resolved.startsWith(parent + path.sep);
-}
-// inject minimal client into served HTML
-const RELOAD_SNIPPET = `<script>
-try {
-  const es = new EventSource('/__events');
-  es.addEventListener('reload', () => location.reload());
-} catch (_) {}
-</script>`;
-const safeJsonName = (name) => typeof name === 'string'
-    && /^[a-zA-Z0-9._/-]+$/.test(name)
-    ? name
-    : null;
+import { VirtualFolders } from './virtual-folders.js';
+/**
+ * Reads the body of the given request up to the given size limit.
+ */
 function readBody(request, limit) {
     return new Promise((resolve, reject) => {
         let size = 0;
@@ -41,11 +29,21 @@ function readBody(request, limit) {
         request.on('error', reject);
     });
 }
+// inject minimal client into served HTML
+const RELOAD_SNIPPET = `
+  <script>
+  try {
+    const es = new EventSource('/__events');
+    es.addEventListener('reload', () => location.reload());
+  } catch (_) {}
+  </script>
+`;
 const options = { 'access-control-allow-origin': '*',
     'access-control-allow-methods': 'GET,POST,PUT,OPTIONS',
     'access-control-allow-headers': 'content-type' };
-export function startServer({ root = '.', port = 3000, host = 'localhost', logger = console } = {}) {
+export function startServer({ root = '.', port = 3000, host = 'localhost', logger = console, mounts = {} } = {}) {
     const FILES_DIR = path.resolve(root);
+    const virtualFolders = new VirtualFolders(FILES_DIR, mounts);
     // ---------- hot reload (SSE)
     const sseClients = new Set();
     const sseHeaders = { 'content-type': 'text/event-stream',
@@ -75,51 +73,53 @@ export function startServer({ root = '.', port = 3000, host = 'localhost', logge
             }
         }, 50);
     };
-    watchStaticTree(FILES_DIR, () => broadcastReload());
-    // ---------- JSON API helpers
-    const jsonFilePath = (name) => {
-        const base = safeJsonName(name);
-        if (!base)
-            return null;
-        const file = base.endsWith('.json')
-            ? base
-            : (base + '.json');
-        const full = path.join(FILES_DIR, file);
-        return isPathInside(full, FILES_DIR)
-            ? full
-            : null;
+    const stopWatchers = [];
+    for (const watchRoot of virtualFolders.getWatchRoots()) {
+        try {
+            stopWatchers.push(watchStaticTree(watchRoot, () => broadcastReload()));
+        }
+        catch {
+            // ignore
+        }
+    }
+    // ---------- File API helpers
+    const fileApiPath = (relativePath) => {
+        return virtualFolders.toPhysicalPath(relativePath);
     };
-    async function handleJsonApi(request, response, url) {
+    async function handleFileApi(request, response, url) {
         await fsp.mkdir(FILES_DIR, { recursive: true });
-        const name = url.searchParams.get('file');
-        const file = jsonFilePath(name);
-        if (!file) {
-            return send.badRequest(response, 'Invalid "file" name. Allowed: [a-zA-Z0-9._-] and optional .json');
+        const relativePath = VirtualFolders.safeRelativePath(url.searchParams.get('path'));
+        if (!relativePath) {
+            return send.badRequest(response, 'Invalid "path". Use a relative path with URL-style separators.');
+        }
+        const filePath = fileApiPath(relativePath);
+        if (!filePath) {
+            return send.forbidden(response);
         }
         if (request.method === 'GET') {
-            try {
-                return send.json(response, 200, await fsp.readFile(file, 'utf8'));
-            }
-            catch (e) {
-                if (e && typeof e === 'object' && 'code' in e && e.code === 'ENOENT')
-                    return send.notFound(response, 'JSON file not found');
-                throw e;
-            }
+            return send.file(response, filePath);
         }
         if (request.method === 'PUT'
             || request.method === 'POST') {
             try {
                 // 1MB limit
                 const body = await readBody(request, 1000000);
-                let parsed;
-                try {
-                    parsed = JSON.parse(body);
+                await fsp.mkdir(path.dirname(filePath), { recursive: true });
+                // Preserve the old behavior for JSON files.
+                if (path.extname(filePath).toLowerCase() === '.json') {
+                    let parsed;
+                    try {
+                        parsed = JSON.parse(body);
+                    }
+                    catch {
+                        return send.badRequest(response, 'Invalid JSON');
+                    }
+                    await fsp.writeFile(filePath, JSON.stringify(parsed, null, 2) + '\n', 'utf8');
                 }
-                catch {
-                    return send.badRequest(response, 'Invalid JSON');
+                else {
+                    await fsp.writeFile(filePath, body, 'utf8');
                 }
-                await fsp.writeFile(file, JSON.stringify(parsed, null, 2) + '\n', 'utf8');
-                return send.api(response, { file: path.basename(file) });
+                return send.api(response, { path: relativePath });
             }
             catch (error) {
                 return send.apiError(response, error);
@@ -127,19 +127,73 @@ export function startServer({ root = '.', port = 3000, host = 'localhost', logge
         }
         return send.methodNotAllowed(response, 'GET, PUT, POST');
     }
+    async function handleFilesApi(request, response, url) {
+        if (request.method !== 'GET') {
+            return send.methodNotAllowed(response, 'GET');
+        }
+        await fsp.mkdir(FILES_DIR, { recursive: true });
+        const relativePath = VirtualFolders.safeRelativePath(url.searchParams.get('path'), { allowEmpty: true });
+        if (relativePath === null) {
+            return send.badRequest(response, 'Invalid "path". Use a relative directory path.');
+        }
+        const directoryPath = fileApiPath(relativePath);
+        if (!directoryPath) {
+            return send.forbidden(response);
+        }
+        try {
+            const stat = await fsp.stat(directoryPath);
+            if (!stat.isDirectory()) {
+                return send.badRequest(response, '"path" must point to a directory');
+            }
+        }
+        catch (error) {
+            if (error
+                && typeof error === 'object'
+                && 'code' in error
+                && error.code === 'ENOENT') {
+                return send.notFound(response, 'Directory not found');
+            }
+            return send.error(response, error);
+        }
+        try {
+            const entries = await fsp.readdir(directoryPath, { withFileTypes: true });
+            const files = entries
+                .filter(e => e.isFile())
+                .map(e => e.name)
+                .sort((a, b) => a.localeCompare(b));
+            return send.api(response, { path: relativePath,
+                files });
+        }
+        catch (error) {
+            return send.apiError(response, error);
+        }
+    }
     async function serveStatic(request, response, url) {
         const pathname = decodeURIComponent(url.pathname);
         // SSE endpoint
         if (pathname === '/__events') {
             return serveSSE(request, response);
         }
-        // JSON API: /api/json?file=name[.json]
-        if (pathname === '/api/json') {
-            return handleJsonApi(request, response, url);
+        // File API: /api/file?path=relative/path.ext
+        if (pathname === '/api/file') {
+            return handleFileApi(request, response, url);
+        }
+        // Directory listing API: /api/files?path=relative/dir
+        if (pathname === '/api/files') {
+            return handleFilesApi(request, response, url);
+        }
+        const relativeUrlPath = pathname.startsWith('/')
+            ? pathname.slice(1)
+            : pathname;
+        const safeUrlPath = VirtualFolders.safeRelativePath(relativeUrlPath, { allowEmpty: true });
+        if (safeUrlPath === null) {
+            return send.forbidden(response);
         }
         // Resolve file path
-        let filePath = path.normalize(path.join(FILES_DIR, pathname));
-        if (!isPathInside(filePath, FILES_DIR)) {
+        let filePath = safeUrlPath === ''
+            ? FILES_DIR
+            : virtualFolders.toPhysicalPath(safeUrlPath);
+        if (!filePath) {
             return send.forbidden(response);
         }
         // If path is dir, try index.html
@@ -163,8 +217,8 @@ export function startServer({ root = '.', port = 3000, host = 'localhost', logge
                 const html = await fsp.readFile(filePath, 'utf8');
                 const htmlWithReload = html.includes('/__events')
                     ? html
-                    : html.replace(/<\/body\s*>/i, m => `${RELOAD_SNIPPET}\n${m}`) +
-                        (!html.match(/<\/body\s*>/i)
+                    : html.replace(/<\/body\s*>/i, m => `${RELOAD_SNIPPET}\n${m}`)
+                        + (!html.match(/<\/body\s*>/i)
                             ? `\n${RELOAD_SNIPPET}`
                             : '');
                 return send.html(response, htmlWithReload);
@@ -186,8 +240,19 @@ export function startServer({ root = '.', port = 3000, host = 'localhost', logge
             send.error(response, error);
         });
     });
+    server.on('close', () => {
+        for (const stop of stopWatchers) {
+            try {
+                stop();
+            }
+            catch { }
+        }
+    });
     server.listen(port, host, () => {
         logger.log(`FILES: ${FILES_DIR}`);
+        for (const mount of virtualFolders.mounts) {
+            logger.log(`MAP:   /${mount.virtual} -> ${mount.rootDir}`);
+        }
         logger.log(`URL:   http://${host}:${port}`);
     });
     return server;

package/dist/virtual-folders.d.ts

@@ -0,0 +1,19 @@
+export type VerifySafeRelativePathOptions = {
+    allowEmpty?: boolean;
+};
+export type VirtualFolderMount = {
+    virtual: string;
+    rootDir: string;
+};
+export declare class VirtualFolders {
+    readonly baseDir: string;
+    readonly mounts: ReadonlyArray<VirtualFolderMount>;
+    constructor(baseDir: string, mounts?: Record<string, string>);
+    static safeRelativePath(value: string | null | undefined, { allowEmpty }?: VerifySafeRelativePathOptions): string | null;
+    getWatchRoots(): ReadonlyArray<string>;
+    resolve(relativePath: string): {
+        rootDir: string;
+        relativePath: string;
+    };
+    toPhysicalPath(relativePath: string): string | null;
+}

package/dist/virtual-folders.js

@@ -0,0 +1,102 @@
+import path from 'node:path';
+function isPathInside(child, parent) {
+    const childPath = path.resolve(path.normalize(child));
+    const parentPath = path.resolve(path.normalize(parent));
+    return childPath === parentPath
+        || childPath.startsWith(parentPath + path.sep);
+}
+export class VirtualFolders {
+    constructor(baseDir, mounts = {}) {
+        if (!baseDir
+            || typeof baseDir !== 'string') {
+            throw new TypeError('VirtualFolders: baseDir must be a string');
+        }
+        this.baseDir =
+            path.resolve(path.normalize(baseDir));
+        this.mounts =
+            Object.entries(mounts)
+                .map(([virtual, dir]) => {
+                const safeVirtual = VirtualFolders.safeRelativePath(virtual);
+                if (!safeVirtual) {
+                    throw new TypeError('Invalid mount virtual path');
+                }
+                if (typeof dir !== 'string') {
+                    throw new TypeError('Invalid mount dir');
+                }
+                return {
+                    virtual: safeVirtual,
+                    rootDir: path.resolve(path.normalize(dir))
+                };
+            })
+                // Prefer longer (more specific) virtual paths.
+                .sort((a, b) => b.virtual.length
+                - a.virtual.length);
+    }
+    static safeRelativePath(value, { allowEmpty = false } = {}) {
+        if (value === null
+            || value === undefined) {
+            return allowEmpty
+                ? ''
+                : null;
+        }
+        if (typeof value !== 'string')
+            return null;
+        if (value === '') {
+            return allowEmpty
+                ? ''
+                : null;
+        }
+        if (!/^[a-zA-Z0-9._/-]+$/.test(value))
+            return null;
+        // Force URL-style separators.
+        if (value.includes('\\'))
+            return null;
+        if (value.startsWith('/'))
+            return null;
+        const segments = value.split('/');
+        for (const segment of segments) {
+            if (!segment
+                || segment === '.'
+                || segment === '..') {
+                return null;
+            }
+        }
+        return value;
+    }
+    getWatchRoots() {
+        const set = new Set();
+        set.add(this.baseDir);
+        for (const mount of this.mounts) {
+            set.add(mount.rootDir);
+        }
+        return Array.from(set);
+    }
+    resolve(relativePath) {
+        for (const mount of this.mounts) {
+            if (relativePath === mount.virtual) {
+                return {
+                    rootDir: mount.rootDir,
+                    relativePath: ''
+                };
+            }
+            const prefix = mount.virtual + '/';
+            if (relativePath.startsWith(prefix)) {
+                return {
+                    rootDir: mount.rootDir,
+                    relativePath: relativePath.slice(prefix.length)
+                };
+            }
+        }
+        return {
+            rootDir: this.baseDir,
+            relativePath
+        };
+    }
+    toPhysicalPath(relativePath) {
+        const resolved = this.resolve(relativePath);
+        const full = path.join(resolved.rootDir, resolved.relativePath);
+        return isPathInside(full, resolved.rootDir)
+            ? full
+            : null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "asljs-server",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "A lightweight development-time static files server. Supports live-reload. Provides filesystem read-write API.",
   "type": "module",
   "main": "server.js",