actix/actix-extras
1
0
Fork 0
mirror of https://github.com/actix/actix-extras.git synced 2024-11-24 07:53:00 +01:00
Code Issues Releases Wiki Activity

minor fix guide/

Browse Source
This commit is contained in:
ami44 2017-12-30 21:13:23 +01:00
parent c998c75515
commit 73e2773a10
3 changed files with 59 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
guide/src/qs_1.md
View File

@ -1,6 +1,6 @@
# Quick start # Quick start
Before you can start writing a actix web application, you’ll need a version of Rust installed. Before you can start writing a actix web application, you’ll need a version of Rust installed.
We recommend you use rustup to install or configure such a version. We recommend you use rustup to install or configure such a version.
## Install Rust ## Install Rust
@ -31,4 +31,4 @@ cd actix-web
cargo run --example basic cargo run --example basic
``` ```
Check `examples/` directory for more examples. Check [examples/](https://github.com/actix/actix-web/tree/master/examples) directory for more examples.

12
guide/src/qs_3_5.md
View File

@ -1,8 +1,8 @@
# Server # Server
[*HttpServer*](../actix_web/struct.HttpServer.html) type is responsible for [*HttpServer*](../actix_web/struct.HttpServer.html) type is responsible for
serving http requests. *HttpServer* accept applicaiton factory as a parameter, serving http requests. *HttpServer* accept application factory as a parameter,
Application factory must have `Send` + `Sync` bounderies. More about that in Application factory must have `Send` + `Sync` bounderies. More about that in
*multi-threading* section. To bind to specific socket address `bind()` must be used. *multi-threading* section. To bind to specific socket address `bind()` must be used.
This method could be called multiple times. To start http server one of the *start* This method could be called multiple times. To start http server one of the *start*
methods could be used. `start()` method start simple server, `start_tls()` or `start_ssl()` methods could be used. `start()` method start simple server, `start_tls()` or `start_ssl()`
@ -54,7 +54,7 @@ fn main() {
.resource("/", |r| r.h(httpcodes::HTTPOk))) .resource("/", |r| r.h(httpcodes::HTTPOk)))
.bind("127.0.0.1:0").expect("Can not bind to 127.0.0.1:0") .bind("127.0.0.1:0").expect("Can not bind to 127.0.0.1:0")
.spawn(); .spawn();
let _ = addr.call_fut(dev::StopServer{graceful: true}).wait(); // <- Send `StopServer` message to server. let _ = addr.call_fut(dev::StopServer{graceful: true}).wait(); // <- Send `StopServer` message to server.
} }
``` ```
@ -116,7 +116,7 @@ Note on *HTTP/2.0* protocol over tls without prior knowledge, it requires
[tls alpn](https://tools.ietf.org/html/rfc7301). At the moment only [tls alpn](https://tools.ietf.org/html/rfc7301). At the moment only
`openssl` has `alpn ` support. `openssl` has `alpn ` support.
Please check [example](https://github.com/actix/actix-web/tree/master/examples/tls) Please check [example](https://github.com/actix/actix-web/tree/master/examples/tls)
for full example. for full example.
## Keep-Alive ## Keep-Alive
@ -172,7 +172,7 @@ have specific amount of time to finish serving requests. Workers still alive aft
timeout are force dropped. By default shutdown timeout sets to 30 seconds. timeout are force dropped. By default shutdown timeout sets to 30 seconds.
You can change this parameter with `HttpServer::shutdown_timeout()` method. You can change this parameter with `HttpServer::shutdown_timeout()` method.
You can send stop message to server with server address and specify if you what You can send stop message to server with server address and specify if you what
graceful shutdown or not. `start()` or `spawn()` methods return address of the server. graceful shutdown or not. `start()` or `spawn()` methods return address of the server.
```rust ```rust

102
guide/src/qs_5.md
View File

@ -5,35 +5,35 @@ language. *Regex* crate and it's
[*RegexSet*](https://doc.rust-lang.org/regex/regex/struct.RegexSet.html) is beeing used for [*RegexSet*](https://doc.rust-lang.org/regex/regex/struct.RegexSet.html) is beeing used for
pattern matching. If one of the patterns matches the path information associated with a request, pattern matching. If one of the patterns matches the path information associated with a request,
a particular handler object is invoked. A handler is a specific object that implements a particular handler object is invoked. A handler is a specific object that implements
`Handler` trait, defined in your application, that receives the request and returns `Handler` trait, defined in your application, that receives the request and returns
a response object. More informatin is available in [handler section](../qs_4.html). a response object. More informatin is available in [handler section](../qs_4.html).
## Resource configuration ## Resource configuration
Resource configuraiton is the act of adding a new resource to an application. Resource configuraiton is the act of adding a new resource to an application.
A resource has a name, which acts as an identifier to be used for URL generation. A resource has a name, which acts as an identifier to be used for URL generation.
The name also allows developers to add routes to existing resources. The name also allows developers to add routes to existing resources.
A resource also has a pattern, meant to match against the *PATH* portion of a *URL*, A resource also has a pattern, meant to match against the *PATH* portion of a *URL*,
it does not match against *QUERY* portion (the portion following the scheme and it does not match against *QUERY* portion (the portion following the scheme and
port, e.g., */foo/bar* in the *URL* *http://localhost:8080/foo/bar?q=value*). port, e.g., */foo/bar* in the *URL* *http://localhost:8080/foo/bar?q=value*).
The [Application::resource](../actix_web/struct.Application.html#method.resource) methods The [Application::resource](../actix_web/struct.Application.html#method.resource) methods
add a single resource to application routing table. This method accepts *path pattern* add a single resource to application routing table. This method accepts *path pattern*
and resource configuration funnction. and resource configuration funnction.
```rust ```rust
# extern crate actix_web; # extern crate actix_web;
# use actix_web::*; # use actix_web::*;
# use actix_web::httpcodes::*; # use actix_web::httpcodes::*;
# #
# fn index(req: HttpRequest) -> HttpResponse { # fn index(req: HttpRequest) -> HttpResponse {
# unimplemented!() # unimplemented!()
# } # }
# #
fn main() { fn main() {
Application::new() Application::new()
.resource("/prefix", |r| r.f(index)) .resource("/prefix", |r| r.f(index))
.resource("/user/{name}", .resource("/user/{name}",
|r| r.method(Method::GET).f(|req| HTTPOk)) |r| r.method(Method::GET).f(|req| HTTPOk))
.finish(); .finish();
} }
@ -45,7 +45,7 @@ fn main() {
FnOnce(&mut Resource<_>) -> () FnOnce(&mut Resource<_>) -> ()
``` ```
*Configration function* can set name and register specific routes. *Configration function* can set name and register specific routes.
If resource does not contain any route or does not have any matching routes it If resource does not contain any route or does not have any matching routes it
returns *NOT FOUND* http resources. returns *NOT FOUND* http resources.
@ -56,7 +56,7 @@ New route could be crearted with `Resource::route()` method which returns refere
to new *Route* instance. By default *route* does not contain any predicates, so matches to new *Route* instance. By default *route* does not contain any predicates, so matches
all requests and default handler is `HTTPNotFound`. all requests and default handler is `HTTPNotFound`.
Application routes incoming requests based on route criteria which is defined during Application routes incoming requests based on route criteria which is defined during
resource registration and route registration. Resource matches all routes it contains in resource registration and route registration. Resource matches all routes it contains in
the order that the routes were registered via `Resource::route()`. *Route* can contain the order that the routes were registered via `Resource::route()`. *Route* can contain
any number of *predicates* but only one handler. any number of *predicates* but only one handler.
@ -78,28 +78,28 @@ fn main() {
} }
``` ```
In this example `index` get called for *GET* request, In this example `index` get called for *GET* request,
if request contains `Content-Type` header and value of this header is *text/plain* if request contains `Content-Type` header and value of this header is *text/plain*
and path equals to `/test`. Resource calls handle of the first matches route. and path equals to `/test`. Resource calls handle of the first matches route.
If resource can not match any route "NOT FOUND" response get returned. If resource can not match any route "NOT FOUND" response get returned.
[*Resource::route()*](../actix_web/struct.Resource.html#method.route) method returns [*Resource::route()*](../actix_web/struct.Resource.html#method.route) method returns
[*Route*](../actix_web/struct.Route.html) object. Route can be configured with [*Route*](../actix_web/struct.Route.html) object. Route can be configured with
builder-like pattern. Following configuration methods are available: builder-like pattern. Following configuration methods are available:
* [*Route::p()*](../actix_web/struct.Route.html#method.p) method registers new predicate, * [*Route::p()*](../actix_web/struct.Route.html#method.p) method registers new predicate,
any number of predicates could be registered for each route. any number of predicates could be registered for each route.
* [*Route::f()*](../actix_web/struct.Route.html#method.f) method registers handler function * [*Route::f()*](../actix_web/struct.Route.html#method.f) method registers handler function
for this route. Only one handler could be registered. Usually handler registeration for this route. Only one handler could be registered. Usually handler registeration
is the last config operation. Handler fanction could be function or closure and has type is the last config operation. Handler fanction could be function or closure and has type
`Fn(HttpRequest<S>) -> R + 'static` `Fn(HttpRequest<S>) -> R + 'static`
* [*Route::h()*](../actix_web/struct.Route.html#method.h) method registers handler object * [*Route::h()*](../actix_web/struct.Route.html#method.h) method registers handler object
that implements `Handler` trait. This is similar to `f()` method, only one handler could that implements `Handler` trait. This is similar to `f()` method, only one handler could
be registered. Handler registeration is the last config operation. be registered. Handler registeration is the last config operation.
* [*Route::a()*](../actix_web/struct.Route.html#method.a) method registers asynchandler * [*Route::a()*](../actix_web/struct.Route.html#method.a) method registers asynchandler
function for this route. Only one handler could be registered. Handler registeration function for this route. Only one handler could be registered. Handler registeration
is the last config operation. Handler fanction could be function or closure and has type is the last config operation. Handler fanction could be function or closure and has type
`Fn(HttpRequest<S>) -> Future<Item = HttpResponse, Error = Error> + 'static` `Fn(HttpRequest<S>) -> Future<Item = HttpResponse, Error = Error> + 'static`
@ -110,30 +110,30 @@ The main purpose of route configuration is to match (or not match) the request's
against a URL path pattern. `path` represents the path portion of the URL that was requested. against a URL path pattern. `path` represents the path portion of the URL that was requested.
The way that *actix* does this is very simple. When a request enters the system, The way that *actix* does this is very simple. When a request enters the system,
for each resource configuration registration present in the system, actix checks for each resource configuration registration present in the system, actix checks
the request's path against the pattern declared. *Regex* crate and it's the request's path against the pattern declared. *Regex* crate and it's
[*RegexSet*](https://doc.rust-lang.org/regex/regex/struct.RegexSet.html) is beeing used for [*RegexSet*](https://doc.rust-lang.org/regex/regex/struct.RegexSet.html) is beeing used for
pattern matching. If resource could not be found, *default resource* get used as matched pattern matching. If resource could not be found, *default resource* get used as matched
resource. resource.
When a route configuration is declared, it may contain route predicate arguments. All route When a route configuration is declared, it may contain route predicate arguments. All route
predicates associated with a route declaration must be `true` for the route configuration to predicates associated with a route declaration must be `true` for the route configuration to
be used for a given request during a check. If any predicate in the set of route predicate be used for a given request during a check. If any predicate in the set of route predicate
arguments provided to a route configuration returns `false` during a check, that route is arguments provided to a route configuration returns `false` during a check, that route is
skipped and route matching continues through the ordered set of routes. skipped and route matching continues through the ordered set of routes.
If any route matches, the route matching process stops and the handler associated with If any route matches, the route matching process stops and the handler associated with
route get invoked. route get invoked.
If no route matches after all route patterns are exhausted, *NOT FOUND* response get returned. If no route matches after all route patterns are exhausted, *NOT FOUND* response get returned.
## Resource pattern syntax ## Resource pattern syntax
The syntax of the pattern matching language used by the actix in the pattern The syntax of the pattern matching language used by the actix in the pattern
argument is straightforward. argument is straightforward.
The pattern used in route configuration may start with a slash character. If the pattern The pattern used in route configuration may start with a slash character. If the pattern
does not start with a slash character, an implicit slash will be prepended does not start with a slash character, an implicit slash will be prepended
to it at matching time. For example, the following patterns are equivalent: to it at matching time. For example, the following patterns are equivalent:
``` ```
@ -146,13 +146,13 @@ and:
/{foo}/bar/baz /{foo}/bar/baz
``` ```
A *variable part* (replacement marker) is specified in the form *{identifier}*, A *variable part* (replacement marker) is specified in the form *{identifier}*,
where this means "accept any characters up to the next slash character and use this where this means "accept any characters up to the next slash character and use this
as the name in the `HttpRequest.match_info()` object". as the name in the `HttpRequest.match_info()` object".
A replacement marker in a pattern matches the regular expression `[^{}/]+`. A replacement marker in a pattern matches the regular expression `[^{}/]+`.
A match_info is the `Params` object representing the dynamic parts extracted from a A match_info is the `Params` object representing the dynamic parts extracted from a
*URL* based on the routing pattern. It is available as *request.match_info*. For example, the *URL* based on the routing pattern. It is available as *request.match_info*. For example, the
following pattern defines one literal segment (foo) and two replacement markers (baz, and bar): following pattern defines one literal segment (foo) and two replacement markers (baz, and bar):
@ -174,8 +174,8 @@ foo/1/2/ -> No match (trailing slash)
bar/abc/def -> First segment literal mismatch bar/abc/def -> First segment literal mismatch
``` ```
The match for a segment replacement marker in a segment will be done only up to The match for a segment replacement marker in a segment will be done only up to
the first non-alphanumeric character in the segment in the pattern. So, for instance, the first non-alphanumeric character in the segment in the pattern. So, for instance,
if this route pattern was used: if this route pattern was used:
``` ```
@ -183,8 +183,8 @@ foo/{name}.html
``` ```
The literal path */foo/biz.html* will match the above route pattern, and the match result The literal path */foo/biz.html* will match the above route pattern, and the match result
will be `Params{'name': 'biz'}`. However, the literal path */foo/biz* will not match, will be `Params{'name': 'biz'}`. However, the literal path */foo/biz* will not match,
because it does not contain a literal *.html* at the end of the segment represented because it does not contain a literal *.html* at the end of the segment represented
by *{name}.html* (it only contains biz, not biz.html). by *{name}.html* (it only contains biz, not biz.html).
To capture both segments, two replacement markers can be used: To capture both segments, two replacement markers can be used:
@ -193,21 +193,21 @@ To capture both segments, two replacement markers can be used:
foo/{name}.{ext} foo/{name}.{ext}
``` ```
The literal path */foo/biz.html* will match the above route pattern, and the match The literal path */foo/biz.html* will match the above route pattern, and the match
result will be *Params{'name': 'biz', 'ext': 'html'}*. This occurs because there is a result will be *Params{'name': 'biz', 'ext': 'html'}*. This occurs because there is a
literal part of *.* (period) between the two replacement markers *{name}* and *{ext}*. literal part of *.* (period) between the two replacement markers *{name}* and *{ext}*.
Replacement markers can optionally specify a regular expression which will be used to decide Replacement markers can optionally specify a regular expression which will be used to decide
whether a path segment should match the marker. To specify that a replacement marker should whether a path segment should match the marker. To specify that a replacement marker should
match only a specific set of characters as defined by a regular expression, you must use a match only a specific set of characters as defined by a regular expression, you must use a
slightly extended form of replacement marker syntax. Within braces, the replacement marker slightly extended form of replacement marker syntax. Within braces, the replacement marker
name must be followed by a colon, then directly thereafter, the regular expression. The default name must be followed by a colon, then directly thereafter, the regular expression. The default
regular expression associated with a replacement marker *[^/]+* matches one or more characters regular expression associated with a replacement marker *[^/]+* matches one or more characters
which are not a slash. For example, under the hood, the replacement marker *{foo}* can more which are not a slash. For example, under the hood, the replacement marker *{foo}* can more
verbosely be spelled as *{foo:[^/]+}*. You can change this to be an arbitrary regular expression verbosely be spelled as *{foo:[^/]+}*. You can change this to be an arbitrary regular expression
to match an arbitrary sequence of characters, such as *{foo:\d+}* to match only digits. to match an arbitrary sequence of characters, such as *{foo:\d+}* to match only digits.
Segments must contain at least one character in order to match a segment replacement marker. Segments must contain at least one character in order to match a segment replacement marker.
For example, for the URL */abc/*: For example, for the URL */abc/*:
* */abc/{foo}* will not match. * */abc/{foo}* will not match.
@ -233,7 +233,7 @@ The matchdict will look like so (the value is URL-decoded):
Params{'bar': 'La Pe\xf1a'} Params{'bar': 'La Pe\xf1a'}
``` ```
Literal strings in the path segment should represent the decoded value of the Literal strings in the path segment should represent the decoded value of the
path provided to actix. You don't want to use a URL-encoded value in the pattern. path provided to actix. You don't want to use a URL-encoded value in the pattern.
For example, rather than this: For example, rather than this:
@ -262,12 +262,12 @@ foo/abc/def/a/b/c -> Params{'bar':u'abc', 'tail': 'def/a/b/c'}
## Match information ## Match information
All values representing matched path segments are available in All values representing matched path segments are available in
[`HttpRequest::match_info`](../actix_web/struct.HttpRequest.html#method.match_info). [`HttpRequest::match_info`](../actix_web/struct.HttpRequest.html#method.match_info).
Specific value can be received with Specific value can be received with
[`Params::get()`](../actix_web/dev/struct.Params.html#method.get) method. [`Params::get()`](../actix_web/dev/struct.Params.html#method.get) method.
Any matched parameter can be deserialized into specific type if this type Any matched parameter can be deserialized into specific type if this type
implements `FromParam` trait. For example most of standard integer types implements `FromParam` trait. For example most of standard integer types
implements `FromParam` trait. i.e.: implements `FromParam` trait. i.e.:
@ -323,20 +323,20 @@ fn main() {
} }
``` ```
List of `FromParam` implementation could be found in List of `FromParam` implementation could be found in
[api docs](../actix_web/dev/trait.FromParam.html#foreign-impls) [api docs](../actix_web/dev/trait.FromParam.html#foreign-impls)
## Generating resource URLs ## Generating resource URLs
Use the [HttpRequest.url_for()](../actix_web/struct.HttpRequest.html#method.url_for) Use the [HttpRequest.url_for()](../actix_web/struct.HttpRequest.html#method.url_for)
method to generate URLs based on resource patterns. For example, if you've configured a method to generate URLs based on resource patterns. For example, if you've configured a
resource with the name "foo" and the pattern "{a}/{b}/{c}", you might do this. resource with the name "foo" and the pattern "{a}/{b}/{c}", you might do this.
```rust ```rust
# extern crate actix_web; # extern crate actix_web;
# use actix_web::*; # use actix_web::*;
# use actix_web::httpcodes::*; # use actix_web::httpcodes::*;
# #
fn index(req: HttpRequest) -> HttpResponse { fn index(req: HttpRequest) -> HttpResponse {
let url = req.url_for("foo", &["1", "2", "3"]); // <- generate url for "foo" resource let url = req.url_for("foo", &["1", "2", "3"]); // <- generate url for "foo" resource
HTTPOk.into() HTTPOk.into()
@ -354,7 +354,7 @@ fn main() {
This would return something like the string *http://example.com/test/1/2/3* (at least if This would return something like the string *http://example.com/test/1/2/3* (at least if
the current protocol and hostname implied http://example.com). the current protocol and hostname implied http://example.com).
`url_for()` method return [*Url object*](https://docs.rs/url/1.6.0/url/struct.Url.html) so you `url_for()` method return [*Url object*](https://docs.rs/url/1.6.0/url/struct.Url.html) so you
can modify this url (add query parameters, anchor, etc). can modify this url (add query parameters, anchor, etc).
`url_for()` could be called only for *named* resources otherwise error get returned. `url_for()` could be called only for *named* resources otherwise error get returned.
@ -421,7 +421,7 @@ In this example `/resource`, `//resource///` will be redirected to `/resource/`
In this example path normalization handler get registered for all method, In this example path normalization handler get registered for all method,
but you should not rely on this mechanism to redirect *POST* requests. The redirect of the but you should not rely on this mechanism to redirect *POST* requests. The redirect of the
slash-appending *Not Found* will turn a *POST* request into a GET, losing any slash-appending *Not Found* will turn a *POST* request into a GET, losing any
*POST* data in the original request. *POST* data in the original request.
It is possible to register path normalization only for *GET* requests only It is possible to register path normalization only for *GET* requests only
@ -444,18 +444,18 @@ fn main() {
## Using a Application Prefix to Compose Applications ## Using a Application Prefix to Compose Applications
The `Applicaiton::prefix()`" method allows to set specific application prefix. The `Application::prefix()`" method allows to set specific application prefix.
This prefix represents a resource prefix that will be prepended to all resource patterns added This prefix represents a resource prefix that will be prepended to all resource patterns added
by the resource configuration. This can be used to help mount a set of routes at a different by the resource configuration. This can be used to help mount a set of routes at a different
location than the included callable's author intended while still maintaining the same location than the included callable's author intended while still maintaining the same
resource names. resource names.
For example: For example:
```rust ```rust
# extern crate actix_web; # extern crate actix_web;
# use actix_web::*; # use actix_web::*;
# #
fn show_users(req: HttpRequest) -> HttpResponse { fn show_users(req: HttpRequest) -> HttpResponse {
unimplemented!() unimplemented!()
} }
@ -468,18 +468,18 @@ fn main() {
} }
``` ```
In the above example, the *show_users* route will have an effective route pattern of In the above example, the *show_users* route will have an effective route pattern of
*/users/show* instead of */show* because the application's prefix argument will be prepended */users/show* instead of */show* because the application's prefix argument will be prepended
to the pattern. The route will then only match if the URL path is */users/show*, to the pattern. The route will then only match if the URL path is */users/show*,
and when the `HttpRequest.url_for()` function is called with the route name show_users, and when the `HttpRequest.url_for()` function is called with the route name show_users,
it will generate a URL with that same path. it will generate a URL with that same path.
## Custom route predicates ## Custom route predicates
You can think of predicate as simple function that accept *request* object reference You can think of predicate as simple function that accept *request* object reference
and returns *true* or *false*. Formally predicate is any object that implements and returns *true* or *false*. Formally predicate is any object that implements
[`Predicate`](../actix_web/pred/trait.Predicate.html) trait. Actix provides [`Predicate`](../actix_web/pred/trait.Predicate.html) trait. Actix provides
several predicates, you can check [functions section](../actix_web/pred/index.html#functions) several predicates, you can check [functions section](../actix_web/pred/index.html#functions)
of api docs. of api docs.
Here is simple predicates that check that request contains specific *header*: Here is simple predicates that check that request contains specific *header*: