From 0dae1091723cc4193b47e9af41a4284545510b39 Mon Sep 17 00:00:00 2001
From: Nikolay Kim <fafhrd91@gmail.com>
Date: Fri, 1 Dec 2017 23:42:21 -0800
Subject: [PATCH] missing files

---
 guide/src/qs_4.md | 143 ++++++++++++++++++++++++++++++++++++++++++++++
 guide/src/qs_5.md | 107 ++++++++++++++++++++++++++++++++++
 guide/src/qs_6.md |  36 ++++++++++++
 3 files changed, 286 insertions(+)
 create mode 100644 guide/src/qs_4.md
 create mode 100644 guide/src/qs_5.md
 create mode 100644 guide/src/qs_6.md

diff --git a/guide/src/qs_4.md b/guide/src/qs_4.md
new file mode 100644
index 000000000..969d01b8f
--- /dev/null
+++ b/guide/src/qs_4.md
@@ -0,0 +1,143 @@
+# Handler
+
+A request handler can by any object that implements
+[`Handler` trait](../actix_web/struct.HttpResponse.html#implementations).
+
+By default actix provdes several `Handler` implementations:
+
+* Simple function that accepts `HttpRequest` and returns any object that 
+  can be converted to `HttpResponse`
+* Function that accepts `HttpRequest` and returns `Result<Reply, Into<Error>>` object.
+* Function that accepts `HttpRequest` and return actor that has `HttpContext<A>`as a context. 
+
+Actix provides response conversion into `HttpResponse` for some standard types, 
+like `&'static str`, `String`, etc.
+For complete list of implementations check 
+[HttpResponse documentation](../actix_web/struct.HttpResponse.html#implementations).
+
+Examples:
+
+```rust,ignore
+fn index(req: HttpRequest) -> &'static str {
+    "Hello world!"
+}
+```
+
+```rust,ignore
+fn index(req: HttpRequest) -> String {
+    "Hello world!".to_owned()
+}
+```
+
+```rust,ignore
+fn index(req: HttpRequest) -> Bytes {
+    Bytes::from_static("Hello world!")
+}
+```
+
+```rust,ignore
+fn index(req: HttpRequest) -> Box<Future<Item=HttpResponse, Error=Error>> {
+    ...
+}
+```
+
+## Custom conversion
+
+Let's create response for custom type that serializes to `application/json` response:
+
+```rust
+extern crate actix;
+extern crate actix_web;
+extern crate serde;
+extern crate serde_json;
+#[macro_use] extern crate serde_derive;
+use actix_web::*;
+
+#[derive(Serialize)]
+struct MyObj {
+    name: String,
+}
+
+/// we have to convert Error into HttpResponse as well, but with 
+/// specialization this could be handled genericly.
+impl Into<HttpResponse> for MyObj {
+    fn into(self) -> HttpResponse {
+        let body = match serde_json::to_string(&self) {
+            Err(err) => return Error::from(err).into(),
+            Ok(body) => body,
+        };
+
+        // Create response and set content type
+        HttpResponse::Ok()
+            .content_type("application/json")
+            .body(body).unwrap()
+    }
+}
+
+fn main() {
+    let sys = actix::System::new("example");
+
+    HttpServer::new(
+        Application::default("/")
+            .resource("/", |r| r.handler(
+                Method::GET, |req| {MyObj{name: "user".to_owned()}})))
+        .serve::<_, ()>("127.0.0.1:8088").unwrap();
+
+    println!("Started http server: 127.0.0.1:8088");
+    actix::Arbiter::system().send(actix::msgs::SystemExit(0)); // <- remove this line, this code stops system during testing
+
+    let _ = sys.run();
+}
+```
+
+If `specialization` is enabled, conversion could be simplier:
+
+```rust,ignore
+impl Into<Result<HttpResponse>> for MyObj {
+    fn into(self) -> Result<HttpResponse> {
+        let body = serde_json::to_string(&self)?;
+
+        Ok(HttpResponse::Ok()
+            .content_type("application/json")
+            .body(body)?)
+    }
+}
+```
+
+## Async handlers
+
+There are two different types of async handlers. 
+
+Response object could be generated asynchronously. In this case handle must
+return `Future` object that resolves to `HttpResponse`, i.e:
+
+```rust,ignore
+fn index(req: HttpRequest) -> Box<Future<HttpResponse, Error>> {
+   ...
+}
+```
+
+This handler can be registered with `ApplicationBuilder::async()` and 
+`Resource::async()` methods.
+
+Or response body can be generated asynchronously. In this case body
+must implement stream trait `Stream<Item=Bytes, Error=Error>`, i.e:
+
+
+```rust,ignore
+fn index(req: HttpRequest) -> HttpResponse {
+    let body: Box<Stream<Item=Bytes, Error=Error>> = Box::new(SomeStream::new());
+
+    HttpResponse::Ok().
+       .content_type("application/json")
+       .body(Body::Streaming(body)).unwrap()
+}
+
+fn main() {
+    Application::default("/")
+        .async("/async", index)
+        .finish();
+}
+```
+
+Both methods could be combined. (i.e Async response with streaming body)
diff --git a/guide/src/qs_5.md b/guide/src/qs_5.md
new file mode 100644
index 000000000..157b55c57
--- /dev/null
+++ b/guide/src/qs_5.md
@@ -0,0 +1,107 @@
+# Resources and Routes
+
+All resources and routes register for specific application.
+Application routes incoming requests based on route criteria which is defined during 
+resource registration or path prefix for simple handlers.
+Internally *router* is a list of *resources*. Resource is an entry in *route table*
+which corresponds to requested URL. 
+
+Prefix handler:
+
+```rust,ignore
+fn index(req: Httprequest) -> HttpResponse {
+   ...
+}
+
+fn main() {
+    Application::default("/")
+        .handler("/prefix", |req| index)
+        .finish();
+}
+```
+
+In this example `index` get called for any url which starts with `/prefix`. 
+
+Application prefix combines with handler prefix i.e
+
+```rust,ignore
+fn main() {
+    Application::default("/app")
+        .handler("/prefix", |req| index)
+        .finish();
+}
+```
+
+In this example `index` get called for any url which starts with`/app/prefix`. 
+
+Resource contains set of route for same endpoint. Route corresponds to handling 
+*HTTP method* by calling *web handler*. Resource select route based on *http method*,
+if no route could be matched default response `HTTPMethodNotAllowed` get resturned.
+
+```rust,ignore
+fn main() {
+    Application::default("/")
+        .resource("/prefix", |r| {
+           r.get(HTTPOk)
+           r.post(HTTPForbidden)
+        })
+        .finish();
+}
+```
+
+[`ApplicationBuilder::resource()` method](../actix_web/dev/struct.ApplicationBuilder.html#method.resource)
+accepts configuration function, resource could be configured at once.
+Check [`Resource`](../actix-web/target/doc/actix_web/struct.Resource.html) documentation 
+for more information.
+
+## Variable resources
+
+Resource may have *variable path*also. For instance, a resource with the 
+path '/a/{name}/c' would match all incoming requests with paths such
+as '/a/b/c', '/a/1/c', and '/a/etc/c'.
+
+A *variable part*is specified in the form {identifier}, where the identifier can be
+used later in a request handler to access the matched value for that part. This is
+done by looking up the identifier in the `HttpRequest.match_info` object:
+
+
+```rust
+extern crate actix;
+use actix_web::*;
+
+fn index(req: Httprequest) -> String {
+    format!("Hello, {}", req.match_info.get('name').unwrap())
+}
+
+fn main() {
+    Application::default("/")
+        .resource("/{name}", |r| r.get(index))
+        .finish();
+}
+```
+
+By default, each part matches the regular expression `[^{}/]+`.
+
+You can also specify a custom regex in the form `{identifier:regex}`:
+
+```rust,ignore
+fn main() {
+    Application::default("/")
+        .resource(r"{name:\d+}", |r| r.get(index))
+        .finish();
+}
+```
+
+To match path tail, `{tail:*}` pattern could be used. Tail pattern has to be last
+segment in path otherwise it panics.
+
+```rust,ignore
+fn main() {
+    Application::default("/")
+        .resource(r"/test/{tail:*}", |r| r.get(index))
+        .finish();
+}
+```
+
+Above example would match all incoming requests with path such as
+'/test/b/c', '/test/index.html', and '/test/etc/test'.
diff --git a/guide/src/qs_6.md b/guide/src/qs_6.md
new file mode 100644
index 000000000..8060e455a
--- /dev/null
+++ b/guide/src/qs_6.md
@@ -0,0 +1,36 @@
+# Application state
+
+Application state is shared with all routes within same application.
+State could be accessed with `HttpRequest::state()` method. It is read-only
+but interior mutability pattern with `RefCell` could be used to archive state mutability.
+State could be accessed with `HttpRequest::state()` method or 
+`HttpContext::state()` in case of http actor.
+
+Let's write simple application that uses shared state. We are going to store requests count
+in the state: 
+ 
+```rust
+extern crate actix;
+extern crate actix_web;
+
+use std::cell::Cell;
+use actix_web::*;
+
+// This struct represents state
+struct AppState {
+    counter: Cell<usize>,
+}
+
+fn index(req: HttpRequest<AppState>) -> String {
+    let count = req.state().counter.get() + 1; // <- get count
+    req.state().counter.set(count);            // <- store new count in state
+
+    format!("Request number: {}", count)      // <- response with count
+}
+
+fn main() {
+    Application::build("/", AppState{counter: Cell::new(0)})
+        .resource("/", |r| r.handler(Method::GET, index))
+        .finish();
+}
+```