๐ rocket-booster is a serverless reverse proxy and load balancing library built for Cloudflare Workers. It sits in front of web servers (e.g. web application, storage platform, or RESTful API), forwards HTTP requests or WebSocket traffics from clients to upstream servers and transforms responses with several optimizations to improve page loading time.
- โก Serverless: Deploy instantly to the auto-scaling serverless platform built by Cloudflare. No virtual machines, servers, or containers to manage.
โ๏ธ Load Balancing: Distribute incoming traffics evenly among different upstream servers.- โ๏ธ Hackable: Deliver unique content based on visitor attributes, conduct A/B testing, or build custom middleware to hook into the lifecycle. (Experimental)
- ๐ TypeScript: Extensive type declaration with TSDoc.
- Install Wrangler CLI and generate a project from the rocket-booster-template
npm install -g @cloudflare/wrangler
# JavaScript Template
wrangler generate booster-app https://github.com/booster-labs/rocket-booster-template
- Install dependencies and edit the configuration in
src/index.js
cd booster-app
npm install
- Login and publish to Cloudflare Workers
wrangler login
wrangler publish
- Install the
rocket-booster
package
npm install --save rocket-booster
- Import the
useProxy
function fromrocket-booster
and invoke it with a configuration object. The function returns an object with anapply()
method, which takes the inbound Request to the Worker, and returns the Response fetched from the upstream server.
import useProxy from 'rocket-booster';
const config = {
upstream: {
domain: 'example.com',
protocol: 'https',
},
};
addEventListener('fetch', (event) => {
const proxy = useProxy(config);
const response = proxy.apply(event.request);
event.respondWith(response);
});
- Edit the configuration object to change the request and response. For example, the configuration below will add the header
Access-Control-Allow-Origin: *
to each response from the upstream server, which allows any origin to access the server.
const config = {
upstream: {
domain: 'example.com',
protocol: 'https',
},
cors: {
origin: '*',
},
};
- Build and publish to Cloudflare Workers
wrangler build
wrangler publish
Set up a reverse proxy for https://developer.mozilla.org:
const config = {
upstream: {
domain: 'developer.mozilla.org',
protocol: 'https',
},
};
rocket-booster
could proxy WebSocket traffic to upstream servers. No additional configuration is required. Set up a reverse proxy for wss://echo.websocket.org:
const config = {
upstream: {
domain: 'echo.websocket.org',
protocol: 'https',
},
};
rocket-booster
could set custom headers to request and response, add CORS header, or deliver custom error responses. Set up a reverse proxy for https://example.s3.amazonaws.com:
const config = {
upstream: {
domain: 'example.s3.amazonaws.com',
protocol: 'https',
},
header: {
response: {
'x-response-header': 'Hello from rocket-booster',
},
},
cors: {
origin: ['https://www.example.com'],
methods: ['GET', 'POST'],
credentials: true,
},
error: [{
errorCode: 404,
responsePath: '/404.html',
}],
};
domain
: The domain name of the upstream server.protocol
: The protocol scheme of the upstream server. (optional, defaults to'https'
)port
: The port of the upstream server. (optional, defaults to80
or443
based onprotocol
)path
: The path of the upstream server. (optional, defaults to'\'
)timeout
: The maximum wait time on a request to the upstream server. (optional, defaults to10000
)
const config = {
upstream: {
domain: 'httpbin.org',
protocol: 'https',
port: 443,
path: '/',
timeout: 10000,
},
/* ... */
};
To load balance HTTP traffic to a group of servers, pass an array of server configurations to upstream
. Each request will be forwarded to a randomly selected server. Other load balancing algorithms will be implemented in the future.
const config = {
upstream: [
{
domain: 's1.example.com',
protocol: 'https',
},
{
domain: 's2.example.com',
protocol: 'https',
},
{
domain: 's3.example.com',
protocol: 'https',
},
],
/* ... */
};
request
: Sets request header going upstream to the backend. Accepts an object. (optional, defaults to{}
)response
: Sets response header coming downstream to the client. Accepts an object. (optional, defaults to{}
)
const config = {
/* ... */
header: {
request: {
'x-example-header': 'hello server',
},
response: {
'x-example-header': 'hello client',
},
},
};
minify
: Remove unnecessary characters (like whitespace, comments, etc.) from HTML, CSS, and JavaScript files. (optional, defaults tofalse
)mirage
: Detect screen size and connection speed to optimally deliver images for the current browser window. (optional, defaults tofalse
)
const config = {
/* ... */
optimization: {
mirage: true,
minify: {
javascript: true,
css: true,
html: true,
},
},
};
Several optimizations are enabled by default.
- Brotli: Speed up page load times for visitorโs HTTPS traffic by applying Brotli compression.
- HTTP/2: Improve page load time by connection multiplexing, header compression, and server push.
- HTTP/3 with QUIC: Accelerate HTTP requests by using QUIC, which provides encryption and performance improvements compared to TCP and TLS.
- 0-RTT Connection Resumption: Improve performance for clients who have previously connected to the website.
forwarded
: Sets theX-Forwarded-For
,X-Forwarded-Host
, andX-Forwarded-Proto
headers. (optional, defaults tofalse
)hidePoweredBy
: Removes theX-Powered-By
header, which is set by default in some frameworks such as Express. (optional, defaults tofalse
)ieNoOpen
: Sets theX-Download-Options
header, which is specific to Internet Explorer 8. It forces potentially-unsafe downloads to be saved, mitigating execution of HTML in the website's context. (optional, defaults tofalse
)xssFilter
: Sets theX-XSS-Protection
header to0
to disable browsers' buggy cross-site scripting filter. (optional, defaults tofalse
)noSniff
: Sets theX-Content-Type-Options
header tonosniff
. This mitigates MIME type sniffing which can cause security vulnerabilities. (optional, defaults tofalse
)setCookie
: Sets theDomain
attribute of theSet-Cookie
header to the domain of the worker.
const config = {
/* ... */
security: {
fowarded: true,
hidePoweredBy: true,
ieNoOpen: true,
xssFilter: true,
noSniff: true,
setCookie: true,
},
};
-
origin
: Configures theAccess-Control-Allow-Origin
CORS header. (optional, defaults tofalse
)boolean
: set totrue
to reflect the request origin, or set tofalse
to disable CORS.string[]
: an array of acceptable origins.*
: allow any origin to access the resource.
-
methods
: Configures theAccess-Control-Allow-Methods
CORS header. Expects an array of valid HTTP methods or*
. (optional, defaults to reflecting the method specified in the requestโsAccess-Control-Request-Method
header) -
allowedHeaders
: Configures theAccess-Control-Allow-Headers
CORS header. Expects an array of HTTP headers or *. (optional, defaults to reflecting the headers specified in the requestโsAccess-Control-Request-Headers
header.) -
exposedHeaders
: Configures theAccess-Control-Expose-Headers
CORS header. Expects an array of HTTP headers or*
. (optional, defaults to[]
) -
credentials
: Configures theAccess-Control-Allow-Credentials
CORS header. Set to true to pass the header, otherwise it is omitted. (optional, defaults tofalse
) -
maxAge
: Configures theAccess-Control-Max-Age
CORS header. Set to an integer to pass the header, otherwise it is omitted. (optional)
const config = {
/* ... */
cors: {
origin: true,
methods: [
'GET',
'POST',
],
allowHeaders: [
'Example-Header',
],
exposeHeaders: [
'Example-Header',
],
credentials: true,
maxAge: 86400,
},
};
-
errorCode
: The HTTP status code to return a custom error response to the client. Excepts a valid HTTP status code or an array of valid status code. -
responsePath
: The path and file name of the custom error page for this HTTP status code. For example:/error-pages/403-forbidden.html
-
responseCode
: The HTTP status code to return to the client along with the custom error page. (optional, defaults to the original error code)
const config = {
/* ... */
error: {
errorCode: 404,
responsePath: '/404.html',
},
};
To customize the response of multiple error codes, pass an array of error response objects to error
.
const config = {
/* ... */
error: [
{
errorCode: 404,
responsePath: '/404.html',
},
{
errorCode: [500, 501, 502, 503],
responsePath: '/500.html',
responseCode: 500,
},
],
};
- Request a feature: Create an issue with the Feature request template.
- Report bugs: Create an issue with the Bug report template.
- Add new feature or fix bugs: Fork this repository, edit code, and send a pull request.