{"id":15163661,"url":"https://github.com/marcodpt/minirps","last_synced_at":"2025-04-10T02:26:11.509Z","repository":{"id":198279057,"uuid":"699964377","full_name":"marcodpt/minirps","owner":"marcodpt","description":"Mini reverse proxy server written in rust","archived":false,"fork":false,"pushed_at":"2024-10-25T14:43:08.000Z","size":269,"stargazers_count":15,"open_issues_count":3,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-10-25T15:36:47.754Z","etag":null,"topics":["api","axum","cors","https","hurl","minijinja","reqwest","reverse-proxy","rust","self-contained","server","single-binary","template","webserver","zero-configuration"],"latest_commit_sha":null,"homepage":"https://crates.io/crates/minirps","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marcodpt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-10-03T17:20:59.000Z","updated_at":"2024-10-25T14:43:12.000Z","dependencies_parsed_at":"2023-10-05T06:10:03.372Z","dependency_job_id":"10b69d43-e00c-4b70-a3c3-1d060374404d","html_url":"https://github.com/marcodpt/minirps","commit_stats":null,"previous_names":["marcodpt/minirps"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcodpt%2Fminirps","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcodpt%2Fminirps/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcodpt%2Fminirps/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcodpt%2Fminirps/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marcodpt","download_url":"https://codeload.github.com/marcodpt/minirps/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248143686,"owners_count":21054821,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","axum","cors","https","hurl","minijinja","reqwest","reverse-proxy","rust","self-contained","server","single-binary","template","webserver","zero-configuration"],"created_at":"2024-09-27T03:00:47.059Z","updated_at":"2025-04-10T02:26:11.486Z","avatar_url":"https://github.com/marcodpt.png","language":"Rust","readme":"# ![](favicon.ico)  Mini RPS\n\n[![Version](https://img.shields.io/crates/v/minirps)](https://crates.io/crates/minirps)\n[![Downloads](https://img.shields.io/crates/d/minirps)](https://crates.io/crates/minirps)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/marcodpt/minirps/blob/main/LICENSE)\n\nMini [reverse proxy](https://en.wikipedia.org/wiki/Reverse_proxy) server\nwritten in rust\n\n## ❤️ Features\n - Static file server.\n - HTTPS\n - [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)\n - The optional configuration file can be written in\n[JSON](https://www.json.org/json-en.html) or\n[TOML](https://toml.io/en/).\n - [minijinja](https://github.com/mitsuhiko/minijinja) templates with custom\nfunctions:\n   - read, write and remove files from the filesystem. \n   - Send http requests in the template.\n   - Execute commands in the template.\n   - [Reverse proxy](https://en.wikipedia.org/wiki/Reverse_proxy). \n   - Modify the response headers and status in the template.\n   - Parse and format to:\n     - [JSON](https://www.json.org/json-en.html)\n     - [TOML](https://toml.io/en/)\n     - [FormData](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST)\n - Safe rust and good code organization.\n - No panics after startup (every panic is a bug).\n - Extensively tested with [hurl](https://github.com/Orange-OpenSource/hurl).\n - Good debugging experience with the server displaying requests in the\nterminal and error messages in templates for humans.\n - Designed following the principles of\n[UNIX philosophy](https://en.wikipedia.org/wiki/Unix_philosophy).\n\n## 💻 Install\n```\ncargo install minirps\n```\n\nAlternatively you can use one of the precompiled binaries available with each\nrelease (currently generic Linux only).\n\n## 🎮 Usage\n### Help\n```\nminirps -h\n```\n\n### Simple static file server\n```\nminirps path/to/static/folder\n```\n\n### Serve hidden files\n```\nminirps -a path/to/static/folder\n```\n\n### Ignore markdown files in root folder\n```\nminirps -i \"/*.md\" path/to/static/folder\n```\n\n### Ignore any markdown files\n```\nminirps -i \"/**/*.md\" path/to/static/folder\n```\n\n### Running on port 4000 instead of 3000\n```\nminirps -p 4000 path/to/static/folder\n```\n\n### Using https instead of http\n```\nminirps path/to/static/folder -c path/to/cert.pem -k path/to/key.pem\n```\n\n### Allow [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) from all origins\n```\nminirps -o path/to/static/folder\n```\n\n### Start the server with a config file\nThe supported formats are JSON and TOML.\n```\nminirps -f path/to/config/file\n```\n\n### Send HTML template response instead of API response\nHere it is assumed that there are\n[minijinja](https://github.com/mitsuhiko/minijinja) templates `users.html`\nand `edit_user.html`\n\nconfig.toml\n```toml\ntemplates = \"path/to/templates/folder\"\nassets = \"path/to/static/folder\"\nport = 4000\ncert = \"path/to/cert.pem\"\nkey = \"path/to/key.pem\"\ncors = []\n\n[[routes]]\nmethod = \"GET\"\npath = \"/api/users\"\ntemplate = \"users.html\"\n\n[[routes]]\nmethod = \"GET\"\npath = \"/api/users/:id\"\ntemplate = \"edit_user.html\"\n\n[[routes]]\nmethod = \"POST\"\npath = \"/api/users/:id\"\ntemplate = \"edit_user.html\"\n```\n\nAlternatively you can use a JSON file\n\nconfig.json\n```json\n{\n  \"templates\": \"path/to/templates/folder\",\n  \"assets\": \"path/to/static/folder\",\n  \"port\": 4000,\n  \"cert\": \"path/to/cert.pem\",\n  \"key\": \"path/to/key.pem\",\n  \"cors\": [],\n  \"routes\": [\n    {\n      \"method\": \"GET\",\n      \"path\": \"/api/users\",\n      \"template\": \"users.html\"\n    }, {\n      \"method\": \"GET\",\n      \"path\": \"/api/users/:id\",\n      \"template\": \"edit_user.html\"\n    }, {\n      \"method\": \"POST\",\n      \"path\": \"/api/users/:id\",\n      \"template\": \"edit_user.html\"\n    }\n  ]\n}\n```\n\n## 💯 Examples\n\n### Demo\n```\nminirps -f examples/demo/config.toml\n```\nalternatively\n```\nminirps -f examples/demo/config.json\n```\n\nHere it was implemented:\n - Command Line: use of the command line through a\n[minijinja](https://github.com/mitsuhiko/minijinja) custom function.\n - Periodic Table: A periodic table web interface was built from a JSON file.\n - Star Wars API: Web interface for [swapi](https://swapi.dev/) Star Wars API.\n - Note taking app: An example using the file system to save and read data.\n - Form Data: Sending and reading examples.\n - CORS: A working demo of a CORS request, needs both servers running. \n\n### Test\nIn this example, a static server and some routes are built to test the use of\nreverse proxy and templates automatically using\n[hurl](https://github.com/Orange-OpenSource/hurl).\n\n```\nminirps -f examples/tests/config.toml\n```\n\n```\nhurl --test examples/tests/test.hurl\n```\n\n## 📢 Motivation\nThe objective of this project is to deliver an http server in a single\nself-contained binary.\n\nWhere the basics should be obtained without any configuration file:\n - static file server.\n - HTTPS\n - CORS\n\nAnd where other reverse proxy functionalities are obtained with simple\nconfigurations.\n\nTemplates have the ability to send requests, read and write files and execute\ncommands.\n\nThis way they can interact with resources such as databases without the need\nfor a complete scripting language such as php, python, ruby...\n\nA small, highly extensible server, without having to manage operating system\nversions, dependencies and packages.\n\nIt simply works!\n\n## 📖 Docs\n### config\nCommand line arguments take priority over config file if both are present.  \n\nCommand line argument paths are relative to the current working directory.\n\n`config` paths are relative to your own directory.\n\nCurrently, any changes to `config`, the server must be restarted for them\nto be applied.\n\n#### port: integer?\nOptional integer port number to run the server on, default: 3000\n\n#### all: bool\nWhether to display hidden files. \n\nIn case of confirmation via the command line or `config` file they will be\ndisplayed.\n\n#### ignore: [string]?\nList of files to ignore using glob expressions.\n\nIf the -i option is passed on the command line it will be appended to the list.\n\nThe routes must be considered in relation to the assets folder and not the\nworking directory.\n\nFor a complete reference of glob expressions and possible bugs check this\n[library](https://github.com/devongovett/glob-match).\n\n#### cors: [string]?\nOptional array of strings representing allowed origins for [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) requests.\n\nAn empty array allows all origins.\n\nIf this variable is not defined,[CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) will be disabled.\n\n#### cert: string?\nOptional string with the public key file path for the https server.\n\nOnly if the `cert` and `key` are available will the server run over https.\n\n#### key: string?\nOptional string with the private key file path for the https server.\n\nOnly if the `cert` and `key` are available will the server run over https.\n\n#### assets: string?\nOptional string with the static files folder path.\n\n#### templates: string?\nOptional string with the path to the\n[minijinja](https://github.com/mitsuhiko/minijinja) templates folder.\n\n#### data: string?\nOptional string with the path where templates can `read`, `write` and `remove`\nfiles. If not passed, these functions will be unavailable to templates.\n\n#### routes: [{method, path, template}]\nOptional array of objects that define routes:\n\n - `method` string: one of the http methods:\n   - GET\n   - POST\n   - DELETE\n   - PUT\n   - PATCH\n   - HEAD\n   - OPTIONS\n   - TRACE\n   - CONNECT\n - `path` string: the path associated with the route, `:var` is\nacceptable for setting path variables (ex: /api/user/:id).\n - `template` string: the template path associated with this route within the\n`templates` folder.\n\n### Template variables\n\n#### method: string\nThe `method` associated with this `route`. It is useful when the same template\nis used in many `routes`.\n\n#### url: string\nIt is the junction of the `path` and the `route` `query`.\n\n```\nhttp://localhost:3000/api/users?name=john#me =\u003e /api/users?name=john\n```\n\n#### route: string\nIt is the `route` as declared in the `config` file.\n\n```\n/api/user/:id\n```\n\n#### path: string\nThe associated `path` passed by the client in the request.\n\n```\nhttp://localhost:3000/api/users?name=john =\u003e /api/users\n```\n\n#### query: string?\nThe associated `query` string passed by the client in the request.\n\n```\nhttp://localhost:3000/api/users?name=john =\u003e name=john\n```\n\n#### params: {name: value}\nThe associated object of the `path` `params` associated with the client\nrequest on a given `route`.\n\n - `name` string: The name of the parameter as declared in the `route`.\n - `value` string: The value of the parameter passed in the `path`.\n\n```\n/api/user/:id =\u003e http://localhost:3000/api/user/25 =\u003e {\"id\": \"25\"}\n```\n\n#### vars: {name: value}\nThe associated object of the `query` params associated with the client request.\n\n - `name` string: The name of the parameter passed in the `query`.\n - `value` string: The value of the parameter passed in the `query`.\n\n```\nhttp://localhost:3000/api/users?name=john =\u003e {\"name\": \"john\"}\n```\n\n#### headers: {name: value}\nThe associated object of the headers passed by the client in the request.\n\nNote that all header keys are in **lowercase**.\n\n - `name` string: The name of the header passed in the request.\n - `value` string: The value of the header passed in the request.\n\n```\nContent-Type: text/plain =\u003e {\"content-type\": \"text/plain\"}\n```\n\n#### body: binary\nThe body passed by the client in the request.\n\n### Template return state\nVariables that, if defined, modify the behavior of the server response.\n\nIt only works if they are **declared outside the blocks**\nto be returned in the template's global state.\n\n#### modify {status, headers: {name: value}}\nThe response body is always the result of the template, and this variable\nallows you to modify the status code and headers.\n\n - `status` (integer?): The new response status code, if not passed, will use\n200 by default.\n - `headers` ({name: value}?): The headers that should be changed in the\nresponse.\n\nAn example of a redirect.\n```jinja\n{% set modify = {\"status\": 303, \"headers\": {\"Location\": \"/new/location\"}} %}\n```\n\n#### proxy {url, method, headers: {name, value}, body}\nUses a proxy instead of the template result.\n\n - `url` (string): The proxy URL, is required.\n - `method` (string?): The method used for the proxy request. By default, the\nmethod passed in the original request.\n - `headers` ({name: value}?): The headers that should be changed in the\nproxy request. By default, do not change any header.\n - `body` (binary?): The body of the proxy request. By default,\nthe original body.\n\nA simple proxy that retains the request method, headers, body and path and just\ndirects it to another host.\n```jinja\n{% set proxy = {\"url\": \"https://another.host.ip\"~url} %}\n```\n\n### Custom functions\n\n#### command (cmd) -\u003e {code, stdout, stdin}\nExecutes a command passed in the template.\n\nThis function does not raise errors, in case of failure it returns the\n`code` `999999`, and the error message.\n\n - `cmd` string: The command to be executed by the system.\n - `code` integer: The response code, in general zero indicates OK, and a\nnumber greater than zero the error code.\n - `stdout` binary: The standard output of the executed command.\n - `stderr` binary: The error message returned.\n\nList files in the current directory on UNIX systems.\n```jinja\n{% set res = command(\"ls -l\") %}\n{% set output = res.stdout | parse(\"text\") %}\n```\n\n#### read (file) -\u003e data\nReads the contents of a file, if it does not exist returns `None`.\n\nThis function does not raise errors, any read error will return `None`.\n\nIt will only be available if the `config` file contains the `data`\nproperty with the folder that contains the files that can be read and modified.\n\n - `file` string: The path of the file to read.\n - `data` binary?: The contents of the file or `None` in case of errors.\n\n```jinja\n{% set content = read(\"some/file.json\") | parse(\"json\") %}\n```\n\n#### read (dir: string) -\u003e [{...info}]\nThis function also works with a directory, which in this case will return an\narray with information about the files contained in it.\n\n - `dir` string: If the path passed is a directory.\n\n**info**\n - `accessed` string: Last access date (%Y-%m-%d %H:%M:%S).\n - `created` string: Creation date (%Y-%m-%d %H:%M:%S).\n - `modified` string: Modification date (%Y-%m-%d %H:%M:%S).\n - `is_dir` bool: True if it is a directory.\n - `is_file` bool: True if it is a file.\n - `is_symlink` bool: True if it is a symbolic link.\n - `name` string: Entry name.\n - `len` u64: Size in bytes.\n\n```jinja\n{% set content = read(\"some/dir\") %}\n{% for entry in content %}\n  {{entry.name}}\n{% endfor %}\n```\n\n#### write (file, data) -\u003e error\nWrites to a file. If necessary, create folders for the file. Always overwrites\ncontent if it exists.\n\nIf an error occur, the error text will be returned, otherwise `None`.\nTherefore, it does not raise errors.\n\nIt will only be available if the `config` file contains the `data`\nproperty with the folder that contains the files that can be read and modified.\n\n - `file` string: The file path.\n - `data` binary: The raw data to be written.\n - `error` string?: Error message or `None`.\n\n```jinja\n{% set data = \"Hello world!\" %}\n{{write(\"some/file.txt\", data | bytes)}}\n```\n\n#### remove (entry) -\u003e error\nRemoves a file or directory recursively.\n\nIf an error occur, the error text will be returned, otherwise `None`.\nTherefore, it does not raise errors.\n\nIt will only be available if the `config` file contains the `data`\nproperty with the folder that contains the files that can be read and modified.\n\n - `entry` string: The path of the file or directory to be removed.\n - `error` string?: Error message or `None`.\n\n```jinja\n{{remove(\"some/dir\")}}\n```\n\n```jinja\n{{remove(\"some/file.txt\")}}\n```\n\n#### {method} (url, body) -\u003e {status, headers, body}\nSends a synchronous request to an external resource.\n\nThis function does not raise errors, any error in the request will be returned\n`status` code `400` with the `body` containing the error message.\n\n - `url` string: The URL of the request.\n - `body` binary: The body of the request.\n - `status` integer: The HTTP status code of the response.\n - `headers` {`name` string: `value` string}: Response headers.\n - `body` binary: Response body.\n - `method`:\n   - `get` (url) -\u003e {status, headers, body}\n   - `delete` (url) -\u003e {status, headers, body}\n   - `head` (url) -\u003e {status, headers, body}\n   - `options` (url) -\u003e {status, headers, body}\n   - `post` (url, body) -\u003e {status, headers, body}\n   - `put` (url, body) -\u003e {status, headers, body}\n   - `patch` (url, body) -\u003e {status, headers, body}\n\n```jinja\n{% set response = get(\"https://some/api\") %}\n{% set data = response.body | parse(\"json\") %}\n```\n\n```jinja\n{% set body = \"some data\" %}\n{% set response = post(\"https://some/api\", body | bytes) %}\n{% set message = response.body | parse(\"text\") %}\n```\n\n#### log (message) -\u003e ()\nPrints a message from the template on the terminal.\n\n - `message` string: The content of the message.\n\n```jinja\n{{ log(\"hi!\") }}\n```\n\n### Custom filters\n\n#### parse (data, encoding) -\u003e result\nConverts the raw data returned from some function to a template variable using\nthe passed encoding.\n\nThis function raises an `error` if you use an unsupported encoding or if the\ndecoding fails.\n\nReturning the request with `status` code `500` in case of error.\n\n - `data` binary: Raw data returned from some function.\n - `encoding` string: The encoding to be used when reading the data.\nSupported encodings:\n   - form: [FormData](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST)  \n   - json: [JSON](https://www.json.org/json-en.html)\n   - toml: [TOML](https://toml.io/en/)\n   - text: It just transforms the data into text.\n - `result`: A value supported by the template with associated data.\n\n```jinja\n{% set data = read(\"some/file.txt\") | parse(\"text\") %}\n```\n\n```jinja\n{% set response = get(\"https://some/api\") %}\n{% set data = response.body | parse(\"json\") %}\n```\n\n#### format (data, encoding) -\u003e text\nConverts a template variable to a formatted string.\n\nThis function raises an `error` if you use an unsupported encoding or if the\nencoding fails.\n\nReturning the request with `status` code `500` in case of error.\n\n - `data`: Any template variable.\n - `encoding` string: The type of encoding to be adopted when formatting the\ntext. Supported encodings:\n   - form: [FormData](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST)  \n   - json: [JSON](https://www.json.org/json-en.html)\n   - toml: [TOML](https://toml.io/en/)\n   - debug: Uses rust pretty print formatter.\n - `text` string: The text after encoding.\n\n```jinja\n{% set data = {\"name\": \"John\", \"age\": 30} %}\n{% set text = data | format(\"form\") %}\n{{text}}\n```\n\n```\nname=John\u0026age=30\n```\n\n#### bytes (data) -\u003e raw\nConverts text to binary format.\n\n - `data` string: Any text.\n - `raw` binary: Text converted to binary.\n\n```jinja\n{% set error = write('hello.txt', 'Hello World!' | bytes) %}\n```\n\n```jinja\n{% set response = post('http://myip/some/api', 'Hello World!' | bytes) %}\n```\n\n## 📦 Releases\nCurrently, only binaries for generic versions of Linux are distributed across\nreleases.\n```\nsudo apt install pkg-config libssl-dev musl-tools\nrustup update\nrustup target add x86_64-unknown-linux-musl\ncargo update\ncargo build --release --target x86_64-unknown-linux-musl\n```\n\n## 🤝 Contributing\nIt's a very simple project.\nAny contribution, any feedback is greatly appreciated.\n\n## ⭐ Support\nIf this project was useful to you, consider giving it a star on github, it's a\nway to increase evidence and attract more contributors.\n\n## 🙏 Acknowledgment\nThis work would not be possible if it were not for these related projects:\n - [minijinja](https://github.com/mitsuhiko/minijinja)\n - [axum](https://github.com/tokio-rs/axum)\n - [reqwest](https://github.com/seanmonstar/reqwest)\n - [hurl](https://github.com/Orange-OpenSource/hurl)\n - [serde](https://github.com/serde-rs/serde)\n - [clap](https://github.com/clap-rs/clap)\n - [glob-match](https://github.com/devongovett/glob-match)\n\nA huge thank you to all the people who contributed to these projects.\n","funding_links":[],"categories":["Applications"],"sub_categories":["Web Servers"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcodpt%2Fminirps","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarcodpt%2Fminirps","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcodpt%2Fminirps/lists"}