cgi

Create CGI programmes


Keywords
http, cgi, web, rust
License
AGPL-3.0

Documentation

rust-cgi

Easily create CGI[1][2] programmes[3] in Rust based on http types.

crates.io released version badge
crates.io released licencegpl

Installation & Usage

Cargo.toml:

[dependencies]
cgi = "0.6"

Use the cgi_main! macro, with a function that takes a cgi::Request and returns a cgi::Response.

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!:

extern crate cgi;

cgi::cgi_try_main! { |request: cgi::Request| -> Result<cgi::Response, String> {
    let greeting = std::fs::read_to_string("greeting.txt").map_err(|_| "Couldn't open file")?;

    Ok(cgi::text_response(200, greeting))
} }

It will parse & extract the CGI environmental variables, and the HTTP request body to create Request<u8>, call your function to create a response, and convert your Response into the correct format and print to stdout. If this programme is not called as CGI (e.g. missing required environmental variables), it will panic.

It is also possible to call the cgi::handle function directly inside your main function:

extern crate cgi;

fn main() { cgi::handle(|request: cgi::Request| -> cgi::Response {
    cgi::html_response(200, "<html><body><h1>Hello World!</h1></body></html>")
})}

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 cgi::empty_response(404); to return a HTTP 404 Not Found.

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, e.g. `return

cgi::string_response(200, "Hello World!")

returns a simple plain text response.

cgi::binary_response(status_code, blob)

Sends blob with that status code.

Re-exports

http is re-exported, (as cgi::http).

cgi::Response/Request are http::Response<Vec<u8>>/Request<Vec<u8>>.

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):

mkdir cgi-bin
cargo build
cp target/debug/example cgi-bin/example
python3 -m http.server --cgi

See also

Things using this

  • 'Suggestions welcome!'

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.

Copyright

Copyright GNU Affero GPL v3 (or later). See the file LICENCE


1. Retro!
2. Common Gateway Interface 1.1, RFC 3875
3. Yes, I’m spelling it programme, the correct way.