/
index.xml
39 lines (39 loc) · 16.9 KB
/
index.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
<?xml version="1.0" encoding="utf-8" standalone="yes"?><rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom"><channel><title>Actix Web | A powerful, pragmatic, and extremely fast web framework for Rust. on actix</title><link>https://actix.rs/</link><description>Recent content in Actix Web | A powerful, pragmatic, and extremely fast web framework for Rust. on actix</description><generator>Hugo -- gohugo.io</generator><language>en-US</language><atom:link href="https://actix.rs/index.xml" rel="self" type="application/rss+xml"/><item><title>What is Actix Web</title><link>https://actix.rs/docs/whatis/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://actix.rs/docs/whatis/</guid><description>Actix Web is part of an Ecosystem of Crates Long ago, Actix Web was built on top of the actix actor framework. Now, Actix Web is largely unrelated to the actor framework and is built using a different system. Though actix is still maintained, its usefulness as a general tool is diminishing as the futures and async/await ecosystem matures. At this time, the use of actix is only required for WebSocket endpoints.</description></item><item><title>Getting Started</title><link>https://actix.rs/docs/getting-started/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://actix.rs/docs/getting-started/</guid><description>Installing Rust If you don&rsquo;t have Rust yet, we recommend you use rustup to manage your Rust installation. The official rust guide has a wonderful section on getting started.
Actix Web currently has a minimum supported Rust version (MSRV) of 1.54. Running rustup update will ensure you have the latest and greatest Rust version available. As such, this guide assumes you are running Rust 1.54 or later.
Hello, world! Start by creating a new binary-based Cargo project and changing into the new directory:</description></item><item><title>Application</title><link>https://actix.rs/docs/application/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://actix.rs/docs/application/</guid><description>Writing an Application 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.
All actix-web servers are built around the 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.
An application&rsquo;s scope acts as a namespace for all routes, i.e. all routes for a specific application scope have the same url path prefix.</description></item><item><title>Server</title><link>https://actix.rs/docs/server/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://actix.rs/docs/server/</guid><description>The HTTP Server The HttpServer type is responsible for serving HTTP requests.
HttpServer accepts an application factory as a parameter, and the application factory must have Send + Sync boundaries. More about that in the multi-threading section.
To start the web server it must first be bound to a network socket. Use HttpServer::bind() with a socket address tuple or string such as (&quot;127.0.0.1&quot;, 8080) or &quot;0.0.0.0:8080&quot;. This will fail if the socket is being used by another application.</description></item><item><title>Handlers</title><link>https://actix.rs/docs/handlers/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://actix.rs/docs/handlers/</guid><description>Request Handlers A request handler is an async function that accepts zero or more parameters that can be extracted from a request (i.e., impl FromRequest) and returns a type that can be converted into an HttpResponse (i.e., impl Responder).
Request handling happens in two stages. First the handler object is called, returning any object that implements the Responder trait. Then, respond_to() is called on the returned object, converting itself to a HttpResponse or Error.</description></item><item><title>Extractors</title><link>https://actix.rs/docs/extractors/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://actix.rs/docs/extractors/</guid><description>Type-safe information extraction Actix Web provides a facility for type-safe request information access called extractors (i.e., impl FromRequest). There are lots of built-in extractor implementations (see implementors).
An extractor can be accessed as an argument to a handler function. Actix Web supports up to 12 extractors per handler function. Argument position does not matter.
asyncfn index(path: web::Path&lt;(String,String)&gt;,json: web::Json&lt;MyInfo&gt;)-&gt; implResponder{letpath=path.into_inner();format!(&#34;{} {} {} {}&#34;,path.0,path.1,json.id,json.username)} Path Path provides information that is extracted from the request&rsquo;s path.</description></item><item><title>Errors</title><link>https://actix.rs/docs/errors/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://actix.rs/docs/errors/</guid><description>Errors Actix Web uses its own actix_web::error::Error type and actix_web::error::ResponseError trait for error handling from web handlers.
If a handler returns an Error (referring to the general Rust trait std::error::Error) in a Result that also implements the ResponseError trait, actix-web will render that error as an HTTP response with its corresponding actix_web::http::StatusCode. An internal server error is generated by default:
pubtraitResponseError{fn error_response(&amp;self)-&gt; Response&lt;Body&gt;;fn status_code(&amp;self)-&gt; StatusCode;}A Responder coerces compatible Results into HTTP responses:</description></item><item><title>URL Dispatch</title><link>https://actix.rs/docs/url-dispatch/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://actix.rs/docs/url-dispatch/</guid><description>URL Dispatch URL dispatch provides a simple way for mapping URLs to handler code using a simple pattern matching language. If one of the patterns matches the path information associated with a request, a particular handler object is invoked.
A request handler is a function that accepts zero or more parameters that can be extracted from a request (i.e., impl FromRequest) and returns a type that can be converted into an HttpResponse (i.</description></item><item><title>Requests</title><link>https://actix.rs/docs/request/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://actix.rs/docs/request/</guid><description>JSON Request There are several options for json body deserialization.
The first option is to use Json extractor. First, you define a handler function that accepts Json&lt;T&gt; as a parameter, then, you use the .to() method for registering this handler. It is also possible to accept arbitrary valid json object by using serde_json::Value as a type T.
First example of json of JSON Request depends on serde:
[dependencies] serde = { version = &#34;1.</description></item><item><title>Responses</title><link>https://actix.rs/docs/response/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://actix.rs/docs/response/</guid><description>Response A builder-like pattern is used to construct an instance of HttpResponse. HttpResponse provides several methods that return a HttpResponseBuilder instance, which implements various convenience methods for building responses.
Check the documentation for type descriptions.
The methods .body, .finish, and .json finalize response creation and return a constructed HttpResponse instance. If this methods is called on the same builder instance multiple times, the builder will panic.
useactix_web::{http::header::ContentType,HttpResponse};asyncfn index()-&gt; HttpResponse{HttpResponse::Ok().</description></item><item><title>Testing</title><link>https://actix.rs/docs/testing/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://actix.rs/docs/testing/</guid><description>Testing Every application should be well tested. Actix Web provides tools to perform unit and integration tests.
Unit Tests For unit testing, actix-web provides a request builder type. TestRequest implements a builder-like pattern. You can generate a HttpRequest instance with to_http_request() and call your handler with it.
#[cfg(test)]mod tests{usesuper::*;useactix_web::{http::{self,header::ContentType},test,};#[actix_web::test]asyncfn test_index_ok(){letreq=test::TestRequest::default().insert_header(ContentType::plaintext()).to_http_request();letresp=index(req).await;assert_eq!(resp.status(),http::StatusCode::OK);}#[actix_web::test]asyncfn test_index_not_ok(){letreq=test::TestRequest::default().to_http_request();letresp=index(req).await;assert_eq!(resp.status(),http::StatusCode::BAD_REQUEST);}} Integration tests There are a few methods for testing your application. Actix Web can be used to run the application with specific handlers in a real HTTP server.</description></item><item><title>Middleware</title><link>https://actix.rs/docs/middleware/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://actix.rs/docs/middleware/</guid><description>Middleware Actix Web&rsquo;s middleware system allows us to add additional behavior to request/response processing. Middleware can hook into an incoming request process, enabling us to modify requests as well as halt request processing to return a response early.
Middleware can also hook into response processing.
Typically, middleware is involved in the following actions:
Pre-process the Request Post-process a Response Modify application state Access external services (redis, logging, sessions) Middleware is registered for each App, scope, or Resource and executed in opposite order as registration.</description></item><item><title>Static Files</title><link>https://actix.rs/docs/static-files/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://actix.rs/docs/static-files/</guid><description>Individual file It is possible to serve static files with a custom path pattern and NamedFile. To match a path tail, we can use a [.*] regex.
useactix_files::NamedFile;useactix_web::{HttpRequest,Result};usestd::path::PathBuf;asyncfn index(req: HttpRequest)-&gt; Result&lt;NamedFile&gt;{letpath: PathBuf=req.match_info().query(&#34;filename&#34;).parse().unwrap();Ok(NamedFile::open(path)?)}#[actix_web::main]asyncfn main()-&gt; std::io::Result&lt;()&gt;{useactix_web::{web,App,HttpServer};HttpServer::new(||App::new().route(&#34;/{filename:.*}&#34;,web::get().to(index))).bind((&#34;127.0.0.1&#34;,8080))?.run().await} Directory To serve files from specific directories and sub-directories, Files can be used. Files must be registered with an App::service() method, otherwise it will be unable to serve sub-paths.
useactix_filesasfs;useactix_web::{App,HttpServer};#[actix_web::main]asyncfn main()-&gt; std::io::Result&lt;()&gt;{HttpServer::new(||App::new().service(fs::Files::new(&#34;/static&#34;,&#34;.&#34;).show_files_listing())).bind((&#34;127.0.0.1&#34;,8080))?.run().await} By default files listing for sub-directories is disabled.</description></item><item><title>Websockets</title><link>https://actix.rs/docs/websockets/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://actix.rs/docs/websockets/</guid><description>Actix Web supports WebSockets with the actix-web-actors crate. It is possible to convert a request&rsquo;s Payload to a stream of ws::Message with a web::Payload and then use stream combinators to handle actual messages, but it is simpler to handle websocket communications with an http actor.
The following is an example of a simple websocket echo server:
useactix::{Actor,StreamHandler};useactix_web::{web,App,Error,HttpRequest,HttpResponse,HttpServer};useactix_web_actors::ws;/// Define HTTP actor struct MyWs;implActorforMyWs{type Context=ws::WebsocketContext&lt;Self&gt;;}/// Handler for ws::Message message implStreamHandler&lt;Result&lt;ws::Message,ws::ProtocolError&gt;&gt;forMyWs{fn handle(&amp;mutself,msg: Result&lt;ws::Message,ws::ProtocolError&gt;,ctx: &amp;mutSelf::Context){matchmsg{Ok(ws::Message::Ping(msg))=&gt;ctx.</description></item><item><title>HTTP/2</title><link>https://actix.rs/docs/http2/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://actix.rs/docs/http2/</guid><description>Actix Web will prefer HTTP/2 connections if the client signals support for it via TLS ALPN.
Negotiation When either of the rustls or openssl features are enabled, HttpServer provides the bind_rustls method and bind_openssl methods, respectively.
[dependencies] actix-web = { version = &#34;4&#34;, features = [&#34;openssl&#34;] } openssl = { version = &#34;0.10&#34;, features = [&#34;v110&#34;] } useactix_web::{web,App,HttpRequest,HttpServer,Responder};useopenssl::ssl::{SslAcceptor,SslFiletype,SslMethod};asyncfn index(_req: HttpRequest)-&gt; implResponder{&#34;Hello.&#34;}#[actix_web::main]asyncfn main()-&gt; std::io::Result&lt;()&gt;{// load TLS keys // to create a self-signed temporary cert for testing: // `openssl req -x509 -newkey rsa:4096 -nodes -keyout key.</description></item><item><title>Auto-Reloading</title><link>https://actix.rs/docs/autoreload/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://actix.rs/docs/autoreload/</guid><description>Auto-Reloading Development Server During development it can be very handy to have cargo automatically recompile the code on changes. This can be accomplished very easily by using cargo-watch.
cargo watch -x &#39;run --bin app&#39; Historical Note An old version of this page recommended using a combination of systemfd and listenfd, but this has many gotchas and was difficult to integrate properly, especially when part of a broader development workflow. We consider cargo-watch to be sufficient for auto-reloading purposes.</description></item><item><title>Databases</title><link>https://actix.rs/docs/databases/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://actix.rs/docs/databases/</guid><description>Async Options We have several example projects showing use of async database adapters:
Postgres: https://github.com/actix/examples/tree/master/databases/postgres SQLite: https://github.com/actix/examples/tree/master/databases/sqlite MongoDB: https://github.com/actix/examples/tree/master/databases/mongodb Diesel The current version of Diesel (v1) does not support asynchronous operations, so it is important to use the web::block function to offload your database operations to the Actix runtime thread-pool.
You can create action functions that correspond to all the operations your app will perform on the database.</description></item><item><title>HTTP Server Initialization</title><link>https://actix.rs/docs/http_server_init/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://actix.rs/docs/http_server_init/</guid><description>Architecture overview Below is a diagram of HttpServer initialization, which happens on the following code
#[actix_web::main]asyncfn main()-&gt; std::io::Result&lt;()&gt;{HttpServer::new(||{App::new().</description></item><item><title>Connection Lifecycle</title><link>https://actix.rs/docs/conn_lifecycle/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://actix.rs/docs/conn_lifecycle/</guid><description>Architecture overview After Server has started listening to all sockets, Accept and Worker are two main loops responsible for processing incoming client connections.
Once connection accepted Application level protocol processing happens in a protocol specific Dispatcher loop spawned from Worker.
Please note, below diagrams are outlining happy-path scenarios only. Accept loop in more detail Most of code implementation resides in actix-server crate for struct Accept.
Worker loop in more detail Most of code implementation resides in actix-server crate for struct Worker.</description></item><item><title>Contributor Covenant Code of Conduct</title><link>https://actix.rs/community/coc/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://actix.rs/community/coc/</guid><description>Our Pledge In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
Our Standards Examples of behavior that contributes to creating a positive environment include:
Using welcoming and inclusive language Being respectful of differing viewpoints and experiences Gracefully accepting constructive criticism Focusing on what is best for the community Showing empathy towards other community members Examples of unacceptable behavior by participants include:</description></item></channel></rss>