c24a96308b
Problem: To support Server-Side Events (SSE, aka JS EventSource) it is necessary for the server to keep open an HTTP request and dribble out data (the event stream) as it is generated. Currently, Rocket handles this poorly. It likes to fill in complete chunks. Also there is no way to force a flush of the underlying stream: in particular, there is a BufWriter underneath hyper. hyper would honour a flush request, but there is no way to send one. Options: Ideally the code which is producing the data would be able to explicitly designate when a flush should occur. Certainly it would not be acceptable to flush all the time for all readers. 1. Invent a new kind of Body (UnbufferedChunked) which translates the data from each Read::read() call into a single call to the stream write, and which always flushes. This would be a seriously invasive change. And it would mean that SSE systems with fast event streams might work poorly. 2. Invent a new kind of Body which doesn't use Read at all, and instead has a more sophisticated API. This would be super-invasive and heavyweight. 3. Find a way to encode the necessary information in the Read trait protocol. Chosen solution: It turns out that option 3 is quite easy. The read() call can return an io::Error. There are at least some errors that clearly ought not to occur here. An obvious one is ErrorKind::WouldBlock. Rocket expects the reader to block. WouldBlock is only applicable to nonblocking objects. And indeed the reader will generally want to return it (once) when it is about to block. We have the Stream treat io::Error with ErrorKind::WouldBlock, from its reader, as a request to flush. There are two effects: we stop trying to accumulate a full chunk, and we issue a flush call to the underlying writer (which, eventually, makes it all the way down into hyper and BufWriter). Implementation: We provide a method ReadExt::read_max_wfs which is like read_max but which handles the WouldBlock case specially. It tells its caller whether a flush was wanted. This is implemented by adding a new code to read_max_internal. with a boolean to control it. This seemed better than inventing a trait or something. (The other read_max call site is reading http headers in data.rs, and I think it wants to tread WouldBlock as an error.) Risks and downsides: Obviously this ad-hoc extension to the Read protocol is not particularly pretty. At least, people who aren't doing SSE (or similar) won't need it and can ignore it. If for some reason the data source is actually nonblocking, this new arrangement would spin, rather than calling the situation a fatal error. This possibility seems fairly remote, in production settings at least. To migitate this it might be possible for the loop in Rocket::issue_response to bomb out if it notices it is sending lots of consecutive empty chunks. It is possible that async Rocket will want to take a different approach entirely. But it will definitely need to solve this problem somehow, and naively it seems like the obvious transformation to eg the Tokio read trait would have the same API limitation and admit the same solution. (Having a flush occur every time the body stream future returns Pending would not be good for performance, I think.) |
||
|---|---|---|
| .github | ||
| contrib | ||
| core | ||
| examples | ||
| scripts | ||
| site | ||
| .gitattributes | ||
| .gitignore | ||
| CHANGELOG.md | ||
| Cargo.toml | ||
| LICENSE-APACHE | ||
| LICENSE-MIT | ||
| README.md | ||
README.md
Rocket
Rocket is a web framework for Rust (nightly) with a focus on ease-of-use, expressibility, and speed. Here's an example of a complete Rocket application:
#![feature(proc_macro_hygiene, decl_macro)]
#[macro_use] extern crate rocket;
#[get("/<name>/<age>")]
fn hello(name: String, age: u8) -> String {
format!("Hello, {} year old named {}!", age, name)
}
fn main() {
rocket::ignite().mount("/hello", routes![hello]).launch();
}
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
Rocket is extensively documented:
- Overview: A brief look at what makes Rocket special.
- Quickstart: How to get started as quickly as possible.
- Getting Started: How to start your first Rocket project.
- Guide: A detailed guide and reference to Rocket.
- API Documentation: The "rustdocs".
The official community support channels are #rocket:mozilla.org on Matrix
and the bridged #rocket IRC channel on Freenode at chat.freenode.net. We
recommend joining us on Matrix via Riot. If your prefer IRC, you can join via
the Kiwi IRC client or a client of your own.
Building
Nightly
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 --all-features
Examples
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:
cd examples/hello_world
cargo run
You should see Hello, world! by visiting http://localhost:8000.
Testing
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. The test.sh script accepts no flags or either the
--release flag to test in release mode or the --contrib flag to test all
contrib modules individually. This script gets run by CI.
To test a crate individually, run cargo test --all-features in the
corresponding crate directory.
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 library, which was
extracted from rustc, for testing. See the compiler test
documentation
for information on how to write compiler tests.
Documentation
You can build the Rocket API documentation locally by running
./scripts/mk-docs.sh. The resulting documentation is what gets uploaded to
api.rocket.rs.
Contributing
Contributions are absolutely, positively welcome and encouraged! Contributions come in many forms. You could:
- Submit a feature request or bug report as an issue.
- Ask for improved documentation as an issue.
- Comment on issues that require feedback.
- Contribute code via pull requests.
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.
All pull requests are code reviewed and tested by the CI. Note that unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Rocket by you shall be dual licensed under the MIT License and Apache License, Version 2.0, without any additional terms or conditions.
License
Rocket is licensed under either of the following, at your option:
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)
The Rocket website source is licensed under separate terms.