Struct actix_web::Scope

pub struct Scope<S> { /* private fields */ }

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 actix_web::{http, App, HttpRequest, HttpResponse};

fn main() {
    let app = App::new().scope("/{project_id}/", |scope| {
        scope
            .resource("/path1", |r| r.f(|_| HttpResponse::Ok()))
            .resource("/path2", |r| r.f(|_| HttpResponse::Ok()))
            .resource("/path3", |r| r.f(|_| 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<S: 'static> Scope<S>

pub fn new(path: &str) -> Scope<S>

Create a new scope

pub fn filter<T: Predicate<S> + 'static>(self, p: T) -> Self

Add match predicate to scope.

use actix_web::{http, pred, App, HttpRequest, HttpResponse, Path};

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

fn main() {
    let app = App::new().scope("/app", |scope| {
        scope
            .filter(pred::Header("content-type", "text/plain"))
            .route("/test1", http::Method::GET, index)
            .route("/test2", http::Method::POST, |_: HttpRequest| {
                HttpResponse::MethodNotAllowed()
            })
    });
}

pub fn with_state<F, T: 'static>(self, path: &str, state: T, f: F) -> Scope<S>where
    F: FnOnce(Scope<T>) -> Scope<T>,

Create nested scope with new state.

use actix_web::{App, HttpRequest};

struct AppState;

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

fn main() {
    let app = App::new().scope("/app", |scope| {
        scope.with_state("/state2", AppState, |scope| {
            scope.resource("/test1", |r| r.f(index))
        })
    });
}

pub fn nested<F>(self, path: &str, f: F) -> Scope<S>where
    F: FnOnce(Scope<S>) -> Scope<S>,

Create nested scope.

use actix_web::{App, HttpRequest};

struct AppState;

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

fn main() {
    let app = App::with_state(AppState).scope("/app", |scope| {
        scope.nested("/v1", |scope| scope.resource("/test1", |r| r.f(index)))
    });
}

pub fn route<T, F, R>(self, path: &str, method: Method, f: F) -> Scope<S>where
    F: WithFactory<T, S, R>,
    R: Responder + 'static,
    T: FromRequest<S> + 'static,

Configure route for a specific path.

This is a simplified version of the Scope::resource() method. Handler functions need to accept one request extractor argument.

This method could be called multiple times, in that case multiple routes would be registered for same resource path.

use actix_web::{http, App, HttpRequest, HttpResponse, Path};

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

fn main() {
    let app = App::new().scope("/app", |scope| {
        scope.route("/test1", http::Method::GET, index).route(
            "/test2",
            http::Method::POST,
            |_: HttpRequest| HttpResponse::MethodNotAllowed(),
        )
    });
}

pub fn resource<F, R>(self, path: &str, f: F) -> Scope<S>where
    F: FnOnce(&mut Resource<S>) -> R + 'static,

Configure resource for a specific path.

This method is similar to an App::resource() method. Resources may have variable path segments. Resource path uses scope path as a path prefix.

use actix_web::*;

fn main() {
    let app = App::new().scope("/api", |scope| {
        scope.resource("/users/{userid}/{friend}", |r| {
            r.get().f(|_| HttpResponse::Ok());
            r.head().f(|_| HttpResponse::MethodNotAllowed());
            r.route()
                .filter(pred::Any(pred::Get()).or(pred::Put()))
                .filter(pred::Header("Content-Type", "text/plain"))
                .f(|_| HttpResponse::Ok())
        })
    });
}

pub fn default_resource<F, R>(self, f: F) -> Scope<S>where
    F: FnOnce(&mut Resource<S>) -> R + 'static,

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

pub fn handler<H: Handler<S>>(self, path: &str, handler: H) -> Scope<S>

Configure handler for specific path prefix.

A path prefix consists of valid path segments, i.e for the prefix /app any request with the paths /app, /app/ or /app/test would match, but the path /application would not.

use actix_web::{http, App, HttpRequest, HttpResponse};

fn main() {
    let app = App::new().scope("/scope-prefix", |scope| {
        scope.handler("/app", |req: &HttpRequest| match *req.method() {
            http::Method::GET => HttpResponse::Ok(),
            http::Method::POST => HttpResponse::MethodNotAllowed(),
            _ => HttpResponse::NotFound(),
        })
    });
}

pub fn middleware<M: Middleware<S>>(self, mw: M) -> Scope<S>

Register a scope middleware

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

Note Middleware::finish() fires right after response get prepared. It does not wait until body get sent to the peer.