orator-http-proxy 1.0.0 → 1.0.4

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,7 +1,111 @@
-# Orator Service Server Proxy
+# Orator HTTP Proxy
 
-Proxy API requests from a stable prefix.  This lets you map /1.0/ to one set
-of servers, /1.1/ to another and /1.0/CustomApi* to a third.
+> HTTP proxy pass-through for Orator service servers
 
-Meant to be used for local development and pass-through API for front-side
-web servers, not an industrial-grade API routing service.
+Orator HTTP Proxy provides a simple way to forward incoming requests to a backend service. Register route prefixes that should be proxied, point them at a destination URL, and the module handles the rest. This is useful for microservice architectures where a frontend server needs to proxy API calls to a separate backend service.
+
+## Features
+
+- **Route-Based Proxying** - Proxy specific route prefixes to a destination URL
+- **Multi-Verb Support** - Proxies GET, PUT, POST, and DELETE requests
+- **Configurable** - Settings via constructor options or Fable settings
+- **HTTP-to-HTTPS** - Handles proxying from HTTP origins to HTTPS destinations
+- **Fable Service Provider** - Registers as a standard Fable service
+
+## Quick Start
+
+```javascript
+const libFable = require('fable');
+const libOrator = require('orator');
+const libOratorServiceServerRestify = require('orator-serviceserver-restify');
+const libOratorHTTPProxy = require('orator-http-proxy');
+
+const _Fable = new libFable({
+	Product: 'MyProxyServer',
+	ServicePort: 8080
+});
+
+// Set up Orator with Restify
+_Fable.serviceManager.addServiceType('Orator', libOrator);
+_Fable.serviceManager.addServiceType('OratorServiceServer', libOratorServiceServerRestify);
+_Fable.serviceManager.instantiateServiceProvider('Orator');
+_Fable.serviceManager.instantiateServiceProvider('OratorServiceServer');
+
+// Set up the proxy
+_Fable.serviceManager.addServiceType('OratorHTTPProxy', libOratorHTTPProxy);
+_Fable.serviceManager.instantiateServiceProvider('OratorHTTPProxy',
+	{
+		DestinationURL: 'http://backend-api:3000/',
+		RequestPrefixList: ['/api/v1/*']
+	});
+
+// Initialize Orator and connect proxy routes
+_Fable.Orator.initialize(
+	() =>
+	{
+		_Fable.OratorHTTPProxy.connectProxyRoutes();
+		_Fable.Orator.startService();
+	});
+```
+
+## Installation
+
+```bash
+npm install orator-http-proxy
+```
+
+## Configuration
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `DestinationURL` | string | `"http://127.0.0.1/"` | URL to proxy requests to |
+| `RequestPrefixList` | array | `["/1.0/*"]` | Route prefixes to intercept and proxy |
+| `LogLevel` | number | `0` | Logging verbosity (higher = more output) |
+| `httpProxyOptions` | object | `{}` | Additional options passed to `http-proxy` |
+
+Settings can also be provided via Fable settings:
+
+| Fable Setting | Maps To |
+|---------------|---------|
+| `OratorHTTPProxyDestinationURL` | `DestinationURL` |
+| `OratorHTTPProxyRequestPrefixList` | `RequestPrefixList` |
+| `OratorHTTPProxyLogLevel` | `LogLevel` |
+
+## API
+
+### connectProxyRoutes(pRequestPrefixList, pProxyURL)
+
+Create proxy handlers for the specified route prefixes. Both parameters are optional and fall back to the configured defaults.
+
+```javascript
+// Use configured defaults
+_Fable.OratorHTTPProxy.connectProxyRoutes();
+
+// Override at call time
+_Fable.OratorHTTPProxy.connectProxyRoutes(
+	['/api/*', '/data/*'],
+	'http://other-backend:4000/'
+);
+```
+
+## 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-restify](https://github.com/stevenvelozo/orator-serviceserver-restify) - Restify service server implementation
+- [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/debug/Harness.js

@@ -4,7 +4,9 @@ const defaultFableSettings = (
 	{
 		Product:'Orator-Proxy',
 		ProductVersion: '1.0.0',
-		APIServerPort: 8765
+		APIServerPort: 8765,
+
+		OratorHTTPProxyDestinationURL: 'http://127.0.0.1:8086/'
 	});
 
 // Initialize Fable
@@ -33,7 +35,7 @@ tmpAnticipate.anticipate(
 		// Create an endpoint.  This can also be done after the service is started.
 		_Orator.serviceServer.get
 		(
-			'/test/:hash',
+			'/1.0/test/:hash',
 			(pRequest, pResponse, fNext) =>
 			{
 				// Send back the request parameters
@@ -45,7 +47,17 @@ tmpAnticipate.anticipate(
 		return fStageComplete();
 	});
 
+// Add the http proxy service
+const libOratorServeStatic = require(`../source/Orator-HTTP-Proxy.js`);
+_Fable.serviceManager.addServiceType('OratorHTTPProxy', libOratorServeStatic);
+_Fable.serviceManager.instantiateServiceProvider('OratorHTTPProxy', {LogLevel: 2});
 // Proxy all /1.0/ requests to the locally-running bookstore service (you need to run this from https://github.com/stevenvelozo/retold-harness ... it's a one-liner to start the service)
+tmpAnticipate.anticipate(
+	(fNext)=>
+	{
+		_Fable.OratorHTTPProxy.connectProxyRoutes();
+		return fNext();
+	});
 
 
 // Now start the service server.

package/debug/serve/index.html

@@ -0,0 +1,9 @@
+<html>
+<head>
+	<title>Debug</title>
+</head>
+<body>
+	<h1>Debug</h1>
+	<p>Debugging is the process of finding and resolving defects or problems within a computer program that prevent correct operation of computer software or a system.</p>
+</body>
+</html>

package/docs/README.md

@@ -0,0 +1,67 @@
+# Orator HTTP Proxy
+
+> HTTP proxy pass-through for Orator service servers
+
+Orator HTTP Proxy is a Fable service that forwards incoming requests matching specified route prefixes to a backend destination URL. It uses the [http-proxy](https://github.com/http-party/node-http-proxy) library under the hood.
+
+This is a common pattern in microservice architectures: a frontend Orator server handles static files and client-facing routes, while proxying API calls to a separate backend service. Instead of configuring a reverse proxy at the infrastructure level, you can handle it right in your application.
+
+## Features
+
+- **Route-Based Proxying** - Proxy specific route prefixes to a destination URL
+- **Multi-Verb Support** - Proxies GET, PUT, POST, and DELETE requests
+- **Configurable** - Settings via constructor options or Fable settings
+- **HTTP-to-HTTPS** - Handles proxying from HTTP origins to HTTPS destinations
+- **Fable Service Provider** - Registers as a standard Fable service
+
+## How It Works
+
+When you call `connectProxyRoutes()`, the module registers GET, PUT, POST, and DELETE handlers on the Orator service server for each prefix in the `RequestPrefixList`. When a matching request comes in, it is forwarded to the `DestinationURL` using `http-proxy`.
+
+```
+Client Request: GET /api/v1/users
+    ↓
+Orator ServiceServer matches /api/v1/*
+    ↓
+HTTP Proxy forwards to http://backend:3000/api/v1/users
+    ↓
+Backend response is returned to the client
+```
+
+## Quick Start
+
+```javascript
+const libFable = require('fable');
+const libOrator = require('orator');
+const libOratorServiceServerRestify = require('orator-serviceserver-restify');
+const libOratorHTTPProxy = require('orator-http-proxy');
+
+const _Fable = new libFable({
+	Product: 'MyProxyServer',
+	ServicePort: 8080
+});
+
+_Fable.serviceManager.addServiceType('Orator', libOrator);
+_Fable.serviceManager.addServiceType('OratorServiceServer', libOratorServiceServerRestify);
+_Fable.serviceManager.addServiceType('OratorHTTPProxy', libOratorHTTPProxy);
+_Fable.serviceManager.instantiateServiceProvider('Orator');
+_Fable.serviceManager.instantiateServiceProvider('OratorServiceServer');
+_Fable.serviceManager.instantiateServiceProvider('OratorHTTPProxy',
+	{
+		DestinationURL: 'http://backend-api:3000/',
+		RequestPrefixList: ['/api/v1/*']
+	});
+
+_Fable.Orator.initialize(
+	() =>
+	{
+		_Fable.OratorHTTPProxy.connectProxyRoutes();
+		_Fable.Orator.startService();
+	});
+```
+
+## Related Packages
+
+- [orator](https://github.com/stevenvelozo/orator) - Main Orator service abstraction
+- [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,8 @@
+- Getting Started
+
+  - [Introduction](/)
+  - [Getting Started](getting-started.md)
+
+- Reference
+
+  - [Configuration](configuration.md)

package/docs/configuration.md

@@ -0,0 +1,87 @@
+# Configuration
+
+## Options
+
+Configuration can be provided through constructor options, Fable settings, or both. The module checks in this order:
+
+1. Constructor options (passed when instantiating the service)
+2. Fable settings (with `OratorHTTPProxy` prefix)
+3. Built-in defaults
+
+### Constructor Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `DestinationURL` | string | `"http://127.0.0.1/"` | URL to proxy requests to |
+| `RequestPrefixList` | array | `["/1.0/*"]` | Route prefixes to intercept and proxy |
+| `LogLevel` | number | `0` | Logging verbosity (0 = quiet, higher = more output) |
+| `httpProxyOptions` | object | `{}` | Additional options passed to `http-proxy` |
+
+### Fable Settings
+
+| Fable Setting | Maps To |
+|---------------|---------|
+| `OratorHTTPProxyDestinationURL` | `DestinationURL` |
+| `OratorHTTPProxyRequestPrefixList` | `RequestPrefixList` |
+| `OratorHTTPProxyLogLevel` | `LogLevel` |
+
+### Example: Configuration via Options
+
+```javascript
+_Fable.serviceManager.instantiateServiceProvider('OratorHTTPProxy',
+	{
+		DestinationURL: 'http://backend:3000/',
+		RequestPrefixList: ['/api/*'],
+		LogLevel: 2
+	});
+```
+
+### Example: Configuration via Fable Settings
+
+```javascript
+const _Fable = new libFable({
+	Product: 'MyProxyServer',
+	ServicePort: 8080,
+	OratorHTTPProxyDestinationURL: 'http://backend:3000/',
+	OratorHTTPProxyRequestPrefixList: ['/api/*'],
+	OratorHTTPProxyLogLevel: 2
+});
+
+_Fable.serviceManager.instantiateServiceProvider('OratorHTTPProxy');
+```
+
+### Example: JSON Configuration File
+
+```json
+{
+	"Product": "MyProxyServer",
+	"ServicePort": 8080,
+	"OratorHTTPProxyDestinationURL": "http://backend:3000/",
+	"OratorHTTPProxyRequestPrefixList": ["/api/*"],
+	"OratorHTTPProxyLogLevel": 0
+}
+```
+
+## HTTP Proxy Options
+
+The `httpProxyOptions` object is passed directly to the `http-proxy` library. Some useful options:
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `secure` | boolean | Verify SSL certificates (default: `false` in proxy handler) |
+| `changeOrigin` | boolean | Change the origin header to the target URL |
+| `headers` | object | Additional headers to add to proxied requests |
+| `ws` | boolean | Enable WebSocket proxying |
+
+```javascript
+_Fable.serviceManager.instantiateServiceProvider('OratorHTTPProxy',
+	{
+		DestinationURL: 'https://secure-backend:443/',
+		RequestPrefixList: ['/api/*'],
+		httpProxyOptions:
+		{
+			changeOrigin: true,
+			headers: { 'X-Proxy-Source': 'orator' }
+		}
+	});
+```

package/docs/cover.md

@@ -0,0 +1,11 @@
+# Orator HTTP Proxy <small>1</small>
+
+> HTTP proxy pass-through for Orator service servers
+
+- Route-based proxying to backend services
+- Supports GET, PUT, POST, and DELETE
+- Configurable via options or Fable settings
+- Handles HTTP-to-HTTPS proxying
+
+[GitHub](https://github.com/stevenvelozo/orator-http-proxy)
+[Get Started](#orator-http-proxy)

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 orator-http-proxy
+```
+
+You will also need `orator` and a service server implementation (like `orator-serviceserver-restify`):
+
+```bash
+npm install fable orator orator-serviceserver-restify orator-http-proxy
+```
+
+## Basic Setup
+
+```javascript
+const libFable = require('fable');
+const libOrator = require('orator');
+const libOratorServiceServerRestify = require('orator-serviceserver-restify');
+const libOratorHTTPProxy = require('orator-http-proxy');
+
+const _Fable = new libFable({
+	Product: 'MyProxyServer',
+	ServicePort: 8080
+});
+
+// Set up Orator with Restify
+_Fable.serviceManager.addServiceType('Orator', libOrator);
+_Fable.serviceManager.addServiceType('OratorServiceServer', libOratorServiceServerRestify);
+_Fable.serviceManager.instantiateServiceProvider('Orator');
+_Fable.serviceManager.instantiateServiceProvider('OratorServiceServer');
+
+// Set up the proxy
+_Fable.serviceManager.addServiceType('OratorHTTPProxy', libOratorHTTPProxy);
+_Fable.serviceManager.instantiateServiceProvider('OratorHTTPProxy',
+	{
+		DestinationURL: 'http://backend-api:3000/',
+		RequestPrefixList: ['/api/v1/*']
+	});
+
+// Initialize and connect
+_Fable.Orator.initialize(
+	() =>
+	{
+		_Fable.OratorHTTPProxy.connectProxyRoutes();
+		_Fable.Orator.startService();
+	});
+```
+
+## Multiple Proxy Prefixes
+
+You can proxy multiple route prefixes to the same backend:
+
+```javascript
+_Fable.serviceManager.instantiateServiceProvider('OratorHTTPProxy',
+	{
+		DestinationURL: 'http://backend-api:3000/',
+		RequestPrefixList: ['/api/v1/*', '/api/v2/*', '/auth/*']
+	});
+```
+
+## Multiple Backends
+
+To proxy different prefixes to different backends, instantiate multiple proxy services:
+
+```javascript
+_Fable.serviceManager.instantiateServiceProvider('OratorHTTPProxy',
+	{
+		DestinationURL: 'http://api-service:3000/',
+		RequestPrefixList: ['/api/*']
+	}, 'APIProxy');
+
+_Fable.serviceManager.instantiateServiceProvider('OratorHTTPProxy',
+	{
+		DestinationURL: 'http://auth-service:4000/',
+		RequestPrefixList: ['/auth/*']
+	}, 'AuthProxy');
+
+// Connect both after Orator initializes
+_Fable.Orator.initialize(
+	() =>
+	{
+		_Fable.servicesMap['OratorHTTPProxy']['APIProxy'].connectProxyRoutes();
+		_Fable.servicesMap['OratorHTTPProxy']['AuthProxy'].connectProxyRoutes();
+		_Fable.Orator.startService();
+	});
+```
+
+## Combining with Static Files
+
+A common pattern is to serve a frontend application statically while proxying API calls to a backend:
+
+```javascript
+_Fable.Orator.initialize(
+	() =>
+	{
+		// Proxy API calls to the backend
+		_Fable.OratorHTTPProxy.connectProxyRoutes();
+
+		// Serve static files for everything else
+		_Fable.Orator.addStaticRoute('./public/', 'index.html', '/*');
+
+		_Fable.Orator.startService();
+	});
+```

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/retold-catalog.json

@@ -0,0 +1,41 @@
+{
+	"Generated": "2026-02-18T03:42:52.610Z",
+	"GitHubOrg": "stevenvelozo",
+	"DefaultBranch": "master",
+	"Groups": [
+		{
+			"Name": "Debug",
+			"Key": "debug",
+			"Description": "",
+			"Modules": [
+				{
+					"Name": "serve",
+					"Repo": "serve",
+					"Group": "debug",
+					"Branch": "master",
+					"HasDocs": false,
+					"HasCover": false,
+					"Sidebar": [],
+					"DocFiles": []
+				}
+			]
+		},
+		{
+			"Name": "Dist",
+			"Key": "dist",
+			"Description": "",
+			"Modules": [
+				{
+					"Name": "indoctrinate_content_staging",
+					"Repo": "indoctrinate_content_staging",
+					"Group": "dist",
+					"Branch": "master",
+					"HasDocs": false,
+					"HasCover": false,
+					"Sidebar": [],
+					"DocFiles": []
+				}
+			]
+		}
+	]
+}

package/docs/retold-keyword-index.json

@@ -0,0 +1,19 @@
+{
+	"Generated": "2026-02-18T03:42:52.690Z",
+	"DocumentCount": 0,
+	"LunrIndex": {
+		"version": "2.3.9",
+		"fields": [
+			"title",
+			"module",
+			"group",
+			"body"
+		],
+		"fieldVectors": [],
+		"invertedIndex": [],
+		"pipeline": [
+			"stemmer"
+		]
+	},
+	"Documents": {}
+}