1
0
mirror of https://github.com/actix/actix-website synced 2024-12-22 03:24:55 +01:00
actix-website/docs/application.md

106 lines
6.1 KiB
Markdown
Raw Normal View History

2018-05-22 23:15:08 +02:00
---
title: Application
---
import CodeBlock from "@site/src/components/code_block";
2018-05-22 23:15:08 +02:00
# Writing an Application
2022-02-26 05:41:49 +01:00
`actix-web` provides various primitives to build web servers and applications with Rust. It provides routing, middleware, pre-processing of requests, post-processing of responses, etc.
2018-05-22 23:15:08 +02:00
2022-02-26 05:41:49 +01:00
All `actix-web` servers are built around the [`App`][app] instance. It is used for registering routes for resources and middleware. It also stores application state shared across all handlers within the same scope.
2018-05-22 23:15:08 +02:00
2022-02-26 05:41:49 +01:00
An application's [`scope`][scope] acts as a namespace for all routes, i.e. all routes for a specific application scope have the same url path prefix. The application prefix always contains a leading "/" slash. If a supplied prefix does not contain leading slash, it is automatically inserted. The prefix should consist of value path segments.
2018-05-22 23:15:08 +02:00
2022-02-26 05:41:49 +01:00
> For an application with scope `/app`, any request with the paths `/app`, `/app/`, or `/app/test` would match; however, the path `/application` would not match.
2018-05-22 23:15:08 +02:00
<CodeBlock example="application" file="app.rs" section="setup" />
2018-05-22 23:15:08 +02:00
2022-02-26 05:41:49 +01:00
In this example, an application with the `/app` prefix and an `index.html` resource is created. This resource is available through the `/app/index.html` url.
2018-05-22 23:15:08 +02:00
> For more information, check the [URL Dispatch][usingappprefix] section.
2018-05-22 23:15:08 +02:00
## State
2022-02-26 05:41:49 +01:00
Application state is shared with all routes and resources within the same scope. State can be accessed with the [`web::Data<T>`][data] extractor where `T` is the type of the state. State is also accessible for middleware.
2018-05-22 23:15:08 +02:00
2019-07-15 11:35:50 +02:00
Let's write a simple application and store the application name in the state:
2018-05-22 23:15:08 +02:00
<CodeBlock example="application" file="state.rs" section="setup" />
2018-05-22 23:15:08 +02:00
Next, pass in the state when initializing the App and start the application:
2018-05-22 23:15:08 +02:00
<CodeBlock example="application" file="state.rs" section="start_app" />
2018-05-22 23:15:08 +02:00
Any number of state types could be registered within the application.
2020-01-02 07:43:41 +01:00
2019-07-15 11:35:50 +02:00
## Shared Mutable State
2019-02-26 04:45:46 +01:00
2022-02-26 05:41:49 +01:00
`HttpServer` accepts an application factory rather than an application instance. An `HttpServer` constructs an application instance for each thread. Therefore, application data must be constructed multiple times. If you want to share data between different threads, a shareable object should be used, e.g. `Send` + `Sync`.
2022-04-07 17:22:17 +02:00
Internally, [`web::Data`][data] uses `Arc`. So in order to avoid creating two `Arc`s, we should create our Data before registering it using [`App::app_data()`][appdata].
2019-07-15 11:35:50 +02:00
2022-02-26 05:41:49 +01:00
In the following example, we will write an application with mutable, shared state. First, we define our state and create our handler:
2019-07-15 11:35:50 +02:00
<CodeBlock example="application" file="mutable_state.rs" section="setup_mutable" />
2019-07-15 11:35:50 +02:00
and register the data in an `App`:
2019-07-15 11:35:50 +02:00
<CodeBlock example="application" file="mutable_state.rs" section="make_app_mutable" />
2018-05-22 23:15:08 +02:00
2022-04-07 17:22:17 +02:00
Key takeaways:
2023-11-01 16:28:34 +01:00
2022-04-07 17:22:17 +02:00
- State initialized _inside_ the closure passed to `HttpServer::new` is local to the worker thread and may become de-synced if modified.
- To achieve _globally shared state_, it must be created **outside** of the closure passed to `HttpServer::new` and moved/cloned in.
2019-06-13 09:24:25 +02:00
## Using an Application Scope to Compose Applications
2018-06-08 06:08:11 +02:00
2022-02-26 05:41:49 +01:00
The [`web::scope()`][webscope] method allows setting a resource group prefix. This scope represents a resource prefix that will be prepended to all resource patterns added by the resource configuration. This can be used to help mount a set of routes at a different location than the original author intended while still maintaining the same resource names.
2018-06-08 06:08:11 +02:00
For example:
<CodeBlock example="application" file="scope.rs" section="scope" />
2018-06-08 06:08:11 +02:00
2022-02-26 05:41:49 +01:00
In the above example, the `show_users` route will have an effective route pattern of `/users/show` instead of `/show` because the application's scope argument will be prepended to the pattern. The route will then only match if the URL path is `/users/show`, and when the [`HttpRequest.url_for()`][urlfor] function is called with the route name `show_users`, it will generate a URL with that same path.
2018-06-08 06:08:11 +02:00
2019-06-13 09:24:25 +02:00
## Application guards and virtual hosting
2018-06-08 06:08:11 +02:00
2022-04-07 16:44:10 +02:00
You can think of a guard as a simple function that accepts a _request_ object reference and returns _true_ or _false_. Formally, a guard is any object that implements the [`Guard`][guardtrait] trait. Actix Web provides several guards. You can check the [functions section][guardfuncs] of the API docs.
2018-06-08 06:08:11 +02:00
2023-09-20 11:46:47 +02:00
One of the provided guards is [`Host`][guardhost]. It can be used as a filter based on request header information.
2018-06-08 06:08:11 +02:00
<CodeBlock example="application" file="vh.rs" section="vh" />
## Configure
2022-02-26 05:41:49 +01:00
For simplicity and reusability both [`App`][appconfig] and [`web::Scope`][webscopeconfig] provide the `configure` method. This function is useful for moving parts of the configuration to a different module or even library. For example, some of the resource's configuration could be moved to a different module.
<CodeBlock example="application" file="config.rs" section="config" />
The result of the above example would be:
```
/ -> "/"
/app -> "app"
/api/test -> "test"
```
2020-09-12 17:21:54 +02:00
Each [`ServiceConfig`][serviceconfig] can have its own `data`, `routes`, and `services`.
2020-01-02 07:43:41 +01:00
2020-09-12 17:21:54 +02:00
<!-- LINKS -->
2024-03-02 18:44:20 +01:00
[usingappprefix]: /docs/url-dispatch#using-an-application-prefix-to-compose-applications
2021-02-26 19:48:27 +01:00
[stateexample]: https://github.com/actix/examples/blob/master/basics/state/src/main.rs
2022-03-06 00:55:35 +01:00
[guardtrait]: https://docs.rs/actix-web/4/actix_web/guard/trait.Guard.html
[guardfuncs]: https://docs.rs/actix-web/4/actix_web/guard/index.html#functions
2023-09-20 11:46:47 +02:00
[guardhost]: https://docs.rs/actix-web/4/actix_web/guard/fn.Host.html
2022-03-06 00:55:35 +01:00
[data]: https://docs.rs/actix-web/4/actix_web/web/struct.Data.html
[app]: https://docs.rs/actix-web/4/actix_web/struct.App.html
[appconfig]: https://docs.rs/actix-web/4/actix_web/struct.App.html#method.configure
[appdata]: https://docs.rs/actix-web/4/actix_web/struct.App.html#method.app_data
[scope]: https://docs.rs/actix-web/4/actix_web/struct.Scope.html
[webscopeconfig]: https://docs.rs/actix-web/4/actix_web/struct.Scope.html#method.configure
[webscope]: https://docs.rs/actix-web/4/actix_web/web/fn.scope.html
[urlfor]: https://docs.rs/actix-web/4/actix_web/struct.HttpRequest.html#method.url_for
[serviceconfig]: https://docs.rs/actix-web/4/actix_web/web/struct.ServiceConfig.html