orator-serviceserver-restify 2.0.4 → 2.0.7

package/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing to Retold
+
+We welcome contributions to Retold and its modules. This guide covers the expectations and process for contributing.
+
+## Code of Conduct
+
+The Retold community values **empathy**, **equity**, **kindness**, and **thoughtfulness**. We expect all participants to treat each other with respect, assume good intent, and engage constructively. These values apply to all interactions: pull requests, issues, discussions, and code review.
+
+## How to Contribute
+
+### Pull Requests
+
+Pull requests are the preferred method for contributing changes. To submit one:
+
+1. Fork the module repository you want to change
+2. Create a branch for your work
+3. Make your changes, following the code style of the module you are editing
+4. Ensure your changes have test coverage (see below)
+5. Open a pull request against the module's main branch
+
+**Submitting a pull request does not guarantee it will be accepted.** Maintainers review contributions for fit, quality, and alignment with the project's direction. A PR may be declined, or you may be asked to revise it. This is normal and not a reflection on the quality of your effort.
+
+### Reporting Issues
+
+If you find a bug or have a feature suggestion, open an issue on the relevant module's repository. Include enough detail to reproduce the problem or understand the proposal.
+
+## Test Coverage
+
+Every commit must include test coverage for the changes it introduces. Retold modules use Mocha in TDD style. Before submitting:
+
+- **Write tests** for any new functionality or bug fixes
+- **Run the existing test suite** with `npm test` and confirm all tests pass
+- **Check coverage** with `npm run coverage` if the module supports it
+
+Pull requests that break existing tests or lack coverage for new code will not be merged.
+
+## Code Style
+
+Follow the conventions of the module you are working in. The general Retold style is:
+
+- **Tabs** for indentation, never spaces
+- **Plain JavaScript** only (no TypeScript)
+- **Allman-style braces** (opening brace on its own line)
+- **Variable naming:** `pVariable` for parameters, `tmpVariable` for temporaries, `libSomething` for imports
+
+When in doubt, match what the surrounding code does.
+
+## Repository Structure
+
+Each module is its own git repository. The [retold](https://github.com/stevenvelozo/retold) repository tracks module organization but does not contain module source code. Direct your pull request to the specific module repository where your change belongs.

package/README.md

@@ -1,3 +1,118 @@
-# Restify Orator Service Server
+# Orator ServiceServer Restify
 
-Restify abstraction for Orator.  Needs more documentation.  Feeling brave?  You can `npm i` and `node debug/Harness.js` and it will serve up a silly test endpoint.
+> Production HTTP service server for Orator, powered by Restify
+
+This is the Restify implementation of the Orator service server interface. It wraps [Restify](https://restify.com/) to provide a full-featured HTTP API server with body parsing, middleware, and all standard HTTP verbs. When you need a real network-facing API server, this is the module you reach for.
+
+## Features
+
+- **Full HTTP Support** - All standard HTTP verbs (GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD)
+- **Restify Middleware** - Both `use` (post-routing) and `pre` (pre-routing) middleware support
+- **Body Parsing** - Built-in Restify body parser with multipart support
+- **Configurable** - Restify server options passed through from Fable settings
+- **Fable Service Provider** - Registers as `OratorServiceServer` in the Fable service manager
+
+## 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
+});
+
+_Fable.serviceManager.addServiceType('Orator', libOrator);
+_Fable.serviceManager.addServiceType('OratorServiceServer', libOratorServiceServerRestify);
+_Fable.serviceManager.instantiateServiceProvider('Orator');
+_Fable.serviceManager.instantiateServiceProvider('OratorServiceServer');
+
+// Register routes
+_Fable.Orator.serviceServer.get('/api/status',
+	(pRequest, pResponse, fNext) =>
+	{
+		pResponse.send({ status: 'ok' });
+		return fNext();
+	});
+
+_Fable.Orator.serviceServer.postWithBodyParser('/api/items',
+	(pRequest, pResponse, fNext) =>
+	{
+		pResponse.send({ created: true, item: pRequest.body });
+		return fNext();
+	});
+
+// Start the server
+_Fable.Orator.startService();
+```
+
+## Installation
+
+```bash
+npm install orator-serviceserver-restify
+```
+
+## Configuration
+
+Restify-specific configuration is passed through the `RestifyConfiguration` setting:
+
+```javascript
+const _Fable = new libFable({
+	ServicePort: 8080,
+	RestifyConfiguration: {
+		strictNext: true
+	}
+});
+```
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `RestifyConfiguration` | object | `{}` | Options passed to `restify.createServer()` |
+| `RestifyConfiguration.maxParamLength` | number | `Number.MAX_SAFE_INTEGER` | Maximum URL parameter length |
+
+## Middleware
+
+The Restify server supports two types of middleware:
+
+```javascript
+const tmpServiceServer = _Fable.Orator.serviceServer;
+
+// Post-routing middleware (runs after route matching)
+tmpServiceServer.use(
+	(pRequest, pResponse, fNext) =>
+	{
+		return fNext();
+	});
+
+// Pre-routing middleware (runs before route matching)
+tmpServiceServer.pre(
+	(pRequest, pResponse, fNext) =>
+	{
+		return fNext();
+	});
+```
+
+## 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) - API server abstraction
+- [orator-serviceserver-base](https://github.com/stevenvelozo/orator-serviceserver-base) - Abstract service server base class
+- [fable](https://github.com/stevenvelozo/fable) - Application services framework
+
+## License
+
+MIT
+
+## Contributing
+
+Pull requests are welcome. For details on our code of conduct, contribution process, and testing requirements, see the [Retold Contributing Guide](https://github.com/stevenvelozo/retold/blob/main/docs/contributing.md).

package/docs/README.md

@@ -0,0 +1,74 @@
+# Orator ServiceServer Restify
+
+> Production HTTP service server for Orator, powered by Restify
+
+This is the Restify implementation of the Orator service server interface. It wraps [Restify](https://restify.com/) to provide a production-ready HTTP API server. The module extends `orator-serviceserver-base`, overriding the `do*` methods to delegate route registration directly to the underlying Restify server instance.
+
+## Features
+
+- **Full HTTP Support** - All standard HTTP verbs (GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD)
+- **Restify Middleware** - Both `use` (post-routing) and `pre` (pre-routing) middleware support
+- **Body Parsing** - Built-in Restify body parser with multipart support
+- **Configurable** - Restify server options passed through from Fable settings
+- **Fable Service Provider** - Registers as `OratorServiceServer` in the Fable service manager
+
+## 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
+});
+
+_Fable.serviceManager.addServiceType('Orator', libOrator);
+_Fable.serviceManager.addServiceType('OratorServiceServer', libOratorServiceServerRestify);
+_Fable.serviceManager.instantiateServiceProvider('Orator');
+_Fable.serviceManager.instantiateServiceProvider('OratorServiceServer');
+
+_Fable.Orator.serviceServer.get('/api/hello',
+	(pRequest, pResponse, fNext) =>
+	{
+		pResponse.send({ message: 'Hello from Restify!' });
+		return fNext();
+	});
+
+_Fable.Orator.startService();
+```
+
+## Installation
+
+```bash
+npm install orator-serviceserver-restify
+```
+
+## How It Works
+
+The Restify service server creates a Restify server instance in its constructor and delegates all route and middleware registration directly to it:
+
+```
+Orator → serviceServer.get('/path', handler)
+  → OratorServiceServerBase.get() [validates route]
+    → OratorServiceServerRestify.doGet() [calls this.server.get()]
+      → Restify server handles the route
+```
+
+## Accessing the Raw Restify Server
+
+The underlying Restify server instance is available at `serviceServer.server`:
+
+```javascript
+const tmpRestifyServer = _Fable.Orator.serviceServer.server;
+```
+
+This gives you direct access to any Restify-specific features not exposed through the Orator interface.
+
+## Related Packages
+
+- [orator](https://github.com/stevenvelozo/orator) - Main Orator service abstraction
+- [orator-serviceserver-base](https://github.com/stevenvelozo/orator-serviceserver-base) - Abstract base class
+- [fable](https://github.com/stevenvelozo/fable) - Service provider framework

package/docs/_sidebar.md

@@ -0,0 +1,10 @@
+- Getting Started
+
+  - [Introduction](/)
+  - [Getting Started](getting-started.md)
+
+- Reference
+
+  - [Configuration](configuration.md)
+  - [Middleware](middleware.md)
+  - [Body Parsing](body-parsing.md)

package/docs/body-parsing.md

@@ -0,0 +1,57 @@
+# Body Parsing
+
+The Restify service server uses Restify's built-in body parser plugin to parse incoming request bodies. There are two ways to use body parsing: per-route convenience methods and manual registration.
+
+## Per-Route Body Parsing
+
+The simplest approach is to use the `*WithBodyParser` convenience methods, which automatically inject the body parser middleware before your route handler:
+
+```javascript
+_Fable.Orator.serviceServer.postWithBodyParser('/api/items',
+	(pRequest, pResponse, fNext) =>
+	{
+		// pRequest.body is already parsed
+		let tmpNewItem = pRequest.body;
+		pResponse.send({ created: true, item: tmpNewItem });
+		return fNext();
+	});
+
+_Fable.Orator.serviceServer.putWithBodyParser('/api/items/:id',
+	(pRequest, pResponse, fNext) =>
+	{
+		let tmpUpdatedItem = pRequest.body;
+		pResponse.send({ updated: true, item: tmpUpdatedItem });
+		return fNext();
+	});
+```
+
+Available for all HTTP verbs: `getWithBodyParser`, `postWithBodyParser`, `putWithBodyParser`, `delWithBodyParser`, `patchWithBodyParser`, `optsWithBodyParser`, `headWithBodyParser`.
+
+## Global Body Parsing
+
+To parse request bodies for all routes, register the body parser as middleware:
+
+```javascript
+_Fable.Orator.serviceServer.use(_Fable.Orator.serviceServer.bodyParser());
+```
+
+## Default Body Parser Configuration
+
+The Restify body parser is configured with these defaults:
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `maxBodySize` | `0` | Maximum body size (0 = unlimited) |
+| `mapParams` | `false` | Do not map body parameters to `req.params` |
+| `mapFiles` | `false` | Do not map file uploads |
+| `overrideParams` | `false` | Do not override URL params with body params |
+| `multiples` | `true` | Allow multiple file uploads |
+| `hash` | `'sha1'` | Hash algorithm for file uploads |
+
+## Content Types
+
+The Restify body parser handles these content types automatically:
+
+- `application/json` - Parsed as JSON
+- `application/x-www-form-urlencoded` - Parsed as URL-encoded form data
+- `multipart/form-data` - Parsed as multipart form data (file uploads)

package/docs/configuration.md

@@ -0,0 +1,61 @@
+# Configuration
+
+The Restify service server accepts configuration through Fable settings. Restify-specific options are passed in the `RestifyConfiguration` object.
+
+## Configuration Lookup
+
+The module checks for Restify configuration in this order:
+
+1. `options.RestifyConfiguration` (service instantiation options)
+2. `fable.settings.RestifyConfiguration` (Fable settings)
+3. Empty object `{}` (default)
+
+## Default Configuration
+
+The module sets one default that Restify doesn't:
+
+```javascript
+{
+	maxParamLength: Number.MAX_SAFE_INTEGER
+}
+```
+
+This prevents Restify from truncating long URL parameters. Your `RestifyConfiguration` settings are merged on top of this default.
+
+## Configuration Options
+
+Any option accepted by `restify.createServer()` can be passed through `RestifyConfiguration`:
+
+```javascript
+const _Fable = new libFable({
+	Product: 'MyAPIServer',
+	ServicePort: 8080,
+	RestifyConfiguration: {
+		strictNext: true,
+		maxParamLength: 500
+	}
+});
+```
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `maxParamLength` | number | `Number.MAX_SAFE_INTEGER` | Maximum URL parameter length |
+| `strictNext` | boolean | `false` | Require next() to be called in handlers |
+| `name` | string | - | Server name (uses Restify default if not set) |
+| `version` | string | - | API version string |
+
+## Example: JSON Configuration File
+
+```json
+{
+	"Product": "MyAPIServer",
+	"ProductVersion": "2.0.0",
+	"ServicePort": 8080,
+	"RestifyConfiguration": {
+		"strictNext": true
+	},
+	"LogStreams": [
+		{ "level": "info" }
+	]
+}
+```

package/docs/cover.md

@@ -0,0 +1,11 @@
+# Orator ServiceServer Restify <small>2</small>
+
+> Production HTTP service server for Orator, powered by Restify
+
+- Full HTTP verb support with route handler chaining
+- Restify pre and post-routing middleware
+- Built-in body parser with multipart support
+- Seamless integration with the Orator service lifecycle
+
+[GitHub](https://github.com/stevenvelozo/orator-serviceserver-restify)
+[Get Started](#orator-serviceserver-restify)

package/docs/css/docuserve.css

@@ -0,0 +1,73 @@
+/* ============================================================================
+   Pict Docuserve - Base Styles
+   ============================================================================ */
+
+/* Reset and base */
+*, *::before, *::after {
+	box-sizing: border-box;
+}
+
+html, body {
+	margin: 0;
+	padding: 0;
+	font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+	font-size: 16px;
+	line-height: 1.5;
+	color: #423D37;
+	background-color: #fff;
+	-webkit-font-smoothing: antialiased;
+	-moz-osx-font-smoothing: grayscale;
+}
+
+/* Typography */
+h1, h2, h3, h4, h5, h6 {
+	margin-top: 0;
+	line-height: 1.3;
+}
+
+a {
+	color: #2E7D74;
+	text-decoration: none;
+}
+
+a:hover {
+	color: #256861;
+}
+
+/* Application container */
+#Docuserve-Application-Container {
+	min-height: 100vh;
+}
+
+/* Utility: scrollbar styling */
+::-webkit-scrollbar {
+	width: 8px;
+}
+
+::-webkit-scrollbar-track {
+	background: #F5F0E8;
+}
+
+::-webkit-scrollbar-thumb {
+	background: #D4CCBE;
+	border-radius: 4px;
+}
+
+::-webkit-scrollbar-thumb:hover {
+	background: #B5AA9A;
+}
+
+/* Responsive adjustments */
+@media (max-width: 768px) {
+	html {
+		font-size: 14px;
+	}
+
+	#Docuserve-Sidebar-Container {
+		display: none;
+	}
+
+	.docuserve-body {
+		flex-direction: column;
+	}
+}

package/docs/getting-started.md

@@ -0,0 +1,106 @@
+# Getting Started
+
+## Installation
+
+```bash
+npm install fable orator orator-serviceserver-restify
+```
+
+## Setup
+
+The Restify service server is registered with Fable as the `OratorServiceServer` service type. Orator will use it automatically once it's instantiated:
+
+```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 service types
+_Fable.serviceManager.addServiceType('Orator', libOrator);
+_Fable.serviceManager.addServiceType('OratorServiceServer', libOratorServiceServerRestify);
+
+// Instantiate (order doesn't matter -- Orator finds the service server during initialization)
+_Fable.serviceManager.instantiateServiceProvider('Orator');
+_Fable.serviceManager.instantiateServiceProvider('OratorServiceServer');
+```
+
+## Defining Routes
+
+Register route handlers on the service server using standard HTTP verb methods:
+
+```javascript
+const tmpServiceServer = _Fable.Orator.serviceServer;
+
+// GET request
+tmpServiceServer.get('/api/items',
+	(pRequest, pResponse, fNext) =>
+	{
+		pResponse.send([{ id: 1, name: 'Item One' }]);
+		return fNext();
+	});
+
+// GET with URL parameters
+tmpServiceServer.get('/api/items/:id',
+	(pRequest, pResponse, fNext) =>
+	{
+		pResponse.send({ id: pRequest.params.id });
+		return fNext();
+	});
+
+// POST with body parsing
+tmpServiceServer.postWithBodyParser('/api/items',
+	(pRequest, pResponse, fNext) =>
+	{
+		let tmpNewItem = pRequest.body;
+		pResponse.send({ created: true, item: tmpNewItem });
+		return fNext();
+	});
+
+// PUT with body parsing
+tmpServiceServer.putWithBodyParser('/api/items/:id',
+	(pRequest, pResponse, fNext) =>
+	{
+		pResponse.send({ updated: true, id: pRequest.params.id });
+		return fNext();
+	});
+
+// DELETE
+tmpServiceServer.del('/api/items/:id',
+	(pRequest, pResponse, fNext) =>
+	{
+		pResponse.send({ deleted: true });
+		return fNext();
+	});
+```
+
+## Starting the Server
+
+```javascript
+_Fable.Orator.startService(
+	() =>
+	{
+		_Fable.log.info('Server is ready');
+	});
+```
+
+## Stopping the Server
+
+```javascript
+_Fable.Orator.stopService(
+	() =>
+	{
+		_Fable.log.info('Server stopped');
+	});
+```
+
+## Next Steps
+
+- [Configuration](configuration.md) - Customize the Restify server
+- [Middleware](middleware.md) - Add request processing middleware
+- [Body Parsing](body-parsing.md) - Configure request body parsing

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="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/middleware.md

@@ -0,0 +1,79 @@
+# Middleware
+
+The Restify service server supports two types of middleware, matching Restify's own middleware pipeline.
+
+## Post-Routing Middleware (use)
+
+Middleware registered with `use()` runs after the route has been matched but before the route handler executes:
+
+```javascript
+_Fable.Orator.serviceServer.use(
+	(pRequest, pResponse, fNext) =>
+	{
+		_Fable.log.trace(`${pRequest.method} ${pRequest.url}`);
+		return fNext();
+	});
+```
+
+This is the standard middleware pattern. The base class validates that the parameter is a function, then the Restify implementation passes it to the underlying Restify server's `use()` method.
+
+## Pre-Routing Middleware (pre)
+
+Middleware registered with `pre()` runs before the route is even matched. This is useful for things like request sanitization, CORS headers, or URL rewriting:
+
+```javascript
+_Fable.Orator.serviceServer.pre(
+	(pRequest, pResponse, fNext) =>
+	{
+		// Runs before routing
+		return fNext();
+	});
+```
+
+## Middleware Order
+
+```
+Incoming Request
+    ↓
+pre() middleware (before routing)
+    ↓
+Route Matching
+    ↓
+use() middleware (after routing)
+    ↓
+Route Handler(s)
+    ↓
+Response
+```
+
+## Example: Request Logging
+
+```javascript
+_Fable.Orator.serviceServer.use(
+	(pRequest, pResponse, fNext) =>
+	{
+		let tmpStartTime = Date.now();
+
+		pResponse.on('finish',
+			() =>
+			{
+				let tmpDuration = Date.now() - tmpStartTime;
+				_Fable.log.info(`${pRequest.method} ${pRequest.url} ${pResponse.statusCode} ${tmpDuration}ms`);
+			});
+
+		return fNext();
+	});
+```
+
+## Example: CORS Headers
+
+```javascript
+_Fable.Orator.serviceServer.pre(
+	(pRequest, pResponse, fNext) =>
+	{
+		pResponse.header('Access-Control-Allow-Origin', '*');
+		pResponse.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, PATCH, OPTIONS');
+		pResponse.header('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+		return fNext();
+	});
+```