@tdio/static-serve 0.0.4

package/README.md

@@ -0,0 +1,248 @@
+# static-serve
+
+A simple, lightweight static file server written in Go, designed with features for modern web application serving.
+
+## Features
+
+- **Static File Serving**: Serves files from a specified root directory.
+- **Dotfile Hiding**: Automatically hides files and directories starting with a dot (`.`) for security.
+- **SPA Mode**: Supports Single Page Application (SPA) routing by redirecting 404s to `index.html` (enabled via `--spa`).
+- **Virtual Mounts**: Mount files or directories to specific paths using `--mount`.
+- **Reverse Proxy (Fallback)**: Proxy specific paths to upstream URLs using `--proxy`. Local files take priority; proxy only triggers when a file is not found locally.
+- **HTTPS Mode**: Serve over TLS with `--tls-cert` and `--tls-key`.
+- **CORS Controls**: Opt-in CORS middleware with origin, credentials, and max-age tuning.
+- **Health Check**: Built-in health check endpoint at `/healthz`.
+- **Request Tracing**: Adds `X-Request-Id` headers to requests for tracing.
+- **Response Caching Hints**: Default `Cache-Control` plus weak ETag generation and 304 handling.
+- **Custom Logging**: Configurable request logging format.
+- **Graceful Shutdown**: Handles OS interrupts for graceful server shutdown.
+
+## Architecture
+
+The server processes requests through a middleware pipeline, with the proxy acting as a **fallback** when local files are not found:
+
+```mermaid
+flowchart TB
+    subgraph client [Client]
+        REQ[HTTP Request]
+    end
+
+    subgraph middleware [Middleware Pipeline]
+        TRACE[Tracing]
+        LOG[Logging]
+        CORS[CORS]
+        CACHE[Caching]
+    end
+
+    subgraph handler [Request Handler]
+        ROUTER[Router]
+        FS[File Server]
+        FALLBACK{File Found?}
+        PROXY[Proxy to Upstream]
+    end
+
+    subgraph response [Response]
+        LOCAL[Local File]
+        UPSTREAM[Upstream Response]
+        ERR404[404 Not Found]
+    end
+
+    REQ --> TRACE --> LOG --> CORS --> CACHE --> ROUTER
+    ROUTER --> FS
+    FS --> FALLBACK
+    FALLBACK -->|Yes| LOCAL
+    FALLBACK -->|No & Proxy Match| PROXY --> UPSTREAM
+    FALLBACK -->|No & No Proxy| ERR404
+```
+
+### Request Flow
+
+1. **Tracing**: Assigns a unique `X-Request-Id` to each request
+2. **Logging**: Logs request details in configurable format
+3. **CORS**: Handles preflight requests and sets CORS headers
+4. **Caching**: Adds `Cache-Control` headers and handles `ETag`/`304` responses
+5. **Router**: Routes to mounted paths, health checks, or default file server
+6. **File Server**: Attempts to serve the file from local filesystem
+7. **Fallback Proxy**: If file not found (404) and a proxy rule matches, forwards to upstream
+
+## Installation
+
+You can install `static-serve` globally using npm:
+
+```sh
+npm install -g @tdio/static-serve
+```
+
+Or run it directly using `npx`:
+
+```sh
+npx @tdio/static-serve [OPTIONS] [ROOT_DIR]
+```
+
+## Usage
+
+```sh
+static-serve [OPTIONS] [ROOT_DIR]
+```
+
+If `ROOT_DIR` is not specified, it defaults to the current directory (`./`).
+
+### Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--address` | The TCP address to listen on. | `:3000` |
+| `--mount` | Mount specific directory to a virtual path (can be repeated). Format: `<physical_path>:<virtual_path>` or `src=<physical_path>,dst=<virtual_path>`  | `""` |
+| `--proxy` | Proxy specific upstream to a virtual path (can be repeated). | `""` |
+| `--spa` | Enable SPA mode (redirects missing files to `/index.html`). | `false` |
+| `--logger-format` | Custom server logger format (Go template syntax). | `{{.Method}} {{.URL.Path}} {{.Status}} {{.RemoteAddr}} {{.UserAgent}}` |
+| `--tls-cert` | Path to TLS certificate file. Enables HTTPS (requires `--tls-key`). | `""` |
+| `--tls-key` | Path to TLS private key file. Enables HTTPS (requires `--tls-cert`). | `""` |
+| `--cors` | Enable CORS middleware for all routes. | `false` |
+| `--cors-allow-origins` | Comma-separated allowed origins (`*` allowed). | `*` |
+| `--cors-allow-credentials` | Whether to include `Access-Control-Allow-Credentials`. | `false` |
+| `--cors-max-age` | Preflight cache max-age (Go duration). | `24h0m0s` |
+| `-v` | Print version and exit. | `false` |
+
+### Mount Configuration
+
+`static-serve` allows you to mount files or directories to virtual paths. This is useful for serving assets from multiple locations or exposing individual files at specific URLs.
+
+* Simple Format: `--mount <physical_path>:<virtual_path>`
+* Advanced Format (Key-Value): `--mount src=<physical_path>,dst=<virtual_path>`
+
+Parameters:
+- `src` (or `source`): The physical directory or file on your machine.
+- `dst` (or `path`): The virtual path on the server where the source will be accessible.
+
+Examples:
+
+```sh 
+# Mount a directory (these two forms are functionally identical)
+static-serve --mount /mnt/test/static:/static
+static-serve --mount src=/mnt/test/static,dst=/static
+
+# Mount a single file
+static-serve --mount ./config.json:/api/config
+static-serve --mount src=./config.json,dst=/api/config
+```
+
+### Proxy Configuration
+
+`static-serve` supports proxying requests to upstream servers using a **fallback pattern**:
+
+```
+Local File Found?  ──Yes──►  Serve Local File
+        │
+        No
+        │
+        ▼
+Proxy Rule Matches?  ──Yes──►  Forward to Upstream
+        │
+        No
+        │
+        ▼
+    Return 404
+```
+
+This is useful for:
+- **Development**: Serve local static assets while proxying API calls to a backend server
+- **Caching/CDN pattern**: Serve cached files locally, fetch from origin on cache miss
+- **Hybrid deployments**: Override specific upstream resources with local versions
+
+#### Simple Format
+
+`<url_path>:<upstream_url>`
+
+Example: `/api:http://localhost:8080`
+
+_Note: This format automatically enables `change_origin` and `strip_prefix`._
+
+#### Advanced Format (Key-Value)
+
+`path=<url_path>,url=<upstream_url>[,change_origin=bool][,strip_prefix=bool][,methods=GET|POST|...]`
+
+Parameters:
+- `path`: The virtual path on the current server to match.
+- `url`: The upstream URL to forward requests to.
+- `change_origin`: Whether to rewrite the `Host` header to match the upstream URL. **Default: `true`**.
+- `strip_prefix`: Whether to strip the matched path prefix before forwarding the request. **Default: `true`**.
+- `method(s)`: pipe-separated list of HTTP methods to proxy. If specified, only these methods will be proxied. Others will pass through to local file serving or return 405. **Default: all methods**.
+
+### Examples
+
+**Serve current directory on port 8080:**
+```sh
+static-serve --address :8080
+```
+
+**Serve specific directory with SPA mode enabled:**
+```sh
+static-serve --spa ./dist
+```
+
+**Mount files or directories:**
+```sh
+# Mount directories
+static-serve --mount "/var/www/static:/static" --mount "/mnt/media/images:/images" ./public
+
+# Mount a single file
+static-serve --mount "./config.json:/api/config"
+
+# Using advanced KV format
+static-serve --mount "src=/var/www/static,dst=/static"
+static-serve --mount "src=./config.json,dst=/api/config"
+```
+
+**Proxy API requests (fallback behavior):**
+
+1. **Basic Proxy**: Forward `/api` to `http://localhost:8080` when files don't exist locally.
+   ```sh
+   static-serve --proxy "/api:http://localhost:8080"
+   ```
+   - If `./api/users.json` exists locally → serves the local file
+   - If `./api/users.json` doesn't exist → forwards to `http://localhost:8080/users`
+
+2. **Advanced Config**: Forward `/api` but keep the `/api` prefix in the upstream request.
+   ```sh
+   static-serve --proxy "path=/api,url=http://localhost:8080,strip_prefix=false"
+   ```
+   Requests to `http://localhost:3000/api/users` will be forwarded to `http://localhost:8080/api/users` (if no local file exists).
+
+3. **Method Filtering**: Only proxy POST and PUT requests to the upstream server.
+   ```sh
+   static-serve --proxy "path=/api,url=http://localhost:8080,methods=POST|PUT"
+   ```
+   - `GET /api/users` → serves local `./api/users` or 404
+   - `POST /api/users` → proxies to `http://localhost:8080/users` (if no local file exists)
+
+4. **Local Override Pattern**: Override specific upstream assets with local versions.
+   ```sh
+   # Create local override
+   mkdir -p ./assets
+   echo "local override" > ./assets/config.json
+
+   # Start server with proxy fallback
+   static-serve --proxy "/assets:http://cdn.example.com/assets" ./
+   ```
+   - `GET /assets/config.json` → serves local `./assets/config.json`
+   - `GET /assets/other.js` → proxies to `http://cdn.example.com/assets/other.js`
+
+**Serve over HTTPS:**
+```sh
+static-serve --tls-cert ./cert.pem --tls-key ./key.pem ./public
+```
+
+**Enable CORS for specific origins:**
+```sh
+static-serve --cors --cors-allow-origins "https://app.example.com,https://admin.example.com" --cors-allow-credentials
+```
+
+## Health Check
+
+The server exposes a health check endpoint at `/healthz`.
+
+```sh
+curl http://localhost:3000/healthz
+# Returns 204 No Content if healthy
+```

package/bin/cli.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+
+const { spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const PACKAGE_PREFIX = 'static-serve'; // Must match build-npm.js
+const PACKAGE_SCOPE = '@tdio'; // Must match build-npm.js
+
+// Map generic 'x64' to Node's arch if needed, but usually they match.
+// Node: x64, arm64, ia32, etc.
+const platform = process.platform;
+const arch = process.arch;
+
+const targetPackage = `${PACKAGE_SCOPE}/${PACKAGE_PREFIX}-${platform}-${arch}`
+
+let binaryPath;
+
+try {
+  // Resolve the package.json of the platform-specific package
+  // This throws if the package is not installed
+  const pkgJsonPath = require.resolve(`${targetPackage}/package.json`);
+  const pkgDir = path.dirname(pkgJsonPath);
+
+  // Binary name is predictable: static-serve on Unix, static-serve.exe on Windows
+  const binFile = platform === 'win32' ? `${PACKAGE_PREFIX}.exe` : PACKAGE_PREFIX;
+  binaryPath = path.join(pkgDir, binFile);
+
+} catch (err) {
+  // Fallback: Check if we are running from the source repo/local build
+  // Useful for development
+  const localBuildPath = path.join(__dirname, '..', 'out', `${PACKAGE_PREFIX}-${platform === 'win32' ? 'windows' : platform}-${arch === 'x64' ? 'amd64' : arch}${platform === 'win32' ? '.exe' : ''}`);
+
+  if (fs.existsSync(localBuildPath)) {
+    binaryPath = localBuildPath;
+  } else {
+    console.error(`Failed to locate binary for ${platform}-${arch}.`);
+    console.error(`Tried package: ${targetPackage}`);
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+const child = spawn(binaryPath, process.argv.slice(2), {
+  stdio: 'inherit'
+});
+
+child.on('exit', (code) => {
+  process.exit(code);
+});
+

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@tdio/static-serve",
+  "version": "0.0.4",
+  "description": "A simple, lightweight static file server written in Go, designed with features for modern web application serving",
+  "bin": {
+    "static-serve": "./bin/cli.js"
+  },
+  "author": "allex <allex.wxn@gmail.com> (http://iallex.com/)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/allex/static-serve"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "files": [
+    "bin/cli.js"
+  ],
+  "license": "MIT",
+  "optionalDependencies": {
+    "@tdio/static-serve-darwin-x64": "0.0.4",
+    "@tdio/static-serve-darwin-arm64": "0.0.4",
+    "@tdio/static-serve-linux-x64": "0.0.4",
+    "@tdio/static-serve-linux-arm64": "0.0.4",
+    "@tdio/static-serve-win32-x64": "0.0.4",
+    "@tdio/static-serve-win32-arm64": "0.0.4"
+  }
+}