oblien 2.2.37 → 2.2.39

package/docs/serve.md

@@ -0,0 +1,84 @@
+# Static server
+
+Serve a folder over HTTP and put it on the public internet in one step. The
+server is built entirely on Node's `http`/`fs` — **no extra dependencies** — and
+the CLI wires it straight into the [edge tunnel](./edge-tunnel.md), so a
+directory becomes a public HTTPS URL with a single command.
+
+## CLI
+
+```bash
+oblien serve                       # serve ./public
+oblien serve ./dist                # serve ./dist
+oblien serve ./dist --slug my-app  # pick the public subdomain
+oblien serve ./build --spa         # single-page-app fallback
+oblien serve ./site --domain preview.example.com
+```
+
+`oblien serve` starts a static server on a loopback port and then forwards it
+through the edge exactly like `oblien tunnel <port>` — so every tunnel flag
+works here too:
+
+| Flag | Description |
+| --- | --- |
+| `--port <n>` | Local port to serve on (default: an OS-assigned free port) |
+| `--slug <slug>` | Custom subdomain slug for the public URL |
+| `--name <name>` | Tunnel display name (default: the folder name) |
+| `--domain <domain>` | Base domain or exact custom hostname (see [edge-tunnel](./edge-tunnel.md)) |
+| `--expires-in <ttl>` | Tunnel token TTL, e.g. `30s`, `5m`, `1h`, `7d` |
+| `--spa` | Serve `index.html` for any unmatched path (client-side routing) |
+| `--no-listing` | Disable auto-generated directory listings |
+| `--index <file>` | Directory index filename (default: `index.html`) |
+
+Press `Ctrl+C` to stop — the tunnel disconnects and the local server shuts down.
+
+## What the server handles
+
+- **Correct MIME types** for common web, font, image, media, and document extensions.
+- **Streamed responses** (`createReadStream`) — large files never buffer in memory.
+- **`Range` requests** — media seeking / resumable downloads return `206 Partial Content`.
+- **Revalidation** — `ETag` + `Last-Modified` yield `304 Not Modified` on conditional requests.
+- **Directory handling** — serves `index.html`, redirects `/dir` → `/dir/`, and renders a clean listing when there's no index (unless `--no-listing`).
+- **SPA fallback** (`--spa`) — unmatched paths return the root `index.html`.
+- **Path-traversal protection** — requests are resolved against the root; anything escaping it lexically is rejected (`403`), and a file whose canonical path (following symlinks) leaves the root is rejected (`404`).
+- **Dotfiles denied by default** — `.git/`, `.env`, and other dot-paths return `404` (the server is often public), except `.well-known/`. Opt in with `allowDotfiles`.
+
+## Programmatic use
+
+The same server is exported from the SDK, so you can start it yourself and pair
+it with the [`TunnelClient`](./edge-tunnel.md) or use it standalone:
+
+```typescript
+import { startStaticServer } from 'oblien';
+
+const site = await startStaticServer({
+  root: './public',
+  spa: true,           // optional: index.html fallback
+  // port: 8080,       // optional: default is an OS-assigned free port
+  // host: '127.0.0.1' // optional: default loopback only
+});
+
+console.log(`serving on ${site.url}`); // http://127.0.0.1:<port>
+
+// ...later
+await site.close();
+```
+
+`startStaticServer(options)` resolves once the server is listening and returns a
+handle: `{ port, host, url, server, close() }`. The `port` is always resolved —
+even when you omit it and let the OS choose. For finer control, `createStaticServer(options)`
+returns a non-listening `http.Server`, and `createStaticHandler(options)` returns a
+raw `(req, res)` handler you can mount on your own server.
+
+### Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `root` | `string` | — | Directory to serve (resolved against cwd) |
+| `host` | `string` | `127.0.0.1` | Interface to bind |
+| `port` | `number` | `0` (auto) | Port to listen on |
+| `index` | `string` | `index.html` | Directory index filename |
+| `listing` | `boolean` | `true` | Render a listing when a directory has no index |
+| `spa` | `boolean` | `false` | Serve the root index for unmatched paths |
+| `allowDotfiles` | `boolean` | `false` | Serve dotfiles/dot-directories (`.well-known/` is always allowed) |
+| `onRequest` | `(info) => void` | — | Per-request hook: `{ method, path, status }` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oblien",
-  "version": "2.2.37",
+  "version": "2.2.39",
   "description": "Official TypeScript SDK for the Oblien Workspace API",
   "type": "module",
   "main": "./dist/index.js",