mirror of https://github.com/rwf2/Rocket.git
96 lines
3.3 KiB
Markdown
96 lines
3.3 KiB
Markdown
# Rocket [](https://travis-ci.com/SergioBenitez/Rocket)
|
|
|
|
Rocket is a work-in-progress web framework for Rust (nightly) with a focus on
|
|
ease-of-use, expressability, and speed. Here's an example of a complete Rocket
|
|
application:
|
|
|
|
```rust
|
|
#![feature(plugin)]
|
|
#![plugin(rocket_codegen)]
|
|
|
|
extern crate rocket;
|
|
use rocket::Rocket;
|
|
|
|
#[get("/<name>/<age>")]
|
|
fn hello(name: &str, age: u8) -> String {
|
|
format!("Hello, {} year old named {}!", age, name)
|
|
}
|
|
|
|
fn main() {
|
|
Rocket::new("localhost", 8000).mount_and_launch("/hello", routes![hello]);
|
|
}
|
|
```
|
|
|
|
Visiting `localhost:8000/hello/John/58`, for example, will trigger the `hello`
|
|
route resulting in the string `Hello, 58 year old named John!` being sent to the
|
|
browser. If an `<age>` string was passed in that can't be parsed as a `u8`, the
|
|
route won't get called, resulting in a 404 error.
|
|
|
|
## Overview
|
|
|
|
Rocket employs code generation to remove the need for boilerplate involved with
|
|
parsing requests and request parameters, prevent invalid and/or incorrect
|
|
requests from invoking a user's request handler, and allow the user to define
|
|
what is valid and/or correct.
|
|
|
|
Rocket uses type _guards_, or _constraints_, on request handlers to
|
|
accomplishing it's safety and correctness goals. In Rocket, handlers are _only_
|
|
invoked if all types that appear in the request handler's argument list can be
|
|
derived from the incoming request.
|
|
|
|
In their simplest incarnation, guards can be types expected of parameters in a
|
|
matched path. This is illustrated in the previous example where the `hello`
|
|
request handler is only be invoked if the dynamic path parameter `<age>` parses
|
|
as a `u8`. Guards can also be derived directly from a request. For instance, you
|
|
can define an `AdminUser` type that can be derived only if the proper cookies
|
|
were sent along with the request. Then, by simply including the type in a
|
|
handler's argument list as follows:
|
|
|
|
#[get("/admin/post/<id>")]
|
|
fn admin(user: AdminUser, id: isize) -> { .. }
|
|
|
|
you can be assured that the handler will be invoked _only_ if an administrative
|
|
user is logged in. Any number of such guards can be included. For example, to
|
|
retrieve the request's cookies along with the admin user, simply include the
|
|
`&Cookies` type in the argument list:
|
|
|
|
#[get("/admin/post/<id>")]
|
|
fn admin(user: AdminUser, cookies: &Cookies, id: isize) -> { .. }
|
|
|
|
Full documentation about built-in request guards is coming soon.
|
|
|
|
## Building
|
|
|
|
### Nightly
|
|
|
|
Rocket requires a nightly version of Rust as it makes heavy use of syntax
|
|
extensions. This also means that the first two unwieldly lines in the Rust file
|
|
above are required.
|
|
|
|
### Examples
|
|
|
|
Try running the examples in the `examples/` folder. For instance, the following
|
|
sequence of commands builds and runs the `Hello, world!` example:
|
|
|
|
```
|
|
cd examples/hello_world
|
|
cargo run
|
|
```
|
|
|
|
Then visit `localhost:8000`. You should see `Hello, world!`.
|
|
|
|
### OS X
|
|
|
|
Apple has stopped shipping `openssl` with OS X.11. As such, if your build fails
|
|
to compile with some `openssl` related errors, you'll need to install `openssl`,
|
|
`cargo clean`, and then `cargo build` again. Here are some lightweight
|
|
instructions:
|
|
|
|
```
|
|
brew install openssl
|
|
brew link --force openssl
|
|
export OPENSSL_INCLUDE_DIR=`brew --prefix openssl`/include
|
|
export OPENSSL_LIB_DIR=`brew --prefix openssl`/lib
|
|
```
|
|
|