mirror of https://github.com/rwf2/Rocket.git
Update site content for restructure.
This commit is contained in:
Sergio Benitez
parent
1c0f2d41a7
commit
26ee132782
|
|
@ -7,20 +7,39 @@ website](https://rocket.rs).
|
|||
|
||||
This directory contains the following:
|
||||
|
||||
* `index.toml` - Source data for the index (`/`).
|
||||
* `news.toml` - Source data for the news page (`/news`).
|
||||
* `overview.toml` - Source data for the overview page (`/overview`).
|
||||
* `guide.md` - Index page for the [Rocket Programming Guide] (`/guide`).
|
||||
* `news/*.md` - News articles linked to from `news.toml`.
|
||||
* `index.toml` - Source data for the index.
|
||||
* `overview.toml` - Source data for the overview page (`overview/`).
|
||||
* `news/index.toml` - Source data for the news page (`news/`).
|
||||
* `news/*.md` - News articles linked to from `news/index.toml`.
|
||||
* `guide/*.md` - Guide pages linked to from `guide.md`.
|
||||
|
||||
[Rocket Programming Guide]: https://rocket.rs/guide/
|
||||
|
||||
### Guide Links
|
||||
|
||||
Cross-linking to pages in the guide is accomplished via absolute links rooted at
|
||||
`/guide/`. To link to the page whose source is at `guide/page.md`, for instance,
|
||||
link to `/guide/page`.
|
||||
Cross-linking guide pages is accomplished via relative links. Outside of the
|
||||
index, this is: `../{page}#anchor`. For instance, to link to the **Quickstart >
|
||||
Running Examples** page, use `../quickstart#running-examples`.
|
||||
|
||||
### Aliases
|
||||
|
||||
Aliases are shorthand URLs that start with `@` (e.g, `@api`). They are used
|
||||
throughout the guide to simplify versioning URLs to Rocket's source code and the
|
||||
Rocket API. They are replaced at build time with a URL prefix. At present, the
|
||||
following aliases are available, where `${version}` is Rocket's version string
|
||||
at the time of compilation:
|
||||
|
||||
* `@example`: https://github.com/SergioBenitez/Rocket/tree/${version}/examples
|
||||
* `@github`: https://github.com/SergioBenitez/Rocket/tree/${version}
|
||||
* `@api`: https://api.rocket.rs/${version}
|
||||
|
||||
For example, to link to `Rocket::launch()`, you might write:
|
||||
|
||||
```md
|
||||
Launch an instance of your application using the [`launch()`] method.
|
||||
|
||||
[`launch()`]: @api/rocket/struct.Rocket.html#method.launch
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
|
|
|
|||
|
|
@ -3,7 +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](/guide/getting-started)
|
||||
like extra guidance doing so, see the [getting started](../getting-started)
|
||||
section.
|
||||
|
||||
## Running Examples
|
||||
|
|
@ -100,7 +100,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](https://api.rocket.rs/rocket/response/trait.Responder.html).
|
||||
trait](@api/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:
|
||||
|
|
@ -213,7 +213,7 @@ use rocket::Data;
|
|||
use rocket::http::RawStr;
|
||||
```
|
||||
|
||||
The [Data](https://api.rocket.rs/rocket/data/struct.Data.html) structure is key
|
||||
The [Data](@api/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.
|
||||
|
||||
|
|
@ -289,7 +289,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](https://api.rocket.rs/rocket/response/trait.Responder.html#provided-implementations)
|
||||
[Responder](@api/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.
|
||||
|
||||
|
|
@ -305,8 +305,7 @@ fn retrieve(id: &RawStr) -> Option<File> {
|
|||
```
|
||||
|
||||
Unfortunately, there's a problem with this code. Can you spot the issue? The
|
||||
[`RawStr`](https://api.rocket.rs/rocket/http/struct.RawStr.html) type should tip
|
||||
you off!
|
||||
[`RawStr`](@api/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
|
||||
|
|
@ -320,7 +319,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](https://api.rocket.rs/rocket/request/trait.FromParam.html) trait to
|
||||
[FromParam](@api/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:
|
||||
|
|
@ -398,10 +397,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](https://api.rocket.rs/rocket/local/) to write
|
||||
unit tests for your pastebin.
|
||||
* Use the [`local` module](@api/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](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/pastebin).
|
||||
GitHub](@example/pastebin).
|
||||
|
|
@ -22,7 +22,5 @@ guide.
|
|||
|
||||
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](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples)
|
||||
or the [Rocket source
|
||||
code](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/lib/src). Whatever you
|
||||
decide to do next, we hope you have a blast!
|
||||
[Rocket examples](@example) or the [Rocket source code](@github/lib/src).
|
||||
Whatever you decide to do next, we hope you have a blast!
|
||||
|
|
@ -71,7 +71,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](/guide/requests) section describes the available options for
|
||||
[Requests](../requests) section describes the available options for
|
||||
constructing routes.
|
||||
|
||||
## Mounting
|
||||
|
|
@ -179,7 +179,7 @@ we expected.
|
|||
|
||||
A version of this example's complete crate, ready to `cargo run`, can be found
|
||||
on
|
||||
[GitHub](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/hello_world).
|
||||
[GitHub](@example/hello_world).
|
||||
You can find dozens of other complete examples, spanning all of Rocket's
|
||||
features, in the [GitHub examples
|
||||
directory](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/).
|
||||
directory](@example/).
|
||||
|
|
@ -38,7 +38,7 @@ to the root path:
|
|||
```
|
||||
|
||||
The grammar for these attributes is defined formally in the
|
||||
[`rocket_codegen`](https://api.rocket.rs/rocket_codegen/) API docs.
|
||||
[`rocket_codegen`](@api/rocket_codegen/) API docs.
|
||||
|
||||
### HEAD Requests
|
||||
|
||||
|
|
@ -56,8 +56,8 @@ request methods under certain conditions. If a `POST` request contains a body of
|
|||
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](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/todo/static/index.html.tera#L47)
|
||||
makes use of this feature to submit `PUT` and `DELETE` requests from a web form.
|
||||
example](@example/todo/static/index.html.tera#L47) makes use of this feature to
|
||||
submit `PUT` and `DELETE` requests from a web form.
|
||||
|
||||
## Dynamic Segments
|
||||
|
||||
|
|
@ -95,8 +95,8 @@ fn hello(name: String, age: u8, cool: bool) -> String {
|
|||
}
|
||||
```
|
||||
|
||||
[`FromParam`]: https://api.rocket.rs/rocket/request/trait.FromParam.html
|
||||
[`FromParam` API docs]: https://api.rocket.rs/rocket/request/trait.FromParam.html
|
||||
[`FromParam`]: @api/rocket/request/trait.FromParam.html
|
||||
[`FromParam` API docs]: @api/rocket/request/trait.FromParam.html
|
||||
|
||||
### Raw Strings
|
||||
|
||||
|
|
@ -114,7 +114,7 @@ segment, a `RawStr` points to a potentially undecoded string. By contrast, a
|
|||
you want direct but potentially unsafe access to the string (`&RawStr`), or safe
|
||||
access to the string at the cost of an allocation (`String`).
|
||||
|
||||
[`RawStr`]: https://api.rocket.rs/rocket/http/struct.RawStr.html
|
||||
[`RawStr`]: @api/rocket/http/struct.RawStr.html
|
||||
|
||||
## Forwarding
|
||||
|
||||
|
|
@ -215,7 +215,7 @@ fn files(file: PathBuf) -> Option<NamedFile> {
|
|||
}
|
||||
```
|
||||
|
||||
[`FromSegments`]: https://api.rocket.rs/rocket/request/trait.FromSegments.html
|
||||
[`FromSegments`]: @api/rocket/request/trait.FromSegments.html
|
||||
|
||||
## Format
|
||||
|
||||
|
|
@ -263,7 +263,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()`]: https://api.rocket.rs/rocket/http/struct.ContentType.html#method.parse_flexible
|
||||
[`ContentType::parse_flexible()`]: @api/rocket/http/struct.ContentType.html#method.parse_flexible
|
||||
|
||||
## Request Guards
|
||||
|
||||
|
|
@ -295,8 +295,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`]: https://api.rocket.rs/rocket/request/trait.FromRequest.html
|
||||
[`Cookies`]: https://api.rocket.rs/rocket/http/enum.Cookies.html
|
||||
[`FromRequest`]: @api/rocket/request/trait.FromRequest.html
|
||||
[`Cookies`]: @api/rocket/http/enum.Cookies.html
|
||||
|
||||
### Custom Guards
|
||||
|
||||
|
|
@ -388,7 +388,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]: https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/cookies
|
||||
[cookies example]: @example/cookies
|
||||
|
||||
### Private Cookies
|
||||
|
||||
|
|
@ -422,7 +422,7 @@ fn logout(mut cookies: Cookies) -> Flash<Redirect> {
|
|||
}
|
||||
```
|
||||
|
||||
[`Cookies::add()`]: https://api.rocket.rs/rocket/http/enum.Cookies.html#method.add
|
||||
[`Cookies::add()`]: @api/rocket/http/enum.Cookies.html#method.add
|
||||
|
||||
### Secret Key
|
||||
|
||||
|
|
@ -439,12 +439,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](/guide/configuration) section of the guide.
|
||||
For more information on configuration, see the [Configuration](../configuration)
|
||||
section of the guide.
|
||||
|
||||
[`get_private`]: https://api.rocket.rs/rocket/http/enum.Cookies.html#method.get_private
|
||||
[`add_private`]: https://api.rocket.rs/rocket/http/enum.Cookies.html#method.add_private
|
||||
[`remove_private`]: https://api.rocket.rs/rocket/http/enum.Cookies.html#method.remove_private
|
||||
[`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
|
||||
|
||||
### One-At-A-Time
|
||||
|
||||
|
|
@ -497,7 +497,7 @@ fn new(input: T) -> String { ... }
|
|||
|
||||
Any type that implements [`FromData`] is also known as _data guard_.
|
||||
|
||||
[`FromData`]: https://api.rocket.rs/rocket/data/trait.FromData.html
|
||||
[`FromData`]: @api/rocket/data/trait.FromData.html
|
||||
|
||||
### Forms
|
||||
|
||||
|
|
@ -533,8 +533,8 @@ forward or failure can be caught by using the `Option` and `Result` types:
|
|||
fn new(task: Option<Form<Task>>) -> String { ... }
|
||||
```
|
||||
|
||||
[`FromForm`]: https://api.rocket.rs/rocket/request/trait.FromForm.html
|
||||
[`FromFormValue`]: https://api.rocket.rs/rocket/request/trait.FromFormValue.html
|
||||
[`FromForm`]: @api/rocket/request/trait.FromForm.html
|
||||
[`FromFormValue`]: @api/rocket/request/trait.FromFormValue.html
|
||||
|
||||
#### Lenient Parsing
|
||||
|
||||
|
|
@ -564,7 +564,7 @@ struct Task { .. }
|
|||
fn new(task: LenientForm<Task>) { .. }
|
||||
```
|
||||
|
||||
[`LenientForm`]: https://api.rocket.rs/rocket/request/struct.LenientForm.html
|
||||
[`LenientForm`]: @api/rocket/request/struct.LenientForm.html
|
||||
|
||||
#### Field Renaming
|
||||
|
||||
|
|
@ -629,14 +629,14 @@ struct Person {
|
|||
}
|
||||
```
|
||||
|
||||
The [forms validation](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/form_validation)
|
||||
and [forms kitchen sink](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/form_kitchen_sink)
|
||||
The [forms validation](@example/form_validation)
|
||||
and [forms kitchen sink](@example/form_kitchen_sink)
|
||||
examples on GitHub provide further illustrations.
|
||||
|
||||
### JSON
|
||||
|
||||
Handling JSON data is no harder: simply use the
|
||||
[`Json`](https://api.rocket.rs/rocket_contrib/struct.Json.html) type:
|
||||
[`Json`](@api/rocket_contrib/struct.Json.html) type:
|
||||
|
||||
```rust
|
||||
#[derive(Deserialize)]
|
||||
|
|
@ -653,13 +653,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]: https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/json
|
||||
[JSON example]: @example/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`](https://api.rocket.rs/rocket/data/struct.Data.html)
|
||||
possible via the [`Data`](@api/rocket/data/struct.Data.html)
|
||||
type:
|
||||
|
||||
```rust
|
||||
|
|
@ -674,9 +674,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](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/raw_upload)
|
||||
for the full crate.
|
||||
[GitHub example code](@example/raw_upload) for the full crate.
|
||||
|
||||
## Query Strings
|
||||
|
||||
|
|
@ -731,14 +729,14 @@ fn new(task: Option<Task>) { ... }
|
|||
|
||||
For a concrete illustration on how to handle query parameters, see [the
|
||||
`query_params`
|
||||
example](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/query_params).
|
||||
example](@example/query_params).
|
||||
|
||||
## Error Catchers
|
||||
|
||||
Routing may fail for a variety of reasons. These include:
|
||||
|
||||
* A [request guard](#request-guards) returns `Failure`.
|
||||
* A handler returns a [`Responder`](/guide/responses/#responder) that fails.
|
||||
* A handler returns a [`Responder`](../responses/#responder) that fails.
|
||||
* No matching route was found.
|
||||
|
||||
If any of these conditions occur, Rocket returns an error to the client. To do
|
||||
|
|
@ -775,8 +773,8 @@ looks like:
|
|||
rocket::ignite().register(catchers![not_found])
|
||||
```
|
||||
|
||||
Unlike route request handlers, catchers take exactly zero or one parameters. If
|
||||
the catcher takes a parameter, it must be of type
|
||||
[`&Request`](https://api.rocket.rs/rocket/struct.Request.html) The [error
|
||||
catcher example](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/errors)
|
||||
on GitHub illustrates their use in full.
|
||||
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.
|
||||
|
||||
[`&Request]: @api/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`]: https://api.rocket.rs/rocket/response/trait.Responder.html
|
||||
[`Responder`]: @api/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`]: https://api.rocket.rs/rocket/response/struct.Response.html
|
||||
[`Response`]: @api/rocket/response/struct.Response.html
|
||||
|
||||
### Wrapping
|
||||
|
||||
|
|
@ -31,10 +31,9 @@ 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](https://api.rocket.rs/rocket/response/status/index.html) 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:
|
||||
[`status` module](@api/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:
|
||||
|
||||
```rust
|
||||
use rocket::response::status;
|
||||
|
|
@ -45,10 +44,10 @@ fn new(id: usize) -> status::Accepted<String> {
|
|||
}
|
||||
```
|
||||
|
||||
Similarly, the types in the [`content`
|
||||
module](https://api.rocket.rs/rocket/response/content/index.html) 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:
|
||||
Similarly, the types in the [`content` module](@api/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:
|
||||
|
||||
```rust
|
||||
use rocket::response::content;
|
||||
|
|
@ -59,14 +58,14 @@ fn json() -> content::Json<&'static str> {
|
|||
}
|
||||
```
|
||||
|
||||
[`Accepted`]: https://api.rocket.rs/rocket/response/status/struct.Accepted.html
|
||||
[`content::Json`]: https://api.rocket.rs/rocket/response/content/struct.Json.html
|
||||
[`Accepted`]: @api/rocket/response/status/struct.Accepted.html
|
||||
[`content::Json`]: @api/rocket/response/content/struct.Json.html
|
||||
|
||||
### Errors
|
||||
|
||||
Responders may fail; they need not _always_ generate a response. Instead, they
|
||||
can return an `Err` with a given status code. When this happens, Rocket forwards
|
||||
the request to the [error catcher](/guide/requests/#error-catchers) for the
|
||||
the request to the [error catcher](../requests/#error-catchers) for the
|
||||
given status code.
|
||||
|
||||
If an error catcher has been registered for the given status code, Rocket will
|
||||
|
|
@ -78,7 +77,7 @@ for a custom status code, Rocket uses the **500** error catcher to return a
|
|||
response.
|
||||
|
||||
While not encouraged, you can also forward a request to a catcher manually by
|
||||
using the [`Failure`](https://api.rocket.rs/rocket/response/struct.Failure.html)
|
||||
using the [`Failure`](@api/rocket/response/struct.Failure.html)
|
||||
type. For instance, to forward to the catcher for **406 - Not Acceptable**, you
|
||||
would write:
|
||||
|
||||
|
|
@ -181,13 +180,13 @@ many of these responders in the [`response`] module. Among these are:
|
|||
* [`status`] - Contains types that override the status code of a response.
|
||||
* [`Flash`] - Sets a "flash" cookie that is removed when accessed.
|
||||
|
||||
[`status`]: https://api.rocket.rs/rocket/response/status/index.html
|
||||
[`response`]: https://api.rocket.rs/rocket/response/index.html
|
||||
[`NamedFile`]: https://api.rocket.rs/rocket/response/struct.NamedFile.html
|
||||
[`Content`]: https://api.rocket.rs/rocket/response/struct.Content.html
|
||||
[`Redirect`]: https://api.rocket.rs/rocket/response/struct.Redirect.html
|
||||
[`Stream`]: https://api.rocket.rs/rocket/response/struct.Stream.html
|
||||
[`Flash`]: https://api.rocket.rs/rocket/response/struct.Flash.html
|
||||
[`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
|
||||
|
||||
### Streaming
|
||||
|
||||
|
|
@ -205,7 +204,7 @@ fn stream() -> io::Result<Stream<UnixStream>> {
|
|||
|
||||
```
|
||||
|
||||
[`rocket_contrib`]: https://api.rocket.rs/rocket_contrib/index.html
|
||||
[`rocket_contrib`]: @api/rocket_contrib/
|
||||
|
||||
### JSON
|
||||
|
||||
|
|
@ -233,10 +232,10 @@ fails, a **500 - Internal Server Error** is returned.
|
|||
|
||||
The [JSON example on GitHub] provides further illustration.
|
||||
|
||||
[`JSON`]: https://api.rocket.rs/rocket_contrib/struct.Json.html
|
||||
[`JSON`]: @api/rocket_contrib/struct.Json.html
|
||||
[`Serialize`]: https://docs.serde.rs/serde/trait.Serialize.html
|
||||
[`serde`]: https://docs.serde.rs/serde/
|
||||
[JSON example on GitHub]: https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/json
|
||||
[JSON example on GitHub]: @example/json
|
||||
|
||||
### Templates
|
||||
|
||||
|
|
@ -269,7 +268,7 @@ This means that you don't need to rebuild your application to observe template
|
|||
changes: simply refresh! In release builds, reloading is disabled.
|
||||
|
||||
For templates to be properly registered, the template fairing must be attached
|
||||
to the instance of Rocket. The [Fairings](/guide/fairings) sections of the guide
|
||||
to the instance of Rocket. The [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:
|
||||
|
||||
|
|
@ -283,9 +282,8 @@ fn main() {
|
|||
|
||||
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 on
|
||||
GitHub](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/handlebars_templates)
|
||||
is a fully composed application that makes use of Handlebars templates.
|
||||
The [Handlebars Templates example on GitHub](@example/handlebars_templates) is a
|
||||
fully composed application that makes use of Handlebars templates.
|
||||
|
||||
[`Template`]: https://api.rocket.rs/rocket_contrib/struct.Template.html
|
||||
[configurable]: /guide/configuration/#extras
|
||||
[`Template`]: @api/rocket_contrib/struct.Template.html
|
||||
[configurable]: ../configuration/#extras
|
||||
|
|
@ -22,7 +22,7 @@ The process for using managed state is simple:
|
|||
### Adding State
|
||||
|
||||
To instruct Rocket to manage state for your application, call the
|
||||
[`manage`](https://api.rocket.rs/rocket/struct.Rocket.html#method.manage) method
|
||||
[`manage`](@api/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:
|
||||
|
|
@ -48,8 +48,8 @@ rocket::ignite()
|
|||
### Retrieving State
|
||||
|
||||
State that is being managed by Rocket can be retrieved via the
|
||||
[`State`](https://api.rocket.rs/rocket/struct.State.html) type: a [request
|
||||
guard](/guide/requests/#request-guards) for managed state. To use the request
|
||||
[`State`](@api/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
|
||||
`HitCount` in a `count` route as follows:
|
||||
|
|
@ -74,11 +74,9 @@ the offending route. Instead, Rocket will log an error message and return a
|
|||
**500** error to the client.
|
||||
|
||||
You can find a complete example using the `HitCount` structure in the [state
|
||||
example on
|
||||
GitHub](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/state) and
|
||||
learn more about the [`manage`
|
||||
method](https://api.rocket.rs/rocket/struct.Rocket.html#method.manage) and
|
||||
[`State` type](https://api.rocket.rs/rocket/struct.State.html) in the API docs.
|
||||
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.
|
||||
|
||||
### Within Guards
|
||||
|
||||
|
|
@ -94,7 +92,7 @@ fn from_request(req: &'a Request<'r>) -> request::Outcome<T, ()> {
|
|||
}
|
||||
```
|
||||
|
||||
[`Request::guard()`]: https://api.rocket.rs/rocket/struct.Request.html#method.guard
|
||||
[`Request::guard()`]: @api/rocket/struct.Request.html#method.guard
|
||||
|
||||
### Request-Local State
|
||||
|
||||
|
|
@ -142,8 +140,8 @@ request-local state to cache expensive authentication and authorization
|
|||
computations, and the [`Fairing`] documentation, which uses request-local state
|
||||
to implement request timing.
|
||||
|
||||
[`FromRequest`]: https://api.rocket.rs/rocket/request/trait.FromRequest.htmll#request-local-state
|
||||
[`Fairing`]: https://api.rocket.rs/rocket/fairing/trait.Fairing.html#request-local-state
|
||||
[`FromRequest`]: @api/rocket/request/trait.FromRequest.htmll#request-local-state
|
||||
[`Fairing`]: @api/rocket/fairing/trait.Fairing.html#request-local-state
|
||||
|
||||
## Databases
|
||||
|
||||
|
|
@ -255,4 +253,4 @@ fn get_logs(conn: LogsDbConn, id: usize) -> Result<Logs> {
|
|||
For more on Rocket's built-in database support, see the
|
||||
[`rocket_contrib::databases`] module documentation.
|
||||
|
||||
[`rocket_contrib::databases`]: https://api.rocket.rs/rocket_contrib/databases/index.html
|
||||
[`rocket_contrib::databases`]: @api/rocket_contrib/databases/index.html
|
||||
|
|
@ -33,10 +33,10 @@ _unless_ the authentication or authorization applies to all or most of the
|
|||
application. On the other hand, you _should_ use a fairing to record timing and
|
||||
usage statistics or to enforce global security policies.
|
||||
|
||||
[`Fairing`]: https://api.rocket.rs/rocket/fairing/trait.Fairing.html
|
||||
[request guard]: /guide/requests/#request-guards
|
||||
[request guards]: /guide/requests/#request-guards
|
||||
[data guards]: /guide/requests/#body-data
|
||||
[`Fairing`]: @api/rocket/fairing/trait.Fairing.html
|
||||
[request guard]: ../requests/#request-guards
|
||||
[request guards]: ../requests/#request-guards
|
||||
[data guards]: ../requests/#body-data
|
||||
|
||||
### Attaching
|
||||
|
||||
|
|
@ -52,8 +52,8 @@ rocket::ignite()
|
|||
.launch();
|
||||
```
|
||||
|
||||
[`attach`]: https://api.rocket.rs/rocket/struct.Rocket.html#method.attach
|
||||
[`Rocket`]: https://api.rocket.rs/rocket/struct.Rocket.html
|
||||
[`attach`]: @api/rocket/struct.Rocket.html#method.attach
|
||||
[`Rocket`]: @api/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
|
||||
|
|
@ -68,12 +68,11 @@ events is described below:
|
|||
* **Attach (`on_attach`)**
|
||||
|
||||
An attach callback is called when a fairing is first attached via the
|
||||
[`attach`](https://api.rocket.rs/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 the parsed value into managed state for later
|
||||
retrieval.
|
||||
[`attach`](@api/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
|
||||
the parsed value into managed state for later retrieval.
|
||||
|
||||
* **Launch (`on_launch`)**
|
||||
|
||||
|
|
@ -108,12 +107,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`]: https://api.rocket.rs/rocket/fairing/struct.Info.html
|
||||
[`info`]: https://api.rocket.rs/rocket/fairing/trait.Fairing.html#tymethod.info
|
||||
[`on_attach`]: https://api.rocket.rs/rocket/fairing/trait.Fairing.html#method.on_attach
|
||||
[`on_launch`]: https://api.rocket.rs/rocket/fairing/trait.Fairing.html#method.on_launch
|
||||
[`on_request`]: https://api.rocket.rs/rocket/fairing/trait.Fairing.html#method.on_request
|
||||
[`on_response`]: https://api.rocket.rs/rocket/fairing/trait.Fairing.html#method.on_response
|
||||
[`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
|
||||
|
||||
### Requirements
|
||||
|
||||
|
|
@ -182,8 +181,7 @@ impl Fairing for Counter {
|
|||
```
|
||||
|
||||
For brevity, imports are not shown. The complete example can be found in the
|
||||
[`Fairing`
|
||||
documentation](https://api.rocket.rs/rocket/fairing/trait.Fairing.html#example).
|
||||
[`Fairing` documentation](@api/rocket/fairing/trait.Fairing.html#example).
|
||||
|
||||
## Ad-Hoc Fairings
|
||||
|
||||
|
|
@ -212,4 +210,4 @@ rocket::ignite()
|
|||
}));
|
||||
```
|
||||
|
||||
[`AdHoc`]: https://api.rocket.rs/rocket/fairing/enum.AdHoc.html
|
||||
[`AdHoc`]: @api/rocket/fairing/enum.AdHoc.html
|
||||
|
|
@ -36,10 +36,10 @@ instance. Usage is straightforward:
|
|||
let response = req.dispatch();
|
||||
```
|
||||
|
||||
[`local`]: https://api.rocket.rs/rocket/local/index.html
|
||||
[`Client`]: https://api.rocket.rs/rocket/local/struct.Client.html
|
||||
[`LocalRequest`]: https://api.rocket.rs/rocket/local/struct.LocalRequest.html
|
||||
[`Rocket`]: https://api.rocket.rs/rocket/struct.Rocket.html
|
||||
[`local`]: @api/rocket/local/index.html
|
||||
[`Client`]: @api/rocket/local/struct.Client.html
|
||||
[`LocalRequest`]: @api/rocket/local/struct.LocalRequest.html
|
||||
[`Rocket`]: @api/rocket/struct.Rocket.html
|
||||
|
||||
## Validating Responses
|
||||
|
||||
|
|
@ -57,13 +57,13 @@ a few below:
|
|||
* [`body_string`]: returns the body data as a `String`.
|
||||
* [`body_bytes`]: returns the body data as a `Vec<u8>`.
|
||||
|
||||
[`LocalResponse`]: https://api.rocket.rs/rocket/local/struct.LocalResponse.html
|
||||
[`Response`]: https://api.rocket.rs/rocket/struct.Response.html
|
||||
[`status`]: https://api.rocket.rs/rocket/struct.Response.html#method.status
|
||||
[`content_type`]: https://api.rocket.rs/rocket/struct.Response.html#method.content_type
|
||||
[`headers`]: https://api.rocket.rs/rocket/struct.Response.html#method.headers
|
||||
[`body_string`]: https://api.rocket.rs/rocket/struct.Response.html#method.body_string
|
||||
[`body_bytes`]: https://api.rocket.rs/rocket/struct.Response.html#method.body_bytes
|
||||
[`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
|
||||
|
||||
These methods are typically used in combination with the `assert_eq!` or
|
||||
`assert!` macros as follows:
|
||||
|
|
@ -178,8 +178,7 @@ mod test {
|
|||
```
|
||||
|
||||
The tests can be run with `cargo test`. You can find the full source code to
|
||||
[this example on
|
||||
GitHub](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/testing).
|
||||
[this example on GitHub](@example/testing).
|
||||
|
||||
## Codegen Debug
|
||||
|
||||
|
|
@ -131,8 +131,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()`]: https://api.rocket.rs/rocket/struct.Request.html#method.limits
|
||||
[`Json`]: https://api.rocket.rs/rocket_contrib/struct.Json.html#incoming-data-limits
|
||||
[`Request::limits()`]: @api/rocket/struct.Request.html#method.limits
|
||||
[`Json`]: @api/rocket_contrib/struct.Json.html#incoming-data-limits
|
||||
|
||||
## Extras
|
||||
|
||||
|
|
@ -140,7 +140,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](https://api.rocket.rs/rocket_contrib/struct.Template.html) type
|
||||
[Template](@api/rocket_contrib/struct.Template.html) type
|
||||
accepts a value for the `template_dir` configuration parameter. The parameter
|
||||
can be set in `Rocket.toml` as follows:
|
||||
|
||||
|
|
@ -167,8 +167,8 @@ To retrieve a custom, extra configuration parameter in your application, we
|
|||
recommend using an [ad-hoc attach fairing] in combination with [managed state].
|
||||
For example, if your application makes use of a custom `assets_dir` parameter:
|
||||
|
||||
[ad-hoc attach fairing]: /guide/fairings/#ad-hoc-fairings
|
||||
[managed state]: /guide/state/#managed-state
|
||||
[ad-hoc attach fairing]: ../fairings/#ad-hoc-fairings
|
||||
[managed state]: ../state/#managed-state
|
||||
|
||||
```toml
|
||||
[development]
|
||||
|
|
@ -6,7 +6,7 @@ This is the official guide. 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 concise and purely technical documentation, see the [API
|
||||
documentation](https://api.rocket.rs).
|
||||
documentation](@api).
|
||||
|
||||
The guide is split into several sections, each with a focus on a different
|
||||
aspect of Rocket. The sections are:
|
||||
|
|
@ -12,21 +12,21 @@ title = "Type Safe"
|
|||
text = "From request to response Rocket ensures that your types mean something."
|
||||
image = "helmet"
|
||||
button = "Learn More"
|
||||
url = "/overview/#how-rocket-works"
|
||||
url = "overview/#how-rocket-works"
|
||||
|
||||
[[top_features]]
|
||||
title = "Boilerplate Free"
|
||||
text = "Spend your time writing code that really matters, and let Rocket generate the rest."
|
||||
image = "robot-free"
|
||||
button = "See Examples"
|
||||
url = "/overview/#anatomy-of-a-rocket-application"
|
||||
url = "overview/#anatomy-of-a-rocket-application"
|
||||
|
||||
[[top_features]]
|
||||
title = "Easy To Use"
|
||||
text = "Rocket makes extensive use of Rust's code generation tools to provide a clean API."
|
||||
image = "sun"
|
||||
button = "Get Started"
|
||||
url = "/guide"
|
||||
url = "guide"
|
||||
margin = 2
|
||||
|
||||
[[top_features]]
|
||||
|
|
@ -34,7 +34,7 @@ title = "Extensible"
|
|||
text = "Easily create your own primitives that any Rocket application can use."
|
||||
image = "telescope"
|
||||
button = "See How"
|
||||
url = "/overview/#anatomy-of-a-rocket-application"
|
||||
url = "overview/#anatomy-of-a-rocket-application"
|
||||
margin = 9
|
||||
|
||||
###############################################################################
|
||||
|
|
@ -134,7 +134,7 @@ text = '''
|
|||
title = 'Templating'
|
||||
text = "Rocket makes rendering templates a breeze with built-in templating support."
|
||||
image = 'templating-icon'
|
||||
url = '/guide/responses/#templates'
|
||||
url = 'guide/responses/#templates'
|
||||
button = 'Learn More'
|
||||
color = 'blue'
|
||||
|
||||
|
|
@ -142,7 +142,7 @@ color = 'blue'
|
|||
title = 'Cookies'
|
||||
text = "View, add, or remove cookies, with or without encryption, without hassle."
|
||||
image = 'cookies-icon'
|
||||
url = '/guide/requests/#cookies'
|
||||
url = 'guide/requests/#cookies'
|
||||
button = 'Learn More'
|
||||
color = 'purple'
|
||||
margin = -6
|
||||
|
|
@ -151,7 +151,7 @@ margin = -6
|
|||
title = 'Streams'
|
||||
text = "Rocket streams all incoming and outgoing data, so size isn't a concern."
|
||||
image = 'streams-icon'
|
||||
url = '/guide/requests/#streaming'
|
||||
url = 'guide/requests/#streaming'
|
||||
button = 'Learn More'
|
||||
color = 'red'
|
||||
margin = -29
|
||||
|
|
@ -160,7 +160,7 @@ margin = -29
|
|||
title = 'Config Environments'
|
||||
text = "Configure your application your way for development, staging, and production."
|
||||
image = 'config-icon'
|
||||
url = '/guide/configuration/#environment'
|
||||
url = 'guide/configuration/#environment'
|
||||
button = 'Learn More'
|
||||
color = 'yellow'
|
||||
margin = -3
|
||||
|
|
@ -169,7 +169,7 @@ margin = -3
|
|||
title = 'Query Strings'
|
||||
text = "Handling query strings and parameters is type-safe and easy in Rocket."
|
||||
image = 'query-icon'
|
||||
url = '/guide/requests/#query-strings'
|
||||
url = 'guide/requests/#query-strings'
|
||||
button = 'Learn More'
|
||||
color = 'orange'
|
||||
margin = -3
|
||||
|
|
@ -178,7 +178,7 @@ margin = -3
|
|||
title = 'Testing Library'
|
||||
text = "Unit test your applications with ease using the built-in testing library."
|
||||
image = 'testing-icon'
|
||||
url = '/guide/testing#testing'
|
||||
url = 'guide/testing#testing'
|
||||
button = 'Learn More'
|
||||
color = 'green'
|
||||
|
||||
|
|
|
|||
|
|
@ -46,8 +46,8 @@ state's type in the function signature. It works in two easy steps:
|
|||
value passed into `manage`.
|
||||
|
||||
Rocket takes care of the rest! `State` works through Rocket's [request
|
||||
guards](/guide/requests/#request-guards). You can call `manage` any number of
|
||||
times, as long as each call corresponds to a value of a different type.
|
||||
guards](../../guide/requests/#request-guards). You can call `manage` any number
|
||||
of times, as long as each call corresponds to a value of a different type.
|
||||
|
||||
As a simple example, consider the following "hit counter" example application:
|
||||
|
||||
|
|
@ -110,16 +110,15 @@ help: maybe add a call to 'manage' here?
|
|||
| ^^^^^^^^^^^^^^^^
|
||||
```
|
||||
|
||||
You can read more about managed state in the [guide](/guide/state/), the API
|
||||
docs for
|
||||
[manage](https://api.rocket.rs/rocket/struct.Rocket.html#method.manage), and the
|
||||
API docs for [State](https://api.rocket.rs/rocket/struct.State.html).
|
||||
You can read more about managed state in the [guide](../../guide/state/), the
|
||||
API docs for [manage](@api/rocket/struct.Rocket.html#method.manage), and the API
|
||||
docs for [State](@api/rocket/struct.State.html).
|
||||
|
||||
### Unmounted Routes Lint
|
||||
|
||||
A common mistake that new Rocketeers make is forgetting to
|
||||
[mount](/guide/overview/#mounting) declared routes. In Rocket v0.2, Rocket adds
|
||||
a _lint_ that results in a compile-time warning for unmounted routes. As a
|
||||
[mount](../../guide/overview/#mounting) declared routes. In Rocket v0.2, Rocket
|
||||
adds a _lint_ that results in a compile-time warning for unmounted routes. As a
|
||||
simple illustration, consider the canonical "Hello, world!" Rocket application
|
||||
below, and note that we've forgotten to mount the `hello` route:
|
||||
|
||||
|
|
@ -157,8 +156,7 @@ help: maybe add a call to 'mount' here?
|
|||
The lint can be disabled selectively per route by adding an
|
||||
`#[allow(unmounted_route)]` annotation to a given route declaration. It can also
|
||||
be disabled globally by adding `#![allow(unmounted_route)]`. You can read more
|
||||
about this lint in the [codegen
|
||||
documentation](https://api.rocket.rs/rocket_codegen/index.html).
|
||||
about this lint in the [codegen documentation](@api/rocket_codegen/index.html).
|
||||
|
||||
### Configuration via Environment Variables
|
||||
|
||||
|
|
@ -176,7 +174,7 @@ Configuration parameters set via environment variables take precedence over
|
|||
parameters set via the `Rocket.toml` configuration file. Note that _any_
|
||||
parameter can be set via an environment variable, include _extras_. For more
|
||||
about configuration in Rocket, see the [configuration section of the
|
||||
guide](/guide/overview/#configuration).
|
||||
guide](../../guide/overview/#configuration).
|
||||
|
||||
### And Plenty More!
|
||||
|
||||
|
|
@ -392,5 +390,5 @@ contributing!
|
|||
|
||||
Not already using Rocket? Rocket is extensively documented, making it easy for
|
||||
you to start writing your web applications in Rocket! See the
|
||||
[overview](/overview) or start writing code immediately by reading through [the
|
||||
guide](/guide).
|
||||
[overview](../../overview) or start writing code immediately by reading through
|
||||
[the guide](../../guide).
|
||||
|
|
|
|||
|
|
@ -21,8 +21,8 @@ sacrificing flexibility or type safety. All with minimal code.
|
|||
|
||||
Not already using Rocket? Join the thousands of users and dozens of companies
|
||||
happily using Rocket today! Rocket's extensive documentation makes it easy. Get
|
||||
started now by [reading through the guide](/guide) or learning more from [the
|
||||
overview](/overview).
|
||||
started now by [reading through the guide](../../guide) or learning more from
|
||||
[the overview](../../overview).
|
||||
|
||||
## What's New?
|
||||
|
||||
|
|
@ -61,7 +61,7 @@ limitations and abilities, and includes implementation examples. I encourage you
|
|||
to experiment with fairings and report your experiences. As always, feedback is
|
||||
instrumental in solidifying a robust design.
|
||||
|
||||
[`Fairing`]: https://api.rocket.rs/rocket/fairing/trait.Fairing.html
|
||||
[`Fairing`]: @api/rocket/fairing/trait.Fairing.html
|
||||
[fairings guide]: /guide/fairings
|
||||
|
||||
### Native TLS Support
|
||||
|
|
@ -126,10 +126,10 @@ automatically generates a fresh key at launch.
|
|||
For more details on private cookies, see the [private cookies] section of the
|
||||
guide.
|
||||
|
||||
[`Cookies`]: https://api.rocket.rs/rocket/http/enum.Cookies.html
|
||||
[`get_private`]: https://api.rocket.rs/rocket/http/enum.Cookies.html#method.get_private
|
||||
[`add_private`]: https://api.rocket.rs/rocket/http/enum.Cookies.html#method.add_private
|
||||
[`remove_private`]: https://api.rocket.rs/rocket/http/enum.Cookies.html#method.remove_private
|
||||
[`Cookies`]: @api/rocket/http/enum.Cookies.html
|
||||
[`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
|
||||
[private cookies]: /guide/requests/#private-cookies
|
||||
|
||||
### Form Field Naming
|
||||
|
|
@ -163,9 +163,9 @@ struct External {
|
|||
|
||||
Rocket will automatically match the form field named "type" to the structure
|
||||
field named `api_type`. For more details on form field naming, see the [field
|
||||
renaming](/guide/requests/#field-renaming) section of the guide.
|
||||
renaming](../../guide/requests/#field-renaming) section of the guide.
|
||||
|
||||
[`FromForm`]: https://api.rocket.rs/rocket/request/trait.FromForm.html
|
||||
[`FromForm`]: @api/rocket/request/trait.FromForm.html
|
||||
|
||||
### And Plenty More!
|
||||
|
||||
|
|
@ -189,7 +189,7 @@ following new features:
|
|||
* [`Response::content_type()`] was added to retrieve the Content-Type header
|
||||
of a response.
|
||||
* Data limits on incoming data are [now
|
||||
configurable](/guide/configuration/#data-limits).
|
||||
configurable](../../guide/configuration/#data-limits).
|
||||
* [`Request::limits()`] was added to retrieve incoming data limits.
|
||||
* Responders may dynamically adjust their response based on the incoming
|
||||
request.
|
||||
|
|
@ -211,28 +211,28 @@ following new features:
|
|||
* The [`NotFound`] responder was added for simple **404** response
|
||||
construction.
|
||||
|
||||
[`MsgPack`]: https://api.rocket.rs/rocket_contrib/struct.MsgPack.html
|
||||
[`Rocket::launch()`]: https://api.rocket.rs/rocket/struct.Rocket.html#method.launch
|
||||
[`LaunchError`]: https://api.rocket.rs/rocket/error/struct.LaunchError.html
|
||||
[Default rankings]: https://api.rocket.rs/rocket/struct.Route.html
|
||||
[`&Route`]: https://api.rocket.rs/rocket/struct.Route.html
|
||||
[`Route`]: https://api.rocket.rs/rocket/struct.Route.html
|
||||
[`Accept`]: https://api.rocket.rs/rocket/http/struct.Accept.html
|
||||
[`Request::accept()`]: https://api.rocket.rs/rocket/struct.Request.html#method.accept
|
||||
[`contrib`]: https://api.rocket.rs/rocket_contrib/
|
||||
[`Rocket::routes()`]: https://api.rocket.rs/rocket/struct.Rocket.html#method.routes
|
||||
[`Response::body_string()`]: https://api.rocket.rs/rocket/struct.Response.html#method.body_string
|
||||
[`Response::body_bytes()`]: https://api.rocket.rs/rocket/struct.Response.html#method.body_bytes
|
||||
[`Response::content_type()`]: https://api.rocket.rs/rocket/struct.Response.html#method.content_type
|
||||
[`Request::guard()`]: https://api.rocket.rs/rocket/struct.Request.html#method.guard
|
||||
[`Request::limits()`]: https://api.rocket.rs/rocket/struct.Request.html#method.limits
|
||||
[`Request::route()`]: https://api.rocket.rs/rocket/struct.Request.html#method.route
|
||||
[`Config`]: https://api.rocket.rs/rocket/struct.Config.html
|
||||
[`Cookies`]: https://api.rocket.rs/rocket/http/enum.Cookies.html
|
||||
[`Config::get_datetime()`]: https://api.rocket.rs/rocket/struct.Config.html#method.get_datetime
|
||||
[`LenientForm`]: https://api.rocket.rs/rocket/request/struct.LenientForm.html
|
||||
[configuration parameters]: https://api.rocket.rs/rocket/config/index.html#environment-variables
|
||||
[`NotFound`]: https://api.rocket.rs/rocket/response/status/struct.NotFound.html
|
||||
[`MsgPack`]: @api/rocket_contrib/struct.MsgPack.html
|
||||
[`Rocket::launch()`]: @api/rocket/struct.Rocket.html#method.launch
|
||||
[`LaunchError`]: @api/rocket/error/struct.LaunchError.html
|
||||
[Default rankings]: @api/rocket/struct.Route.html
|
||||
[`&Route`]: @api/rocket/struct.Route.html
|
||||
[`Route`]: @api/rocket/struct.Route.html
|
||||
[`Accept`]: @api/rocket/http/struct.Accept.html
|
||||
[`Request::accept()`]: @api/rocket/struct.Request.html#method.accept
|
||||
[`contrib`]: @api/rocket_contrib/
|
||||
[`Rocket::routes()`]: @api/rocket/struct.Rocket.html#method.routes
|
||||
[`Response::body_string()`]: @api/rocket/struct.Response.html#method.body_string
|
||||
[`Response::body_bytes()`]: @api/rocket/struct.Response.html#method.body_bytes
|
||||
[`Response::content_type()`]: @api/rocket/struct.Response.html#method.content_type
|
||||
[`Request::guard()`]: @api/rocket/struct.Request.html#method.guard
|
||||
[`Request::limits()`]: @api/rocket/struct.Request.html#method.limits
|
||||
[`Request::route()`]: @api/rocket/struct.Request.html#method.route
|
||||
[`Config`]: @api/rocket/struct.Config.html
|
||||
[`Cookies`]: @api/rocket/http/enum.Cookies.html
|
||||
[`Config::get_datetime()`]: @api/rocket/struct.Config.html#method.get_datetime
|
||||
[`LenientForm`]: @api/rocket/request/struct.LenientForm.html
|
||||
[configuration parameters]: @api/rocket/config/index.html#environment-variables
|
||||
[`NotFound`]: @api/rocket/response/status/struct.NotFound.html
|
||||
|
||||
## Breaking Changes
|
||||
|
||||
|
|
@ -267,9 +267,9 @@ In addition to new features, Rocket saw the following improvements:
|
|||
* The format of a request is always logged when available.
|
||||
|
||||
[`yansi`]: https://crates.io/crates/yansi
|
||||
[`Request`]: https://api.rocket.rs/rocket/struct.Request.html
|
||||
[`State`]: https://api.rocket.rs/rocket/struct.State.html
|
||||
[`Config`]: https://api.rocket.rs/rocket/struct.Config.html
|
||||
[`Request`]: @api/rocket/struct.Request.html
|
||||
[`State`]: @api/rocket/struct.State.html
|
||||
[`Config`]: @api/rocket/struct.Config.html
|
||||
|
||||
## What's Next?
|
||||
|
||||
|
|
|
|||
|
|
@ -47,7 +47,7 @@ Each dynamic parameter (`name` and `age`) must have a type, here `&str` and
|
|||
`u8`, respectively. Rocket will attempt to parse the string in the parameter's
|
||||
position in the path into that type. The route will only be called if parsing
|
||||
succeeds. To parse the string, Rocket uses the
|
||||
[FromParam](https://api.rocket.rs/rocket/request/trait.FromParam.html) trait,
|
||||
[FromParam](@api/rocket/request/trait.FromParam.html) trait,
|
||||
which you can implement for your own types!
|
||||
'''
|
||||
|
||||
|
|
@ -55,7 +55,7 @@ which you can implement for your own types!
|
|||
name = "Handling Data"
|
||||
content = '''
|
||||
Request body data is handled in a special way in Rocket: via the
|
||||
[FromData](https://api.rocket.rs/rocket/data/trait.FromData.html) trait. Any
|
||||
[FromData](@api/rocket/data/trait.FromData.html) trait. Any
|
||||
type that implements `FromData` can be derived from incoming body data. To tell
|
||||
Rocket that you're expecting request body data, the `data` route argument is
|
||||
used with the name of the parameter in the request handler:
|
||||
|
|
@ -69,13 +69,13 @@ fn login(user_form: Form<UserLogin>) -> String {
|
|||
|
||||
The `login` route above says that it expects `data` of type `Form<UserLogin>` in
|
||||
the `user_form` parameter. The
|
||||
[Form](https://api.rocket.rs/rocket/request/struct.Form.html) type is a built-in
|
||||
[Form](@api/rocket/request/struct.Form.html) type is a built-in
|
||||
Rocket type that knows how to parse web forms into structures. Rocket will
|
||||
automatically attempt to parse the request body into the `Form` and call the
|
||||
`login` handler if parsing succeeds. Other built-in `FromData` types include
|
||||
[`Data`](https://api.rocket.rs/rocket/struct.Data.html),
|
||||
[`Json`](https://api.rocket.rs/rocket_contrib/struct.Json.html), and
|
||||
[`Flash`](https://api.rocket.rs/rocket/response/struct.Flash.html)
|
||||
[`Data`](@api/rocket/struct.Data.html),
|
||||
[`Json`](@api/rocket_contrib/struct.Json.html), and
|
||||
[`Flash`](@api/rocket/response/struct.Flash.html)
|
||||
'''
|
||||
|
||||
[[panels]]
|
||||
|
|
@ -99,7 +99,7 @@ fn sensitive(key: ApiKey) -> &'static str { ... }
|
|||
`ApiKey` protects the `sensitive` handler from running incorrectly. In order for
|
||||
Rocket to call the `sensitive` handler, the `ApiKey` type needs to be derived
|
||||
through a
|
||||
[FromRequest](https://api.rocket.rs/rocket/request/trait.FromRequest.html)
|
||||
[FromRequest](@api/rocket/request/trait.FromRequest.html)
|
||||
implementation, which in this case, validates the API key header. Request guards
|
||||
are a powerful and unique Rocket concept; they centralize application policy and
|
||||
invariants through types.
|
||||
|
|
@ -109,7 +109,7 @@ invariants through types.
|
|||
name = "Responders"
|
||||
content = '''
|
||||
The return type of a request handler can be any type that implements
|
||||
[Responder](https://api.rocket.rs/rocket/response/trait.Responder.html):
|
||||
[Responder](@api/rocket/response/trait.Responder.html):
|
||||
|
||||
```rust
|
||||
#[get("/")]
|
||||
|
|
@ -119,12 +119,12 @@ fn route() -> T { ... }
|
|||
Above, T must implement `Responder`. Rocket implements `Responder` for many of
|
||||
the standard library types including `&str`, `String`, `File`, `Option`, and
|
||||
`Result`. Rocket also implements custom responders such as
|
||||
[Redirect](https://api.rocket.rs/rocket/response/struct.Redirect.html),
|
||||
[Flash](https://api.rocket.rs/rocket/response/struct.Flash.html), and
|
||||
[Template](https://api.rocket.rs/rocket_contrib/struct.Template.html).
|
||||
[Redirect](@api/rocket/response/struct.Redirect.html),
|
||||
[Flash](@api/rocket/response/struct.Flash.html), and
|
||||
[Template](@api/rocket_contrib/struct.Template.html).
|
||||
|
||||
The task of a `Responder` is to generate a
|
||||
[`Response`](https://api.rocket.rs/rocket/response/struct.Response.html), if
|
||||
[`Response`](@api/rocket/response/struct.Response.html), if
|
||||
possible. `Responder`s can fail with a status code. When they do, Rocket calls
|
||||
the corresponding error catcher, a `catch` route, which can be declared as
|
||||
follows:
|
||||
|
|
|
|||
Loading…
Reference in New Issue