Rocket/README.md

163 lines
5.8 KiB
Markdown
Raw Normal View History

2016-09-12 08:46:08 +00:00
# Rocket [![Build Status](https://travis-ci.com/SergioBenitez/Rocket.svg?token=CVq3HTkPNimYtLm3RHCn&branch=master)](https://travis-ci.com/SergioBenitez/Rocket)
2016-04-05 02:04:46 +00:00
2016-03-12 18:54:38 +00:00
Rocket is a work-in-progress web framework for Rust (nightly) with a focus on
2016-04-06 19:50:51 +00:00
ease-of-use, expressability, and speed. Here's an example of a complete Rocket
application:
2016-03-12 18:54:38 +00:00
```rust
#![feature(plugin)]
2016-09-09 03:38:58 +00:00
#![plugin(rocket_codegen)]
2016-03-12 18:54:38 +00:00
extern crate rocket;
2016-09-04 11:10:35 +00:00
#[get("/<name>/<age>")]
2016-04-06 19:50:51 +00:00
fn hello(name: &str, age: u8) -> String {
2016-04-03 11:28:09 +00:00
format!("Hello, {} year old named {}!", age, name)
2016-03-12 18:54:38 +00:00
}
fn main() {
2016-10-04 02:49:12 +00:00
rocket::ignite().mount("/hello", routes![hello]).launch();
2016-03-12 18:54:38 +00:00
}
```
2016-04-06 19:50:51 +00:00
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.
## Documentation
2016-09-13 23:32:57 +00:00
Rocket is extensively documented:
2016-09-13 23:32:57 +00:00
* [Quickstart](guide/quickstart): How to get started as quickly as possible.
* [Getting Started](guide/getting_started): How to start your first project.
* [Overview](overview): A brief introduction.
* [Guide](guide): A detailed guide and reference to every component.
2016-10-09 11:29:22 +00:00
* [API Documentation](https://api.rocket.rs): The "rustdocs" (API documentation).
2016-09-04 22:07:47 +00:00
## Building
### Nightly
2016-03-12 18:54:38 +00:00
Rocket requires a nightly version of Rust as it makes heavy use of syntax
extensions. This means that the first two unwieldly lines in the introductory
example above are required.
### Core, Codegen, and Contrib
All of the Rocket libraries are managed by Cargo. As a result, compiling them is
simple.
* Core: `cd lib && cargo build`
* Codegen: `cd codegen && cargo build`
* Contrib: `cd contrib && cargo build`
2016-03-12 18:54:38 +00:00
2016-09-04 22:07:47 +00:00
### Examples
2016-03-12 18:54:38 +00:00
Rocket ships with an extensive number of examples in the `examples/` directory
which can be compiled and run with Cargo. For instance, the following sequence
of commands builds and runs the `Hello, world!` example:
2016-03-12 18:54:38 +00:00
```
2016-04-06 19:50:51 +00:00
cd examples/hello_world
2016-03-12 18:54:38 +00:00
cargo run
```
You should see `Hello, world!` by visiting `http://localhost:8000`.
## Testing
2016-03-12 18:54:38 +00:00
To test Rocket, simply run `./scripts/test.sh` from the root of the source tree.
This will build and test the `core`, `codegen`, and `contrib` libraries as well
as all of the examples. This is the script that gets run by Travis CI.
2016-03-12 18:54:38 +00:00
### Core
Testing for the core library is done inline in the corresponding module. For
example, the tests for routing can be found at the bottom of the
`lib/src/router/mod.rs` file.
### Codegen
Code generation tests can be found in `codegen/tests`. We use the
[compiletest](https://crates.io/crates/compiletest_rs) library, which was
extracted from `rustc`, for testing. See the [compiler test
documentation](https://github.com/rust-lang/rust/blob/master/COMPILER_TESTS.md)
for information on how to write compiler tests.
## Contributing
Contributions are absolutely, positively welcome and encouraged! Contributions
come in many forms. You could:
1. Submit a feature request or bug report as an [issue](https://github.com/SergioBenitez/Rocket/issues).
2. Ask for improved documentation as an [issue](https://github.com/SergioBenitez/Rocket/issues).
3. Comment on [issues that require
feedback](https://github.com/SergioBenitez/Rocket/issues?q=is%3Aissue+is%3Aopen+label%3A%22feedback+wanted%22).
4. Contribute code via [pull requests](https://github.com/SergioBenitez/Rocket/pulls).
We aim to keep Rocket's code quality at the highest level. This means that any
code you contribute must be:
* **Commented:** Public items _must_ be commented.
* **Documented:** Exposed items _must_ have rustdoc comments with
examples, if applicable.
* **Styled:** Your code should be `rustfmt`'d when possible.
* **Simple:** Your code should accomplish its task as simply and
idiomatically as possible.
* **Tested:** You must add (and pass) convincing tests for any functionality you add.
* **Focused:** Your code should do what it's supposed to do and nothing more.
2016-03-12 18:54:38 +00:00
All pull requests are code reviewed and tested by the CI.
2016-12-16 01:19:23 +00:00
## Performance
Rocket is designed to be performant. At this time, its performance is
[bottlenecked by the Hyper HTTP
library](https://github.com/SergioBenitez/Rocket/issues/17). Even so, Rocket
currently performs _better_ than the latest version of Hyper on a simple "Hello,
world!" benchmark:
**Machine Specs:**
* **Logical Cores:** 12 (6 cores x 2 threads)
* **Memory:** 24gb ECC DDR3 @ 1600mhz
* **Processor:** Intel Xeon X5675 @ 3.07GHz
* **Operating System:** Mac OS X v10.11.6
2016-12-16 01:22:33 +00:00
**Hyper v0.10.0-a.0** (46 LOC) results (best of 3, +/- 300 req/s, +/- 1us latency):
2016-12-16 01:19:23 +00:00
2016-12-17 17:32:40 +00:00
Running 10s test @ http://localhost:80
2 threads and 10 connections
Thread Stats Avg Stdev Max +/- Stdev
Latency 175.12us 40.38us 429.00us 70.79%
Req/Sec 28.00k 2.41k 36.79k 72.28%
562692 requests in 10.10s, 81.57MB read
Requests/sec: 55715.98
Transfer/sec: 8.08MB
2016-12-16 01:19:23 +00:00
2016-12-16 01:22:33 +00:00
**Rocket v0.0.11** (8 LOC) results (best of 3, +/- 200 req/s, +/- 0.5us latency):
2016-12-16 01:19:23 +00:00
2016-12-17 17:32:40 +00:00
Running 10s test @ http://localhost:80
2 threads and 10 connections
Thread Stats Avg Stdev Max +/- Stdev
Latency 163.97us 27.47us 699.00us 70.30%
Req/Sec 29.58k 1.02k 32.39k 64.85%
594546 requests in 10.10s, 82.78MB read
Requests/sec: 58868.83
Transfer/sec: 8.20MB
2016-12-16 01:19:23 +00:00
**Summary:**
2016-12-17 17:32:40 +00:00
* Rocket throughput higher by 5.7% (higher is better).
* Rocket latency lower by 7.4% (lower is better).
2016-12-16 01:19:23 +00:00
### Future Improvements
2016-12-16 01:19:23 +00:00
Rocket is currently built on a synchronous HTTP backend. Once the Rust
2016-12-16 01:22:33 +00:00
asynchronous I/O libraries have stabilized, a migration to a new, more
performant HTTP backend is planned. We expect performance to improve
significantly at that time. The [Stabilize HTTP
2016-12-16 01:19:23 +00:00
Library](https://github.com/SergioBenitez/Rocket/issues/17) issue tracks the
progress on this front.