rwf2
/
Rocket
mirror of https://github.com/rwf2/Rocket.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Reorganize and upgrade markup in site docs. 

The guide is now in docs/guide. All other site assets are being migrated
to a separate repository. The guide markup has been upgraded to take
advantages of improvements in the static site generator used to build
the Rocket website.
This commit is contained in:
Sergio Benitez 2024-03-02 00:08:04 -08:00
parent 9b1cf229d7
commit 70dcba3626
13 changed files with 130 additions and 136 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@ -151,4 +151,4 @@ Rocket is licensed under either of the following, at your option:
* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0) * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
* MIT License ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT) * MIT License ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
The Rocket site docs source is licensed under [separate terms](docs/LICENSE). The Rocket site docs are licensed under [separate terms](docs/LICENSE).

2
docs/guide/00-introduction.md
View File

@ -2,7 +2,7 @@
Rocket is a web framework for Rust. If you'd like, you can think of Rocket as Rocket is a web framework for Rust. If you'd like, you can think of Rocket as
being a more flexible, friendly medley of [Rails](http://rubyonrails.org), being a more flexible, friendly medley of [Rails](http://rubyonrails.org),
[Flask](http://flask.pocoo.org/), [Flask](https://flask.palletsprojects.com/),
[Bottle](http://bottlepy.org/docs/dev/index.html), and [Bottle](http://bottlepy.org/docs/dev/index.html), and
[Yesod](http://www.yesodweb.com/). We prefer to think of Rocket as something [Yesod](http://www.yesodweb.com/). We prefer to think of Rocket as something
new. Rocket aims to be fast, easy, and flexible while offering guaranteed safety new. Rocket aims to be fast, easy, and flexible while offering guaranteed safety

5
docs/guide/01-quickstart.md
View File

@ -3,8 +3,7 @@
Before you can start writing a Rocket application, you'll need a **nightly** Before you can start writing a Rocket application, you'll need a **nightly**
version of Rust installed. We recommend you use [rustup](https://rustup.rs/) to version of Rust installed. We recommend you use [rustup](https://rustup.rs/) to
install or configure such a version. If you don't have Rust installed and would install or configure such a version. If you don't have Rust installed and would
like extra guidance doing so, see the [getting started](../getting-started) like extra guidance doing so, see [Getting Started].
section.
## Running Examples ## Running Examples
@ -29,4 +28,4 @@ with `cargo run`.
libraries. When copying the examples for your own use, you should modify the libraries. When copying the examples for your own use, you should modify the
`Cargo.toml` files as explained in the [Getting Started] guide. `Cargo.toml` files as explained in the [Getting Started] guide.
[Getting Started]: ../getting-started [Getting Started]: ../getting-started/

6
docs/guide/03-overview.md
View File

@ -74,7 +74,7 @@ fn world() -> &'static str { // <- request handler
This declares the `world` route to match against the static path `"/world"` on This declares the `world` route to match against the static path `"/world"` on
incoming `GET` requests. The `world` route is simple, but additional route incoming `GET` requests. The `world` route is simple, but additional route
parameters are necessary when building more interesting applications. The parameters are necessary when building more interesting applications. The
[Requests](../requests) section describes the available options for [Requests](../requests/) section describes the available options for
constructing routes. constructing routes.
## Mounting ## Mounting
@ -206,6 +206,6 @@ If we visit `localhost:8000/hello/world`, we see `Hello, world!`, exactly as we
expected. expected.
A version of this example's complete crate, ready to `cargo run`, can be found A version of this example's complete crate, ready to `cargo run`, can be found
on [GitHub](@example/hello_world). You can find dozens of other complete on [GitHub](@git/v0.4/examples/hello_world). You can find dozens of other complete
examples, spanning all of Rocket's features, in the [GitHub examples examples, spanning all of Rocket's features, in the [GitHub examples
directory](@example/). directory](@git/v0.4/examples/).

76
docs/guide/04-requests.md
View File

@ -30,7 +30,7 @@ validations. Rocket's code generation takes care of actually validating the
properties. This section describes how to ask Rocket to validate against all of properties. This section describes how to ask Rocket to validate against all of
these properties and more. these properties and more.
[`route`]: @api/rocket/attr.route.html [`route`]: @api/v0.4/rocket/attr.route.html
## Methods ## Methods
@ -66,7 +66,7 @@ request contains a body of `Content-Type: application/x-www-form-urlencoded` and
the form's **first** field has the name `_method` and a valid HTTP method name the form's **first** field has the name `_method` and a valid HTTP method name
as its value (such as `"PUT"`), that field's value is used as the method for the as its value (such as `"PUT"`), that field's value is used as the method for the
incoming request. This allows Rocket applications to submit non-`POST` forms. incoming request. This allows Rocket applications to submit non-`POST` forms.
The [todo example](@example/todo/static/index.html.tera#L47) makes use of this The [todo example](@git/v0.4/examples/todo/static/index.html.tera#L47) makes use of this
feature to submit `PUT` and `DELETE` requests from a web form. feature to submit `PUT` and `DELETE` requests from a web form.
## Dynamic Paths ## Dynamic Paths
@ -115,8 +115,8 @@ fn hello(name: String, age: u8, cool: bool) -> String {
} }
``` ```
[`FromParam`]: @api/rocket/request/trait.FromParam.html [`FromParam`]: @api/v0.4/rocket/request/trait.FromParam.html
[`FromParam` API docs]: @api/rocket/request/trait.FromParam.html [`FromParam` API docs]: @api/v0.4/rocket/request/trait.FromParam.html
! note: Rocket types _raw_ strings separately from decoded strings. ! note: Rocket types _raw_ strings separately from decoded strings.
@ -135,7 +135,7 @@ fn hello(name: String, age: u8, cool: bool) -> String {
potentially unsafe access to the string (`&RawStr`), or safe access to the potentially unsafe access to the string (`&RawStr`), or safe access to the
string at the cost of an allocation (`String`). string at the cost of an allocation (`String`).
[`RawStr`]: @api/rocket/http/struct.RawStr.html [`RawStr`]: @api/v0.4/rocket/http/struct.RawStr.html
### Multiple Segments ### Multiple Segments
@ -185,9 +185,9 @@ fn files(file: PathBuf) -> Option<NamedFile> {
`rocket.mount("/public", StaticFiles::from("/static"))` `rocket.mount("/public", StaticFiles::from("/static"))`
[`rocket_contrib`]: @api/rocket_contrib/ [`rocket_contrib`]: @api/v0.4/rocket_contrib/
[`StaticFiles`]: @api/rocket_contrib/serve/struct.StaticFiles.html [`StaticFiles`]: @api/v0.4/rocket_contrib/serve/struct.StaticFiles.html
[`FromSegments`]: @api/rocket/request/trait.FromSegments.html [`FromSegments`]: @api/v0.4/rocket/request/trait.FromSegments.html
## Forwarding ## Forwarding
@ -325,7 +325,7 @@ Any number of dynamic query segments are allowed. A query segment can be of any
type, including your own, as long as the type implements the [`FromFormValue`] type, including your own, as long as the type implements the [`FromFormValue`]
trait. trait.
[`FromFormValue`]: @api/rocket/request/trait.FromFormValue.html [`FromFormValue`]: @api/v0.4/rocket/request/trait.FromFormValue.html
### Optional Parameters ### Optional Parameters
@ -362,7 +362,7 @@ value `false` if it is missing. The default value for a missing parameter can be
customized for your own types that implement `FromFormValue` by implementing customized for your own types that implement `FromFormValue` by implementing
[`FromFormValue::default()`]. [`FromFormValue::default()`].
[`FromFormValue::default()`]: @api/rocket/request/trait.FromFormValue.html#method.default [`FromFormValue::default()`]: @api/v0.4/rocket/request/trait.FromFormValue.html#method.default
### Multiple Segments ### Multiple Segments
@ -412,9 +412,9 @@ fn item(id: usize, user: Option<Form<User>>) { /* ... */ }
``` ```
For more query handling examples, see [the `query_params` For more query handling examples, see [the `query_params`
example](@example/query_params). example](@git/v0.4/examples/query_params).
[`FromQuery`]: @api/rocket/request/trait.FromQuery.html [`FromQuery`]: @api/v0.4/rocket/request/trait.FromQuery.html
## Request Guards ## Request Guards
@ -454,8 +454,8 @@ short-circuiting; if one guard fails, the remaining are not attempted. To learn
more about request guards and implementing them, see the [`FromRequest`] more about request guards and implementing them, see the [`FromRequest`]
documentation. documentation.
[`FromRequest`]: @api/rocket/request/trait.FromRequest.html [`FromRequest`]: @api/v0.4/rocket/request/trait.FromRequest.html
[`Cookies`]: @api/rocket/http/enum.Cookies.html [`Cookies`]: @api/v0.4/rocket/http/enum.Cookies.html
### Custom Guards ### Custom Guards
@ -610,7 +610,7 @@ be set and removed using the `Cookies` guard. The [cookies example] on GitHub
illustrates further use of the `Cookies` type to get and set cookies, while the illustrates further use of the `Cookies` type to get and set cookies, while the
[`Cookies`] documentation contains complete usage information. [`Cookies`] documentation contains complete usage information.
[cookies example]: @example/cookies [cookies example]: @git/v0.4/examples/cookies
### Private Cookies ### Private Cookies
@ -651,7 +651,7 @@ fn logout(mut cookies: Cookies) -> Flash<Redirect> {
} }
``` ```
[`Cookies::add()`]: @api/rocket/http/enum.Cookies.html#method.add [`Cookies::add()`]: @api/v0.4/rocket/http/enum.Cookies.html#method.add
Support for private cookies, which depends on the [`ring`] library, can be Support for private cookies, which depends on the [`ring`] library, can be
omitted at build time by disabling Rocket's default features, in-turn disabling omitted at build time by disabling Rocket's default features, in-turn disabling
@ -680,12 +680,12 @@ Generating a string suitable for use as a `secret_key` configuration value is
usually done through tools like `openssl`. Using `openssl`, a 256-bit base64 key usually done through tools like `openssl`. Using `openssl`, a 256-bit base64 key
can be generated with the command `openssl rand -base64 32`. can be generated with the command `openssl rand -base64 32`.
For more information on configuration, see the [Configuration](../configuration) For more information on configuration, see the [Configuration](../configuration/)
section of the guide. section of the guide.
[`get_private`]: @api/rocket/http/enum.Cookies.html#method.get_private [`get_private`]: @api/v0.4/rocket/http/enum.Cookies.html#method.get_private
[`add_private`]: @api/rocket/http/enum.Cookies.html#method.add_private [`add_private`]: @api/v0.4/rocket/http/enum.Cookies.html#method.add_private
[`remove_private`]: @api/rocket/http/enum.Cookies.html#method.remove_private [`remove_private`]: @api/v0.4/rocket/http/enum.Cookies.html#method.remove_private
### One-At-A-Time ### One-At-A-Time
@ -819,7 +819,7 @@ header will match `user`. If instead the route had been declared as `post`,
Rocket would match the `format` against the `Content-Type` header of the Rocket would match the `format` against the `Content-Type` header of the
incoming response. incoming response.
[`ContentType::parse_flexible()`]: @api/rocket/http/struct.ContentType.html#method.parse_flexible [`ContentType::parse_flexible()`]: @api/v0.4/rocket/http/struct.ContentType.html#method.parse_flexible
## Body Data ## Body Data
@ -840,7 +840,7 @@ fn new(input: T) { /* .. */ }
Any type that implements [`FromData`] is also known as _a data guard_. Any type that implements [`FromData`] is also known as _a data guard_.
[`FromData`]: @api/rocket/data/trait.FromData.html [`FromData`]: @api/v0.4/rocket/data/trait.FromData.html
### Forms ### Forms
@ -890,9 +890,9 @@ and `Result` types:
fn new(task: Option<Form<Task>>) { /* .. */ } fn new(task: Option<Form<Task>>) { /* .. */ }
``` ```
[`Form`]: @api/rocket/request/struct.Form.html [`Form`]: @api/v0.4/rocket/request/struct.Form.html
[`FromForm`]: @api/rocket/request/trait.FromForm.html [`FromForm`]: @api/v0.4/rocket/request/trait.FromForm.html
[`FromFormValue`]: @api/rocket/request/trait.FromFormValue.html [`FromFormValue`]: @api/v0.4/rocket/request/trait.FromFormValue.html
#### Lenient Parsing #### Lenient Parsing
@ -932,7 +932,7 @@ struct Task {
fn new(task: LenientForm<Task>) { /* .. */ } fn new(task: LenientForm<Task>) { /* .. */ }
``` ```
[`LenientForm`]: @api/rocket/request/struct.LenientForm.html [`LenientForm`]: @api/v0.4/rocket/request/struct.LenientForm.html
#### Field Renaming #### Field Renaming
@ -1034,13 +1034,13 @@ decorated enum. The implementation returns successfully when the form value
matches, case insensitively, the stringified version of a variant's name, matches, case insensitively, the stringified version of a variant's name,
returning an instance of said variant. returning an instance of said variant.
The [form validation](@example/form_validation) and [form kitchen The [form validation](@git/v0.4/examples/form_validation) and [form kitchen
sink](@example/form_kitchen_sink) examples provide further illustrations. sink](@git/v0.4/examples/form_kitchen_sink) examples provide further illustrations.
### JSON ### JSON
Handling JSON data is no harder: simply use the Handling JSON data is no harder: simply use the
[`Json`](@api/rocket_contrib/json/struct.Json.html) type from [`Json`](@api/v0.4/rocket_contrib/json/struct.Json.html) type from
[`rocket_contrib`]: [`rocket_contrib`]:
```rust ```rust
@ -1067,13 +1067,13 @@ The only condition is that the generic type in `Json` implements the
`Deserialize` trait from [Serde](https://github.com/serde-rs/json). See the `Deserialize` trait from [Serde](https://github.com/serde-rs/json). See the
[JSON example] on GitHub for a complete example. [JSON example] on GitHub for a complete example.
[JSON example]: @example/json [JSON example]: @git/v0.4/examples/json
### Streaming ### Streaming
Sometimes you just want to handle incoming data directly. For example, you might Sometimes you just want to handle incoming data directly. For example, you might
want to stream the incoming data out to a file. Rocket makes this as simple as want to stream the incoming data out to a file. Rocket makes this as simple as
possible via the [`Data`](@api/rocket/data/struct.Data.html) possible via the [`Data`](@api/v0.4/rocket/data/struct.Data.html)
type: type:
```rust ```rust
@ -1094,7 +1094,7 @@ The route above accepts any `POST` request to the `/upload` path with
`tmp/upload.txt`, and the number of bytes written is returned as a plain text `tmp/upload.txt`, and the number of bytes written is returned as a plain text
response if the upload succeeds. If the upload fails, an error response is response if the upload succeeds. If the upload fails, an error response is
returned. The handler above is complete. It really is that simple! See the returned. The handler above is complete. It really is that simple! See the
[GitHub example code](@example/raw_upload) for the full crate. [GitHub example code](@git/v0.4/examples/raw_upload) for the full crate.
! warning: You should _always_ set limits when reading incoming data. ! warning: You should _always_ set limits when reading incoming data.
@ -1175,10 +1175,10 @@ fn main() {
Unlike route request handlers, catchers take exactly zero or one parameter. If Unlike route request handlers, catchers take exactly zero or one parameter. If
the catcher takes a parameter, it must be of type [`&Request`]. The [error the catcher takes a parameter, it must be of type [`&Request`]. The [error
catcher example](@example/errors) on GitHub illustrates their use in full. catcher example](@git/v0.4/examples/errors) on GitHub illustrates their use in full.
[`catch`]: @api/rocket/attr.catch.html [`catch`]: @api/v0.4/rocket/attr.catch.html
[`register()`]: @api/rocket/struct.Rocket.html#method.register [`register()`]: @api/v0.4/rocket/struct.Rocket.html#method.register
[`mount()`]: @api/rocket/struct.Rocket.html#method.mount [`mount()`]: @api/v0.4/rocket/struct.Rocket.html#method.mount
[`catchers!`]: @api/rocket/macro.catchers.html [`catchers!`]: @api/v0.4/rocket/macro.catchers.html
[`&Request`]: @api/rocket/struct.Request.html [`&Request`]: @api/v0.4/rocket/struct.Request.html

68
docs/guide/05-responses.md
View File

@ -6,7 +6,7 @@ trait can be returned, including your own. In this section, we describe the
`Responder` trait as well as several useful `Responder`s provided by Rocket. `Responder` trait as well as several useful `Responder`s provided by Rocket.
We'll also briefly discuss how to implement your own `Responder`. We'll also briefly discuss how to implement your own `Responder`.
[`Responder`]: @api/rocket/response/trait.Responder.html [`Responder`]: @api/v0.4/rocket/response/trait.Responder.html
## Responder ## Responder
@ -17,7 +17,7 @@ decides which to use. For instance, `String` uses a fixed-sized body, while
`File` uses a streamed response. Responders may dynamically adjust their `File` uses a streamed response. Responders may dynamically adjust their
responses according to the incoming `Request` they are responding to. responses according to the incoming `Request` they are responding to.
[`Response`]: @api/rocket/response/struct.Response.html [`Response`]: @api/v0.4/rocket/response/struct.Response.html
### Wrapping ### Wrapping
@ -31,7 +31,7 @@ struct WrappingResponder<R>(R);
A wrapping responder modifies the response returned by `R` before responding A wrapping responder modifies the response returned by `R` before responding
with that same response. For instance, Rocket provides `Responder`s in the with that same response. For instance, Rocket provides `Responder`s in the
[`status` module](@api/rocket/response/status/) that override the status code of [`status` module](@api/v0.4/rocket/response/status/) that override the status code of
the wrapped `Responder`. As an example, the [`Accepted`] type sets the status to the wrapped `Responder`. As an example, the [`Accepted`] type sets the status to
`202 - Accepted`. It can be used as follows: `202 - Accepted`. It can be used as follows:
@ -48,7 +48,7 @@ fn new(id: usize) -> status::Accepted<String> {
} }
``` ```
Similarly, the types in the [`content` module](@api/rocket/response/content/) Similarly, the types in the [`content` module](@api/v0.4/rocket/response/content/)
can be used to override the Content-Type of a response. For instance, to set the can be used to override the Content-Type of a response. For instance, to set the
Content-Type of `&'static str` to JSON, you can use the [`content::Json`] type Content-Type of `&'static str` to JSON, you can use the [`content::Json`] type
as follows: as follows:
@ -67,8 +67,8 @@ fn json() -> content::Json<&'static str> {
! warning: This is _not_ the same as the [`Json`] in [`rocket_contrib`]! ! warning: This is _not_ the same as the [`Json`] in [`rocket_contrib`]!
[`Accepted`]: @api/rocket/response/status/struct.Accepted.html [`Accepted`]: @api/v0.4/rocket/response/status/struct.Accepted.html
[`content::Json`]: @api/rocket/response/content/struct.Json.html [`content::Json`]: @api/v0.4/rocket/response/content/struct.Json.html
### Errors ### Errors
@ -163,7 +163,7 @@ simply including fields of these types.
For more on using the `Responder` derive, see the [`Responder` derive] For more on using the `Responder` derive, see the [`Responder` derive]
documentation. documentation.
[`Responder` derive]: @api/rocket/derive.Responder.html [`Responder` derive]: @api/v0.4/rocket/derive.Responder.html
## Implementations ## Implementations
@ -291,14 +291,14 @@ library. Among these are:
* [`MsgPack`] - Automatically serializes values into MessagePack. * [`MsgPack`] - Automatically serializes values into MessagePack.
* [`Template`] - Renders a dynamic template using handlebars or Tera. * [`Template`] - Renders a dynamic template using handlebars or Tera.
[`status`]: @api/rocket/response/status/ [`status`]: @api/v0.4/rocket/response/status/
[`response`]: @api/rocket/response/ [`response`]: @api/v0.4/rocket/response/
[`NamedFile`]: @api/rocket/response/struct.NamedFile.html [`NamedFile`]: @api/v0.4/rocket/response/struct.NamedFile.html
[`Content`]: @api/rocket/response/struct.Content.html [`Content`]: @api/v0.4/rocket/response/struct.Content.html
[`Redirect`]: @api/rocket/response/struct.Redirect.html [`Redirect`]: @api/v0.4/rocket/response/struct.Redirect.html
[`Stream`]: @api/rocket/response/struct.Stream.html [`Stream`]: @api/v0.4/rocket/response/struct.Stream.html
[`Flash`]: @api/rocket/response/struct.Flash.html [`Flash`]: @api/v0.4/rocket/response/struct.Flash.html
[`MsgPack`]: @api/rocket_contrib/msgpack/struct.MsgPack.html [`MsgPack`]: @api/v0.4/rocket_contrib/msgpack/struct.MsgPack.html
### Streaming ### Streaming
@ -325,7 +325,7 @@ fn stream() -> Result<Stream<UnixStream>, std::io::Error> {
# } # }
``` ```
[`rocket_contrib`]: @api/rocket_contrib/ [`rocket_contrib`]: @api/v0.4/rocket_contrib/
### JSON ### JSON
@ -362,10 +362,10 @@ fails, a **500 - Internal Server Error** is returned.
The [JSON example on GitHub] provides further illustration. The [JSON example on GitHub] provides further illustration.
[`Json`]: @api/rocket_contrib/json/struct.Json.html [`Json`]: @api/v0.4/rocket_contrib/json/struct.Json.html
[`Serialize`]: https://docs.serde.rs/serde/trait.Serialize.html [`Serialize`]: https://docs.serde.rs/serde/trait.Serialize.html
[`serde`]: https://docs.serde.rs/serde/ [`serde`]: https://docs.serde.rs/serde/
[JSON example on GitHub]: @example/json [JSON example on GitHub]: @git/v0.4/examples/json
## Templates ## Templates
@ -397,7 +397,7 @@ structs, `HashMaps`, and others.
For a template to be renderable, it must first be registered. The `Template` For a template to be renderable, it must first be registered. The `Template`
fairing automatically registers all discoverable templates when attached. The fairing automatically registers all discoverable templates when attached. The
[Fairings](../fairings) sections of the guide provides more information on [Fairings](../fairings/) sections of the guide provides more information on
fairings. To attach the template fairing, simply call fairings. To attach the template fairing, simply call
`.attach(Template::fairing())` on an instance of `Rocket` as follows: `.attach(Template::fairing())` on an instance of `Rocket` as follows:
@ -436,11 +436,11 @@ reloading is disabled.
The [`Template`] API documentation contains more information about templates, The [`Template`] API documentation contains more information about templates,
including how to customize a template engine to add custom helpers and filters. including how to customize a template engine to add custom helpers and filters.
The [Handlebars templates example](@example/handlebars_templates) is a The [Handlebars templates example](@git/v0.4/examples/handlebars_templates) is a
fully composed application that makes use of Handlebars templates, while the fully composed application that makes use of Handlebars templates, while the
[Tera templates example](@example/tera_templates) does the same for Tera. [Tera templates example](@git/v0.4/examples/tera_templates) does the same for Tera.
[`Template`]: @api/rocket_contrib/templates/struct.Template.html [`Template`]: @api/v0.4/rocket_contrib/templates/struct.Template.html
[configurable]: ../configuration/#extras [configurable]: ../configuration/#extras
## Typed URIs ## Typed URIs
@ -654,15 +654,15 @@ uri!(person: id = 100, details = UserDetails { age: Some(20), nickname: "Bob".in
See the [`FromUriParam`] documentation for further details. See the [`FromUriParam`] documentation for further details.
[`Origin`]: @api/rocket/http/uri/struct.Origin.html [`Origin`]: @api/v0.4/rocket/http/uri/struct.Origin.html
[`UriPart`]: @api/rocket/http/uri/trait.UriPart.html [`UriPart`]: @api/v0.4/rocket/http/uri/trait.UriPart.html
[`Uri`]: @api/rocket/http/uri/enum.Uri.html [`Uri`]: @api/v0.4/rocket/http/uri/enum.Uri.html
[`Redirect::to()`]: @api/rocket/response/struct.Redirect.html#method.to [`Redirect::to()`]: @api/v0.4/rocket/response/struct.Redirect.html#method.to
[`uri!`]: @api/rocket/macro.uri.html [`uri!`]: @api/v0.4/rocket/macro.uri.html
[`UriDisplay`]: @api/rocket/http/uri/trait.UriDisplay.html [`UriDisplay`]: @api/v0.4/rocket/http/uri/trait.UriDisplay.html
[`FromUriParam`]: @api/rocket/http/uri/trait.FromUriParam.html [`FromUriParam`]: @api/v0.4/rocket/http/uri/trait.FromUriParam.html
[`Path`]: @api/rocket/http/uri/enum.Path.html [`Path`]: @api/v0.4/rocket/http/uri/enum.Path.html
[`Query`]: @api/rocket/http/uri/enum.Query.html [`Query`]: @api/v0.4/rocket/http/uri/enum.Query.html
[`Ignorable`]: @api/rocket/http/uri/trait.Ignorable.html [`Ignorable`]: @api/v0.4/rocket/http/uri/trait.Ignorable.html
[`UriDisplayPath`]: @api/rocket/derive.UriDisplayPath.html [`UriDisplayPath`]: @api/v0.4/rocket/derive.UriDisplayPath.html
[`UriDisplayQuery`]: @api/rocket/derive.UriDisplayQuery.html [`UriDisplayQuery`]: @api/v0.4/rocket/derive.UriDisplayQuery.html

18
docs/guide/06-state.md
View File

@ -30,7 +30,7 @@ The process for using managed state is simple:
### Adding State ### Adding State
To instruct Rocket to manage state for your application, call the To instruct Rocket to manage state for your application, call the
[`manage`](@api/rocket/struct.Rocket.html#method.manage) method [`manage`](@api/v0.4/rocket/struct.Rocket.html#method.manage) method
on an instance of `Rocket`. For example, to ask Rocket to manage a `HitCount` on an instance of `Rocket`. For example, to ask Rocket to manage a `HitCount`
structure with an internal `AtomicUsize` with an initial value of `0`, we can structure with an internal `AtomicUsize` with an initial value of `0`, we can
write the following: write the following:
@ -63,7 +63,7 @@ rocket::ignite()
### Retrieving State ### Retrieving State
State that is being managed by Rocket can be retrieved via the State that is being managed by Rocket can be retrieved via the
[`State`](@api/rocket/struct.State.html) type: a [request [`State`](@api/v0.4/rocket/struct.State.html) type: a [request
guard](../requests/#request-guards) for managed state. To use the request guard](../requests/#request-guards) for managed state. To use the request
guard, add a `State<T>` type to any request handler, where `T` is the type of guard, add a `State<T>` type to any request handler, where `T` is the type of
the managed state. For example, we can retrieve and respond with the current the managed state. For example, we can retrieve and respond with the current
@ -108,9 +108,9 @@ fn state(hit_count: State<HitCount>, config: State<Config>) { /* .. */ }
**500** error to the client. **500** error to the client.
You can find a complete example using the `HitCount` structure in the [state You can find a complete example using the `HitCount` structure in the [state
example on GitHub](@example/state) and learn more about the [`manage` example on GitHub](@git/v0.4/examples/state) and learn more about the [`manage`
method](@api/rocket/struct.Rocket.html#method.manage) and [`State` method](@api/v0.4/rocket/struct.Rocket.html#method.manage) and [`State`
type](@api/rocket/struct.State.html) in the API docs. type](@api/v0.4/rocket/struct.State.html) in the API docs.
### Within Guards ### Within Guards
@ -142,7 +142,7 @@ impl<'a, 'r> FromRequest<'a, 'r> for T {
} }
``` ```
[`Request::guard()`]: @api/rocket/struct.Request.html#method.guard [`Request::guard()`]: @api/v0.4/rocket/struct.Request.html#method.guard
## Request-Local State ## Request-Local State
@ -204,8 +204,8 @@ which uses request-local state to cache expensive authentication and
authorization computations, and the [`Fairing`] documentation, which uses authorization computations, and the [`Fairing`] documentation, which uses
request-local state to implement request timing. request-local state to implement request timing.
[`FromRequest` request-local state]: @api/rocket/request/trait.FromRequest.html#request-local-state [`FromRequest` request-local state]: @api/v0.4/rocket/request/trait.FromRequest.html#request-local-state
[`Fairing`]: @api/rocket/fairing/trait.Fairing.html#request-local-state [`Fairing`]: @api/v0.4/rocket/fairing/trait.Fairing.html#request-local-state
## Databases ## Databases
@ -355,4 +355,4 @@ postgres = { version = "0.15", features = ["with-chrono"] }
For more on Rocket's built-in database support, see the For more on Rocket's built-in database support, see the
[`rocket_contrib::databases`] module documentation. [`rocket_contrib::databases`] module documentation.
[`rocket_contrib::databases`]: @api/rocket_contrib/databases/index.html [`rocket_contrib::databases`]: @api/v0.4/rocket_contrib/databases/index.html

24
docs/guide/07-fairings.md
View File

@ -36,7 +36,7 @@ that can be used to solve problems in a clean, composable, and robust manner.
fairing to record timing and usage statistics or to enforce global security fairing to record timing and usage statistics or to enforce global security
policies. policies.
[`Fairing`]: @api/rocket/fairing/trait.Fairing.html [`Fairing`]: @api/v0.4/rocket/fairing/trait.Fairing.html
[request guard]: ../requests/#request-guards [request guard]: ../requests/#request-guards
[request guards]: ../requests/#request-guards [request guards]: ../requests/#request-guards
[data guards]: ../requests/#body-data [data guards]: ../requests/#body-data
@ -60,8 +60,8 @@ rocket::ignite()
# } # }
``` ```
[`attach`]: @api/rocket/struct.Rocket.html#method.attach [`attach`]: @api/v0.4/rocket/struct.Rocket.html#method.attach
[`Rocket`]: @api/rocket/struct.Rocket.html [`Rocket`]: @api/v0.4/rocket/struct.Rocket.html
Fairings are executed in the order in which they are attached: the first Fairings are executed in the order in which they are attached: the first
attached fairing has its callbacks executed before all others. Because fairing attached fairing has its callbacks executed before all others. Because fairing
@ -76,7 +76,7 @@ events is described below:
* **Attach (`on_attach`)** * **Attach (`on_attach`)**
An attach callback is called when a fairing is first attached via the An attach callback is called when a fairing is first attached via the
[`attach`](@api/rocket/struct.Rocket.html#method.attach) method. An attach [`attach`](@api/v0.4/rocket/struct.Rocket.html#method.attach) method. An attach
callback can arbitrarily modify the `Rocket` instance being constructed and callback can arbitrarily modify the `Rocket` instance being constructed and
optionally abort launch. Attach fairings are commonly used to parse and optionally abort launch. Attach fairings are commonly used to parse and
validate configuration values, aborting on bad configurations, and inserting validate configuration values, aborting on bad configurations, and inserting
@ -115,12 +115,12 @@ fairing and determine the set of callbacks the fairing is registering for. A
[`on_launch`], [`on_request`], and [`on_response`]. Each callback has a default [`on_launch`], [`on_request`], and [`on_response`]. Each callback has a default
implementation that does absolutely nothing. implementation that does absolutely nothing.
[`Info`]: @api/rocket/fairing/struct.Info.html [`Info`]: @api/v0.4/rocket/fairing/struct.Info.html
[`info`]: @api/rocket/fairing/trait.Fairing.html#tymethod.info [`info`]: @api/v0.4/rocket/fairing/trait.Fairing.html#tymethod.info
[`on_attach`]: @api/rocket/fairing/trait.Fairing.html#method.on_attach [`on_attach`]: @api/v0.4/rocket/fairing/trait.Fairing.html#method.on_attach
[`on_launch`]: @api/rocket/fairing/trait.Fairing.html#method.on_launch [`on_launch`]: @api/v0.4/rocket/fairing/trait.Fairing.html#method.on_launch
[`on_request`]: @api/rocket/fairing/trait.Fairing.html#method.on_request [`on_request`]: @api/v0.4/rocket/fairing/trait.Fairing.html#method.on_request
[`on_response`]: @api/rocket/fairing/trait.Fairing.html#method.on_response [`on_response`]: @api/v0.4/rocket/fairing/trait.Fairing.html#method.on_response
### Requirements ### Requirements
@ -196,7 +196,7 @@ impl Fairing for Counter {
``` ```
The complete example can be found in the [`Fairing` The complete example can be found in the [`Fairing`
documentation](@api/rocket/fairing/trait.Fairing.html#example). documentation](@api/v0.4/rocket/fairing/trait.Fairing.html#example).
## Ad-Hoc Fairings ## Ad-Hoc Fairings
@ -225,4 +225,4 @@ rocket::ignite()
})); }));
``` ```
[`AdHoc`]: @api/rocket/fairing/struct.AdHoc.html [`AdHoc`]: @api/v0.4/rocket/fairing/struct.AdHoc.html

24
docs/guide/08-testing.md
View File

@ -49,10 +49,10 @@ instance. Usage is straightforward:
# let _ = response; # let _ = response;
``` ```
[`local`]: @api/rocket/local/ [`local`]: @api/v0.4/rocket/local/
[`Client`]: @api/rocket/local/struct.Client.html [`Client`]: @api/v0.4/rocket/local/struct.Client.html
[`LocalRequest`]: @api/rocket/local/struct.LocalRequest.html [`LocalRequest`]: @api/v0.4/rocket/local/struct.LocalRequest.html
[`Rocket`]: @api/rocket/struct.Rocket.html [`Rocket`]: @api/v0.4/rocket/struct.Rocket.html
## Validating Responses ## Validating Responses
@ -70,13 +70,13 @@ a few below:
* [`body_string`]: returns the body data as a `String`. * [`body_string`]: returns the body data as a `String`.
* [`body_bytes`]: returns the body data as a `Vec<u8>`. * [`body_bytes`]: returns the body data as a `Vec<u8>`.
[`LocalResponse`]: @api/rocket/local/struct.LocalResponse.html [`LocalResponse`]: @api/v0.4/rocket/local/struct.LocalResponse.html
[`Response`]: @api/rocket/struct.Response.html [`Response`]: @api/v0.4/rocket/struct.Response.html
[`status`]: @api/rocket/struct.Response.html#method.status [`status`]: @api/v0.4/rocket/struct.Response.html#method.status
[`content_type`]: @api/rocket/struct.Response.html#method.content_type [`content_type`]: @api/v0.4/rocket/struct.Response.html#method.content_type
[`headers`]: @api/rocket/struct.Response.html#method.headers [`headers`]: @api/v0.4/rocket/struct.Response.html#method.headers
[`body_string`]: @api/rocket/struct.Response.html#method.body_string [`body_string`]: @api/v0.4/rocket/struct.Response.html#method.body_string
[`body_bytes`]: @api/rocket/struct.Response.html#method.body_bytes [`body_bytes`]: @api/v0.4/rocket/struct.Response.html#method.body_bytes
These methods are typically used in combination with the `assert_eq!` or These methods are typically used in combination with the `assert_eq!` or
`assert!` macros as follows: `assert!` macros as follows:
@ -252,7 +252,7 @@ mod test {
``` ```
The tests can be run with `cargo test`. You can find the full source code to The tests can be run with `cargo test`. You can find the full source code to
[this example on GitHub](@example/testing). [this example on GitHub](@git/v0.4/examples/testing).
## Codegen Debug ## Codegen Debug

10
docs/guide/09-configuration.md
View File

@ -143,8 +143,8 @@ incoming JSON data. You should use the `limits` parameter for your application's
data limits as well. Data limits can be retrieved at runtime via the data limits as well. Data limits can be retrieved at runtime via the
[`Request::limits()`] method. [`Request::limits()`] method.
[`Request::limits()`]: @api/rocket/struct.Request.html#method.limits [`Request::limits()`]: @api/v0.4/rocket/struct.Request.html#method.limits
[`Json`]: @api/rocket_contrib/json/struct.Json.html#incoming-data-limits [`Json`]: @api/v0.4/rocket_contrib/json/struct.Json.html#incoming-data-limits
## Extras ## Extras
@ -152,7 +152,7 @@ In addition to overriding default configuration parameters, a configuration file
can also define values for any number of _extra_ configuration parameters. While can also define values for any number of _extra_ configuration parameters. While
these parameters aren't used by Rocket directly, other libraries, or your own these parameters aren't used by Rocket directly, other libraries, or your own
application, can use them as they wish. As an example, the application, can use them as they wish. As an example, the
[Template](@api/rocket_contrib/templates/struct.Template.html) type [Template](@api/v0.4/rocket_contrib/templates/struct.Template.html) type
accepts a value for the `template_dir` configuration parameter. The parameter accepts a value for the `template_dir` configuration parameter. The parameter
can be set in `Rocket.toml` as follows: can be set in `Rocket.toml` as follows:
@ -292,8 +292,8 @@ all configuration from `Rocket.toml` or environment variables. In other words,
using `rocket::custom()` results in `Rocket.toml` and environment variables using `rocket::custom()` results in `Rocket.toml` and environment variables
being ignored. being ignored.
[`rocket::custom()`]: @api/rocket/fn.custom.html [`rocket::custom()`]: @api/v0.4/rocket/fn.custom.html
[`ConfigBuilder`]: @api/rocket/config/struct.ConfigBuilder.html [`ConfigBuilder`]: @api/v0.4/rocket/config/struct.ConfigBuilder.html
## Configuring TLS ## Configuring TLS

14
docs/guide/10-pastebin.md
View File

@ -104,7 +104,7 @@ string with the specified contents. Rocket will take the string and return it as
the body of a fully formed HTTP response with `Content-Type: text/plain`. You the body of a fully formed HTTP response with `Content-Type: text/plain`. You
can read more about how Rocket formulates responses at the [API documentation can read more about how Rocket formulates responses at the [API documentation
for the Responder for the Responder
trait](@api/rocket/response/trait.Responder.html). trait](@api/v0.4/rocket/response/trait.Responder.html).
Remember that routes first need to be mounted before Rocket dispatches requests Remember that routes first need to be mounted before Rocket dispatches requests
to them. To mount the `index` route, modify the main function so that it reads: to them. To mount the `index` route, modify the main function so that it reads:
@ -226,7 +226,7 @@ use rocket::Data;
use rocket::http::RawStr; use rocket::http::RawStr;
``` ```
The [Data](@api/rocket/data/struct.Data.html) structure is key The [Data](@api/v0.4/rocket/data/struct.Data.html) structure is key
here: it represents an unopened stream to the incoming request body data. We'll here: it represents an unopened stream to the incoming request body data. We'll
use it to efficiently stream the incoming request to a file. use it to efficiently stream the incoming request to a file.
@ -334,7 +334,7 @@ Here's a first take at implementing the `retrieve` route. The route below takes
in an `<id>` as a dynamic path element. The handler uses the `id` to construct a in an `<id>` as a dynamic path element. The handler uses the `id` to construct a
path to the paste inside `upload/`, and then attempts to open the file at that path to the paste inside `upload/`, and then attempts to open the file at that
path, optionally returning the `File` if it exists. Rocket treats a `None` path, optionally returning the `File` if it exists. Rocket treats a `None`
[Responder](@api/rocket/response/trait.Responder.html#provided-implementations) [Responder](@api/v0.4/rocket/response/trait.Responder.html#provided-implementations)
as a **404** error, which is exactly what we want to return when the requested as a **404** error, which is exactly what we want to return when the requested
paste doesn't exist. paste doesn't exist.
@ -370,7 +370,7 @@ fn main() {
``` ```
Unfortunately, there's a problem with this code. Can you spot the issue? The Unfortunately, there's a problem with this code. Can you spot the issue? The
[`RawStr`](@api/rocket/http/struct.RawStr.html) type should tip you off! [`RawStr`](@api/v0.4/rocket/http/struct.RawStr.html) type should tip you off!
The issue is that the _user_ controls the value of `id`, and as a result, can The issue is that the _user_ controls the value of `id`, and as a result, can
coerce the service into opening files inside `upload/` that aren't meant to be coerce the service into opening files inside `upload/` that aren't meant to be
@ -384,7 +384,7 @@ provides the tools to prevent this and other kinds of attacks from happening.
To prevent the attack, we need to _validate_ `id` before we use it. Since the To prevent the attack, we need to _validate_ `id` before we use it. Since the
`id` is a dynamic parameter, we can use Rocket's `id` is a dynamic parameter, we can use Rocket's
[FromParam](@api/rocket/request/trait.FromParam.html) trait to [FromParam](@api/v0.4/rocket/request/trait.FromParam.html) trait to
implement the validation and ensure that the `id` is a valid `PasteId` before implement the validation and ensure that the `id` is a valid `PasteId` before
using it. We do this by implementing `FromParam` for `PasteId` in using it. We do this by implementing `FromParam` for `PasteId` in
`src/paste_id.rs`, as below: `src/paste_id.rs`, as below:
@ -475,10 +475,10 @@ through some of them to get a better feel for Rocket. Here are some ideas:
* Add a new route, `GET /<id>/<lang>` that syntax highlights the paste with ID * Add a new route, `GET /<id>/<lang>` that syntax highlights the paste with ID
`<id>` for language `<lang>`. If `<lang>` is not a known language, do no `<id>` for language `<lang>`. If `<lang>` is not a known language, do no
highlighting. Possibly validate `<lang>` with `FromParam`. highlighting. Possibly validate `<lang>` with `FromParam`.
* Use the [`local` module](@api/rocket/local/) to write unit tests for your * Use the [`local` module](@api/v0.4/rocket/local/) to write unit tests for your
pastebin. pastebin.
* Dispatch a thread before `launch`ing Rocket in `main` that periodically * Dispatch a thread before `launch`ing Rocket in `main` that periodically
cleans up idling old pastes in `upload/`. cleans up idling old pastes in `upload/`.
You can find the full source code for the [completed pastebin tutorial on You can find the full source code for the [completed pastebin tutorial on
GitHub](@example/pastebin). GitHub](@git/v0.4/examples/pastebin).

5
docs/guide/11-conclusion.md
View File

@ -22,5 +22,6 @@ a client of your own.
The best way to learn Rocket is to _build something_. It should be fun and easy, The best way to learn Rocket is to _build something_. It should be fun and easy,
and there's always someone to help. Alternatively, you can read through the and there's always someone to help. Alternatively, you can read through the
[Rocket examples](@example) or the [Rocket source code](@github/core/lib/src). [Rocket examples](@git/v0.4/examples) or the [Rocket source
Whatever you decide to do next, we hope you have a blast! code](@git/v0.4/core/lib/src). Whatever you decide to do next, we hope you have
a blast!

12
docs/guide/index.md
View File

@ -6,7 +6,7 @@ This is the official guide for Rocket v0.4. It is designed to serve as a
starting point to writing web applications with Rocket and Rust. The guide is starting point to writing web applications with Rocket and Rust. The guide is
also designed to be a reference for experienced Rocket developers. This guide is also designed to be a reference for experienced Rocket developers. This guide is
conversational in tone. For purely technical documentation with examples, see conversational in tone. For purely technical documentation with examples, see
the [API documentation](@api). the [API documentation](@api/v0.4).
The guide is split into several sections, each with a focus on a different The guide is split into several sections, each with a focus on a different
aspect of Rocket. The sections are: aspect of Rocket. The sections are:
@ -33,12 +33,6 @@ aspect of Rocket. The sections are:
## Getting Help ## Getting Help
The official community support channels are [`#rocket:mozilla.org`] on Matrix The official community support channels is [`#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.
[`#rocket:mozilla.org`]: https://chat.mozilla.org/#/room/#rocket:mozilla.org [`#rocket:mozilla.org`]: @chat
[`#rocket`]: https://kiwiirc.com/client/chat.freenode.net/#rocket
[Matrix via Riot]: https://chat.mozilla.org/#/room/#rocket:mozilla.org
[Kiwi IRC Client]: https://kiwiirc.com/client/chat.freenode.net/#rocket