orator 5.0.1 → 5.0.2

package/README.md

@@ -1,107 +1,84 @@
 # Orator
 
-Orator API Server, meant to interact well with Fable, Meadow and FoxHound.
+> An unopinionated API server abstraction for REST and IPC services
 
-[![Coverage Status](https://coveralls.io/repos/stevenvelozo/orator/badge.svg?branch=master)](https://coveralls.io/r/stevenvelozo/orator?branch=master) [![Build Status](https://travis-ci.org/stevenvelozo/orator.svg?branch=master)](https://travis-ci.org/stevenvelozo/orator) [![Dependency Status](https://david-dm.org/stevenvelozo/orator.svg)](https://david-dm.org/stevenvelozo/orator) [![devDependency Status](https://david-dm.org/stevenvelozo/orator/dev-status.svg)](https://david-dm.org/stevenvelozo/orator#info=devDependencies)
+Orator is not an attempt to reinvent the wheel. Nor do we want to make a car with five of them. Orator is a thin abstraction layer over service server implementations (like Restify), providing a consistent interface for building API servers. You can spin up a web server in a single simple line, and configuration is managed through a consistent JSON format -- so as you begin to have 10 or 15 or 5,000 microservices, you don't have a bunch of boilerplate API server code laying around.
 
-This is not an attempt to reinvent the wheel.  Nor do we want to make a car with five of them.
+## Features
 
-Orator is a wrapper for [restify](https://github.com/restify/node-restify), which is an amazing API server.  With Orator, you can spin up a web server in a single simple line.  And config settings are managed via a consistent json format, so as you begin to have 10 or 15 or 5,000 microservices, you don't have a bunch of boilerplate API server code laying around.
+- **Unopinionated Design** - Wraps any service server implementation through a consistent interface
+- **REST and IPC** - Full HTTP server support via Restify, or in-process IPC for testing and microservice composition
+- **Lifecycle Management** - Before/After hooks for initialization and service start phases
+- **Static File Serving** - Built-in static file serving with subdomain-based folder routing
+- **Fable Integration** - First-class service provider in the Fable ecosystem with logging and configuration
+- **Browser & Node.js** - Works in both environments with automatic service server selection
 
-## Creating a Simple Server
+## Quick Start
 
-Okay, so you want to make a simple api server.  You would need to create a node.js project, then install the Orator dependency with npm:
+```javascript
+const libFable = require('fable');
+const libOrator = require('orator');
+const libOratorServiceServerRestify = require('orator-serviceserver-restify');
 
-```sh
-npm install orator --save
-```
+const _Fable = new libFable({
+	Product: 'MyAPIServer',
+	ProductVersion: '1.0.0',
+	ServicePort: 8080
+});
 
-Then within your javascript code, you could write the following:
+_Fable.serviceManager.addServiceType('Orator', libOrator);
+_Fable.serviceManager.addServiceType('OratorServiceServer', libOratorServiceServerRestify);
+_Fable.serviceManager.instantiateServiceProvider('Orator');
+_Fable.serviceManager.instantiateServiceProvider('OratorServiceServer');
 
-```js
-// Load the orator module with a few settings
-var libOrator = require('orator').new(
+_Fable.Orator.serviceServer.get('/hello/:name',
+	(pRequest, pResponse, fNext) =>
 	{
-		Product: 'MyMicroserviceHash',
-		ProductVersion: '9.8.7',
-
-		"APIServerPort": 8000
+		pResponse.send({ greeting: `Hello ${pRequest.params.name}!` });
+		return fNext();
 	});
 
-// Add an API endpoint
-libOrator.webServer.post
-(
-	'/echo/:name',
-	function(pRequest, pResponse, fNext)
+_Fable.Orator.startService(
+	() =>
 	{
-		// Send back whatever was sent as "name" in the URI
-		pResponse.send(pRequest.params);
-		return fNext();
-	}
-);
-
-// Start the web service
-libOrator.startWebServer();
+		console.log('Server is running on port 8080');
+	});
 ```
 
-After writing this code, you could run your service and a browser going to `http://localhost:8000/echo/Gargamel` would return a JSON object with Gargamel as the name.
-
-Of course, this is not much different from the Restify code.  Where it gets interesting is dealing with things like logging and configuration management.  For instance, if you do
+## Installation
 
-```js
-// Load the orator module with a few settings
-var libOrator = require('orator').new(
-	{
-		Product: 'MyMicroserviceHash',
-		ProductVersion: '9.8.7',
+```bash
+npm install orator
+```
 
-		"APIServerPort": 8000,
+## Configuration
 
-		ConfigFile:__dirname+'/MyMicroservice-Config.json'
-	});
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `Product` | string | `"Unnamed_Service"` | Application name identifier |
+| `ProductVersion` | string | `"0.0.1"` | Application version string |
+| `ServicePort` | number | `8080` | Port for the service server to listen on |
+| `APIServerPort` | number | - | Legacy alias for ServicePort (automatically migrated) |
+| `RestifyConfiguration` | object | `{}` | Configuration passed to Restify when using the Restify service server |
 
-// Add an API endpoint
-libOrator.webServer.post
-(
-	'/echo/:name',
-	function(pRequest, pResponse, fNext)
-	{
-		// Send back whatever was sent as "name" in the URI
-		pResponse.send(pRequest.params);
-		return fNext();
-	}
-);
+## Documentation
 
-// Start the web service
-libOrator.startWebServer();
-```
+Full documentation is available in the [`docs`](./docs) folder, or served locally:
 
-Then you could create a file in the same folder as this script called `MyMicroservice-Config.json` and as long as it is valid json, settings can be loaded from there.  Something like this:
-
-```json
-{
-	"APIServerPort": 8080,
-
-	"UUID":
-		{
-			"DataCenter": 0,
-			"Worker": 0
-		},
-
-	"LogStreams":
-		[
-			{
-				"level": "info",
-				"path": "./MyMicroService-Server.log"
-			},
-			{
-				"level": "trace",
-				"streamtype": "process.stdout"
-			}
-		]
-}
+```bash
+npx docsify-cli serve docs
 ```
 
-And suddenly the bunyan logging will write to a file and stdout, and you can configure 20 Docker instances to each have a different Worker ID.
+- [Architecture](docs/architecture.md) - Service server abstraction design
+- [Getting Started](docs/getting-started.md) - Step-by-step setup guide
+- [Static File Serving](docs/static-files.md) - Serving files from disk
+- [IPC Server](docs/ipc-server.md) - In-process service invocation
 
+## Related Packages
 
+- [orator-serviceserver-base](https://github.com/stevenvelozo/orator-serviceserver-base) - Abstract base class for service servers
+- [orator-serviceserver-restify](https://github.com/stevenvelozo/orator-serviceserver-restify) - Restify service server implementation
+- [orator-http-proxy](https://github.com/stevenvelozo/orator-http-proxy) - HTTP proxy pass-through for Orator
+- [orator-static-server](https://github.com/stevenvelozo/orator-static-server) - Static file serving module
+- [fable](https://github.com/stevenvelozo/fable) - Service provider framework
+- [meadow](https://github.com/stevenvelozo/meadow) - Data access layer with automatic REST endpoints

package/docs/README.md

@@ -0,0 +1,142 @@
+# Orator
+
+> An unopinionated API server abstraction for REST and IPC services
+
+Orator is a thin abstraction layer over service server implementations, providing a consistent interface for building API servers. It doesn't care whether you're running Restify, building an in-process service mesh, or doing something entirely novel with your own service server implementation. Orator provides the lifecycle, the configuration, and the conventions -- you provide the service logic.
+
+## Features
+
+- **Unopinionated Design** - Wraps any service server implementation through a consistent interface
+- **REST and IPC** - Full HTTP server support via Restify, or in-process IPC for testing and microservice composition
+- **Lifecycle Management** - Before/After hooks for initialization and service start phases
+- **Static File Serving** - Built-in static file serving with subdomain-based folder routing
+- **Fable Integration** - First-class service provider in the Fable ecosystem with logging and configuration
+- **Browser & Node.js** - Works in both environments with automatic service server selection
+
+## Quick Start
+
+```javascript
+const libFable = require('fable');
+const libOrator = require('orator');
+const libOratorServiceServerRestify = require('orator-serviceserver-restify');
+
+const _Fable = new libFable({
+	Product: 'MyAPIServer',
+	ProductVersion: '1.0.0',
+	ServicePort: 8080
+});
+
+// Register Orator and a service server with Fable
+_Fable.serviceManager.addServiceType('Orator', libOrator);
+_Fable.serviceManager.addServiceType('OratorServiceServer', libOratorServiceServerRestify);
+_Fable.serviceManager.instantiateServiceProvider('Orator');
+_Fable.serviceManager.instantiateServiceProvider('OratorServiceServer');
+
+// Add an API endpoint
+_Fable.Orator.serviceServer.get('/hello/:name',
+	(pRequest, pResponse, fNext) =>
+	{
+		pResponse.send({ greeting: `Hello ${pRequest.params.name}!` });
+		return fNext();
+	});
+
+// Start the service
+_Fable.Orator.startService(
+	() =>
+	{
+		console.log('Server is running on port 8080');
+	});
+```
+
+## Installation
+
+```bash
+npm install orator
+```
+
+## How It Works
+
+Orator follows the Fable service provider pattern. You register it with a Fable instance, and it orchestrates one or more service server implementations to handle incoming requests. If you don't provide a service server, Orator will automatically set up its built-in IPC server -- which is useful for testing and in-process communication where no network traffic is needed.
+
+```
+Fable (Core)
+  └── Orator (Service Orchestration)
+        └── Service Server (Restify, IPC, or custom)
+              ├── Route Registration (GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD)
+              ├── Middleware Pipeline
+              └── Static File Serving
+```
+
+## Configuration
+
+Orator accepts configuration through the Fable settings object:
+
+```json
+{
+	"Product": "MyAPIServer",
+	"ProductVersion": "1.0.0",
+	"ServicePort": 8080,
+	"RestifyConfiguration": {}
+}
+```
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `Product` | string | `"Unnamed_Service"` | Application name identifier |
+| `ProductVersion` | string | `"0.0.1"` | Application version string |
+| `ServicePort` | number | `8080` | Port for the service server to listen on |
+| `APIServerPort` | number | - | Legacy alias for ServicePort (automatically migrated) |
+| `RestifyConfiguration` | object | `{}` | Configuration passed to Restify server creation |
+| `ServiceServerOptions` | object | `{}` | Options passed to the auto-initialized service server |
+
+## API Reference
+
+### Lifecycle Methods
+
+| Method | Description |
+|--------|-------------|
+| `initialize(fCallback)` | Initializes Orator and its service server |
+| `startService(fCallback)` | Starts the service server listening on the configured port |
+| `stopService(fCallback)` | Stops the running service server |
+
+### Route Invocation
+
+| Method | Description |
+|--------|-------------|
+| `invoke(pMethod, pRoute, pData, fCallback)` | Programmatically invoke a registered route without HTTP |
+
+### Static Files
+
+| Method | Description |
+|--------|-------------|
+| `addStaticRoute(pFilePath, pDefaultFile, pRoute, pRouteStrip, pParams)` | Serve static files from a directory |
+
+### Legacy Methods
+
+| Method | Maps To |
+|--------|---------|
+| `startWebServer(fCallback)` | `startService(fCallback)` |
+| `stopWebServer(fCallback)` | `stopService(fCallback)` |
+| `getWebServer()` | Returns `serviceServer` (lazy-initializes if needed) |
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `serviceServer` | object | The active service server instance |
+| `webServer` | object | Legacy alias for `serviceServer` |
+
+## Testing
+
+```bash
+npm test
+```
+
+## Related Packages
+
+- [orator-serviceserver-base](https://github.com/stevenvelozo/orator-serviceserver-base) - Abstract base class for service servers
+- [orator-serviceserver-restify](https://github.com/stevenvelozo/orator-serviceserver-restify) - Restify service server implementation
+- [orator-http-proxy](https://github.com/stevenvelozo/orator-http-proxy) - HTTP proxy pass-through for Orator
+- [orator-static-server](https://github.com/stevenvelozo/orator-static-server) - Static file serving module
+- [fable](https://github.com/stevenvelozo/fable) - Service provider framework
+- [meadow](https://github.com/stevenvelozo/meadow) - Data access layer with automatic REST endpoints

package/docs/_sidebar.md

@@ -0,0 +1,21 @@
+- Getting Started
+
+  - [Introduction](/)
+  - [Getting Started](getting-started.md)
+  - [Architecture](architecture.md)
+
+- Core Concepts
+
+  - [Service Servers](service-servers.md)
+  - [Lifecycle Hooks](lifecycle-hooks.md)
+  - [Static File Serving](static-files.md)
+
+- Service Server Implementations
+
+  - [IPC Server](ipc-server.md)
+  - [Restify Server](restify-server.md)
+
+- Advanced
+
+  - [HTTP Proxy](http-proxy.md)
+  - [Configuration Reference](configuration.md)

package/docs/architecture.md

@@ -0,0 +1,92 @@
+# Architecture
+
+Orator's design separates the concerns of service lifecycle management from the specifics of any HTTP server implementation. This abstraction allows you to swap service servers, test without network overhead, and maintain consistent patterns across many microservices.
+
+## Layered Design
+
+```
+┌─────────────────────────────────────────────┐
+│                   Fable                     │
+│        (Configuration, Logging, DI)         │
+└─────────────────────┬───────────────────────┘
+                      │
+┌─────────────────────▼───────────────────────┐
+│                  Orator                     │
+│    (Lifecycle, Static Files, Invocation)    │
+└─────────────────────┬───────────────────────┘
+                      │
+┌─────────────────────▼───────────────────────┐
+│        OratorServiceServerBase              │
+│     (Abstract Route & Middleware API)       │
+└───────┬─────────────┬───────────────────────┘
+        │             │
+┌───────▼──────┐ ┌────▼──────────────┐
+│  IPC Server  │ │  Restify Server   │
+│  (built-in)  │ │  (network HTTP)   │
+└──────────────┘ └───────────────────┘
+```
+
+### Fable Layer
+
+Fable provides the foundation: dependency injection, configuration management, logging, and service wiring. Orator registers itself as a Fable service and gains access to all of these capabilities automatically.
+
+### Orator Layer
+
+Orator manages the service lifecycle (initialization, starting, stopping) and provides higher-level features like static file serving and programmatic route invocation. It delegates actual HTTP handling to whichever service server implementation is registered.
+
+### Service Server Layer
+
+Service servers implement the actual HTTP verb handling. The base class (`orator-serviceserver-base`) defines the interface, and concrete implementations like `orator-serviceserver-restify` and the built-in IPC server provide the behavior.
+
+## Service Provider Pattern
+
+All Orator modules follow the Fable service provider pattern. Services are registered with a Fable instance by type, then instantiated on demand:
+
+```javascript
+// Register the service types
+_Fable.serviceManager.addServiceType('Orator', libOrator);
+_Fable.serviceManager.addServiceType('OratorServiceServer', libOratorServiceServerRestify);
+
+// Instantiate them -- Fable handles wiring
+_Fable.serviceManager.instantiateServiceProvider('Orator');
+_Fable.serviceManager.instantiateServiceProvider('OratorServiceServer');
+
+// Access via Fable
+_Fable.Orator.startService();
+```
+
+## Auto-Initialization
+
+If no service server is registered when Orator initializes, it will automatically create and register the built-in IPC service server. This makes it possible to use Orator for in-process route invocation without configuring a network server:
+
+```javascript
+// No OratorServiceServer registered -- IPC is used automatically
+_Fable.serviceManager.addServiceType('Orator', libOrator);
+_Fable.serviceManager.instantiateServiceProvider('Orator');
+
+_Fable.Orator.serviceServer.get('/api/data',
+	(pRequest, pResponse, fNext) =>
+	{
+		pResponse.send({ value: 42 });
+		return fNext();
+	});
+
+// Invoke the route programmatically (no network call)
+_Fable.Orator.invoke('GET', '/api/data', {},
+	(pError, pResponseData) =>
+	{
+		console.log(pResponseData); // { value: 42 }
+	});
+```
+
+## Template Method Pattern
+
+The service server base class uses a template method pattern for route registration. The base class validates inputs, and derived classes implement the `do*` methods with actual behavior:
+
+```
+Base: get(pRoute, ...) → validates pRoute → calls doGet(pRoute, ...)
+  └── Restify: doGet(pRoute, ...) → this.server.get(pRoute, ...)
+  └── IPC: doGet(pRoute, ...) → this.addRouteProcessor('GET', pRoute, ...)
+```
+
+This pattern allows derived classes to focus on implementation without duplicating validation logic.

package/docs/configuration.md

@@ -0,0 +1,94 @@
+# Configuration Reference
+
+Orator is configured through the Fable settings object. Settings can be provided directly, loaded from a configuration file, or a combination of both.
+
+## Orator Settings
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `Product` | string | `"Unnamed_Service"` | Application name identifier |
+| `ProductVersion` | string | `"0.0.1"` | Application version string |
+| `ServicePort` | number | `8080` | Port for the service server to listen on |
+| `APIServerPort` | number | - | Legacy alias for `ServicePort` (automatically migrated) |
+| `ServiceServerOptions` | object | `{}` | Options passed to the auto-initialized service server |
+
+## Restify Settings
+
+When using the Restify service server:
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `RestifyConfiguration` | object | `{}` | Configuration passed to `restify.createServer()` |
+| `RestifyConfiguration.maxParamLength` | number | `Number.MAX_SAFE_INTEGER` | Maximum URL parameter length |
+
+## HTTP Proxy Settings
+
+When using the HTTP proxy module:
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `OratorHTTPProxyDestinationURL` | string | `"http://127.0.0.1/"` | URL to proxy requests to |
+| `OratorHTTPProxyRequestPrefixList` | array | `["/1.0/*"]` | Route prefixes to proxy |
+| `OratorHTTPProxyLogLevel` | number | `0` | Proxy logging verbosity |
+
+## Fable Settings
+
+These Fable settings are commonly used with Orator:
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `LogStreams` | array | `[{ level: "info" }]` | Log output destinations |
+| `LogNoisiness` | number | `0` | Controls Orator's internal trace logging |
+| `UUID.DataCenter` | number | `0` | Data center ID for UUID generation |
+| `UUID.Worker` | number | `0` | Worker ID for UUID generation |
+
+## Example Configuration File
+
+```json
+{
+	"Product": "MyAPIServer",
+	"ProductVersion": "2.1.0",
+	"ServicePort": 8080,
+
+	"RestifyConfiguration": {
+		"strictNext": true
+	},
+
+	"UUID": {
+		"DataCenter": 0,
+		"Worker": 1
+	},
+
+	"LogStreams": [
+		{
+			"level": "info",
+			"path": "./server.log"
+		},
+		{
+			"level": "trace",
+			"streamtype": "process.stdout"
+		}
+	]
+}
+```
+
+## Loading Configuration
+
+```javascript
+// Direct configuration
+const _Fable = new libFable({
+	Product: 'MyAPIServer',
+	ServicePort: 8080
+});
+
+// From a JSON file
+const _Fable = new libFable({
+	ConfigFile: __dirname + '/config.json'
+});
+
+// Combined (direct settings override file settings)
+const _Fable = new libFable({
+	ConfigFile: __dirname + '/config.json',
+	ServicePort: 9090  // Overrides whatever is in config.json
+});
+```

package/docs/cover.md

@@ -0,0 +1,11 @@
+# Orator <small>5</small>
+
+> An unopinionated API server abstraction for REST and IPC services
+
+- Consistent interface over any service server implementation
+- Full REST support via Restify with in-process IPC for testing
+- Built-in static file serving with subdomain routing
+- First-class Fable service provider with lifecycle management
+
+[GitHub](https://github.com/stevenvelozo/orator)
+[Get Started](#orator)

package/docs/getting-started.md

@@ -0,0 +1,133 @@
+# Getting Started
+
+This guide walks through setting up an Orator-based API server from scratch.
+
+## Installation
+
+Create a new Node.js project and install the dependencies:
+
+```bash
+mkdir my-api-server && cd my-api-server
+npm init -y
+npm install fable orator orator-serviceserver-restify
+```
+
+## Basic Server
+
+The simplest possible Orator server:
+
+```javascript
+const libFable = require('fable');
+const libOrator = require('orator');
+const libOratorServiceServerRestify = require('orator-serviceserver-restify');
+
+// 1. Create a Fable instance with your service configuration
+const _Fable = new libFable({
+	Product: 'MyAPIServer',
+	ProductVersion: '1.0.0',
+	ServicePort: 8080
+});
+
+// 2. Register Orator and a service server
+_Fable.serviceManager.addServiceType('Orator', libOrator);
+_Fable.serviceManager.addServiceType('OratorServiceServer', libOratorServiceServerRestify);
+_Fable.serviceManager.instantiateServiceProvider('Orator');
+_Fable.serviceManager.instantiateServiceProvider('OratorServiceServer');
+
+// 3. Define your API endpoints
+_Fable.Orator.serviceServer.get('/api/status',
+	(pRequest, pResponse, fNext) =>
+	{
+		pResponse.send({ status: 'ok', timestamp: new Date().toISOString() });
+		return fNext();
+	});
+
+// 4. Start the server
+_Fable.Orator.startService(
+	() =>
+	{
+		_Fable.log.info('API server is ready');
+	});
+```
+
+Run it with `node server.js` and visit `http://localhost:8080/api/status` in your browser.
+
+## Adding Routes
+
+Orator's service server exposes methods for all standard HTTP verbs. Each handler receives `pRequest`, `pResponse`, and `fNext` -- the standard Restify handler signature.
+
+```javascript
+// GET with URL parameters
+_Fable.Orator.serviceServer.get('/api/user/:id',
+	(pRequest, pResponse, fNext) =>
+	{
+		let tmpUserID = pRequest.params.id;
+		pResponse.send({ id: tmpUserID, name: 'Example User' });
+		return fNext();
+	});
+
+// POST with body parsing
+_Fable.Orator.serviceServer.postWithBodyParser('/api/user',
+	(pRequest, pResponse, fNext) =>
+	{
+		let tmpNewUser = pRequest.body;
+		_Fable.log.info(`Creating user: ${tmpNewUser.name}`);
+		pResponse.send({ created: true, user: tmpNewUser });
+		return fNext();
+	});
+
+// PUT, DELETE, PATCH follow the same pattern
+_Fable.Orator.serviceServer.del('/api/user/:id',
+	(pRequest, pResponse, fNext) =>
+	{
+		pResponse.send({ deleted: true, id: pRequest.params.id });
+		return fNext();
+	});
+```
+
+## Using Middleware
+
+Register middleware that runs before all route handlers:
+
+```javascript
+// Add a middleware function
+_Fable.Orator.serviceServer.use(
+	(pRequest, pResponse, fNext) =>
+	{
+		_Fable.log.trace(`${pRequest.method} ${pRequest.url}`);
+		return fNext();
+	});
+```
+
+## Configuration from File
+
+Fable supports loading configuration from a JSON file, which means your Orator server configuration can live outside your code:
+
+```json
+{
+	"Product": "MyAPIServer",
+	"ProductVersion": "1.0.0",
+	"ServicePort": 8080,
+	"LogStreams": [
+		{
+			"level": "info",
+			"path": "./server.log"
+		},
+		{
+			"level": "trace",
+			"streamtype": "process.stdout"
+		}
+	]
+}
+```
+
+```javascript
+const _Fable = new libFable({ ConfigFile: __dirname + '/config.json' });
+```
+
+## Next Steps
+
+- [Architecture](architecture.md) - Understand the service server abstraction
+- [Lifecycle Hooks](lifecycle-hooks.md) - Customize initialization and startup behavior
+- [Static File Serving](static-files.md) - Serve files from disk
+- [IPC Server](ipc-server.md) - Use Orator without a network server