Mini reverse proxy server written in rust
- Very fast single standalone binary.
- Static file server
- Reverse proxy router
- HTTPS
- CORS
- Consume any API data and create custom responses with minijinja templates
- Extensively tested with hurl
- Designed following the principles of UNIX philosophy.
cargo install minirps
Alternatively you can use one of the precompiled binaries available with each release (currently generic Linux only).
minirps -h
minirps path/to/static/folder
Serve hidden files
minirps -a path/to/static/folder
minirps -i "/*.md" path/to/static/folder
minirps -i "/**/*.md" path/to/static/folder
minirps -p 4000 path/to/static/folder
minirps -p 4000 path/to/static/folder -c path/to/cert.pem -k path/to/key.pem
Allow CORS from all origins
minirps -o -p 4000 path/to/static/folder -c path/to/cert.pem -k path/to/key.pem
Here the limit of possible configurations passed by command line has been reached.
To create more complex and interesting examples we need a config.toml
file
minirps -f path/to/config.toml
config.toml
assets = "path/to/static/folder"
port = 4000
cert = "path/to/cert.pem"
key = "path/to/key.pem"
ignore = [
"/**/*.md",
"/secret_*"
]
Allow CORS for my website
config.toml
assets = "path/to/static/folder"
port = 4000
cert = "path/to/cert.pem"
key = "path/to/key.pem"
cors = [
"https://www.my-website.com"
]
Allow CORS from my websites of varying origins
config.toml
assets = "path/to/static/folder"
port = 4000
cert = "path/to/cert.pem"
key = "path/to/key.pem"
cors = [
"http://www.my-website.com",
"https://www.my-website.com",
"http://www.my-other-website.com",
"https://www.my-other-website.com"
]
Allow CORS from all origins
config.toml
assets = "path/to/static/folder"
port = 4000
cert = "path/to/cert.pem"
key = "path/to/key.pem"
cors = []
Add a reverse proxy to an API server running at http://localhost:8000
config.toml
assets = "path/to/static/folder"
port = 4000
cert = "path/to/cert.pem"
key = "path/to/key.pem"
cors = []
# GET https://localhost:4000/api/users => GET http://localhost:8000/users
[[routes]]
method = "GET"
path = "/api/users"
[[routes.requests]]
method = "GET"
url = "http://localhost:8000/users"
# PUT https://localhost:4000/api/users/21 => PUT http://localhost:8000/users/21
[[routes]]
method = "PUT"
path = "/api/users/:id"
[[routes.requests]]
method = "PUT"
url = "http://localhost:8000/users/{{params.id}}"
body = "{{body}}"
config.toml
assets = "path/to/static/folder"
port = 4000
cert = "path/to/cert.pem"
key = "path/to/key.pem"
cors = []
# GET https://localhost:4000/api/users => GET http://localhost:8000/users
[[routes]]
method = "GET"
path = "/api/users"
[[routes.requests]]
name = "users"
method = "GET"
url = "http://localhost:8000/users"
[routes.response]
body = """
{% for user in data.users.json %}
{{user.name}}
{% endfor %}"""
headers = { Content-Type = "text/plain" }
# PUT https://localhost:4000/api/users/21 => PUT http://localhost:8000/users/21
[[routes]]
method = "PUT"
path = "/api/users/:id"
[[routes.requests]]
name = "result"
method = "PUT"
url = "http://localhost:8000/users/{{params.id}}"
body = "{{body}}"
[routes.response]
body = "{% if data.result.status == 200 %}SUCCESS!{% else %}ERROR!{% endif %}"
headers = { Content-Type = "text/plain" }
config.toml
templates = "path/to/templates/folder"
assets = "path/to/static/folder"
port = 4000
cert = "path/to/cert.pem"
key = "path/to/key.pem"
cors = []
# GET https://localhost:4000/api/users => GET http://localhost:8000/users
[[routes]]
method = "GET"
path = "/api/users"
[[routes.requests]]
name = "users"
method = "GET"
url = "http://localhost:8000/users"
[routes.response]
body = "{% include 'users.html' %}"
headers = { Content-Type = "text/html" }
# PUT https://localhost:4000/api/users/21 => PUT http://localhost:8000/users/21
[[routes]]
method = "PUT"
path = "/api/users/:id"
[[routes.requests]]
name = "result"
method = "PUT"
url = "http://localhost:8000/users/{{params.id}}"
body = "{{body}}"
[routes.response]
body = "{% include 'edit.html' %}"
headers = { Content-Type = "text/html" }
In this example we show the use of the command line through a minijinja custom function.
minirps -f examples/command_line/config.toml
In this example, a periodic table was created using local data.
minirps -f examples/periodic_table/config.toml
In this example minijinja templates were used to consume data from swapi's Star Wars API.
minirps -f examples/starwars/config.toml
With https (self-signed certificate, needs to accept security risk in the browser.)
minirps -f examples/starwars/config.json \
-k examples/certs/key.txt \
-c examples/certs/cert.txt
In any example it is possible to add https.
In this example, a static server was created and also a CORS request as a showcase.
Static server
minirps examples/tests/assets
CORS server
minirps examples/tests/assets -o -p 4000
In this example, a static server and some routes are built to test the use of reverse proxy and templates automatically using hurl.
minirps -f examples/tests/config.toml
hurl --test examples/tests/test.hurl
Command line arguments take priority over config file if both are present.
Command line argument paths are relative to the current working directory.
config.toml
paths are relative to your own directory.
Currently, any changes to config.toml
, the server must be restarted for them to be applied.
Optional integer port number to run the server on, default: 3000
Whether to display hidden files.
In case of confirmation via the command line or config.toml
they will be
displayed.
List of files to ignore using glob expressions.
If the -i option is passed on the command line it will be appended to the list.
The routes must be considered in relation to the assets folder and not the working directory.
For a complete reference of glob expressions and possible bugs check this library.
Optional array of strings representing allowed origins for CORS requests.
An empty array allows all origins.
If this variable is not defined,CORS will be disabled.
Optional string with the public key file path for the https server.
Only if the cert
and key
are available will the server run over https.
Optional string with the private key file path for the https server.
Only if the cert
and key
are available will the server run over https.
Optional string with the static files folder path.
Optional string with the path to the minijinja templates folder.
Optional array of objects that define reverse proxy routes:
method
is a string with one of the http methods:- GET
- POST
- DELETE
- PUT
- PATCH
- HEAD
- OPTIONS
- TRACE
- CONNECT
path
is a string with the path associated with the route,:var
is acceptable for setting path variables (ex: /api/user/:id).
routes.requests: [{name: string?, method: string, headers: {header: string}?, url: string, body: string?}]?
Requests is an optional array of objects that represent requests that need to be made to generate the response.
name
is an optional string that will be used (if present) to store the response data associated with the request to be made available in minijinja templates.method
is a required string containing the http method (or a minijinja template) as described in the routes definition.headers
is an object with the keys been the header to be setted in the request and the values a string containing the value of the header or a minijinja template to generate it.headers
is an object with the keys being the header to be configured in the request and the values being a string containing the header value or a minijinja template to generate it.url
is a required minijinja template or a raw string associated with the request.body
is an optional minijinja template or a raw string associated with the request.
The response starts with the status, headers, and response body of the last request in the requests array, or if not present an empty 200 response, and the properties here are modifiers of the response sent by the reverse proxy to the client.
status
is an optional string or minijinja template that represents an integer to modify the status code of the response.headers
is an optional object where the keys are the headers to be modified in the response and the values are a string or a minijinja template representing the value associated with the header.body
is an optional string or minijinja template with the body to be replaced with the original response body.
Available minijinja template variables
The associated path passed by the client in the request.
Ex.: /api/user/:id
=> /api/user/25
.
The associated query string or none
passed by the client in the request.
Ex.: http://localhost:3000/api/users?name=john
=> name=john
The associated object of the headers passed by the client in the request.
Note that all header keys are in lowercase.
Ex: Content-Type: text/plain => {"content-type": "text/plain"}
The associated object of the path params associated with the client request on a given route.
Ex: /api/user/:id
=> http://localhost:3000/api/user/25
=> {"id": "25"}
The associated object of the query params associated with the client request.
Ex.: http://localhost:3000/api/users?name=john
=> {"name": "john"}
The body passed by the client in the request.
The body passed by the client in the request converted to json.
If it fails contains the body as a json string.
The data object is where all the results of the reverse proxy request array are stored. A result is stored only if there is a name associated with it and will be available for the next request or response templates.
name
: Object keys are thename
passed in therequests
array.status
: The response status associated with the request.headers
: The response headers associated with the request (the header name is always lowercase in this object)body
: The response body as a string associated with the request.json
: The response body converted to json (or if it fails as json string) associated with the request.
Currently, only binaries for generic versions of Linux are distributed across releases.
sudo apt install pkg-config libssl-dev musl-tools
rustup update
rustup target add x86_64-unknown-linux-musl
cargo update
cargo build --release --target x86_64-unknown-linux-musl
A list of microservices I use combined with minirps
:
- serialscale: An IOT server written in rust for reading weighing data on scales via serial port.
- rawprinter: An IOT server written in rust for connecting via USB to raw printers.
There are already several static page servers.
However, what sets minirps
apart is its high flexibility.
In addition to delivering the basics well: static pages, HTTPS
, CORS
.
Adding minijinja as a template language and request logic allows you to create a powerful reverse proxy.
What php is to apache,
minijinja is to minirps
, with the
difference of being a single binary with a simple configuration that also
accepts its syntax.
My experience building backends has taught me that small servers that connect together produce better results in the long run due to their flexibility and ease of maintenance.
Minirps
tries to be a small server that connects others servers, following
the spirit of UNIX philosophy.
It's a very simple project. Any contribution, any feedback is greatly appreciated.
If this project was useful to you, consider giving it a star on github, it's a way to increase evidence and attract more contributors.
This work would not be possible if it were not for these related projects:
A huge thank you to all the people who contributed to these projects.