mirrors/actix-web
1
0
Fork 0
mirror of https://github.com/actix/actix-web.git synced 2024-06-11 09:49:29 +00:00
Code Issues Projects Releases Wiki Activity

revamp readme and root doc page (#1590)

Browse source
This commit is contained in:
Rob Ede 2020-07-05 01:16:53 +01:00 committed by GitHub
parent deab634247
commit 056803d534
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 87 additions and 93 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

90
README.md
View file

@ -1,58 +1,58 @@
<div align="center"> <div align="center">
<p><h1>Actix web</h1> </p> <h1>Actix web</h1>
<p><strong>Actix web is a small, pragmatic, and extremely fast rust web framework</strong> </p> <p>
<strong>Actix web is a powerful, pragmatic, and extremely fast web framework for Rust</strong>
</p>
<p> <p>
[![Build Status](https://travis-ci.org/actix/actix-web.svg?branch=master)](https://travis-ci.org/actix/actix-web)
[![codecov](https://codecov.io/gh/actix/actix-web/branch/master/graph/badge.svg)](https://codecov.io/gh/actix/actix-web)
[![crates.io](https://meritbadge.herokuapp.com/actix-web)](https://crates.io/crates/actix-web) [![crates.io](https://meritbadge.herokuapp.com/actix-web)](https://crates.io/crates/actix-web)
[![Join the chat at https://gitter.im/actix/actix](https://badges.gitter.im/actix/actix.svg)](https://gitter.im/actix/actix?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[![Documentation](https://docs.rs/actix-web/badge.svg)](https://docs.rs/actix-web) [![Documentation](https://docs.rs/actix-web/badge.svg)](https://docs.rs/actix-web)
[![Download](https://img.shields.io/crates/d/actix-web.svg)](https://crates.io/crates/actix-web)
[![Version](https://img.shields.io/badge/rustc-1.41+-lightgray.svg)](https://blog.rust-lang.org/2020/02/27/Rust-1.41.1.html) [![Version](https://img.shields.io/badge/rustc-1.41+-lightgray.svg)](https://blog.rust-lang.org/2020/02/27/Rust-1.41.1.html)
![License](https://img.shields.io/crates/l/actix-web.svg) ![License](https://img.shields.io/crates/l/actix-web.svg)
<br />
[![Build Status](https://travis-ci.org/actix/actix-web.svg?branch=master)](https://travis-ci.org/actix/actix-web)
[![codecov](https://codecov.io/gh/actix/actix-web/branch/master/graph/badge.svg)](https://codecov.io/gh/actix/actix-web)
[![Download](https://img.shields.io/crates/d/actix-web.svg)](https://crates.io/crates/actix-web)
[![Join the chat at https://gitter.im/actix/actix](https://badges.gitter.im/actix/actix.svg)](https://gitter.im/actix/actix?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
</p> </p>
<h3>
<a href="https://actix.rs">Website</a>
<span> | </span>
<a href="https://gitter.im/actix/actix">Chat</a>
<span> | </span>
<a href="https://github.com/actix/examples">Examples</a>
</h3>
</div> </div>
<br>
Actix web is a simple, pragmatic and extremely fast web framework for Rust. ## Features
* Supported *HTTP/1.x* and *HTTP/2.0* protocols * Supports *HTTP/1.x* and *HTTP/2*
* Streaming and pipelining * Streaming and pipelining
* Keep-alive and slow requests handling * Keep-alive and slow requests handling
* Client/server [WebSockets](https://actix.rs/docs/websockets/) support * Client/server [WebSockets](https://actix.rs/docs/websockets/) support
* Transparent content compression/decompression (br, gzip, deflate) * Transparent content compression/decompression (br, gzip, deflate)
* Configurable [request routing](https://actix.rs/docs/url-dispatch/) * Powerful [request routing](https://actix.rs/docs/url-dispatch/)
* Multipart streams * Multipart streams
* Static assets * Static assets
* SSL support with OpenSSL or Rustls * SSL support using OpenSSL or Rustls
* Middlewares ([Logger, Session, CORS, etc](https://actix.rs/docs/middleware/)) * Middlewares ([Logger, Session, CORS, etc](https://actix.rs/docs/middleware/))
* Includes an asynchronous [HTTP client](https://actix.rs/actix-web/actix_web/client/index.html) * Includes an async [HTTP client](https://actix.rs/actix-web/actix_web/client/index.html)
* Supports [Actix actor framework](https://github.com/actix/actix) * Supports [Actix actor framework](https://github.com/actix/actix)
* Supports Rust 1.40+ * Runs on stable Rust 1.41+
## Docs ## Documentation
* [API documentation (master)](https://actix.rs/actix-web/actix_web) * [Website & User Guide](https://actix.rs)
* [API documentation (docs.rs)](https://docs.rs/actix-web) * [Examples Repository](https://actix.rs/actix-web/actix_web)
* [User guide](https://actix.rs) * [API Documentation](https://docs.rs/actix-web)
* [API Documentation (master branch)](https://actix.rs/actix-web/actix_web)
## Example ## Example
<h2>
WARNING: This example is for the master branch which is currently in beta stages for v3. For
Actix web v2 see the <a href="https://actix.rs/docs/getting-started/">getting started guide</a>.
</h2>
Dependencies: Dependencies:
```toml ```toml
[dependencies] [dependencies]
actix-web = "2" actix-web = "3"
``` ```
Code: Code:
@ -76,37 +76,39 @@ async fn main() -> std::io::Result<()> {
### More examples ### More examples
* [Basics](https://github.com/actix/examples/tree/master/basics/) * [Basic Setup](https://github.com/actix/examples/tree/master/basics/)
* [Stateful](https://github.com/actix/examples/tree/master/state/) * [Application State](https://github.com/actix/examples/tree/master/state/)
* [Multipart streams](https://github.com/actix/examples/tree/master/multipart/) * [JSON Handling](https://github.com/actix/examples/tree/master/json/)
* [Simple websocket](https://github.com/actix/examples/tree/master/websocket/) * [Multipart Streams](https://github.com/actix/examples/tree/master/multipart/)
* [Tera](https://github.com/actix/examples/tree/master/template_tera/) * [Diesel Integration](https://github.com/actix/examples/tree/master/diesel/)
* [Askama](https://github.com/actix/examples/tree/master/template_askama/) templates * [r2d2 Integration](https://github.com/actix/examples/tree/master/r2d2/)
* [Diesel integration](https://github.com/actix/examples/tree/master/diesel/) * [Simple WebSocket](https://github.com/actix/examples/tree/master/websocket/)
* [r2d2](https://github.com/actix/examples/tree/master/r2d2/) * [Tera Templates](https://github.com/actix/examples/tree/master/template_tera/)
* [OpenSSL](https://github.com/actix/examples/tree/master/openssl/) * [Askama Templates](https://github.com/actix/examples/tree/master/template_askama/)
* [Rustls](https://github.com/actix/examples/tree/master/rustls/) * [HTTPS using Rustls](https://github.com/actix/examples/tree/master/rustls/)
* [Tcp/Websocket chat](https://github.com/actix/examples/tree/master/websocket-chat/) * [HTTPS using OpenSSL](https://github.com/actix/examples/tree/master/openssl/)
* [Json](https://github.com/actix/examples/tree/master/json/) * [WebSocket Chat](https://github.com/actix/examples/tree/master/websocket-chat/)
You may consider checking out You may consider checking out
[this directory](https://github.com/actix/examples/tree/master/) for more examples. [this directory](https://github.com/actix/examples/tree/master/) for more examples.
## Benchmarks ## Benchmarks
* [TechEmpower Framework Benchmark](https://www.techempower.com/benchmarks/#section=data-r19) One of the fastest web frameworks available according to the
[TechEmpower Framework Benchmark](https://www.techempower.com/benchmarks/#section=data-r19).
## License ## License
This project is licensed under either of This project is licensed under either of
* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)) * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
* MIT license ([LICENSE-MIT](LICENSE-MIT) or [http://opensource.org/licenses/MIT](http://opensource.org/licenses/MIT)) [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0))
* MIT license ([LICENSE-MIT](LICENSE-MIT) or
[http://opensource.org/licenses/MIT](http://opensource.org/licenses/MIT))
at your option. at your option.
## Code of Conduct ## Code of Conduct
Contribution to the actix-web crate is organized under the terms of the Contribution to the actix-web crate is organized under the terms of the Contributor Covenant, the
Contributor Covenant, the maintainer of actix-web, @fafhrd91, promises to maintainers of Actix web, promises to intervene to uphold that code of conduct.
intervene to uphold that code of conduct.

90
src/lib.rs
View file

@ -1,79 +1,72 @@
#![warn(rust_2018_idioms, warnings)] #![warn(rust_2018_idioms, warnings)]
#![allow(clippy::needless_doctest_main, clippy::type_complexity)] #![allow(clippy::needless_doctest_main, clippy::type_complexity)]
//! Actix web is a small, pragmatic, and extremely fast web framework //! Actix web is a powerful, pragmatic, and extremely fast web framework for Rust.
//! for Rust.
//! //!
//! ## Example //! ## Example
//! //!
//! ```rust,no_run //! ```rust,no_run
//! use actix_web::{web, App, Responder, HttpServer}; //! use actix_web::{get, web, App, HttpServer, Responder};
//! //!
//! async fn index(info: web::Path<(String, u32)>) -> impl Responder { //! #[get("/{id}/{name}/index.html")]
//! format!("Hello {}! id:{}", info.0, info.1) //! async fn index(info: web::Path<(u32, String)>) -> impl Responder {
//! format!("Hello {}! id:{}", info.1, info.0)
//! } //! }
//! //!
//! #[actix_web::main] //! #[actix_web::main]
//! async fn main() -> std::io::Result<()> { //! async fn main() -> std::io::Result<()> {
//! HttpServer::new(|| App::new().service( //! HttpServer::new(|| App::new().service(index))
//! web::resource("/{name}/{id}/index.html").to(index))
//! )
//! .bind("127.0.0.1:8080")? //! .bind("127.0.0.1:8080")?
//! .run() //! .run()
//! .await //! .await
//! } //! }
//! ``` //! ```
//! //!
//! ## Documentation & community resources //! ## Documentation & Community Resources
//! //!
//! Besides the API documentation (which you are currently looking //! In addition to this API documentation, several other resources are available:
//! at!), several other resources are available:
//! //!
//! * [User Guide](https://actix.rs/docs/) //! * [Website & User Guide](https://actix.rs/)
//! * [Chat on gitter](https://gitter.im/actix/actix) //! * [Examples Repository](https://github.com/actix/examples)
//! * [GitHub repository](https://github.com/actix/actix-web) //! * [Community Chat on Gitter](https://gitter.im/actix/actix-web)
//! * [Cargo package](https://crates.io/crates/actix-web)
//! //!
//! To get started navigating the API documentation you may want to //! To get started navigating the API docs, you may consider looking at the following pages first:
//! consider looking at the following pages:
//! //!
//! * [App](struct.App.html): This struct represents an actix-web //! * [App](struct.App.html): This struct represents an Actix web application and is used to
//! application and is used to configure routes and other common //! configure routes and other common application settings.
//! settings.
//! //!
//! * [HttpServer](struct.HttpServer.html): This struct //! * [HttpServer](struct.HttpServer.html): This struct represents an HTTP server instance and is
//! represents an HTTP server instance and is used to instantiate and //! used to instantiate and configure servers.
//! configure servers.
//! //!
//! * [web](web/index.html): This module //! * [web](web/index.html): This module provides essential types for route registration as well as
//! provides essential helper functions and types for application registration. //! common utilities for request handlers.
//! //!
//! * [HttpRequest](struct.HttpRequest.html) and //! * [HttpRequest](struct.HttpRequest.html) and [HttpResponse](struct.HttpResponse.html): These
//! [HttpResponse](struct.HttpResponse.html): These structs //! structs represent HTTP requests and responses and expose methods for creating, inspecting,
//! represent HTTP requests and responses and expose various methods //! and otherwise utilizing them.
//! for inspecting, creating and otherwise utilizing them.
//! //!
//! ## Features //! ## Features
//! //!
//! * Supported *HTTP/1.x* and *HTTP/2.0* protocols //! * Supports *HTTP/1.x* and *HTTP/2*
//! * Streaming and pipelining //! * Streaming and pipelining
//! * Keep-alive and slow requests handling //! * Keep-alive and slow requests handling
//! * `WebSockets` server/client //! * Client/server [WebSockets](https://actix.rs/docs/websockets/) support
//! * Transparent content compression/decompression (br, gzip, deflate) //! * Transparent content compression/decompression (br, gzip, deflate)
//! * Configurable request routing //! * Powerful [request routing](https://actix.rs/docs/url-dispatch/)
//! * Multipart streams //! * Multipart streams
//! * SSL support with OpenSSL or `native-tls` //! * Static assets
//! * Middlewares (`Logger`, `Session`, `CORS`, `DefaultHeaders`) //! * SSL support using OpenSSL or Rustls
//! * Middlewares ([Logger, Session, CORS, etc](https://actix.rs/docs/middleware/))
//! * Includes an async [HTTP client](https://actix.rs/actix-web/actix_web/client/index.html)
//! * Supports [Actix actor framework](https://github.com/actix/actix) //! * Supports [Actix actor framework](https://github.com/actix/actix)
//! * Supported Rust version: 1.40 or later //! * Runs on stable Rust 1.41+
//! //!
//! ## Package feature //! ## Crate Features
//! //!
//! * `client` - enables http client (default enabled) //! * `compress` - content encoding compression support (enabled by default)
//! * `compress` - enables content encoding compression support (default enabled) //! * `openssl` - HTTPS support via `openssl` crate, supports `HTTP/2`
//! * `openssl` - enables ssl support via `openssl` crate, supports `http/2` //! * `rustls` - HTTPS support via `rustls` crate, supports `HTTP/2`
//! * `rustls` - enables ssl support via `rustls` crate, supports `http/2` //! * `secure-cookies` - secure cookies support
//! * `secure-cookies` - enables secure cookies support
mod app; mod app;
mod app_service; mod app_service;
@ -97,12 +90,10 @@ pub mod test;
mod types; mod types;
pub mod web; pub mod web;
pub use actix_web_codegen::*;
pub use actix_rt as rt;
// re-export for convenience
pub use actix_http::Response as HttpResponse; pub use actix_http::Response as HttpResponse;
pub use actix_http::{body, cookie, http, Error, HttpMessage, ResponseError, Result}; pub use actix_http::{body, cookie, http, Error, HttpMessage, ResponseError, Result};
pub use actix_rt as rt;
pub use actix_web_codegen::*;
pub use crate::app::App; pub use crate::app::App;
pub use crate::extract::FromRequest; pub use crate::extract::FromRequest;
@ -203,19 +194,20 @@ pub mod dev {
} }
pub mod client { pub mod client {
//! An HTTP Client //! Actix web async HTTP client.
//! //!
//! ```rust //! ```rust
//! use actix_web::client::Client; //! use actix_web::client::Client;
//! //!
//! #[actix_rt::main] //! #[actix_web::main]
//! async fn main() { //! async fn main() {
//! let mut client = Client::default(); //! let mut client = Client::default();
//! //!
//! // Create request builder and send request //! // Create request builder and send request
//! let response = client.get("http://www.rust-lang.org") //! let response = client.get("http://www.rust-lang.org")
//! .header("User-Agent", "Actix-web") //! .header("User-Agent", "actix-web/3.0")
//! .send().await; // <- Send http request //! .send() // <- Send request
//! .await; // <- Wait for response
//! //!
//! println!("Response: {:?}", response); //! println!("Response: {:?}", response);
//! } //! }