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

Update site content for restructure.

This commit is contained in:
Sergio Benitez 2018-10-15 22:50:35 -07:00
parent 1c0f2d41a7
commit 26ee132782
19 changed files with 218 additions and 213 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
site/README.md
View File

@ -7,20 +7,39 @@ website](https://rocket.rs).
This directory contains the following: This directory contains the following:
* `index.toml` - Source data for the index (`/`). * `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/`).
* `overview.toml` - Source data for the overview page (`/overview`). * `news/index.toml` - Source data for the news page (`news/`).
* `guide.md` - Index page for the [Rocket Programming Guide] (`/guide`). * `news/*.md` - News articles linked to from `news/index.toml`.
* `news/*.md` - News articles linked to from `news.toml`.
* `guide/*.md` - Guide pages linked to from `guide.md`. * `guide/*.md` - Guide pages linked to from `guide.md`.
[Rocket Programming Guide]: https://rocket.rs/guide/ [Rocket Programming Guide]: https://rocket.rs/guide/
### Guide Links ### Guide Links
Cross-linking to pages in the guide is accomplished via absolute links rooted at Cross-linking guide pages is accomplished via relative links. Outside of the
`/guide/`. To link to the page whose source is at `guide/page.md`, for instance, index, this is: `../{page}#anchor`. For instance, to link to the **Quickstart >
link to `/guide/page`. 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 ## License

0
site/guide/introduction.md → site/guide/0-introduction.md
View File

2
site/guide/quickstart.md → site/guide/1-quickstart.md
View File

@ -3,7 +3,7 @@
Before you can start writing a Rocket application, you'll need a **nightly** Before you can start writing a Rocket application, you'll need a **nightly**
version of Rust installed. We recommend you use [rustup](https://rustup.rs/) to version of Rust installed. We recommend you use [rustup](https://rustup.rs/) to
install or configure such a version. If you don't have Rust installed and would install or configure such a version. If you don't have Rust installed and would
like extra guidance doing so, see the [getting started](/guide/getting-started) like extra guidance doing so, see the [getting started](../getting-started)
section. section.
## Running Examples ## Running Examples

17
site/guide/pastebin.md → site/guide/10-pastebin.md
View File

@ -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 the body of a fully formed HTTP response with `Content-Type: text/plain`. You
can read more about how Rocket formulates responses at the [API documentation can read more about how Rocket formulates responses at the [API documentation
for the Responder for the Responder
trait](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 Remember that routes first need to be mounted before Rocket dispatches requests
to them. To mount the `index` route, modify the main function so that it reads: to them. To mount the `index` route, modify the main function so that it reads:
@ -213,7 +213,7 @@ use rocket::Data;
use rocket::http::RawStr; 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 here: it represents an unopened stream to the incoming request body data. We'll
use it to efficiently stream the incoming request to a file. use it to efficiently stream the incoming request to a file.
@ -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 in an `<id>` as a dynamic path element. The handler uses the `id` to construct a
path to the paste inside `upload/`, and then attempts to open the file at that path to the paste inside `upload/`, and then attempts to open the file at that
path, optionally returning the `File` if it exists. Rocket treats a `None` path, optionally returning the `File` if it exists. Rocket treats a `None`
[Responder](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 as a **404** error, which is exactly what we want to return when the requested
paste doesn't exist. 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 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 [`RawStr`](@api/rocket/http/struct.RawStr.html) type should tip you off!
you off!
The issue is that the _user_ controls the value of `id`, and as a result, can The issue is that the _user_ controls the value of `id`, and as a result, can
coerce the service into opening files inside `upload/` that aren't meant to be coerce the service into opening files inside `upload/` that aren't meant to be
@ -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 To prevent the attack, we need to _validate_ `id` before we use it. Since the
`id` is a dynamic parameter, we can use Rocket's `id` is a dynamic parameter, we can use Rocket's
[FromParam](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 implement the validation and ensure that the `id` is a valid `PasteID` before
using it. We do this by implementing `FromParam` for `PasteID` in using it. We do this by implementing `FromParam` for `PasteID` in
`src/paste_id.rs`, as below: `src/paste_id.rs`, as below:
@ -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 * Add a new route, `GET /<id>/<lang>` that syntax highlights the paste with ID
`<id>` for language `<lang>`. If `<lang>` is not a known language, do no `<id>` for language `<lang>`. If `<lang>` is not a known language, do no
highlighting. Possibly validate `<lang>` with `FromParam`. highlighting. Possibly validate `<lang>` with `FromParam`.
* Use the [`local` module](https://api.rocket.rs/rocket/local/) to write * Use the [`local` module](@api/rocket/local/) to write unit tests for your
unit tests for your pastebin. pastebin.
* Dispatch a thread before `launch`ing Rocket in `main` that periodically * Dispatch a thread before `launch`ing Rocket in `main` that periodically
cleans up idling old pastes in `upload/`. cleans up idling old pastes in `upload/`.
You can find the full source code for the [completed pastebin tutorial on You can find the full source code for the [completed pastebin tutorial on
GitHub](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/pastebin). GitHub](@example/pastebin).

6
site/guide/conclusion.md → site/guide/11-conclusion.md
View File

@ -22,7 +22,5 @@ guide.
The best way to learn Rocket is to _build something_. It should be fun and easy, The best way to learn Rocket is to _build something_. It should be fun and easy,
and there's always someone to help. Alternatively, you can read through the and there's always someone to help. Alternatively, you can read through the
[Rocket examples](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples) [Rocket examples](@example) or the [Rocket source code](@github/lib/src).
or the [Rocket source Whatever you decide to do next, we hope you have a blast!
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!

0
site/guide/getting-started.md → site/guide/2-getting-started.md
View File

6
site/guide/overview.md → site/guide/3-overview.md
View File

@ -71,7 +71,7 @@ fn world() -> &'static str { // <- request handler
This declares the `world` route to match against the static path `"/world"` on This declares the `world` route to match against the static path `"/world"` on
incoming `GET` requests. The `world` route is simple, but additional route incoming `GET` requests. The `world` route is simple, but additional route
parameters are necessary when building more interesting applications. The parameters are necessary when building more interesting applications. The
[Requests](/guide/requests) section describes the available options for [Requests](../requests) section describes the available options for
constructing routes. constructing routes.
## Mounting ## Mounting
@ -179,7 +179,7 @@ we expected.
A version of this example's complete crate, ready to `cargo run`, can be found A version of this example's complete crate, ready to `cargo run`, can be found
on 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 You can find dozens of other complete examples, spanning all of Rocket's
features, in the [GitHub examples features, in the [GitHub examples
directory](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/). directory](@example/).

70
site/guide/requests.md → site/guide/4-requests.md
View File

@ -38,7 +38,7 @@ to the root path:
``` ```
The grammar for these attributes is defined formally in the 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 ### 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 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. `"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 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) example](@example/todo/static/index.html.tera#L47) makes use of this feature to
makes use of this feature to submit `PUT` and `DELETE` requests from a web form. submit `PUT` and `DELETE` requests from a web form.
## Dynamic Segments ## 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/rocket/request/trait.FromParam.html
[`FromParam` API docs]: https://api.rocket.rs/rocket/request/trait.FromParam.html [`FromParam` API docs]: @api/rocket/request/trait.FromParam.html
### Raw Strings ### 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 you want direct but potentially unsafe access to the string (`&RawStr`), or safe
access to the string at the cost of an allocation (`String`). 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 ## 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 ## 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 Rocket would match the `format` against the `Content-Type` header of the
incoming response. 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 ## 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`] more about request guards and implementing them, see the [`FromRequest`]
documentation. documentation.
[`FromRequest`]: https://api.rocket.rs/rocket/request/trait.FromRequest.html [`FromRequest`]: @api/rocket/request/trait.FromRequest.html
[`Cookies`]: https://api.rocket.rs/rocket/http/enum.Cookies.html [`Cookies`]: @api/rocket/http/enum.Cookies.html
### Custom Guards ### 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 illustrates further use of the `Cookies` type to get and set cookies, while the
[`Cookies`] documentation contains complete usage information. [`Cookies`] documentation contains complete usage information.
[cookies example]: https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/cookies [cookies example]: @example/cookies
### Private 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 ### 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 usually done through tools like `openssl`. Using `openssl`, a 256-bit base64 key
can be generated with the command `openssl rand -base64 32`. can be generated with the command `openssl rand -base64 32`.
For more information on configuration, see the For more information on configuration, see the [Configuration](../configuration)
[Configuration](/guide/configuration) section of the guide. section of the guide.
[`get_private`]: https://api.rocket.rs/rocket/http/enum.Cookies.html#method.get_private [`get_private`]: @api/rocket/http/enum.Cookies.html#method.get_private
[`add_private`]: https://api.rocket.rs/rocket/http/enum.Cookies.html#method.add_private [`add_private`]: @api/rocket/http/enum.Cookies.html#method.add_private
[`remove_private`]: https://api.rocket.rs/rocket/http/enum.Cookies.html#method.remove_private [`remove_private`]: @api/rocket/http/enum.Cookies.html#method.remove_private
### One-At-A-Time ### One-At-A-Time
@ -497,7 +497,7 @@ fn new(input: T) -> String { ... }
Any type that implements [`FromData`] is also known as _data guard_. 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 ### 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 { ... } fn new(task: Option<Form<Task>>) -> String { ... }
``` ```
[`FromForm`]: https://api.rocket.rs/rocket/request/trait.FromForm.html [`FromForm`]: @api/rocket/request/trait.FromForm.html
[`FromFormValue`]: https://api.rocket.rs/rocket/request/trait.FromFormValue.html [`FromFormValue`]: @api/rocket/request/trait.FromFormValue.html
#### Lenient Parsing #### Lenient Parsing
@ -564,7 +564,7 @@ struct Task { .. }
fn new(task: LenientForm<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 #### Field Renaming
@ -629,14 +629,14 @@ struct Person {
} }
``` ```
The [forms validation](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/form_validation) The [forms validation](@example/form_validation)
and [forms kitchen sink](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/form_kitchen_sink) and [forms kitchen sink](@example/form_kitchen_sink)
examples on GitHub provide further illustrations. examples on GitHub provide further illustrations.
### JSON ### JSON
Handling JSON data is no harder: simply use the 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 ```rust
#[derive(Deserialize)] #[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 `Deserialize` trait from [Serde](https://github.com/serde-rs/json). See the
[JSON example] on GitHub for a complete example. [JSON example] on GitHub for a complete example.
[JSON example]: https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/json [JSON example]: @example/json
### Streaming ### Streaming
Sometimes you just want to handle incoming data directly. For example, you might Sometimes you just want to handle incoming data directly. For example, you might
want to stream the incoming data out to a file. Rocket makes this as simple as want to stream the incoming data out to a file. Rocket makes this as simple as
possible via the [`Data`](https://api.rocket.rs/rocket/data/struct.Data.html) possible via the [`Data`](@api/rocket/data/struct.Data.html)
type: type:
```rust ```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 `tmp/upload.txt`, and the number of bytes written is returned as a plain text
response if the upload succeeds. If the upload fails, an error response is response if the upload succeeds. If the upload fails, an error response is
returned. The handler above is complete. It really is that simple! See the returned. The handler above is complete. It really is that simple! See the
[GitHub example [GitHub example code](@example/raw_upload) for the full crate.
code](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/raw_upload)
for the full crate.
## Query Strings ## Query Strings
@ -731,14 +729,14 @@ fn new(task: Option<Task>) { ... }
For a concrete illustration on how to handle query parameters, see [the For a concrete illustration on how to handle query parameters, see [the
`query_params` `query_params`
example](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/query_params). example](@example/query_params).
## Error Catchers ## Error Catchers
Routing may fail for a variety of reasons. These include: Routing may fail for a variety of reasons. These include:
* A [request guard](#request-guards) returns `Failure`. * 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. * No matching route was found.
If any of these conditions occur, Rocket returns an error to the client. To do 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]) rocket::ignite().register(catchers![not_found])
``` ```
Unlike route request handlers, catchers take exactly zero or one parameters. If Unlike route request handlers, catchers take exactly zero or one parameter. If
the catcher takes a parameter, it must be of type the catcher takes a parameter, it must be of type [`&Request`] The [error
[`&Request`](https://api.rocket.rs/rocket/struct.Request.html) The [error catcher example](@example/errors) on GitHub illustrates their use in full.
catcher example](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/errors)
on GitHub illustrates their use in full. [`&Request]: @api/rocket/struct.Request.html

58
site/guide/responses.md → site/guide/5-responses.md
View File

@ -6,7 +6,7 @@ trait can be returned, including your own. In this section, we describe the
`Responder` trait as well as several useful `Responder`s provided by Rocket. `Responder` trait as well as several useful `Responder`s provided by Rocket.
We'll also briefly discuss how to implement your own `Responder`. We'll also briefly discuss how to implement your own `Responder`.
[`Responder`]: https://api.rocket.rs/rocket/response/trait.Responder.html [`Responder`]: @api/rocket/response/trait.Responder.html
## Responder ## Responder
@ -17,7 +17,7 @@ decides which to use. For instance, `String` uses a fixed-sized body, while
`File` uses a streamed response. Responders may dynamically adjust their `File` uses a streamed response. Responders may dynamically adjust their
responses according to the incoming `Request` they are responding to. responses according to the incoming `Request` they are responding to.
[`Response`]: https://api.rocket.rs/rocket/response/struct.Response.html [`Response`]: @api/rocket/response/struct.Response.html
### Wrapping ### Wrapping
@ -31,10 +31,9 @@ struct WrappingResponder<R>(R);
A wrapping responder modifies the response returned by `R` before responding A wrapping responder modifies the response returned by `R` before responding
with that same response. For instance, Rocket provides `Responder`s in the with that same response. For instance, Rocket provides `Responder`s in the
[`status` module](https://api.rocket.rs/rocket/response/status/index.html) that [`status` module](@api/rocket/response/status/) that override the status code of
override the status code of the wrapped `Responder`. As an example, the the wrapped `Responder`. As an example, the [`Accepted`] type sets the status to
[`Accepted`] type sets the status to `202 - Accepted`. It can be used as `202 - Accepted`. It can be used as follows:
follows:
```rust ```rust
use rocket::response::status; use rocket::response::status;
@ -45,10 +44,10 @@ fn new(id: usize) -> status::Accepted<String> {
} }
``` ```
Similarly, the types in the [`content` Similarly, the types in the [`content` module](@api/rocket/response/content/)
module](https://api.rocket.rs/rocket/response/content/index.html) can be used to can be used to override the Content-Type of a response. For instance, to set the
override the Content-Type of a response. For instance, to set the Content-Type Content-Type of `&'static str` to JSON, you can use the [`content::Json`] type
of `&'static str` to JSON, you can use the [`content::Json`] type as follows: as follows:
```rust ```rust
use rocket::response::content; 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 [`Accepted`]: @api/rocket/response/status/struct.Accepted.html
[`content::Json`]: https://api.rocket.rs/rocket/response/content/struct.Json.html [`content::Json`]: @api/rocket/response/content/struct.Json.html
### Errors ### Errors
Responders may fail; they need not _always_ generate a response. Instead, they 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 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. given status code.
If an error catcher has been registered for the given status code, Rocket will 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. response.
While not encouraged, you can also forward a request to a catcher manually by 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 type. For instance, to forward to the catcher for **406 - Not Acceptable**, you
would write: 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. * [`status`] - Contains types that override the status code of a response.
* [`Flash`] - Sets a "flash" cookie that is removed when accessed. * [`Flash`] - Sets a "flash" cookie that is removed when accessed.
[`status`]: https://api.rocket.rs/rocket/response/status/index.html [`status`]: @api/rocket/response/status/
[`response`]: https://api.rocket.rs/rocket/response/index.html [`response`]: @api/rocket/response/
[`NamedFile`]: https://api.rocket.rs/rocket/response/struct.NamedFile.html [`NamedFile`]: @api/rocket/response/struct.NamedFile.html
[`Content`]: https://api.rocket.rs/rocket/response/struct.Content.html [`Content`]: @api/rocket/response/struct.Content.html
[`Redirect`]: https://api.rocket.rs/rocket/response/struct.Redirect.html [`Redirect`]: @api/rocket/response/struct.Redirect.html
[`Stream`]: https://api.rocket.rs/rocket/response/struct.Stream.html [`Stream`]: @api/rocket/response/struct.Stream.html
[`Flash`]: https://api.rocket.rs/rocket/response/struct.Flash.html [`Flash`]: @api/rocket/response/struct.Flash.html
### Streaming ### 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 ### JSON
@ -233,10 +232,10 @@ fails, a **500 - Internal Server Error** is returned.
The [JSON example on GitHub] provides further illustration. The [JSON example on GitHub] provides further illustration.
[`JSON`]: 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 [`Serialize`]: https://docs.serde.rs/serde/trait.Serialize.html
[`serde`]: https://docs.serde.rs/serde/ [`serde`]: https://docs.serde.rs/serde/
[JSON example on GitHub]: https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/json [JSON example on GitHub]: @example/json
### Templates ### 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. changes: simply refresh! In release builds, reloading is disabled.
For templates to be properly registered, the template fairing must be attached 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 provides more information on fairings. To attach the template fairing, simply
call `.attach(Template::fairing())` on an instance of `Rocket` as follows: 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, The [`Template`] API documentation contains more information about templates,
including how to customize a template engine to add custom helpers and filters. including how to customize a template engine to add custom helpers and filters.
The [Handlebars Templates example on The [Handlebars Templates example on GitHub](@example/handlebars_templates) is a
GitHub](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/handlebars_templates) fully composed application that makes use of Handlebars templates.
is a fully composed application that makes use of Handlebars templates.
[`Template`]: https://api.rocket.rs/rocket_contrib/struct.Template.html [`Template`]: @api/rocket_contrib/struct.Template.html
[configurable]: /guide/configuration/#extras [configurable]: ../configuration/#extras

22
site/guide/state.md → site/guide/6-state.md
View File

@ -22,7 +22,7 @@ The process for using managed state is simple:
### Adding State ### Adding State
To instruct Rocket to manage state for your application, call the To instruct Rocket to manage state for your application, call the
[`manage`](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` on an instance of `Rocket`. For example, to ask Rocket to manage a `HitCount`
structure with an internal `AtomicUsize` with an initial value of `0`, we can structure with an internal `AtomicUsize` with an initial value of `0`, we can
write the following: write the following:
@ -48,8 +48,8 @@ rocket::ignite()
### Retrieving State ### Retrieving State
State that is being managed by Rocket can be retrieved via the State that is being managed by Rocket can be retrieved via the
[`State`](https://api.rocket.rs/rocket/struct.State.html) type: a [request [`State`](@api/rocket/struct.State.html) type: a [request
guard](/guide/requests/#request-guards) for managed state. To use the request guard](../requests/#request-guards) for managed state. To use the request
guard, add a `State<T>` type to any request handler, where `T` is the type of guard, add a `State<T>` type to any request handler, where `T` is the type of
the managed state. For example, we can retrieve and respond with the current the managed state. For example, we can retrieve and respond with the current
`HitCount` in a `count` route as follows: `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. **500** error to the client.
You can find a complete example using the `HitCount` structure in the [state You can find a complete example using the `HitCount` structure in the [state
example on example on GitHub](@example/state) and learn more about the [`manage`
GitHub](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/state) and method](@api/rocket/struct.Rocket.html#method.manage) and [`State`
learn more about the [`manage` type](@api/rocket/struct.State.html) in the API docs.
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.
### Within Guards ### 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 ### 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 computations, and the [`Fairing`] documentation, which uses request-local state
to implement request timing. to implement request timing.
[`FromRequest`]: https://api.rocket.rs/rocket/request/trait.FromRequest.htmll#request-local-state [`FromRequest`]: @api/rocket/request/trait.FromRequest.htmll#request-local-state
[`Fairing`]: https://api.rocket.rs/rocket/fairing/trait.Fairing.html#request-local-state [`Fairing`]: @api/rocket/fairing/trait.Fairing.html#request-local-state
## Databases ## 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 For more on Rocket's built-in database support, see the
[`rocket_contrib::databases`] module documentation. [`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

40
site/guide/fairings.md → site/guide/7-fairings.md
View File

@ -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 application. On the other hand, you _should_ use a fairing to record timing and
usage statistics or to enforce global security policies. usage statistics or to enforce global security policies.
[`Fairing`]: https://api.rocket.rs/rocket/fairing/trait.Fairing.html [`Fairing`]: @api/rocket/fairing/trait.Fairing.html
[request guard]: /guide/requests/#request-guards [request guard]: ../requests/#request-guards
[request guards]: /guide/requests/#request-guards [request guards]: ../requests/#request-guards
[data guards]: /guide/requests/#body-data [data guards]: ../requests/#body-data
### Attaching ### Attaching
@ -52,8 +52,8 @@ rocket::ignite()
.launch(); .launch();
``` ```
[`attach`]: https://api.rocket.rs/rocket/struct.Rocket.html#method.attach [`attach`]: @api/rocket/struct.Rocket.html#method.attach
[`Rocket`]: https://api.rocket.rs/rocket/struct.Rocket.html [`Rocket`]: @api/rocket/struct.Rocket.html
Fairings are executed in the order in which they are attached: the first Fairings are executed in the order in which they are attached: the first
attached fairing has its callbacks executed before all others. Because fairing attached fairing has its callbacks executed before all others. Because fairing
@ -68,12 +68,11 @@ events is described below:
* **Attach (`on_attach`)** * **Attach (`on_attach`)**
An attach callback is called when a fairing is first attached via the An attach callback is called when a fairing is first attached via the
[`attach`](https://api.rocket.rs/rocket/struct.Rocket.html#method.attach) [`attach`](@api/rocket/struct.Rocket.html#method.attach) method. An attach
method. An attach callback can arbitrarily modify the `Rocket` instance callback can arbitrarily modify the `Rocket` instance being constructed and
being constructed and optionally abort launch. Attach fairings are commonly optionally abort launch. Attach fairings are commonly used to parse and
used to parse and validate configuration values, aborting on bad validate configuration values, aborting on bad configurations, and inserting
configurations, and inserting the parsed value into managed state for later the parsed value into managed state for later retrieval.
retrieval.
* **Launch (`on_launch`)** * **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 [`on_launch`], [`on_request`], and [`on_response`]. Each callback has a default
implementation that does absolutely nothing. implementation that does absolutely nothing.
[`Info`]: https://api.rocket.rs/rocket/fairing/struct.Info.html [`Info`]: @api/rocket/fairing/struct.Info.html
[`info`]: https://api.rocket.rs/rocket/fairing/trait.Fairing.html#tymethod.info [`info`]: @api/rocket/fairing/trait.Fairing.html#tymethod.info
[`on_attach`]: https://api.rocket.rs/rocket/fairing/trait.Fairing.html#method.on_attach [`on_attach`]: @api/rocket/fairing/trait.Fairing.html#method.on_attach
[`on_launch`]: https://api.rocket.rs/rocket/fairing/trait.Fairing.html#method.on_launch [`on_launch`]: @api/rocket/fairing/trait.Fairing.html#method.on_launch
[`on_request`]: https://api.rocket.rs/rocket/fairing/trait.Fairing.html#method.on_request [`on_request`]: @api/rocket/fairing/trait.Fairing.html#method.on_request
[`on_response`]: https://api.rocket.rs/rocket/fairing/trait.Fairing.html#method.on_response [`on_response`]: @api/rocket/fairing/trait.Fairing.html#method.on_response
### Requirements ### Requirements
@ -182,8 +181,7 @@ impl Fairing for Counter {
``` ```
For brevity, imports are not shown. The complete example can be found in the For brevity, imports are not shown. The complete example can be found in the
[`Fairing` [`Fairing` documentation](@api/rocket/fairing/trait.Fairing.html#example).
documentation](https://api.rocket.rs/rocket/fairing/trait.Fairing.html#example).
## Ad-Hoc Fairings ## 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

25
site/guide/testing.md → site/guide/8-testing.md
View File

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

10
site/guide/configuration.md → site/guide/9-configuration.md
View File

@ -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 data limits as well. Data limits can be retrieved at runtime via the
[`Request::limits()`] method. [`Request::limits()`] method.
[`Request::limits()`]: https://api.rocket.rs/rocket/struct.Request.html#method.limits [`Request::limits()`]: @api/rocket/struct.Request.html#method.limits
[`Json`]: https://api.rocket.rs/rocket_contrib/struct.Json.html#incoming-data-limits [`Json`]: @api/rocket_contrib/struct.Json.html#incoming-data-limits
## Extras ## 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 can also define values for any number of _extra_ configuration parameters. While
these parameters aren't used by Rocket directly, other libraries, or your own these parameters aren't used by Rocket directly, other libraries, or your own
application, can use them as they wish. As an example, the application, can use them as they wish. As an example, the
[Template](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 accepts a value for the `template_dir` configuration parameter. The parameter
can be set in `Rocket.toml` as follows: can be set in `Rocket.toml` as follows:
@ -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]. 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: For example, if your application makes use of a custom `assets_dir` parameter:
[ad-hoc attach fairing]: /guide/fairings/#ad-hoc-fairings [ad-hoc attach fairing]: ../fairings/#ad-hoc-fairings
[managed state]: /guide/state/#managed-state [managed state]: ../state/#managed-state
```toml ```toml
[development] [development]

2
site/guide.md → site/guide/index.md
View File

@ -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 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 a reference for experienced Rocket developers. This guide is conversational in
tone. For concise and purely technical documentation, see the [API 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 The guide is split into several sections, each with a focus on a different
aspect of Rocket. The sections are: aspect of Rocket. The sections are:

20
site/index.toml
View File

@ -12,21 +12,21 @@ title = "Type Safe"
text = "From request to response Rocket ensures that your types mean something." text = "From request to response Rocket ensures that your types mean something."
image = "helmet" image = "helmet"
button = "Learn More" button = "Learn More"
url = "/overview/#how-rocket-works" url = "overview/#how-rocket-works"
[[top_features]] [[top_features]]
title = "Boilerplate Free" title = "Boilerplate Free"
text = "Spend your time writing code that really matters, and let Rocket generate the rest." text = "Spend your time writing code that really matters, and let Rocket generate the rest."
image = "robot-free" image = "robot-free"
button = "See Examples" button = "See Examples"
url = "/overview/#anatomy-of-a-rocket-application" url = "overview/#anatomy-of-a-rocket-application"
[[top_features]] [[top_features]]
title = "Easy To Use" title = "Easy To Use"
text = "Rocket makes extensive use of Rust's code generation tools to provide a clean API." text = "Rocket makes extensive use of Rust's code generation tools to provide a clean API."
image = "sun" image = "sun"
button = "Get Started" button = "Get Started"
url = "/guide" url = "guide"
margin = 2 margin = 2
[[top_features]] [[top_features]]
@ -34,7 +34,7 @@ title = "Extensible"
text = "Easily create your own primitives that any Rocket application can use." text = "Easily create your own primitives that any Rocket application can use."
image = "telescope" image = "telescope"
button = "See How" button = "See How"
url = "/overview/#anatomy-of-a-rocket-application" url = "overview/#anatomy-of-a-rocket-application"
margin = 9 margin = 9
############################################################################### ###############################################################################
@ -134,7 +134,7 @@ text = '''
title = 'Templating' title = 'Templating'
text = "Rocket makes rendering templates a breeze with built-in templating support." text = "Rocket makes rendering templates a breeze with built-in templating support."
image = 'templating-icon' image = 'templating-icon'
url = '/guide/responses/#templates' url = 'guide/responses/#templates'
button = 'Learn More' button = 'Learn More'
color = 'blue' color = 'blue'
@ -142,7 +142,7 @@ color = 'blue'
title = 'Cookies' title = 'Cookies'
text = "View, add, or remove cookies, with or without encryption, without hassle." text = "View, add, or remove cookies, with or without encryption, without hassle."
image = 'cookies-icon' image = 'cookies-icon'
url = '/guide/requests/#cookies' url = 'guide/requests/#cookies'
button = 'Learn More' button = 'Learn More'
color = 'purple' color = 'purple'
margin = -6 margin = -6
@ -151,7 +151,7 @@ margin = -6
title = 'Streams' title = 'Streams'
text = "Rocket streams all incoming and outgoing data, so size isn't a concern." text = "Rocket streams all incoming and outgoing data, so size isn't a concern."
image = 'streams-icon' image = 'streams-icon'
url = '/guide/requests/#streaming' url = 'guide/requests/#streaming'
button = 'Learn More' button = 'Learn More'
color = 'red' color = 'red'
margin = -29 margin = -29
@ -160,7 +160,7 @@ margin = -29
title = 'Config Environments' title = 'Config Environments'
text = "Configure your application your way for development, staging, and production." text = "Configure your application your way for development, staging, and production."
image = 'config-icon' image = 'config-icon'
url = '/guide/configuration/#environment' url = 'guide/configuration/#environment'
button = 'Learn More' button = 'Learn More'
color = 'yellow' color = 'yellow'
margin = -3 margin = -3
@ -169,7 +169,7 @@ margin = -3
title = 'Query Strings' title = 'Query Strings'
text = "Handling query strings and parameters is type-safe and easy in Rocket." text = "Handling query strings and parameters is type-safe and easy in Rocket."
image = 'query-icon' image = 'query-icon'
url = '/guide/requests/#query-strings' url = 'guide/requests/#query-strings'
button = 'Learn More' button = 'Learn More'
color = 'orange' color = 'orange'
margin = -3 margin = -3
@ -178,7 +178,7 @@ margin = -3
title = 'Testing Library' title = 'Testing Library'
text = "Unit test your applications with ease using the built-in testing library." text = "Unit test your applications with ease using the built-in testing library."
image = 'testing-icon' image = 'testing-icon'
url = '/guide/testing#testing' url = 'guide/testing#testing'
button = 'Learn More' button = 'Learn More'
color = 'green' color = 'green'

24
site/news/2017-02-06-version-0.2.md
View File

@ -46,8 +46,8 @@ state's type in the function signature. It works in two easy steps:
value passed into `manage`. value passed into `manage`.
Rocket takes care of the rest! `State` works through Rocket's [request Rocket takes care of the rest! `State` works through Rocket's [request
guards](/guide/requests/#request-guards). You can call `manage` any number of guards](../../guide/requests/#request-guards). You can call `manage` any number
times, as long as each call corresponds to a value of a different type. 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: 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 You can read more about managed state in the [guide](../../guide/state/), the
docs for API docs for [manage](@api/rocket/struct.Rocket.html#method.manage), and the API
[manage](https://api.rocket.rs/rocket/struct.Rocket.html#method.manage), and the docs for [State](@api/rocket/struct.State.html).
API docs for [State](https://api.rocket.rs/rocket/struct.State.html).
### Unmounted Routes Lint ### Unmounted Routes Lint
A common mistake that new Rocketeers make is forgetting to A common mistake that new Rocketeers make is forgetting to
[mount](/guide/overview/#mounting) declared routes. In Rocket v0.2, Rocket adds [mount](../../guide/overview/#mounting) declared routes. In Rocket v0.2, Rocket
a _lint_ that results in a compile-time warning for unmounted routes. As a adds a _lint_ that results in a compile-time warning for unmounted routes. As a
simple illustration, consider the canonical "Hello, world!" Rocket application simple illustration, consider the canonical "Hello, world!" Rocket application
below, and note that we've forgotten to mount the `hello` route: 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 The lint can be disabled selectively per route by adding an
`#[allow(unmounted_route)]` annotation to a given route declaration. It can also `#[allow(unmounted_route)]` annotation to a given route declaration. It can also
be disabled globally by adding `#![allow(unmounted_route)]`. You can read more be disabled globally by adding `#![allow(unmounted_route)]`. You can read more
about this lint in the [codegen about this lint in the [codegen documentation](@api/rocket_codegen/index.html).
documentation](https://api.rocket.rs/rocket_codegen/index.html).
### Configuration via Environment Variables ### 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_ parameters set via the `Rocket.toml` configuration file. Note that _any_
parameter can be set via an environment variable, include _extras_. For more parameter can be set via an environment variable, include _extras_. For more
about configuration in Rocket, see the [configuration section of the about configuration in Rocket, see the [configuration section of the
guide](/guide/overview/#configuration). guide](../../guide/overview/#configuration).
### And Plenty More! ### And Plenty More!
@ -392,5 +390,5 @@ contributing!
Not already using Rocket? Rocket is extensively documented, making it easy for Not already using Rocket? Rocket is extensively documented, making it easy for
you to start writing your web applications in Rocket! See the you to start writing your web applications in Rocket! See the
[overview](/overview) or start writing code immediately by reading through [the [overview](../../overview) or start writing code immediately by reading through
guide](/guide). [the guide](../../guide).

70
site/news/2017-07-14-version-0.3.md
View File

@ -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 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 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 started now by [reading through the guide](../../guide) or learning more from
overview](/overview). [the overview](../../overview).
## What's New? ## 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 to experiment with fairings and report your experiences. As always, feedback is
instrumental in solidifying a robust design. 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 [fairings guide]: /guide/fairings
### Native TLS Support ### 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 For more details on private cookies, see the [private cookies] section of the
guide. guide.
[`Cookies`]: https://api.rocket.rs/rocket/http/enum.Cookies.html [`Cookies`]: @api/rocket/http/enum.Cookies.html
[`get_private`]: https://api.rocket.rs/rocket/http/enum.Cookies.html#method.get_private [`get_private`]: @api/rocket/http/enum.Cookies.html#method.get_private
[`add_private`]: https://api.rocket.rs/rocket/http/enum.Cookies.html#method.add_private [`add_private`]: @api/rocket/http/enum.Cookies.html#method.add_private
[`remove_private`]: https://api.rocket.rs/rocket/http/enum.Cookies.html#method.remove_private [`remove_private`]: @api/rocket/http/enum.Cookies.html#method.remove_private
[private cookies]: /guide/requests/#private-cookies [private cookies]: /guide/requests/#private-cookies
### Form Field Naming ### Form Field Naming
@ -163,9 +163,9 @@ struct External {
Rocket will automatically match the form field named "type" to the structure 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 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! ### And Plenty More!
@ -189,7 +189,7 @@ following new features:
* [`Response::content_type()`] was added to retrieve the Content-Type header * [`Response::content_type()`] was added to retrieve the Content-Type header
of a response. of a response.
* Data limits on incoming data are [now * 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. * [`Request::limits()`] was added to retrieve incoming data limits.
* Responders may dynamically adjust their response based on the incoming * Responders may dynamically adjust their response based on the incoming
request. request.
@ -211,28 +211,28 @@ following new features:
* The [`NotFound`] responder was added for simple **404** response * The [`NotFound`] responder was added for simple **404** response
construction. construction.
[`MsgPack`]: https://api.rocket.rs/rocket_contrib/struct.MsgPack.html [`MsgPack`]: @api/rocket_contrib/struct.MsgPack.html
[`Rocket::launch()`]: https://api.rocket.rs/rocket/struct.Rocket.html#method.launch [`Rocket::launch()`]: @api/rocket/struct.Rocket.html#method.launch
[`LaunchError`]: https://api.rocket.rs/rocket/error/struct.LaunchError.html [`LaunchError`]: @api/rocket/error/struct.LaunchError.html
[Default rankings]: https://api.rocket.rs/rocket/struct.Route.html [Default rankings]: @api/rocket/struct.Route.html
[`&Route`]: https://api.rocket.rs/rocket/struct.Route.html [`&Route`]: @api/rocket/struct.Route.html
[`Route`]: https://api.rocket.rs/rocket/struct.Route.html [`Route`]: @api/rocket/struct.Route.html
[`Accept`]: https://api.rocket.rs/rocket/http/struct.Accept.html [`Accept`]: @api/rocket/http/struct.Accept.html
[`Request::accept()`]: https://api.rocket.rs/rocket/struct.Request.html#method.accept [`Request::accept()`]: @api/rocket/struct.Request.html#method.accept
[`contrib`]: https://api.rocket.rs/rocket_contrib/ [`contrib`]: @api/rocket_contrib/
[`Rocket::routes()`]: https://api.rocket.rs/rocket/struct.Rocket.html#method.routes [`Rocket::routes()`]: @api/rocket/struct.Rocket.html#method.routes
[`Response::body_string()`]: https://api.rocket.rs/rocket/struct.Response.html#method.body_string [`Response::body_string()`]: @api/rocket/struct.Response.html#method.body_string
[`Response::body_bytes()`]: https://api.rocket.rs/rocket/struct.Response.html#method.body_bytes [`Response::body_bytes()`]: @api/rocket/struct.Response.html#method.body_bytes
[`Response::content_type()`]: https://api.rocket.rs/rocket/struct.Response.html#method.content_type [`Response::content_type()`]: @api/rocket/struct.Response.html#method.content_type
[`Request::guard()`]: https://api.rocket.rs/rocket/struct.Request.html#method.guard [`Request::guard()`]: @api/rocket/struct.Request.html#method.guard
[`Request::limits()`]: https://api.rocket.rs/rocket/struct.Request.html#method.limits [`Request::limits()`]: @api/rocket/struct.Request.html#method.limits
[`Request::route()`]: https://api.rocket.rs/rocket/struct.Request.html#method.route [`Request::route()`]: @api/rocket/struct.Request.html#method.route
[`Config`]: https://api.rocket.rs/rocket/struct.Config.html [`Config`]: @api/rocket/struct.Config.html
[`Cookies`]: https://api.rocket.rs/rocket/http/enum.Cookies.html [`Cookies`]: @api/rocket/http/enum.Cookies.html
[`Config::get_datetime()`]: https://api.rocket.rs/rocket/struct.Config.html#method.get_datetime [`Config::get_datetime()`]: @api/rocket/struct.Config.html#method.get_datetime
[`LenientForm`]: https://api.rocket.rs/rocket/request/struct.LenientForm.html [`LenientForm`]: @api/rocket/request/struct.LenientForm.html
[configuration parameters]: https://api.rocket.rs/rocket/config/index.html#environment-variables [configuration parameters]: @api/rocket/config/index.html#environment-variables
[`NotFound`]: https://api.rocket.rs/rocket/response/status/struct.NotFound.html [`NotFound`]: @api/rocket/response/status/struct.NotFound.html
## Breaking Changes ## 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. * The format of a request is always logged when available.
[`yansi`]: https://crates.io/crates/yansi [`yansi`]: https://crates.io/crates/yansi
[`Request`]: https://api.rocket.rs/rocket/struct.Request.html [`Request`]: @api/rocket/struct.Request.html
[`State`]: https://api.rocket.rs/rocket/struct.State.html [`State`]: @api/rocket/struct.State.html
[`Config`]: https://api.rocket.rs/rocket/struct.Config.html [`Config`]: @api/rocket/struct.Config.html
## What's Next? ## What's Next?

0
site/news.toml → site/news/index.toml
View File

24
site/overview.toml
View File

@ -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 `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 position in the path into that type. The route will only be called if parsing
succeeds. To parse the string, Rocket uses the 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! which you can implement for your own types!
''' '''
@ -55,7 +55,7 @@ which you can implement for your own types!
name = "Handling Data" name = "Handling Data"
content = ''' content = '''
Request body data is handled in a special way in Rocket: via the 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 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 Rocket that you're expecting request body data, the `data` route argument is
used with the name of the parameter in the request handler: 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 `login` route above says that it expects `data` of type `Form<UserLogin>` in
the `user_form` parameter. The 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 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 automatically attempt to parse the request body into the `Form` and call the
`login` handler if parsing succeeds. Other built-in `FromData` types include `login` handler if parsing succeeds. Other built-in `FromData` types include
[`Data`](https://api.rocket.rs/rocket/struct.Data.html), [`Data`](@api/rocket/struct.Data.html),
[`Json`](https://api.rocket.rs/rocket_contrib/struct.Json.html), and [`Json`](@api/rocket_contrib/struct.Json.html), and
[`Flash`](https://api.rocket.rs/rocket/response/struct.Flash.html) [`Flash`](@api/rocket/response/struct.Flash.html)
''' '''
[[panels]] [[panels]]
@ -99,7 +99,7 @@ fn sensitive(key: ApiKey) -> &'static str { ... }
`ApiKey` protects the `sensitive` handler from running incorrectly. In order for `ApiKey` protects the `sensitive` handler from running incorrectly. In order for
Rocket to call the `sensitive` handler, the `ApiKey` type needs to be derived Rocket to call the `sensitive` handler, the `ApiKey` type needs to be derived
through a 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 implementation, which in this case, validates the API key header. Request guards
are a powerful and unique Rocket concept; they centralize application policy and are a powerful and unique Rocket concept; they centralize application policy and
invariants through types. invariants through types.
@ -109,7 +109,7 @@ invariants through types.
name = "Responders" name = "Responders"
content = ''' content = '''
The return type of a request handler can be any type that implements 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 ```rust
#[get("/")] #[get("/")]
@ -119,12 +119,12 @@ fn route() -> T { ... }
Above, T must implement `Responder`. Rocket implements `Responder` for many of Above, T must implement `Responder`. Rocket implements `Responder` for many of
the standard library types including `&str`, `String`, `File`, `Option`, and the standard library types including `&str`, `String`, `File`, `Option`, and
`Result`. Rocket also implements custom responders such as `Result`. Rocket also implements custom responders such as
[Redirect](https://api.rocket.rs/rocket/response/struct.Redirect.html), [Redirect](@api/rocket/response/struct.Redirect.html),
[Flash](https://api.rocket.rs/rocket/response/struct.Flash.html), and [Flash](@api/rocket/response/struct.Flash.html), and
[Template](https://api.rocket.rs/rocket_contrib/struct.Template.html). [Template](@api/rocket_contrib/struct.Template.html).
The task of a `Responder` is to generate a 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 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 the corresponding error catcher, a `catch` route, which can be declared as
follows: follows: