Struct ntex::web::Scope

pub struct Scope<Err: ErrorRenderer, T = ScopeEndpoint<Err>> { /* fields omitted */ }

Resources scope.

Scope is a set of resources with common root path. Scopes collect multiple paths under a common path prefix. Scope path can contain variable path segments as resources. Scope prefix is always complete path segment, i.e /app would be converted to a /app/ and it would not match /app path.

You can get variable path segments from HttpRequest::match_info(). Path extractor also is able to extract scope level variable segments.

use ntex::web::{self, App, HttpResponse};

fn main() {
    let app = App::new().service(
        web::scope("/{project_id}/")
            .service(web::resource("/path1").to(|| async { HttpResponse::Ok() }))
            .service(web::resource("/path2").route(web::get().to(|| async { HttpResponse::Ok() })))
            .service(web::resource("/path3").route(web::head().to(|| async { HttpResponse::MethodNotAllowed() })))
    );
}

In the above example three routes get registered:

• /{project_id}/path1 - reponds to all http method
• /{project_id}/path2 - GET requests
• /{project_id}/path3 - HEAD requests

Implementations

impl<Err: ErrorRenderer> Scope<Err>

pub fn new<T: IntoPattern>(path: T) -> Scope<Err>

Create a new scope

impl<Err, T> Scope<Err, T> where
    T: ServiceFactory<Config = (), Request = WebRequest<Err>, Response = WebResponse, Error = Err::Container, InitError = ()>,
    Err: ErrorRenderer, 

pub fn guard<G: Guard + 'static>(self, guard: G) -> Self

Add match guard to a scope.

use ntex::web::{self, guard, App, HttpRequest, HttpResponse};

async fn index(data: web::types::Path<(String, String)>) -> &'static str {
    "Welcome!"
}

fn main() {
    let app = App::new().service(
        web::scope("/app")
            .guard(guard::Header("content-type", "text/plain"))
            .route("/test1", web::get().to(index))
            .route("/test2", web::post().to(|r: HttpRequest| async {
                HttpResponse::MethodNotAllowed()
            }))
    );
}

pub fn data<U: 'static>(self, data: U) -> Self

Set or override application data. Application data could be accessed by using Data<T> extractor where T is data type.

use std::cell::Cell;
use ntex::web::{self, App, HttpResponse};

struct MyData {
    counter: Cell<usize>,
}

async fn index(data: web::types::Data<MyData>) -> HttpResponse {
    data.counter.set(data.counter.get() + 1);
    HttpResponse::Ok().into()
}

fn main() {
    let app = App::new().service(
        web::scope("/app")
            .data(MyData{ counter: Cell::new(0) })
            .service(
                web::resource("/index.html").route(
                    web::get().to(index)))
    );
}

pub fn app_data<U: 'static>(self, data: U) -> Self

Set or override application data.

This method overrides data stored with App::app_data()

pub fn case_insensitive_routing(self) -> Self

Use ascii case-insensitive routing.

Only static segments could be case-insensitive.

pub fn configure<F>(self, f: F) -> Self where
    F: FnOnce(&mut ServiceConfig<Err>), 

Run external configuration as part of the scope building process

This function is useful for moving parts of configuration to a different module or even library. For example, some of the resource’s configuration could be moved to different module.

use ntex::web::{self, middleware, App, HttpResponse};

// this function could be located in different module
fn config(cfg: &mut web::ServiceConfig) {
    cfg.service(web::resource("/test")
        .route(web::get().to(|| async { HttpResponse::Ok() }))
        .route(web::head().to(|| async { HttpResponse::MethodNotAllowed() }))
    );
}

fn main() {
    let app = App::new()
        .wrap(middleware::Logger::default())
        .service(
            web::scope("/api")
                .configure(config)
        )
        .route("/index.html", web::get().to(|| async { HttpResponse::Ok() }));
}

pub fn service<F>(self, factory: F) -> Self where
    F: WebServiceFactory<Err> + 'static, 

Register http service.

This is similar to App's service registration.

ntex web provides several services implementations:

• Resource is an entry in resource table which corresponds to requested URL.
• Scope is a set of resources with common root path.
• “StaticFiles” is a service for static files support

use ntex::web::{self, App, HttpRequest};

struct AppState;

async fn index(req: HttpRequest) -> &'static str {
    "Welcome!"
}

fn main() {
    let app = App::new().service(
        web::scope("/app").service(
            web::scope("/v1")
                .service(web::resource("/test1").to(index)))
    );
}

pub fn route(self, path: &str, route: Route<Err>) -> Self

Configure route for a specific path.

This is a simplified version of the Scope::service() method. This method can be called multiple times, in that case multiple resources with one route would be registered for same resource path.

use ntex::web::{self, App, HttpResponse};

async fn index(data: web::types::Path<(String, String)>) -> &'static str {
    "Welcome!"
}

fn main() {
    let app = App::new().service(
        web::scope("/app")
            .route("/test1", web::get().to(index))
            .route("/test2", web::post().to(|| async { HttpResponse::MethodNotAllowed() }))
    );
}

pub fn default_service<F, U>(self, f: F) -> Self where
    F: IntoServiceFactory<U>,
    U: ServiceFactory<Config = (), Request = WebRequest<Err>, Response = WebResponse, Error = Err::Container> + 'static,
    U::InitError: Debug, 

Default service to be used if no matching route could be found.

If default resource is not registered, app’s default resource is being used.

pub fn filter<F>(
    self,
    filter: F
) -> Scope<Err, impl ServiceFactory<Config = (), Request = WebRequest<Err>, Response = WebResponse, Error = Err::Container, InitError = ()>> where
    F: ServiceFactory<Config = (), Request = WebRequest<Err>, Response = Either<WebRequest<Err>, WebResponse>, Error = Err::Container, InitError = ()>, 

Register request filter.

Filter runs during inbound processing in the request lifecycle (request -> response), modifying request as necessary, across all requests managed by the Scope.

This is similar to App's filters, but filter get invoked on scope level.

pub fn wrap<M>(
    self,
    mw: M
) -> Scope<Err, impl ServiceFactory<Config = (), Request = WebRequest<Err>, Response = WebResponse, Error = Err::Container, InitError = ()>> where
    M: Transform<T::Service, Request = WebRequest<Err>, Response = WebResponse, Error = Err::Container, InitError = ()>, 

Registers middleware, in the form of a middleware component (type).

That runs during inbound processing in the request lifecycle (request -> response), modifying request as necessary, across all requests managed by the Scope. Scope-level middleware is more limited in what it can modify, relative to Route or Application level middleware, in that Scope-level middleware can not modify WebResponse.

Use middleware when you need to read or modify every request in some way.

pub fn wrap_fn<F, R>(
    self,
    mw: F
) -> Scope<Err, impl ServiceFactory<Config = (), Request = WebRequest<Err>, Response = WebResponse, Error = Err::Container, InitError = ()>> where
    F: Fn(WebRequest<Err>, &T::Service) -> R + Clone,
    R: Future<Output = Result<WebResponse, Err::Container>>, 

Registers middleware, in the form of a closure.

That runs during inbound processing in the request lifecycle (request -> response), modifying request as necessary, across all requests managed by the Scope. Scope-level middleware is more limited in what it can modify, relative to Route or Application level middleware, in that Scope-level middleware can not modify WebResponse.

use ntex::service::Service;
use ntex::web;
use ntex::http::header::{CONTENT_TYPE, HeaderValue};

async fn index() -> &'static str {
    "Welcome!"
}

fn main() {
    let app = web::App::new().service(
        web::scope("/app")
            .wrap_fn(|req, srv| {
                let fut = srv.call(req);
                async {
                    let mut res = fut.await?;
                    res.headers_mut().insert(
                       CONTENT_TYPE, HeaderValue::from_static("text/plain"),
                    );
                    Ok(res)
                }
            })
            .route("/index.html", web::get().to(index)));
}

Trait Implementations

impl<Err, T> WebServiceFactory<Err> for Scope<Err, T> where
    T: ServiceFactory<Config = (), Request = WebRequest<Err>, Response = WebResponse, Error = Err::Container, InitError = ()> + 'static,
    Err: ErrorRenderer, 

fn register(self, config: &mut WebServiceConfig<Err>)