63a14525d8
So. Many. Changes. This is an insane commit: simultaneously one of the best (because of all the wonderful improvements!) and one of the worst (because it is just massive) in the project's history. Routing: * All UTF-8 characters are accepted everywhere in route paths. (#998) * `path` is now `uri` in `route` attribute: `#[route(GET, path = "..")]` becomes `#[route(GET, uri = "..")]`. Forms Revamp * All form related types now reside in a new `form` module. * Multipart forms are supported. (resolves #106) * Collections are supported in forms and queries. (resolves #205) * Nested structures in forms and queries are supported. (resolves #313) * Form fields can be ad-hoc validated with `#[field(validate = expr)]`. * `FromFormValue` is now `FromFormField`, blanket implements `FromForm`. * Form field values are always percent-decoded apriori. Temporary Files * A new `TempFile` data and form guard allows streaming data directly to a file which can then be persisted. * A new `temp_dir` config parameter specifies where to store `TempFile`. * The limits `file` and `file/$ext`, where `$ext` is the file extension, determines the data limit for a `TempFile`. Capped * A new `Capped` type is used to indicate when data has been truncated due to incoming data limits. It allows checking whether data is complete or truncated. * `DataStream` methods return `Capped` types. * `DataStream` API has been revamped to account for `Capped` types. * Several `Capped<T>` types implement `FromData`, `FromForm`. * HTTP 413 (Payload Too Large) errors are now returned when data limits are exceeded. (resolves #972) Hierarchical Limits * Data limits are now hierarchical, delimited with `/`. A limit of `a/b/c` falls back to `a/b` then `a`. Core * `&RawStr` no longer implements `FromParam`. * `&str` implements `FromParam`, `FromData`, `FromForm`. * `FromTransformedData` was removed. * `FromData` gained a lifetime for use with request-local data. * The default error HTML is more compact. * `&Config` is a request guard. * The `DataStream` interface was entirely revamped. * `State` is only exported via `rocket::State`. * A `request::local_cache!()` macro was added for storing values in request-local cache without consideration for type uniqueness by using a locally generated anonymous type. * `Request::get_param()` is now `Request::param()`. * `Request::get_segments()` is now `Request::segments()`, takes a range. * `Request::get_query_value()` is now `Request::query_value()`, can parse any `FromForm` including sequences. * `std::io::Error` implements `Responder` like `Debug<std::io::Error>`. * `(Status, R)` where `R: Responder` implements `Responder` by overriding the `Status` of `R`. * The name of a route is printed first during route matching. * `FlashMessage` now only has one lifetime generic. HTTP * `RawStr` implements `serde::{Serialize, Deserialize}`. * `RawStr` implements _many_ more methods, in particular, those related to the `Pattern` API. * `RawStr::from_str()` is now `RawStr::new()`. * `RawStr::url_decode()` and `RawStr::url_decode_lossy()` only allocate as necessary, return `Cow`. * `Status` implements `Default` with `Status::Ok`. * `Status` implements `PartialEq`, `Eq`, `Hash`, `PartialOrd`, `Ord`. * Authority and origin part of `Absolute` can be modified with new `Absolute::{with,set}_authority()`, `Absolute::{with,set}_origin()` methods. * `Origin::segments()` was removed in favor of methods split into query and path parts and into raw and decoded versions. * The `Segments` iterator is smarter, returns decoded `&str` items. * `Segments::into_path_buf()` is now `Segments::to_path_buf()`. * A new `QuerySegments` is the analogous query segment iterator. * Once set, `expires` on private cookies is not overwritten. (resolves #1506) * `Origin::path()` and `Origin::query()` return `&RawStr`, not `&str`. Codegen * Preserve more spans in `uri!` macro. * Preserve spans `FromForm` field types. * All dynamic parameters in a query string must typecheck as `FromForm`. * `FromFormValue` derive removed; `FromFormField` added. * The `form` `FromForm` and `FromFormField` field attribute is now named `field`. `#[form(field = ..)]` is now `#[field(name = ..)]`. Contrib * `Json` implements `FromForm`. * `MsgPack` implements `FromForm`. * The `json!` macro is exported as `rocket_contrib::json::json!`. * Added clarifying docs to `StaticFiles`. Examples * `form_validation` and `form_kitchen_sink` removed in favor of `forms`. * The `hello_world` example uses unicode in paths. * The `json` example only allocates as necessary. Internal * Codegen uses new `exports` module with the following conventions: - Locals starts with `__` and are lowercased. - Rocket modules start with `_` and are lowercased. - `std` types start with `_` and are titlecased. - Rocket types are titlecased. * A `header` module was added to `http`, contains header types. * `SAFETY` is used as doc-string keyword for `unsafe` related comments. * The `Uri` parser no longer recognizes Rocket route URIs. |
||
|---|---|---|
| .github | ||
| contrib | ||
| core | ||
| examples | ||
| scripts | ||
| site | ||
| .gitattributes | ||
| .gitignore | ||
| Cargo.toml | ||
| CHANGELOG.md | ||
| LICENSE-APACHE | ||
| LICENSE-MIT | ||
| README.md | ||
Rocket
Rocket is an async web framework for Rust with a focus on usability, security, extensibility, and speed.
#[macro_use] extern crate rocket;
#[get("/<name>/<age>")]
fn hello(name: String, age: u8) -> String {
format!("Hello, {} year old named {}!", age, name)
}
#[launch]
fn rocket() -> rocket::Rocket {
rocket::ignite().mount("/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.
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 Element. If your prefer IRC, you can join
via the Kiwi IRC client or a client of your own.
Examples
An extensive number of examples are provided in the examples/ directory. Each
example 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.
Building and Testing
Core and Contrib
The core directory contains the three core libraries: lib, codegen, and
http. The contrib directory contains officially supported community
contributions and similarly consists of lib and codegen.
Public APIs are exposed via lib packages: core/lib is distributed as the
rocket crate while contrib/lib is distributed as the rocket_contrib crate.
The remaining crates are implementation details.
Library Testing
Rocket's complete test suite can be run with ./scripts/test.sh from the root
of the source tree. The script builds and tests all libraries and examples. It
accepts the following flags:
--contrib: tests eachcontribfeature individually--core: tests eachcorefeature individually--release: runs the testing suite inreleasemode
Additionally, a +${toolchain} flag, where ${toolchain} is a valid rustup
toolchain string, can be passed as the first parameter. The flag is forwarded to
cargo commands.
To test crates individually, simply run cargo test --all-features in the
crate's directory.
Codegen Testing
Code generation diagnostics are tested using trybuild; tests can be found in
the codegen/tests/ui-fail directory of both core and contrib. Each test is
symlinked into sibling ui-fail-stable and ui-fail-nightly directories which
contain the expected error output for stable and nightly compilers,
respectively.
Documentation
API documentation is built with ./scripts/mk-docs.sh. The resulting assets are
uploaded to api.rocket.rs.
Documentation for a released version ${x} can be found at
https://api.rocket.rs/v${x} and https://rocket.rs/v${x}. For instance, the
documentation for 0.4 can be found at https://api.rocket.rs/v0.4 and
https://rocket.rs/v0.4. Documentation for unreleased versions in branch
${branch} be found at https://api.rocket.rs/${branch} and
https://rocket.rs/${branch}. For instance, the documentation for the master
branch can be found at https://api.rocket.rs/master and
https://rocket.rs/master. Documentation for unreleased branches is updated
periodically.
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: Complex and non-obvious functionality must be properly commented.
- Documented: Public items must have doc comments with examples, if applicable.
- Styled: Your code's style should match the existing and surrounding code style.
- Simple: Your code should accomplish its task as simply and idiomatically as possible.
- Tested: You must write (and pass) convincing tests for any new functionality.
- Focused: Your code should do what it's supposed to 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 https://www.apache.org/licenses/LICENSE-2.0)
- MIT License (LICENSE-MIT or https://opensource.org/licenses/MIT)
The Rocket website source is licensed under separate terms.