mirror of https://github.com/rwf2/Rocket.git
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
parent
9b1cf229d7
commit
70dcba3626
|
|
@ -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)
|
||||
* 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,7 +2,7 @@
|
|||
|
||||
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),
|
||||
[Flask](http://flask.pocoo.org/),
|
||||
[Flask](https://flask.palletsprojects.com/),
|
||||
[Bottle](http://bottlepy.org/docs/dev/index.html), and
|
||||
[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
|
||||
|
|
|
|||
|
|
@ -3,8 +3,7 @@
|
|||
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
|
||||
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)
|
||||
section.
|
||||
like extra guidance doing so, see [Getting Started].
|
||||
|
||||
## Running Examples
|
||||
|
||||
|
|
@ -29,4 +28,4 @@ with `cargo run`.
|
|||
libraries. When copying the examples for your own use, you should modify the
|
||||
`Cargo.toml` files as explained in the [Getting Started] guide.
|
||||
|
||||
[Getting Started]: ../getting-started
|
||||
[Getting Started]: ../getting-started/
|
||||
|
|
|
|||
|
|
@ -74,7 +74,7 @@ fn world() -> &'static str { // <- request handler
|
|||
This declares the `world` route to match against the static path `"/world"` on
|
||||
incoming `GET` requests. The `world` route is simple, but additional route
|
||||
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.
|
||||
|
||||
## Mounting
|
||||
|
|
@ -206,6 +206,6 @@ If we visit `localhost:8000/hello/world`, we see `Hello, world!`, exactly as we
|
|||
expected.
|
||||
|
||||
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
|
||||
directory](@example/).
|
||||
directory](@git/v0.4/examples/).
|
||||
|
|
|
|||
|
|
@ -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
|
||||
these properties and more.
|
||||
|
||||
[`route`]: @api/rocket/attr.route.html
|
||||
[`route`]: @api/v0.4/rocket/attr.route.html
|
||||
|
||||
## 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
|
||||
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.
|
||||
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.
|
||||
|
||||
## Dynamic Paths
|
||||
|
|
@ -115,8 +115,8 @@ fn hello(name: String, age: u8, cool: bool) -> String {
|
|||
}
|
||||
```
|
||||
|
||||
[`FromParam`]: @api/rocket/request/trait.FromParam.html
|
||||
[`FromParam` API docs]: @api/rocket/request/trait.FromParam.html
|
||||
[`FromParam`]: @api/v0.4/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.
|
||||
|
||||
|
|
@ -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
|
||||
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
|
||||
|
||||
|
|
@ -185,9 +185,9 @@ fn files(file: PathBuf) -> Option<NamedFile> {
|
|||
|
||||
`rocket.mount("/public", StaticFiles::from("/static"))`
|
||||
|
||||
[`rocket_contrib`]: @api/rocket_contrib/
|
||||
[`StaticFiles`]: @api/rocket_contrib/serve/struct.StaticFiles.html
|
||||
[`FromSegments`]: @api/rocket/request/trait.FromSegments.html
|
||||
[`rocket_contrib`]: @api/v0.4/rocket_contrib/
|
||||
[`StaticFiles`]: @api/v0.4/rocket_contrib/serve/struct.StaticFiles.html
|
||||
[`FromSegments`]: @api/v0.4/rocket/request/trait.FromSegments.html
|
||||
|
||||
## 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`]
|
||||
trait.
|
||||
|
||||
[`FromFormValue`]: @api/rocket/request/trait.FromFormValue.html
|
||||
[`FromFormValue`]: @api/v0.4/rocket/request/trait.FromFormValue.html
|
||||
|
||||
### 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
|
||||
[`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
|
||||
|
||||
|
|
@ -412,9 +412,9 @@ fn item(id: usize, user: Option<Form<User>>) { /* ... */ }
|
|||
```
|
||||
|
||||
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
|
||||
|
||||
|
|
@ -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`]
|
||||
documentation.
|
||||
|
||||
[`FromRequest`]: @api/rocket/request/trait.FromRequest.html
|
||||
[`Cookies`]: @api/rocket/http/enum.Cookies.html
|
||||
[`FromRequest`]: @api/v0.4/rocket/request/trait.FromRequest.html
|
||||
[`Cookies`]: @api/v0.4/rocket/http/enum.Cookies.html
|
||||
|
||||
### 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
|
||||
[`Cookies`] documentation contains complete usage information.
|
||||
|
||||
[cookies example]: @example/cookies
|
||||
[cookies example]: @git/v0.4/examples/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
|
||||
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
|
||||
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.
|
||||
|
||||
[`get_private`]: @api/rocket/http/enum.Cookies.html#method.get_private
|
||||
[`add_private`]: @api/rocket/http/enum.Cookies.html#method.add_private
|
||||
[`remove_private`]: @api/rocket/http/enum.Cookies.html#method.remove_private
|
||||
[`get_private`]: @api/v0.4/rocket/http/enum.Cookies.html#method.get_private
|
||||
[`add_private`]: @api/v0.4/rocket/http/enum.Cookies.html#method.add_private
|
||||
[`remove_private`]: @api/v0.4/rocket/http/enum.Cookies.html#method.remove_private
|
||||
|
||||
### 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
|
||||
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
|
||||
|
||||
|
|
@ -840,7 +840,7 @@ fn new(input: T) { /* .. */ }
|
|||
|
||||
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
|
||||
|
||||
|
|
@ -890,9 +890,9 @@ and `Result` types:
|
|||
fn new(task: Option<Form<Task>>) { /* .. */ }
|
||||
```
|
||||
|
||||
[`Form`]: @api/rocket/request/struct.Form.html
|
||||
[`FromForm`]: @api/rocket/request/trait.FromForm.html
|
||||
[`FromFormValue`]: @api/rocket/request/trait.FromFormValue.html
|
||||
[`Form`]: @api/v0.4/rocket/request/struct.Form.html
|
||||
[`FromForm`]: @api/v0.4/rocket/request/trait.FromForm.html
|
||||
[`FromFormValue`]: @api/v0.4/rocket/request/trait.FromFormValue.html
|
||||
|
||||
#### Lenient Parsing
|
||||
|
||||
|
|
@ -932,7 +932,7 @@ struct Task {
|
|||
fn new(task: LenientForm<Task>) { /* .. */ }
|
||||
```
|
||||
|
||||
[`LenientForm`]: @api/rocket/request/struct.LenientForm.html
|
||||
[`LenientForm`]: @api/v0.4/rocket/request/struct.LenientForm.html
|
||||
|
||||
#### 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,
|
||||
returning an instance of said variant.
|
||||
|
||||
The [form validation](@example/form_validation) and [form kitchen
|
||||
sink](@example/form_kitchen_sink) examples provide further illustrations.
|
||||
The [form validation](@git/v0.4/examples/form_validation) and [form kitchen
|
||||
sink](@git/v0.4/examples/form_kitchen_sink) examples provide further illustrations.
|
||||
|
||||
### JSON
|
||||
|
||||
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`]:
|
||||
|
||||
```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
|
||||
[JSON example] on GitHub for a complete example.
|
||||
|
||||
[JSON example]: @example/json
|
||||
[JSON example]: @git/v0.4/examples/json
|
||||
|
||||
### Streaming
|
||||
|
||||
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
|
||||
possible via the [`Data`](@api/rocket/data/struct.Data.html)
|
||||
possible via the [`Data`](@api/v0.4/rocket/data/struct.Data.html)
|
||||
type:
|
||||
|
||||
```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
|
||||
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
|
||||
[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.
|
||||
|
||||
|
|
@ -1175,10 +1175,10 @@ fn main() {
|
|||
|
||||
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
|
||||
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
|
||||
[`register()`]: @api/rocket/struct.Rocket.html#method.register
|
||||
[`mount()`]: @api/rocket/struct.Rocket.html#method.mount
|
||||
[`catchers!`]: @api/rocket/macro.catchers.html
|
||||
[`&Request`]: @api/rocket/struct.Request.html
|
||||
[`catch`]: @api/v0.4/rocket/attr.catch.html
|
||||
[`register()`]: @api/v0.4/rocket/struct.Rocket.html#method.register
|
||||
[`mount()`]: @api/v0.4/rocket/struct.Rocket.html#method.mount
|
||||
[`catchers!`]: @api/v0.4/rocket/macro.catchers.html
|
||||
[`&Request`]: @api/v0.4/rocket/struct.Request.html
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
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
|
||||
|
||||
|
|
@ -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
|
||||
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
|
||||
|
||||
|
|
@ -31,7 +31,7 @@ struct WrappingResponder<R>(R);
|
|||
|
||||
A wrapping responder modifies the response returned by `R` before responding
|
||||
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
|
||||
`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
|
||||
Content-Type of `&'static str` to JSON, you can use the [`content::Json`] type
|
||||
as follows:
|
||||
|
|
@ -67,8 +67,8 @@ fn json() -> content::Json<&'static str> {
|
|||
|
||||
! warning: This is _not_ the same as the [`Json`] in [`rocket_contrib`]!
|
||||
|
||||
[`Accepted`]: @api/rocket/response/status/struct.Accepted.html
|
||||
[`content::Json`]: @api/rocket/response/content/struct.Json.html
|
||||
[`Accepted`]: @api/v0.4/rocket/response/status/struct.Accepted.html
|
||||
[`content::Json`]: @api/v0.4/rocket/response/content/struct.Json.html
|
||||
|
||||
### Errors
|
||||
|
||||
|
|
@ -163,7 +163,7 @@ simply including fields of these types.
|
|||
For more on using the `Responder` derive, see the [`Responder` derive]
|
||||
documentation.
|
||||
|
||||
[`Responder` derive]: @api/rocket/derive.Responder.html
|
||||
[`Responder` derive]: @api/v0.4/rocket/derive.Responder.html
|
||||
|
||||
## Implementations
|
||||
|
||||
|
|
@ -291,14 +291,14 @@ library. Among these are:
|
|||
* [`MsgPack`] - Automatically serializes values into MessagePack.
|
||||
* [`Template`] - Renders a dynamic template using handlebars or Tera.
|
||||
|
||||
[`status`]: @api/rocket/response/status/
|
||||
[`response`]: @api/rocket/response/
|
||||
[`NamedFile`]: @api/rocket/response/struct.NamedFile.html
|
||||
[`Content`]: @api/rocket/response/struct.Content.html
|
||||
[`Redirect`]: @api/rocket/response/struct.Redirect.html
|
||||
[`Stream`]: @api/rocket/response/struct.Stream.html
|
||||
[`Flash`]: @api/rocket/response/struct.Flash.html
|
||||
[`MsgPack`]: @api/rocket_contrib/msgpack/struct.MsgPack.html
|
||||
[`status`]: @api/v0.4/rocket/response/status/
|
||||
[`response`]: @api/v0.4/rocket/response/
|
||||
[`NamedFile`]: @api/v0.4/rocket/response/struct.NamedFile.html
|
||||
[`Content`]: @api/v0.4/rocket/response/struct.Content.html
|
||||
[`Redirect`]: @api/v0.4/rocket/response/struct.Redirect.html
|
||||
[`Stream`]: @api/v0.4/rocket/response/struct.Stream.html
|
||||
[`Flash`]: @api/v0.4/rocket/response/struct.Flash.html
|
||||
[`MsgPack`]: @api/v0.4/rocket_contrib/msgpack/struct.MsgPack.html
|
||||
|
||||
### 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
|
||||
|
||||
|
|
@ -362,10 +362,10 @@ fails, a **500 - Internal Server Error** is returned.
|
|||
|
||||
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
|
||||
[`serde`]: https://docs.serde.rs/serde/
|
||||
[JSON example on GitHub]: @example/json
|
||||
[JSON example on GitHub]: @git/v0.4/examples/json
|
||||
|
||||
## Templates
|
||||
|
||||
|
|
@ -397,7 +397,7 @@ structs, `HashMaps`, and others.
|
|||
|
||||
For a template to be renderable, it must first be registered. The `Template`
|
||||
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
|
||||
`.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,
|
||||
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
|
||||
[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
|
||||
|
||||
## 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.
|
||||
|
||||
[`Origin`]: @api/rocket/http/uri/struct.Origin.html
|
||||
[`UriPart`]: @api/rocket/http/uri/trait.UriPart.html
|
||||
[`Uri`]: @api/rocket/http/uri/enum.Uri.html
|
||||
[`Redirect::to()`]: @api/rocket/response/struct.Redirect.html#method.to
|
||||
[`uri!`]: @api/rocket/macro.uri.html
|
||||
[`UriDisplay`]: @api/rocket/http/uri/trait.UriDisplay.html
|
||||
[`FromUriParam`]: @api/rocket/http/uri/trait.FromUriParam.html
|
||||
[`Path`]: @api/rocket/http/uri/enum.Path.html
|
||||
[`Query`]: @api/rocket/http/uri/enum.Query.html
|
||||
[`Ignorable`]: @api/rocket/http/uri/trait.Ignorable.html
|
||||
[`UriDisplayPath`]: @api/rocket/derive.UriDisplayPath.html
|
||||
[`UriDisplayQuery`]: @api/rocket/derive.UriDisplayQuery.html
|
||||
[`Origin`]: @api/v0.4/rocket/http/uri/struct.Origin.html
|
||||
[`UriPart`]: @api/v0.4/rocket/http/uri/trait.UriPart.html
|
||||
[`Uri`]: @api/v0.4/rocket/http/uri/enum.Uri.html
|
||||
[`Redirect::to()`]: @api/v0.4/rocket/response/struct.Redirect.html#method.to
|
||||
[`uri!`]: @api/v0.4/rocket/macro.uri.html
|
||||
[`UriDisplay`]: @api/v0.4/rocket/http/uri/trait.UriDisplay.html
|
||||
[`FromUriParam`]: @api/v0.4/rocket/http/uri/trait.FromUriParam.html
|
||||
[`Path`]: @api/v0.4/rocket/http/uri/enum.Path.html
|
||||
[`Query`]: @api/v0.4/rocket/http/uri/enum.Query.html
|
||||
[`Ignorable`]: @api/v0.4/rocket/http/uri/trait.Ignorable.html
|
||||
[`UriDisplayPath`]: @api/v0.4/rocket/derive.UriDisplayPath.html
|
||||
[`UriDisplayQuery`]: @api/v0.4/rocket/derive.UriDisplayQuery.html
|
||||
|
|
|
|||
|
|
@ -30,7 +30,7 @@ The process for using managed state is simple:
|
|||
### Adding State
|
||||
|
||||
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`
|
||||
structure with an internal `AtomicUsize` with an initial value of `0`, we can
|
||||
write the following:
|
||||
|
|
@ -63,7 +63,7 @@ rocket::ignite()
|
|||
### Retrieving State
|
||||
|
||||
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, 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
|
||||
|
|
@ -108,9 +108,9 @@ fn state(hit_count: State<HitCount>, config: State<Config>) { /* .. */ }
|
|||
**500** error to the client.
|
||||
|
||||
You can find a complete example using the `HitCount` structure in the [state
|
||||
example on GitHub](@example/state) and learn more about the [`manage`
|
||||
method](@api/rocket/struct.Rocket.html#method.manage) and [`State`
|
||||
type](@api/rocket/struct.State.html) in the API docs.
|
||||
example on GitHub](@git/v0.4/examples/state) and learn more about the [`manage`
|
||||
method](@api/v0.4/rocket/struct.Rocket.html#method.manage) and [`State`
|
||||
type](@api/v0.4/rocket/struct.State.html) in the API docs.
|
||||
|
||||
### 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
|
||||
|
||||
|
|
@ -204,8 +204,8 @@ which uses request-local state to cache expensive authentication and
|
|||
authorization computations, and the [`Fairing`] documentation, which uses
|
||||
request-local state to implement request timing.
|
||||
|
||||
[`FromRequest` request-local state]: @api/rocket/request/trait.FromRequest.html#request-local-state
|
||||
[`Fairing`]: @api/rocket/fairing/trait.Fairing.html#request-local-state
|
||||
[`FromRequest` request-local state]: @api/v0.4/rocket/request/trait.FromRequest.html#request-local-state
|
||||
[`Fairing`]: @api/v0.4/rocket/fairing/trait.Fairing.html#request-local-state
|
||||
|
||||
## Databases
|
||||
|
||||
|
|
@ -355,4 +355,4 @@ postgres = { version = "0.15", features = ["with-chrono"] }
|
|||
For more on Rocket's built-in database support, see the
|
||||
[`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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
policies.
|
||||
|
||||
[`Fairing`]: @api/rocket/fairing/trait.Fairing.html
|
||||
[`Fairing`]: @api/v0.4/rocket/fairing/trait.Fairing.html
|
||||
[request guard]: ../requests/#request-guards
|
||||
[request guards]: ../requests/#request-guards
|
||||
[data guards]: ../requests/#body-data
|
||||
|
|
@ -60,8 +60,8 @@ rocket::ignite()
|
|||
# }
|
||||
```
|
||||
|
||||
[`attach`]: @api/rocket/struct.Rocket.html#method.attach
|
||||
[`Rocket`]: @api/rocket/struct.Rocket.html
|
||||
[`attach`]: @api/v0.4/rocket/struct.Rocket.html#method.attach
|
||||
[`Rocket`]: @api/v0.4/rocket/struct.Rocket.html
|
||||
|
||||
Fairings are executed in the order in which they are attached: the first
|
||||
attached fairing has its callbacks executed before all others. Because fairing
|
||||
|
|
@ -76,7 +76,7 @@ events is described below:
|
|||
* **Attach (`on_attach`)**
|
||||
|
||||
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
|
||||
optionally abort launch. Attach fairings are commonly used to parse and
|
||||
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
|
||||
implementation that does absolutely nothing.
|
||||
|
||||
[`Info`]: @api/rocket/fairing/struct.Info.html
|
||||
[`info`]: @api/rocket/fairing/trait.Fairing.html#tymethod.info
|
||||
[`on_attach`]: @api/rocket/fairing/trait.Fairing.html#method.on_attach
|
||||
[`on_launch`]: @api/rocket/fairing/trait.Fairing.html#method.on_launch
|
||||
[`on_request`]: @api/rocket/fairing/trait.Fairing.html#method.on_request
|
||||
[`on_response`]: @api/rocket/fairing/trait.Fairing.html#method.on_response
|
||||
[`Info`]: @api/v0.4/rocket/fairing/struct.Info.html
|
||||
[`info`]: @api/v0.4/rocket/fairing/trait.Fairing.html#tymethod.info
|
||||
[`on_attach`]: @api/v0.4/rocket/fairing/trait.Fairing.html#method.on_attach
|
||||
[`on_launch`]: @api/v0.4/rocket/fairing/trait.Fairing.html#method.on_launch
|
||||
[`on_request`]: @api/v0.4/rocket/fairing/trait.Fairing.html#method.on_request
|
||||
[`on_response`]: @api/v0.4/rocket/fairing/trait.Fairing.html#method.on_response
|
||||
|
||||
### Requirements
|
||||
|
||||
|
|
@ -196,7 +196,7 @@ impl Fairing for Counter {
|
|||
```
|
||||
|
||||
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
|
||||
|
||||
|
|
@ -225,4 +225,4 @@ rocket::ignite()
|
|||
}));
|
||||
```
|
||||
|
||||
[`AdHoc`]: @api/rocket/fairing/struct.AdHoc.html
|
||||
[`AdHoc`]: @api/v0.4/rocket/fairing/struct.AdHoc.html
|
||||
|
|
|
|||
|
|
@ -49,10 +49,10 @@ instance. Usage is straightforward:
|
|||
# let _ = response;
|
||||
```
|
||||
|
||||
[`local`]: @api/rocket/local/
|
||||
[`Client`]: @api/rocket/local/struct.Client.html
|
||||
[`LocalRequest`]: @api/rocket/local/struct.LocalRequest.html
|
||||
[`Rocket`]: @api/rocket/struct.Rocket.html
|
||||
[`local`]: @api/v0.4/rocket/local/
|
||||
[`Client`]: @api/v0.4/rocket/local/struct.Client.html
|
||||
[`LocalRequest`]: @api/v0.4/rocket/local/struct.LocalRequest.html
|
||||
[`Rocket`]: @api/v0.4/rocket/struct.Rocket.html
|
||||
|
||||
## Validating Responses
|
||||
|
||||
|
|
@ -70,13 +70,13 @@ a few below:
|
|||
* [`body_string`]: returns the body data as a `String`.
|
||||
* [`body_bytes`]: returns the body data as a `Vec<u8>`.
|
||||
|
||||
[`LocalResponse`]: @api/rocket/local/struct.LocalResponse.html
|
||||
[`Response`]: @api/rocket/struct.Response.html
|
||||
[`status`]: @api/rocket/struct.Response.html#method.status
|
||||
[`content_type`]: @api/rocket/struct.Response.html#method.content_type
|
||||
[`headers`]: @api/rocket/struct.Response.html#method.headers
|
||||
[`body_string`]: @api/rocket/struct.Response.html#method.body_string
|
||||
[`body_bytes`]: @api/rocket/struct.Response.html#method.body_bytes
|
||||
[`LocalResponse`]: @api/v0.4/rocket/local/struct.LocalResponse.html
|
||||
[`Response`]: @api/v0.4/rocket/struct.Response.html
|
||||
[`status`]: @api/v0.4/rocket/struct.Response.html#method.status
|
||||
[`content_type`]: @api/v0.4/rocket/struct.Response.html#method.content_type
|
||||
[`headers`]: @api/v0.4/rocket/struct.Response.html#method.headers
|
||||
[`body_string`]: @api/v0.4/rocket/struct.Response.html#method.body_string
|
||||
[`body_bytes`]: @api/v0.4/rocket/struct.Response.html#method.body_bytes
|
||||
|
||||
These methods are typically used in combination with the `assert_eq!` or
|
||||
`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
|
||||
[this example on GitHub](@example/testing).
|
||||
[this example on GitHub](@git/v0.4/examples/testing).
|
||||
|
||||
## Codegen Debug
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
[`Request::limits()`] method.
|
||||
|
||||
[`Request::limits()`]: @api/rocket/struct.Request.html#method.limits
|
||||
[`Json`]: @api/rocket_contrib/json/struct.Json.html#incoming-data-limits
|
||||
[`Request::limits()`]: @api/v0.4/rocket/struct.Request.html#method.limits
|
||||
[`Json`]: @api/v0.4/rocket_contrib/json/struct.Json.html#incoming-data-limits
|
||||
|
||||
## 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
|
||||
these parameters aren't used by Rocket directly, other libraries, or your own
|
||||
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
|
||||
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
|
||||
being ignored.
|
||||
|
||||
[`rocket::custom()`]: @api/rocket/fn.custom.html
|
||||
[`ConfigBuilder`]: @api/rocket/config/struct.ConfigBuilder.html
|
||||
[`rocket::custom()`]: @api/v0.4/rocket/fn.custom.html
|
||||
[`ConfigBuilder`]: @api/v0.4/rocket/config/struct.ConfigBuilder.html
|
||||
|
||||
## Configuring TLS
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
can read more about how Rocket formulates responses at the [API documentation
|
||||
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
|
||||
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;
|
||||
```
|
||||
|
||||
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
|
||||
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
|
||||
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`
|
||||
[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
|
||||
paste doesn't exist.
|
||||
|
||||
|
|
@ -370,7 +370,7 @@ fn main() {
|
|||
```
|
||||
|
||||
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
|
||||
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
|
||||
`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
|
||||
using it. We do this by implementing `FromParam` for `PasteId` in
|
||||
`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
|
||||
`<id>` for language `<lang>`. If `<lang>` is not a known language, do no
|
||||
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.
|
||||
* Dispatch a thread before `launch`ing Rocket in `main` that periodically
|
||||
cleans up idling old pastes in `upload/`.
|
||||
|
||||
You can find the full source code for the [completed pastebin tutorial on
|
||||
GitHub](@example/pastebin).
|
||||
GitHub](@git/v0.4/examples/pastebin).
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
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).
|
||||
Whatever you decide to do next, we hope you have a blast!
|
||||
[Rocket examples](@git/v0.4/examples) or the [Rocket source
|
||||
code](@git/v0.4/core/lib/src). Whatever you decide to do next, we hope you have
|
||||
a blast!
|
||||
|
|
|
|||
|
|
@ -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
|
||||
also designed to be a reference for experienced Rocket developers. This guide is
|
||||
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
|
||||
aspect of Rocket. The sections are:
|
||||
|
|
@ -33,12 +33,6 @@ aspect of Rocket. The sections are:
|
|||
|
||||
## Getting Help
|
||||
|
||||
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.
|
||||
The official community support channels is [`#rocket:mozilla.org`] on Matrix.
|
||||
|
||||
[`#rocket:mozilla.org`]: https://chat.mozilla.org/#/room/#rocket:mozilla.org
|
||||
[`#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
|
||||
[`#rocket:mozilla.org`]: @chat
|
||||
|
|
|
|||
Loading…
Reference in New Issue