Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/argo/argo
Argo is a modular HTTP gateway for Web APIs.
https://github.com/argo/argo
Last synced: about 2 months ago
JSON representation
Argo is a modular HTTP gateway for Web APIs.
- Host: GitHub
- URL: https://github.com/argo/argo
- Owner: argo
- License: mit
- Created: 2012-11-27T16:47:11.000Z (almost 12 years ago)
- Default Branch: master
- Last Pushed: 2020-07-21T03:16:43.000Z (about 4 years ago)
- Last Synced: 2024-07-27T00:24:41.862Z (about 2 months ago)
- Language: JavaScript
- Homepage:
- Size: 318 KB
- Stars: 87
- Watchers: 16
- Forks: 7
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-nodejs - argo - An extensible, asynchronous HTTP reverse proxy and origin server.  (Repository / HTTP)
README
# Argo
An extensible, asynchronous HTTP reverse proxy and origin server.
## Examples
### Adding Cross-Origin Resource Sharing
Setup the server:
```javascript
var argo = require('argo');
argo()
.use(function(handle) {
handle('response', function(env, next) {
env.response.setHeader('Access-Control-Allow-Origin', '*');
next(env);
});
})
.target('http://weather.yahooapis.com')
.listen(1337);
```
Make a request:
```bash
$ curl -i http://localhost:1337/forecastrss?w=2467861
HTTP/1.1 200 OK
Date: Thu, 28 Feb 2013 20:55:03 GMT
Content-Type: text/xml;charset=UTF-8
Connection: keep-alive
Server: YTS/1.20.13
Access-Control-Allow-Origin: *
Content-Length: 2337
```
### Serving an API Response
Setup the server:
```javascript
var argo = require('argo');
argo()
.get('^/dogs$', function(handle) {
handle('request', function(env, next) {
env.response.statusCode = 200;
env.response.body = { dogs: ['Alfred', 'Rover', 'Dino'] };
next(env);
});
})
.listen(1337);
```
Make a request:
```bash
$ curl -i http://localhost:1337/dogs
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 34
Date: Thu, 28 Feb 2013 20:44:46 GMT
Connection: keep-alive
{"dogs":["Alfred","Rover","Dino"]}
```
## Install
```bash
$ npm install argo
```
## Documentation
* [handleFunction](#handleFunction)
* [use(handleFunction)](#usehandle)
* [use(package)](#usepackage)
* [target](#target)
* [route](#route)
* Method filters
* [get](#get)
* [post](#post)
* [put](#put)
* [head](#head)
* [del](#del)
* [options](#options)
* [trace](#trace)
* [copy](#copy)
* [lock](#lock)
* [mkcol](#mkcol)
* [move](#move)
* [propfind](#propfind)
* [proppatch](#proppatch)
* [unlock](#unlock)
* [report](#report)
* [mkactivity](#mkactivity)
* [checkout](#checkout)
* [merge](#merge)
* [msearch](#msearch)
* [notify](#notify)
* [subscribe](#subscribe)
* [unsubscribe](#unsubscribe)
* [patch](#patch)
* [search](#search)
* [map](#map)
* [include](#include)
* [listen](#listen)
* [Error Handling](#error-handling)
## Usage
### handleFunction(type, [options], callback)
* `type`: `'request'` or `'response'`
* `options`: Mostly used for internal purposes. Optional.
* `callback(env, next)`: A request or response callback. `env` is an environment context that is passed to every handler, and `next` is a reference to the next function in the pipeline.
When the handler is complete and wishes to pass to the next function in the pipeline, it must call `next(env)`.
`handleFunction` is used to set up request and response handlers.
```javascript
argo()
//For every request add 'X-Custom-Header' with value 'Yippee!'
.use(function(handle) {
handle('request', function(env, next) {
env.request.headers['X-Custom-Header'] = 'Yippee!';
next(env);
});
})
```
### use(package)
Alias for `include(package)`.
`target` is used for proxying requests to a backend server.
* `uri`: a string pointing to the target URI.
Example:
```javascript
argo()
.target('http://weather.yahooapis.com')
```
### route(path, [options], handleFunction)
* `path`: a regular expression used to match HTTP Request URI path.
* `options`: an object with a `methods` property to filter HTTP methods (e.g., `{ methods: ['GET','POST'] }`). Optional.
* `handleFunction`: Same as in `use`.
Example:
```javascript
argo()
.route('^/greeting$', function(handle) {
handle('request', function(env, next) {
env.response.statusCode = 200;
env.response.headers = { 'Content-Type': 'text/plain' };
env.response.body = 'Hello World!';
next(env);
});
})
```
### Method filters
#### get(path, handleFunction)
#### post(path, handleFunction)
#### put(path, handleFunction)
#### head(path, handleFunction)
#### del(path, handleFunction)
#### options(path, handleFunction)
#### trace(path, handleFunction)
#### copy(path, handleFunction)
#### lock(path, handleFunction)
#### mkcol(path, handleFunction)
#### move(path, handleFunction)
#### propfind(path, handleFunction)
#### proppatch(path, handleFunction)
#### unlock(path, handleFunction)
#### report(path, handleFunction)
#### mkactivity(path, handleFunction)
#### checkout(path, handleFunction)
#### merge(path, handleFunction)
#### msearch(path, handleFunction)
#### notify(path, handleFunction)
#### subscribe(path, handleFunction)
#### unsubscribe(path, handleFunction)
#### patch(path, handleFunction)
#### search(path, handleFunction)
Method filters built on top of `route`. `del` and `msearch` correspond to
the DELETE and M-SEARCH methods, respectively.
Example:
```javascript
argo()
.get('^/puppies$', function(handle) {
handle('request', function(env, next) {
env.response.body = JSON.stringify([{name: 'Sparky', breed: 'Fox Terrier' }]);
next(env);
});
})
```
### map(path, [options], argoSegmentFunction)
`map` is used to delegate control to sub-Argo instances based on a request URI path.
* `path`: a regular expression used to match the HTTP Request URI path.
* `options`: an object with a `methods` property to filter HTTP methods (e.g., `{ methods: ['GET','POST'] }`). Optional.
* `argoSegmentFunction`: a function that is passed an instance of `argo` for additional setup.
Example:
```javascript
argo()
.map('^/payments', function(server) {
server
.use(oauth)
.target('http://backend_payment_server');
})
```
### include(package)
* `package`: An object that contains a `package` property.
The `package` property is a function that takes an argo instance as a paramter and returns an object that contains a `name` and an `install` function.
Example:
```javascript
var superPackage = function(argo) {
return {
name: 'Super Package',
install: function() {
argo
.use(oauth)
.route('^/super$', require('./super'));
}
};
};
argo()
.include({ package: superPackage})
```
### listen(port)
* `port`: A port on which the server should listen.
Argo allows a special `error` handler for capturing state when an uncaught exception occurs.
```javascript
argo()
.use(function(handle) {
handle('error', function(env, error, next) {
console.log(error.message);
env.response.statusCode = 500;
env.response.body = 'Internal Server Error';
next(env);
process.exit();
});
})
.get('^/$', function(handle) {
handle('request', function(env, next) {
env.response.body = 'Hello World!';
next(env);
});
})
.get('^/explode$', function(handle) {
handle('request', function(env, next) {
setImmediate(function() { throw new Error('Ahoy!'); });
});
})
.listen(3000);
```
Unlike other named pipelines, there should be only one error handler assigned to an Argo server. It is recommended to exit the process once an error has been handled. This feature uses [domains](http://nodejs.org/api/domain.html).
See [`cluster.js`](https://github.com/argo/argo/blob/master/example/cluster.js) for an example of using error handling to restart workers in a cluster.
## Tests
Unit tests:
```bash
$ npm test
```
Test Coverage:
```bash
$ npm run-script coverage
```
## License
MIT