From 9eb77c0f8979951266523526d703ae4999ccc9c4 Mon Sep 17 00:00:00 2001 From: Rob Ede Date: Mon, 31 Jan 2022 22:01:52 +0000 Subject: [PATCH] doc tweaks --- actix-router/CHANGES.md | 6 ++-- actix-router/src/quoter.rs | 6 ++-- actix-router/src/resource.rs | 8 +++--- actix-router/src/router.rs | 54 +++++++++++++++++++----------------- src/app_service.rs | 10 +++---- src/scope.rs | 6 ++-- 6 files changed, 46 insertions(+), 44 deletions(-) diff --git a/actix-router/CHANGES.md b/actix-router/CHANGES.md index 1e6c72c14..368138603 100644 --- a/actix-router/CHANGES.md +++ b/actix-router/CHANGES.md @@ -1,11 +1,11 @@ # Changes ## Unreleased - 2021-xx-xx -- Remove the unused `ResourceInfo`. [#2612] +- Remove unused `ResourceInfo`. [#2612] - Add `RouterBuilder::push`. [#2612] - Change signature of `ResourceDef::capture_match_info_fn` to remove `user_data` parameter. [#2612] -- Replace `Option` with `U` in `Router` api. [#2612] -- Relax bounds in `Router::recognize*` and `ResourceDef::capture_match_info`. [#2612] +- Replace `Option` with `U` in `Router` API. [#2612] +- Relax bounds on `Router::recognize*` and `ResourceDef::capture_match_info`. [#2612] - `Quoter::requote` now returns `Option>`. [#2613] [#2612]: https://github.com/actix/actix-web/pull/2612 diff --git a/actix-router/src/quoter.rs b/actix-router/src/quoter.rs index 73b1e72dd..8a1e99e1d 100644 --- a/actix-router/src/quoter.rs +++ b/actix-router/src/quoter.rs @@ -64,14 +64,14 @@ impl Quoter { quoter } - /// Re-quotes... ? + /// Decodes safe percent-encoded sequences from `val`. /// /// Returns `None` when no modification to the original byte string was required. /// /// Non-ASCII bytes are accepted as valid input. /// - /// Behavior for invalid/incomplete percent-encoding sequences is unspecified and may include removing - /// the invalid sequence from the output or passing it as it is. + /// Behavior for invalid/incomplete percent-encoding sequences is unspecified and may include + /// removing the invalid sequence from the output or passing it as-is. pub fn requote(&self, val: &[u8]) -> Option> { let mut has_pct = 0; let mut pct = [b'%', 0, 0]; diff --git a/actix-router/src/resource.rs b/actix-router/src/resource.rs index 2a24f2999..d6b27f7cf 100644 --- a/actix-router/src/resource.rs +++ b/actix-router/src/resource.rs @@ -632,9 +632,9 @@ impl ResourceDef { /// assert_eq!(path.get("path").unwrap(), "HEAD/Cargo.toml"); /// assert_eq!(path.unprocessed(), ""); /// ``` - pub fn capture_match_info(&self, path: &mut R) -> bool { + pub fn capture_match_info(&self, resource: &mut R) -> bool { profile_method!(capture_match_info); - self.capture_match_info_fn(path, |_| true) + self.capture_match_info_fn(resource, |_| true) } /// Collects dynamic segment values into `resource` after matching paths and executing @@ -651,11 +651,11 @@ impl ResourceDef { /// ``` /// use actix_router::{Path, ResourceDef}; /// - /// fn try_match(resource: &ResourceDef, path: &mut Path<&str>) -> bool { + /// fn try_match(resource: &ResourceDef, resource: &mut Path<&str>) -> bool { /// let admin_allowed = std::env::var("ADMIN_ALLOWED").is_ok(); /// /// resource.capture_match_info_fn( - /// path, + /// resource, /// // when env var is not set, reject when path contains "admin" /// |res| !(!admin_allowed && res.path().contains("admin")), /// ) diff --git a/actix-router/src/router.rs b/actix-router/src/router.rs index fa9e7583b..f0e598683 100644 --- a/actix-router/src/router.rs +++ b/actix-router/src/router.rs @@ -7,22 +7,25 @@ pub struct ResourceId(pub u16); /// Resource router. /// -/// It matches a [routable resource](Resource) to an ordered list of _routes_, -/// each is defined by an single [`ResourceDef`] and containes two types of custom data: +/// It matches a [routing resource](Resource) to an ordered list of _routes_. Each is defined by a +/// single [`ResourceDef`] and contains two types of custom data: /// 1. The route _value_, of the generic type `T`. -/// 2. Some _context_ data, of the generic type `U`, which is only provided to the check function in -/// [`recognize_fn`](Self::recognize_fn). +/// 1. Some _context_ data, of the generic type `U`, which is only provided to the check function in +/// [`recognize_fn`](Self::recognize_fn). This parameter defaults to `()` and can be omitted if +/// not required. pub struct Router { - routes: Vec<(ResourceDef, (T, U))>, + routes: Vec<(ResourceDef, T, U)>, } impl Router { + /// Constructs new `RouterBuilder` with empty route list. pub fn build() -> RouterBuilder { RouterBuilder { routes: Vec::new() } } - /// Finds the value in the router that matches a given [routable resource](Resource) - /// and stores the match result, including the captured dynamic segments, into the `resource`. + /// Finds the value in the router that matches a given [routing resource](Resource). + /// + /// The match result, including the captured dynamic segments, in the `resource`. pub fn recognize(&self, resource: &mut R) -> Option<(&T, ResourceId)> where R: Resource, @@ -31,8 +34,7 @@ impl Router { self.recognize_fn(resource, |_, _| true) } - /// Similar to [`recognize`](Self::recognize), - /// but returns a mutable reference to the matching value. + /// Same as [`recognize`](Self::recognize) but returns a mutable reference to the matched value. pub fn recognize_mut(&mut self, resource: &mut R) -> Option<(&mut T, ResourceId)> where R: Resource, @@ -41,12 +43,13 @@ impl Router { self.recognize_mut_fn(resource, |_, _| true) } - /// Similar to [`recognize`](Self::recognize), - /// but executes an additional check function before accepting the route - /// as fully matched and storing the match result into `resource`. + /// Finds the value in the router that matches a given [routing resource](Resource) and passes + /// an additional predicate check using context data. /// - /// The check function is provided with a reference to the `resource` itself - /// and to the context data of the route being matched. + /// Similar to [`recognize`](Self::recognize). However, before accepting the route as matched, + /// the `check` closure is executed, passing the resource and each route's context data. If the + /// closure returns true then the match result is stored into `resource` and a reference to + /// the matched _value_ is returned. pub fn recognize_fn(&self, resource: &mut R, mut check: F) -> Option<(&T, ResourceId)> where R: Resource, @@ -54,7 +57,7 @@ impl Router { { profile_method!(recognize_checked); - for (rdef, (val, ctx)) in self.routes.iter() { + for (rdef, val, ctx) in self.routes.iter() { if rdef.capture_match_info_fn(resource, |res| check(res, ctx)) { return Some((val, ResourceId(rdef.id()))); } @@ -63,8 +66,8 @@ impl Router { None } - /// Similar to [`recognize_fn`](Self::recognize), - /// but returns a mutable reference to the matching value. + /// Same as [`recognize_fn`](Self::recognize_fn) but returns a mutable reference to the matched + /// value. pub fn recognize_mut_fn( &mut self, resource: &mut R, @@ -76,7 +79,7 @@ impl Router { { profile_method!(recognize_mut_checked); - for (rdef, (val, ctx)) in self.routes.iter_mut() { + for (rdef, val, ctx) in self.routes.iter_mut() { if rdef.capture_match_info_fn(resource, |res| check(res, ctx)) { return Some((val, ResourceId(rdef.id()))); } @@ -86,25 +89,26 @@ impl Router { } } -/// Builds the list of routes for a [resource router](Router). +/// Builder for an ordered [routing](Router) list. pub struct RouterBuilder { - routes: Vec<(ResourceDef, (T, U))>, + routes: Vec<(ResourceDef, T, U)>, } impl RouterBuilder { - /// Adds a new route at the back of the routes list. + /// Adds a new route to the end of the routing list. /// - /// Returns a mutable reference to elements of the new route. + /// Returns mutable references to elements of the new route. pub fn push( &mut self, rdef: ResourceDef, val: T, ctx: U, ) -> (&mut ResourceDef, &mut T, &mut U) { - self.routes.push((rdef, (val, ctx))); + profile_method!(push); + self.routes.push((rdef, val, ctx)); self.routes .last_mut() - .map(|(rdef, (val, ctx))| (rdef, val, ctx)) + .map(|(rdef, val, ctx)| (rdef, val, ctx)) .unwrap() } @@ -141,7 +145,7 @@ where self.push(ResourceDef::prefix(prefix), val, U::default()) } - /// Registers resource for ResourceDef. + /// Registers resource for [`ResourceDef`]. pub fn rdef(&mut self, rdef: ResourceDef, val: T) -> (&mut ResourceDef, &mut T, &mut U) { profile_method!(rdef); self.push(rdef, val, U::default()) diff --git a/src/app_service.rs b/src/app_service.rs index 7910f10a3..3ef31ac75 100644 --- a/src/app_service.rs +++ b/src/app_service.rs @@ -21,8 +21,6 @@ use crate::{ Error, HttpResponse, }; -type Guards = Vec>; - /// Service factory to convert `Request` to a `ServiceRequest`. /// /// It also executes data factories. @@ -244,7 +242,7 @@ pub struct AppRoutingFactory { [( ResourceDef, BoxedHttpServiceFactory, - RefCell>, + RefCell>>>, )], >, default: Rc, @@ -262,7 +260,7 @@ impl ServiceFactory for AppRoutingFactory { // construct all services factory future with it's resource def and guards. let factory_fut = join_all(self.services.iter().map(|(path, factory, guards)| { let path = path.clone(); - let guards = guards.borrow_mut().take(); + let guards = guards.borrow_mut().take().unwrap_or_default(); let factory_fut = factory.new_service(()); async move { let service = factory_fut.await?; @@ -295,7 +293,7 @@ impl ServiceFactory for AppRoutingFactory { /// The Actix Web router default entry point. pub struct AppRouting { - router: Router>, + router: Router>>, default: BoxedHttpService, } @@ -309,7 +307,7 @@ impl Service for AppRouting { fn call(&self, mut req: ServiceRequest) -> Self::Future { let res = self.router.recognize_fn(&mut req, |req, guards| { let guard_ctx = req.guard_ctx(); - guards.iter().flatten().all(|guard| guard.check(&guard_ctx)) + guards.iter().all(|guard| guard.check(&guard_ctx)) }); if let Some((srv, _info)) = res { diff --git a/src/scope.rs b/src/scope.rs index f8d836810..0fcc83d70 100644 --- a/src/scope.rs +++ b/src/scope.rs @@ -467,7 +467,7 @@ impl ServiceFactory for ScopeFactory { // construct all services factory future with it's resource def and guards. let factory_fut = join_all(self.services.iter().map(|(path, factory, guards)| { let path = path.clone(); - let guards = guards.borrow_mut().take(); + let guards = guards.borrow_mut().take().unwrap_or_default(); let factory_fut = factory.new_service(()); async move { let service = factory_fut.await?; @@ -496,7 +496,7 @@ impl ServiceFactory for ScopeFactory { } pub struct ScopeService { - router: Router>>>, + router: Router>>, default: BoxedHttpService, } @@ -510,7 +510,7 @@ impl Service for ScopeService { fn call(&self, mut req: ServiceRequest) -> Self::Future { let res = self.router.recognize_fn(&mut req, |req, guards| { let guard_ctx = req.guard_ctx(); - guards.iter().flatten().all(|guard| guard.check(&guard_ctx)) + guards.iter().all(|guard| guard.check(&guard_ctx)) }); if let Some((srv, _info)) = res {