diff --git a/README.md b/README.md index 932822d..9a2db22 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,42 @@ Caronte is an HTTP programmable proxying library that supports websockets. It is suitable for implementing components such as proxies and load balancers. +### Core Concept + +A new proxy is created by calling `createProxyServer` and passing +an `options` object as argument ([valid properties are available here](https://github.com/yawnt/caronte/blob/master/lib/caronte.js#L26-L39)) + +```javascript +var caronte = require('caronte'); + +var proxy = caronte.createProxyServer(options); +``` + +An object will be returned with four values: + +* web `req, res, [options]` (used for proxying regular HTTP(S) requests) +* ws `req, socket, head, [options]` (used for proxying WS(S) requests) +* ee (an EventEmitter2 that emits events, you can hook into them to customize behaviour) +* listen `port` (a function that wraps the object in a webserver, for your convenience) + +Is it then possible to proxy requests by calling these functions + +```javascript +require('http').createServer(function(req, res) { + proxy.web(req, res, { target: 'http://mytarget.com:8080' }); +}); +``` + +When a request is proxied it follows two different pipelines ([available here](https://github.com/yawnt/caronte/tree/master/lib/caronte/passes)) +which apply trasformations to both the `req` and `res` object. +The first pipeline (ingoing) is responsible for the creation and manipulation of the stream that connects your client to the target. +The second pipeline (outgoing) is responsible for the creation and manipulation of the stream that, from your target, returns datas +to the client. + +You can easily add a `pass` (stages) into both the pipelines (XXX: ADD API). + +In addition, every stage emits a corresponding event so introspection during the process is always available. + ### Contributing and Issues * Search on Google/Github