orator-static-server 1.0.1 → 2.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Steven Velozo
+Copyright (c) 2024 Steven Velozo
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,5 +1,104 @@
-# Orator Static File Server
+# Orator Static Server
 
-Very basic static file server for local development and lightweight tasks.
+> Static file serving for Orator API servers
 
-Leverages restify static server.
+Orator Static Server provides static file serving capabilities for Orator. The core static file serving functionality is built directly into the main [orator](https://github.com/stevenvelozo/orator) module via the `addStaticRoute` method, which serves files from disk with MIME type detection and subdomain-based folder routing.
+
+## Features
+
+- **File Serving** - Serve static files from any directory on disk
+- **MIME Detection** - Automatic Content-Type headers based on file extension
+- **Default Files** - Configurable default file (e.g., `index.html`) for directory requests
+- **Route Stripping** - Strip URL prefixes before mapping to the filesystem
+- **Subdomain Routing** - Serve different folders based on request subdomain
+
+## Usage
+
+Static file serving is available through the main Orator module's `addStaticRoute` method:
+
+```javascript
+const libFable = require('fable');
+const libOrator = require('orator');
+const libOratorServiceServerRestify = require('orator-serviceserver-restify');
+
+const _Fable = new libFable({
+	Product: 'MyStaticServer',
+	ServicePort: 8080
+});
+
+_Fable.serviceManager.addServiceType('Orator', libOrator);
+_Fable.serviceManager.addServiceType('OratorServiceServer', libOratorServiceServerRestify);
+_Fable.serviceManager.instantiateServiceProvider('Orator');
+_Fable.serviceManager.instantiateServiceProvider('OratorServiceServer');
+
+// Serve static files from ./public
+_Fable.Orator.addStaticRoute('./public/');
+
+_Fable.Orator.startService();
+```
+
+## API
+
+### addStaticRoute(pFilePath, pDefaultFile, pRoute, pRouteStrip, pParams)
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `pFilePath` | string | *required* | Path to the directory to serve files from |
+| `pDefaultFile` | string | `"index.html"` | Default file for directory requests |
+| `pRoute` | string | `"/*"` | Route pattern to match |
+| `pRouteStrip` | string | `"/"` | URL prefix to strip before filesystem lookup |
+| `pParams` | object | `{}` | Options passed to `serve-static` |
+
+## Examples
+
+### Single Page Application
+
+```javascript
+// All routes fall back to index.html
+_Fable.Orator.addStaticRoute('./dist/', 'index.html', '/*');
+```
+
+### Serving Under a Subpath
+
+```javascript
+// /app/styles.css serves ./dist/styles.css
+_Fable.Orator.addStaticRoute('./dist/', 'index.html', '/app/*', '/app/');
+```
+
+### API Server with Static Frontend
+
+```javascript
+// API routes first
+_Fable.Orator.serviceServer.get('/api/data',
+	(pRequest, pResponse, fNext) =>
+	{
+		pResponse.send({ value: 42 });
+		return fNext();
+	});
+
+// Static files for everything else
+_Fable.Orator.addStaticRoute('./public/', 'index.html', '/*');
+```
+
+## Subdomain Folder Routing
+
+When a request arrives with a subdomain, Orator checks if a matching subfolder exists in the serve directory. If it does, files are served from that subfolder.
+
+For a serve path of `./sites/`:
+- `http://clienta.example.com/page.html` checks for `./sites/clienta/page.html`
+- If `./sites/clienta/` exists, it serves from there
+- Otherwise, falls back to `./sites/page.html`
+
+## Documentation
+
+Full documentation is available in the [`docs`](./docs) folder, or served locally:
+
+```bash
+npx docsify-cli serve docs
+```
+
+## Related Packages
+
+- [orator](https://github.com/stevenvelozo/orator) - Main Orator service (includes addStaticRoute)
+- [orator-serviceserver-restify](https://github.com/stevenvelozo/orator-serviceserver-restify) - Restify service server
+- [fable](https://github.com/stevenvelozo/fable) - Service provider framework

package/docs/README.md

@@ -0,0 +1,49 @@
+# Orator Static Server
+
+> Static file serving for Orator API servers
+
+Orator Static Server provides static file serving capabilities for Orator-based applications. The core functionality lives in the main `orator` module's `addStaticRoute` method -- this documentation covers how to use it effectively for development servers, single page applications, and multi-tenant hosting.
+
+## Features
+
+- **File Serving** - Serve static files from any directory on disk
+- **MIME Detection** - Automatic Content-Type headers based on file extension
+- **Default Files** - Configurable default file (e.g., `index.html`) for directory requests
+- **Route Stripping** - Strip URL prefixes before mapping to the filesystem
+- **Subdomain Routing** - Serve different folders based on request subdomain
+
+## Quick Start
+
+```javascript
+const libFable = require('fable');
+const libOrator = require('orator');
+const libOratorServiceServerRestify = require('orator-serviceserver-restify');
+
+const _Fable = new libFable({
+	Product: 'MyStaticServer',
+	ServicePort: 8080
+});
+
+_Fable.serviceManager.addServiceType('Orator', libOrator);
+_Fable.serviceManager.addServiceType('OratorServiceServer', libOratorServiceServerRestify);
+_Fable.serviceManager.instantiateServiceProvider('Orator');
+_Fable.serviceManager.instantiateServiceProvider('OratorServiceServer');
+
+_Fable.Orator.addStaticRoute('./public/');
+_Fable.Orator.startService();
+```
+
+## How It Works
+
+When `addStaticRoute` is called, Orator registers a GET route handler on the service server that:
+
+1. Checks for subdomain-based folder routing
+2. Strips the configured URL prefix from the request path
+3. Sets the appropriate MIME type Content-Type header
+4. Serves the file from disk using `serve-static`
+
+## Related Packages
+
+- [orator](https://github.com/stevenvelozo/orator) - Main Orator service (includes addStaticRoute)
+- [orator-serviceserver-restify](https://github.com/stevenvelozo/orator-serviceserver-restify) - Restify service server
+- [fable](https://github.com/stevenvelozo/fable) - Service provider framework

package/docs/_sidebar.md

@@ -0,0 +1,9 @@
+- Getting Started
+
+  - [Introduction](/)
+  - [Getting Started](getting-started.md)
+
+- Reference
+
+  - [API Reference](api-reference.md)
+  - [Subdomain Routing](subdomain-routing.md)

package/docs/api-reference.md

@@ -0,0 +1,68 @@
+# API Reference
+
+## addStaticRoute(pFilePath, pDefaultFile, pRoute, pRouteStrip, pParams)
+
+Registers a GET route handler that serves static files from a directory on disk.
+
+### Parameters
+
+| Parameter | Type | Default | Required | Description |
+|-----------|------|---------|----------|-------------|
+| `pFilePath` | string | - | Yes | Path to the directory to serve files from |
+| `pDefaultFile` | string | `"index.html"` | No | Default file when no specific file is requested |
+| `pRoute` | string | `"/*"` | No | Route pattern to match for static file requests |
+| `pRouteStrip` | string | `"/"` | No | Prefix to strip from URL paths before filesystem lookup |
+| `pParams` | object | `{}` | No | Additional options passed to the `serve-static` library |
+
+### Returns
+
+`true` if the route was successfully installed, `false` if `pFilePath` is not a string.
+
+### Examples
+
+**Minimal:**
+```javascript
+_Fable.Orator.addStaticRoute('./public/');
+```
+
+**With default file:**
+```javascript
+_Fable.Orator.addStaticRoute('./public/', 'app.html');
+```
+
+**With custom route:**
+```javascript
+_Fable.Orator.addStaticRoute('./public/', 'index.html', '/static/*');
+```
+
+**With route stripping:**
+```javascript
+_Fable.Orator.addStaticRoute('./dist/', 'index.html', '/app/*', '/app/');
+```
+
+**With serve-static options:**
+```javascript
+_Fable.Orator.addStaticRoute('./public/', 'index.html', '/*', '/',
+	{
+		maxAge: '1d',
+		etag: true
+	});
+```
+
+## MIME Type Detection
+
+Orator automatically sets the `Content-Type` response header based on the requested file's extension. It uses the `mime` library for detection and defaults to `application/octet-stream` for unknown file types.
+
+The module handles both v1 and v2 of the `mime` library transparently, using `mime.lookup()` or `mime.getType()` depending on which is available.
+
+## serve-static Options
+
+The `pParams` parameter is passed directly to [serve-static](https://github.com/expressjs/serve-static). Some useful options:
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `maxAge` | number/string | Set the Cache-Control max-age header (in ms or as a string like `'1d'`) |
+| `etag` | boolean | Generate ETags for files |
+| `dotfiles` | string | How to handle dotfiles: `'allow'`, `'deny'`, or `'ignore'` |
+| `redirect` | boolean | Redirect to trailing `/` when pathname is a directory |
+| `index` | string/boolean | Override the default file (set to `false` to disable) |

package/docs/cover.md

@@ -0,0 +1,11 @@
+# Orator Static Server <small>1</small>
+
+> Static file serving for Orator API servers
+
+- Serve files from any directory on disk
+- Automatic MIME type detection
+- Subdomain-based folder routing
+- Configurable default files and route stripping
+
+[GitHub](https://github.com/stevenvelozo/orator-static-server)
+[Get Started](#orator-static-server)

package/docs/getting-started.md

@@ -0,0 +1,84 @@
+# Getting Started
+
+## Installation
+
+Static file serving is built into the main `orator` module:
+
+```bash
+npm install fable orator orator-serviceserver-restify
+```
+
+## Basic Static Server
+
+The simplest static file server:
+
+```javascript
+const libFable = require('fable');
+const libOrator = require('orator');
+const libOratorServiceServerRestify = require('orator-serviceserver-restify');
+
+const _Fable = new libFable({
+	Product: 'DevServer',
+	ServicePort: 8080
+});
+
+_Fable.serviceManager.addServiceType('Orator', libOrator);
+_Fable.serviceManager.addServiceType('OratorServiceServer', libOratorServiceServerRestify);
+_Fable.serviceManager.instantiateServiceProvider('Orator');
+_Fable.serviceManager.instantiateServiceProvider('OratorServiceServer');
+
+// Serve files from ./public, defaulting to index.html
+_Fable.Orator.addStaticRoute('./public/');
+
+_Fable.Orator.startService(
+	() =>
+	{
+		_Fable.log.info('Static server is ready');
+	});
+```
+
+## Single Page Application
+
+For SPAs where all routes should resolve to `index.html`:
+
+```javascript
+_Fable.Orator.addStaticRoute('./dist/', 'index.html', '/*');
+```
+
+## API Server with Static Frontend
+
+Register your API routes first, then add static file serving as a catch-all:
+
+```javascript
+// API routes
+_Fable.Orator.serviceServer.get('/api/users',
+	(pRequest, pResponse, fNext) =>
+	{
+		pResponse.send([{ id: 1, name: 'User One' }]);
+		return fNext();
+	});
+
+_Fable.Orator.serviceServer.postWithBodyParser('/api/users',
+	(pRequest, pResponse, fNext) =>
+	{
+		pResponse.send({ created: true });
+		return fNext();
+	});
+
+// Static files for everything else
+_Fable.Orator.addStaticRoute('./public/', 'index.html', '/*');
+```
+
+## Serving Under a Subpath
+
+If your static files should be served under a URL prefix:
+
+```javascript
+// /app/styles.css serves ./dist/styles.css
+_Fable.Orator.addStaticRoute('./dist/', 'index.html', '/app/*', '/app/');
+```
+
+## Next Steps
+
+- [API Reference](api-reference.md) - Complete parameter documentation
+- [Subdomain Routing](subdomain-routing.md) - Multi-tenant static hosting

package/docs/index.html

@@ -0,0 +1,39 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8">
+		<meta http-equiv="X-UA-Compatible" content="IE=edge">
+		<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+		<meta name="description" content="Documentation powered by pict-docuserve">
+
+		<title>Documentation</title>
+
+		<!-- Application Stylesheet -->
+		<link href="https://cdn.jsdelivr.net/npm/pict-docuserve@0/dist/css/docuserve.css" rel="stylesheet">
+		<!-- KaTeX stylesheet for LaTeX equation rendering -->
+		<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css">
+		<!-- PICT Dynamic View CSS Container -->
+		<style id="PICT-CSS"></style>
+
+		<!-- Load the PICT library from jsDelivr CDN -->
+		<script src="https://cdn.jsdelivr.net/npm/pict@1/dist/pict.min.js" type="text/javascript"></script>
+		<!-- Bootstrap the Application -->
+		<script type="text/javascript">
+//<![CDATA[
+		Pict.safeOnDocumentReady(() => { Pict.safeLoadPictApplication(PictDocuserve, 2)});
+//]]>
+		</script>
+	</head>
+	<body>
+		<!-- The root container for the Pict application -->
+		<div id="Docuserve-Application-Container"></div>
+
+		<!-- Mermaid diagram rendering -->
+		<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
+		<script>mermaid.initialize({ startOnLoad: false, theme: 'default' });</script>
+		<!-- KaTeX for LaTeX equation rendering -->
+		<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.js"></script>
+		<!-- Load the Docuserve PICT Application Bundle from jsDelivr CDN -->
+		<script src="https://cdn.jsdelivr.net/npm/pict-docuserve@0/dist/pict-docuserve.min.js" type="text/javascript"></script>
+	</body>
+</html>

package/docs/subdomain-routing.md

@@ -0,0 +1,63 @@
+# Subdomain Folder Routing
+
+Orator's static file serving includes a built-in feature for subdomain-based folder routing. This enables a simple multi-tenant static hosting setup without any additional configuration or infrastructure.
+
+## How It Works
+
+When a request arrives, Orator inspects the `Host` header for subdomain prefixes. If the host has more than one segment (e.g., `clienta.example.com` vs just `localhost`), Orator takes the first segment and checks if a matching subfolder exists in the serve directory.
+
+```
+Request: http://clienta.example.com/page.html
+Host header: clienta.example.com
+    ↓
+Split host: ["clienta", "example", "com"]
+First segment: "clienta"
+    ↓
+Check: does ./sites/clienta/ exist?
+    ├── Yes → Serve from ./sites/clienta/page.html
+    └── No  → Serve from ./sites/page.html
+```
+
+## Setup
+
+```javascript
+// Serve from ./sites, with subdomain-based subfolder routing
+_Fable.Orator.addStaticRoute('./sites/');
+```
+
+## Directory Structure
+
+```
+sites/
+├── index.html           ← Served for requests without subdomain match
+├── styles.css
+├── clienta/
+│   ├── index.html       ← Served for clienta.example.com
+│   └── styles.css
+├── clientb/
+│   ├── index.html       ← Served for clientb.example.com
+│   └── styles.css
+└── shared/
+    └── logo.png
+```
+
+## Example Requests
+
+| Request URL | Served File |
+|------------|-------------|
+| `http://example.com/index.html` | `./sites/index.html` |
+| `http://clienta.example.com/index.html` | `./sites/clienta/index.html` |
+| `http://clientb.example.com/styles.css` | `./sites/clientb/styles.css` |
+| `http://unknown.example.com/page.html` | `./sites/page.html` (no match, falls back) |
+
+## Limitations
+
+- Subdomain routing is one level deep -- it only checks the first subdomain segment
+- The subfolder must exist on disk for the routing to activate
+- Requests to `localhost` or IP addresses won't trigger subdomain routing (only one host segment)
+
+## Use Cases
+
+- **Multi-tenant SaaS frontends** - Each customer gets a branded subdomain serving their customized UI
+- **Development environments** - Different feature branches served from subdomains
+- **A/B testing** - Serve different static builds based on subdomain

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "orator-static-server",
-    "version": "1.0.1",
-    "description": "Orator static file server.",
+    "version": "2.0.0",
+    "description": "Static file serving for Orator API servers.",
     "main": "source/Orator-Static-Server.js",
     "scripts": {
         "test": "./node_modules/mocha/bin/_mocha --exit -u tdd -R spec",
@@ -38,14 +38,17 @@
     },
     "homepage": "https://github.com/stevenvelozo/orator-static-server#readme",
     "dependencies": {
+        "fable-serviceproviderbase": "^3.0.15",
         "finalhandler": "^1.3.1",
-        "orator-serviceserver-base": "^1.0.1",
+        "mime": "^3.0.0",
         "serve-static": "^1.16.2"
     },
     "devDependencies": {
-        "fable": "^3.0.145",
-        "orator": "^5.0.0",
-        "orator-serviceserver-restify": "^2.0.3",
-        "quackage": "^1.0.33"
+        "chai": "^4.3.7",
+        "fable": "^3.1.51",
+        "mocha": "^10.2.0",
+        "orator": "^5.0.1",
+        "orator-serviceserver-restify": "^2.0.5",
+        "quackage": "^1.0.45"
     }
 }