Repository files navigation

Rocket is an async web framework for Rust with a focus on usability, security,extensibility, and speed.

#[macro_use]externcrate rocket;#[get("/<name>/<age>")]fnhello(name:&str,age:u8) ->String{format!("Hello, {} year old named {}!", age, name)}#[launch]fnrocket() ->_{    rocket::build().mount("/hello",routes![hello])}

Visitinglocalhost:8000/hello/John/58, for example, will trigger thehelloroute resulting in the stringHello, 58 year old named John! being sent to thebrowser. If an<age> string was passed in that can't be parsed as au8, theroute won't get called, resulting in a 404 error.

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 Matrixand the bridged#rocket IRC channel on Libera.Chat atirc.libera.chat. Werecommend joining us onMatrix via Element. If your prefer IRC, you can joinvia theKiwi IRC client or a client of your own.

An extensive number of examples are provided in theexamples/ directory. Eachexample can be compiled and run with Cargo. For instance, the following sequenceof commands builds and runs theHello, world! example:

cd examples/hellocargo run

You should seeHello, world! by visitinghttp://localhost:8000.

Thecore directory contains the three core libraries:lib,codegen, andhttp published asrocket,rocket_codegen androcket_http, respectively.The latter two are implementations details and are reexported fromrocket.

Rocket's complete test suite can be run with./scripts/test.sh from the rootof the source tree. The script builds and tests all libraries and examples inall configurations. It accepts the following flags:

• --examples: tests all examples inexamples/
• --contrib: tests eachcontrib library and feature individually
• --core: tests eachcore/lib feature individually
• --benchmarks: runs all benchmarks
• --all: runs all tests in all configurations

Additionally, a+${toolchain} flag, where${toolchain} is a validrustuptoolchain string, can be passed as the first parameter. The flag is forwarded tocargo commands. Any other extra parameters are passed directly tocargo.

To test crates individually, simply runcargo test --all-features in thecrate's directory.

Code generation diagnostics are tested usingtrybuild; tests can be found inthecodegen/tests/ui-fail directories of respectivecodegen crates. Eachtest is symlinked into siblingui-fail-stable andui-fail-nightlydirectories which contain the expected error output for stable and nightlycompilers, respectively. To update codegen test UI output, run a codegen testsuite withTRYBUILD=overwrite and inspect thediff of.std* files.

API documentation is built with./scripts/mk-docs.sh. The resulting assets areuploaded toapi.rocket.rs.

Documentation for a released version${x} can be found athttps://api.rocket.rs/v${x} andhttps://rocket.rs/v${x}. For instance, thedocumentation for0.4 can be found athttps://api.rocket.rs/v0.4 andhttps://rocket.rs/v0.4. Documentation for unreleased versions in branch${branch} be found athttps://api.rocket.rs/${branch} andhttps://rocket.rs/${branch}. For instance, the documentation for themasterbranch can be found athttps://api.rocket.rs/master andhttps://rocket.rs/master. Documentation for unreleased branches is updatedperiodically.

Contributions are absolutely, positively welcome and encouraged! Contributionscome in many forms. You could:

1. Submit a feature request or bug report as anissue.
2. Ask for improved documentation as anissue.
3. Comment onissues that require feedback.
4. Contribute code viapull requests.

We aim to keep Rocket's code quality at the highest level. This means that anycode you contribute must be:

• Commented: Complex and non-obvious functionality must be properlycommented.
• Documented: Public itemsmust have doc comments with examples, ifapplicable.
• Styled: Your code's style should match the existing and surrounding codestyle.
• Simple: Your code should accomplish its task as simply andidiomatically as possible.
• Tested: You must write (and pass) convincing tests for any newfunctionality.
• 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 youexplicitly state otherwise, any contribution intentionally submitted forinclusion in Rocket by you shall be dual licensed under the MIT License andApache License, Version 2.0, without any additional terms or conditions.

Rocket is licensed under either of the following, at your option:

• Apache License, Version 2.0, (LICENSE-APACHE orhttps://www.apache.org/licenses/LICENSE-2.0)
• MIT License (LICENSE-MIT orhttps://opensource.org/licenses/MIT)

The Rocket website docs are licensed underseparate terms.