From 4102b9e1c557cc33ac2d1a325b002c9c68e310c7 Mon Sep 17 00:00:00 2001 From: Nikolay Kim Date: Sat, 7 Oct 2017 23:59:57 -0700 Subject: [PATCH] update docs --- src/httpmessage.rs | 7 +++++- src/lib.rs | 2 +- src/resource.rs | 20 +++++++++++++++- src/route.rs | 10 +++++++- src/router.rs | 57 ++++++++++++++++++++++++++++++++++++++++++---- src/ws.rs | 3 ++- 6 files changed, 89 insertions(+), 10 deletions(-) diff --git a/src/httpmessage.rs b/src/httpmessage.rs index 6826af8c3..1843c911d 100644 --- a/src/httpmessage.rs +++ b/src/httpmessage.rs @@ -146,9 +146,14 @@ impl HttpRequest { &mut self.headers } + /// Get a reference to the Params object. + /// Params is a container for url parameters. + /// Route supports glob patterns: * for a single wildcard segment and :param + /// for matching storing that segment of the request url in the Params object. #[inline] pub fn params(&self) -> &Params { &self.params } + /// Create new request with Params object. pub fn with_params(self, params: Params) -> Self { HttpRequest { method: self.method, @@ -159,7 +164,7 @@ impl HttpRequest { } } - pub fn is_upgrade(&self) -> bool { + pub(crate) fn is_upgrade(&self) -> bool { if let Some(&Connection(ref conn)) = self.headers().get() { conn.contains(&ConnectionOption::from_str("upgrade").unwrap()) } else { diff --git a/src/lib.rs b/src/lib.rs index b4111ae2d..d8c42835f 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -43,5 +43,5 @@ pub use resource::{HttpMessage, HttpResource}; pub use server::HttpServer; pub use context::HttpContext; pub use router::RoutingMap; -pub use route_recognizer::Params; pub use httpmessage::{HttpRequest, HttpResponse, IntoHttpResponse}; +pub use route_recognizer::Params; diff --git a/src/resource.rs b/src/resource.rs index d49fbdc00..eb8a6d327 100644 --- a/src/resource.rs +++ b/src/resource.rs @@ -11,7 +11,24 @@ use context::HttpContext; use httpcodes::HTTPMethodNotAllowed; use httpmessage::{HttpRequest, HttpResponse, IntoHttpResponse}; -/// Resource +/// Http resource +/// +/// `HttpResource` is an entry in route table which corresponds to requested URL. +/// +/// Resource in turn has at least one route. +/// Route corresponds to handling HTTP method by calling route handler. +/// +/// ```rust,ignore +/// +/// struct MyRoute; +/// +/// fn main() { +/// let mut routes = RoutingMap::default(); +/// +/// routes +/// .add_resource("/") +/// .post::(); +/// } pub struct HttpResource { state: PhantomData, routes: HashMap>>, @@ -91,6 +108,7 @@ enum HttpMessageItem where A: Actor> + Route { Actor(A), } +/// Represents response process. pub struct HttpMessage> + Route> (HttpMessageItem); impl HttpMessage where A: Actor> + Route diff --git a/src/route.rs b/src/route.rs index cbbbaae28..c0aa0ac29 100644 --- a/src/route.rs +++ b/src/route.rs @@ -45,24 +45,32 @@ pub enum Frame { Payload(Option), } +/// Trait defines object that could be regestered as resource route. pub trait RouteHandler: 'static { fn handle(&self, req: HttpRequest, payload: Option, state: Rc) -> Task; } /// Actors with ability to handle http requests pub trait Route: Actor> { + /// Route shared state. State is shared with all routes within same application and could be + /// accessed with `HttpContext::state()` method. type State; + /// Handle incoming request. Route actor can return + /// result immediately with `HttpMessage::reply` or `HttpMessage::error`. + /// Actor itself could be returned for handling streaming request/response. + /// In that case `HttpContext::start` and `HttpContext::write` hs to be used. fn request(req: HttpRequest, payload: Option, ctx: &mut HttpContext) -> HttpMessage; + /// This method creates `RouteFactory` for this actor. fn factory() -> RouteFactory { RouteFactory(PhantomData) } } - +/// This is used for routes registration within `HttpResource`. pub struct RouteFactory, S>(PhantomData); impl RouteHandler for RouteFactory diff --git a/src/router.rs b/src/router.rs index 91c34ecfe..d1d519b42 100644 --- a/src/router.rs +++ b/src/router.rs @@ -14,6 +14,20 @@ pub trait HttpHandler: 'static { fn handle(&self, req: HttpRequest, payload: Option) -> Task; } +/// Request routing map +/// +/// Route supports glob patterns: * for a single wildcard segment and :param +/// for matching storing that segment of the request url in the Params object, +/// which is stored in the request. +/// +/// For instance, to route Get requests on any route matching /users/:userid/:friend and +/// store userid and friend in the exposed Params object: +/// +/// ```rust,ignore +/// let mut router = RoutingMap::default(); +/// +/// router.add_resource("/users/:userid/:friendid").get::(); +/// ``` pub struct RoutingMap { apps: HashMap>, resources: HashMap, @@ -30,20 +44,53 @@ impl Default for RoutingMap { impl RoutingMap { - pub fn add(&mut self, path: P, app: HttpApplication) + /// Add `HttpApplication` object with specific prefix. + /// Application prefixes all registered resources with specified prefix. + /// + /// ```rust,ignore + /// + /// struct MyRoute; + /// + /// fn main() { + /// let mut app = HttpApplication::no_state(); + /// app.add("/test") + /// .get::() + /// .post::(); + /// + /// let mut routes = RoutingMap::default(); + /// routes.add("/pre", app); + /// } + /// ``` + /// In this example, `MyRoute` route is available as `http://.../pre/test` url. + pub fn add(&mut self, prefix: P, app: HttpApplication) where P: ToString { - let path = path.to_string(); + let prefix = prefix.to_string(); // we can not override registered resource - if self.apps.contains_key(&path) { - panic!("Resource is registered: {}", path); + if self.apps.contains_key(&prefix) { + panic!("Resource is registered: {}", prefix); } // add application - self.apps.insert(path.clone(), app.prepare(path)); + self.apps.insert(prefix.clone(), app.prepare(prefix)); } + /// This method creates `HttpResource` for specified path + /// or returns mutable reference to resource object. + /// + /// ```rust,ignore + /// + /// struct MyRoute; + /// + /// fn main() { + /// let mut routes = RoutingMap::default(); + /// + /// routes.add_resource("/test") + /// .post::(); + /// } + /// ``` + /// In this example, `MyRoute` route is available as `http://.../test` url. pub fn add_resource

(&mut self, path: P) -> &mut HttpResource where P: ToString { diff --git a/src/ws.rs b/src/ws.rs index 6b27e754b..85a04a493 100644 --- a/src/ws.rs +++ b/src/ws.rs @@ -103,6 +103,7 @@ header! { } +/// `WebSocket` Message #[derive(Debug)] pub enum Message { Text(String), @@ -116,7 +117,7 @@ pub enum Message { /// Prepare `WebSocket` handshake response. /// -/// This function returns handshake HttpResponse, ready to send to peer. +/// This function returns handshake `HttpResponse`, ready to send to peer. /// It does not perform any IO. /// // /// `protocols` is a sequence of known protocols. On successful handshake,