# @namatery/blackbird

> Blackbird is a reverse proxy, with built-in node cluster and load balancing.

Latest version **1.0.3** (published 2023-07-28) · GPL license · 0 weekly downloads

## Install

```sh
npm install @namatery/blackbird
pnpm add @namatery/blackbird
yarn add @namatery/blackbird
bun add @namatery/blackbird
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.3 |
| Published | 2023-07-28 |
| First published | 2023-07-28 |
| Weekly downloads | 0 |
| License | GPL |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 7 |
| Unpacked size | 112.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | Alireza Rezapour |
| Maintainers | namatery |
| Keywords | proxy, reverse-proxy, blackbird |

## Links

- npm: https://www.npmjs.com/package/@namatery/blackbird
- Repository: https://github.com/alireza12prom/blackbird
- Homepage: https://github.com/alireza12prom/blackbird#readme
- Issues: https://github.com/alireza12prom/blackbird/issues
- npm.io page: https://npm.io/package/@namatery/blackbird

## Dependencies (7)

- [cors](https://npm.io/package/cors.md) ^2.8.5
- [chalk](https://npm.io/package/chalk.md) ^4.1.2
- [socket.io](https://npm.io/package/socket.io.md) ^4.7.1
- [url-parse](https://npm.io/package/url-parse.md) ^1.5.10
- [valid-url](https://npm.io/package/valid-url.md) ^1.0.9
- [http-proxy](https://npm.io/package/http-proxy.md) ^1.18.1
- [url-join-ts](https://npm.io/package/url-join-ts.md) ^1.0.5

## Recent versions

- 1.0.3 (latest) — 2023-07-28
- 1.0.2 — 2023-07-28
- 1.0.1 — 2023-07-28

## README

# Blackbird
Blackbird is a reverse proxy, with built-in node cluster and load balancing.

## Installation

To install `Blackbird` you can easily run below command:

```
npm i @namatery/blackbird
```

## How to use Blackbird?

First of all, create a proxy server like below:

```
const proxy = new ReversProxy({
  http: {
    port: 3000,
  },
});
```


> NOTE: `http.port` is required.


## Registering

To register a domain, do like this:

```
proxy.register({
  source: 'http://localhost:3000/',
  target: 'http://test.com/',
  opts: {
    redirect: false,
    ws: false,
  },
});
```

### Options
- `source` [required]: The url that client make a request to it. 
- `target` [required]: The url that if client makes a reqeust to `source`, Blackbird redirects the request to it.
- `redirect` [optional]: If set `true`, Blackbird automatically redirects to HTTPS.
- `ws` [optional]: If set `true`, Blackbird allows clients to make socket connection.

### Notice
- You can set several `target` for a single `source`.
- Before set `redirect` as `true`, make sure you have configured proxy for HTTPS requests.
- For load balancing, Blackbird uses [round-robin] algorithm.


## Enable HTTPS

To enable HTTPS, you can pass creditions like below:

```
const proxy = new ReversProxy({
  http: {
    port: 3000,
  },
  https: {
    port: 9000,
    cert: 'path/to/cert.pem',
    key: 'path/to/key.pem',
    ca: 'path/to/ca.pem',
  },
});
```

> NOTE 1: `port` is required.

> NOTE 2: `cert`, `key` and `ca` can be buffers. (`ca` is optional)

In the above example, the creditoins that we set wil use for all registerd domain, but you can also attach the creditions for a specifyed domain.

```
proxy.attachSSL({
  hostname: 'localhost:3000',
  cert: 'path/to/cert.pem',
  key: 'path/to/key.pem',
  ca: 'path/to/ca.pem',
});
```

> NOTE 1: `hostname` is the hostname that we registerd as `source` above as you saw.

> NOTE 2: You can't attach several creditions for a single `hostname`.


## How to run our proxy?

To start proxy, you have two options. You can either run it in the normal way like below:

```
proxy.start();
```

Or run it in the cluster mode like below:

```
proxy.startCluster(3);
```

In this case Blackbird will run three instances of our proxy. To learn more about `cluster` in nodejs go to [node-cluster].

## Does Blackbird handle CORS in its own?

Yes! Blackbird uses [Express Cors] package to handle this concept and you can enable it like below:
```
const proxy = new ReversProxy({
  http: {
    port: 3000,
  },
  cors: {
    origin: 'http://localhost:3000/'
  }
});
```

> NOTE 1: All the options is similar with [Express Cors] package.


## TODOs
- [x] Writing Unite test for Table repository.
- [x] Writing Unite test for SSL repository.
- [ ] CORS error on redirecting from http to https.
- [ ] CORS error on websocket communication.
- [ ] Writing Unite test for proxy class.


[round-robin]: https://en.wikipedia.org/wiki/Round-robin_scheduling
[node-cluster]: https://nodejs.org/api/cluster.html#:~:text=Clusters%20of%20Node.js%20processes,a%20single%20Node.js%20instance.
[Express Cors]: https://github.com/expressjs/cors

---
_Source: https://npm.io/package/@namatery/blackbird · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._