https://github.com/amandasaurus/rust-cgi
Create CGI programmes in Rust with hyper's http types
https://github.com/amandasaurus/rust-cgi
cgi http rust
Last synced: 3 months ago
JSON representation
Create CGI programmes in Rust with hyper's http types
- Host: GitHub
- URL: https://github.com/amandasaurus/rust-cgi
- Owner: amandasaurus
- License: agpl-3.0
- Created: 2018-05-07T19:56:28.000Z (about 7 years ago)
- Default Branch: main
- Last Pushed: 2025-02-16T16:27:41.000Z (4 months ago)
- Last Synced: 2025-03-28T14:09:26.337Z (3 months ago)
- Topics: cgi, http, rust
- Language: Rust
- Size: 56.6 KB
- Stars: 56
- Watchers: 4
- Forks: 14
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
cgi
===
[](https://crates.io/crates/cgi)
[](LICENSE)
Easily create CGI (Common Gateway Interface) programs in Rust, based on
[`http`](https://crates.io/crates/http) types.
Installation & Usage
--------------------
`Cargo.toml`:
```toml
[dependencies]
cgi = "0.6"
```
Use the `cgi_main!` macro, with a function that takes a `cgi::Request` and returns a
`cgi::Response`.
```rust
extern crate cgi;
cgi::cgi_main! { |request: cgi::Request| -> cgi::Response {
cgi::text_response(200, "Hello World")
} }
```
If your function returns a `Result`, you can use `cgi_try_main!`:
```rust
extern crate cgi;
cgi::cgi_try_main! { |request: cgi::Request| -> Result {
let greeting = std::fs::read_to_string("greeting.txt").map_err(|_| "Couldn't open file")?;
Ok(cgi::text_response(200, greeting))
} }
```
It will parse and extract the CGI environmental variables, and the HTTP request body to create
`Request`, call your function to create a response, and convert your `Response` into the
correct format and print to stdout. If this program is not called as CGI (e.g. missing
required environmental variables), it will gracefully fall back to using reasonable values
(although the values themselves may be subject to change).
It is also possible to call the `cgi::handle` function directly inside your `main` function:
```rust
extern crate cgi;
fn main() { cgi::handle(|request: cgi::Request| -> cgi::Response {
cgi::html_response(200, "
Hello World!
")
})}
```
Response Shortcuts
------------------
Several shortcuts create shortcuts easily:
- `cgi:empty_response(status_code)` - A HTTP Reponse with no body and that HTTP
status code, e.g. `return rust_igi::empty_response(404);` to return a
[HTTP 404 Not Found](https://en.wikipedia.org/wiki/HTTP_404).
- `cgi::html_response(status_code, text)` - Converts `text` to bytes (UTF8) and
sends that as the body with that `status_code` and HTML `Content-Type` header.
- `cgi::string_response(status_code, text)` - Converts `text` to bytes (UTF8),
and sends that as the body with that `status_code` but no `Content-Type` header.
- `cgi::binary_response(status_code, content_type, blob)` - Sends `blob` with
that status code and the provided content type header.
Re-exports
----------
`http` is re-exported, (as `cgi::http`).
`cgi::Response`/`Request` are `http::Response>`/`Request>`.
Running locally
---------------
Python provides a simple CGI webserver you can use to run your scripts. The
binaries must be in a `cgi-bin` directory, so you'll need to create that
directory and copy your binary into it. Given a project named `example`, run
this in your project root directory (i.e. where `Cargo.toml` is):
```shell
mkdir cgi-bin
cargo build
cp target/debug/example cgi-bin/example
python3 -m http.server --cgi
```
and then open http://localhost:8000/cgi-bin/example.
MSRV policy
-----------
Currently the minimum supported Rust version (MSRV) is 1.51.0.
MSRV increases will be kept to a minimum, and will always be accompanied with a minor version bump.
See also
--------
- [Rustdoc for this crate](https://docs.rs/cgi/latest/cgi/)
- [http crate](https://github.com/hyperium/http)
- [RFC 3875 - The Common Gateway Interface (CGI) v1.1](https://tools.ietf.org/html/rfc3875)
Why?
----
CGI is old, and easy to deploy. Just drop a binary in the right place, and
Apache (or whatever) will serve it up. Rust is fast, so for simple things,
there should be less downsides to spinning up a custom HTTP server.