third_party/rust/tower-service/README.md

   1 # Tower Service
   2
   3 The foundational `Service` trait that [Tower] is based on.
   4
   5 [![Crates.io][crates-badge]][crates-url]
   6 [![Documentation][docs-badge]][docs-url]
   7 [![Documentation (master)][docs-master-badge]][docs-master-url]
   8 [![MIT licensed][mit-badge]][mit-url]
   9 [![Build Status][actions-badge]][actions-url]
  10 [![Discord chat][discord-badge]][discord-url]
  11
  12 [crates-badge]: https://img.shields.io/crates/v/tower-service.svg
  13 [crates-url]: https://crates.io/crates/tower-service
  14 [docs-badge]: https://docs.rs/tower-service/badge.svg
  15 [docs-url]: https://docs.rs/tower-service
  16 [docs-master-badge]: https://img.shields.io/badge/docs-master-blue
  17 [docs-master-url]: https://tower-rs.github.io/tower/tower_service
  18 [mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg
  19 [mit-url]: LICENSE
  20 [actions-badge]: https://github.com/tower-rs/tower/workflows/CI/badge.svg
  21 [actions-url]:https://github.com/tower-rs/tower/actions?query=workflow%3ACI
  22 [discord-badge]: https://img.shields.io/discord/500028886025895936?logo=discord&label=discord&logoColor=white
  23 [discord-url]: https://discord.gg/EeF3cQw
  24
  25 ## Overview
  26
  27 The [`Service`] trait provides the foundation upon which [Tower] is built. It is a
  28 simple, but powerful trait. At its heart, `Service` is just an asynchronous
  29 function of request to response.
  30
  31 ```
  32 async fn(Request) -> Result<Response, Error>
  33 ```
  34
  35 Implementations of `Service` take a request, the type of which varies per
  36 protocol, and returns a future representing the eventual completion or failure
  37 of the response.
  38
  39 Services are used to represent both clients and servers. An *instance* of
  40 `Service` is used through a client; a server *implements* `Service`.
  41
  42 By using standardizing the interface, middleware can be created. Middleware
  43 *implement* `Service` by passing the request to another `Service`. The
  44 middleware may take actions such as modify the request.
  45
  46 [`Service`]: https://docs.rs/tower-service/latest/tower_service/trait.Service.html
  47 [Tower]: https://crates.io/crates/tower
  48 ## License
  49
  50 This project is licensed under the [MIT license](LICENSE).
  51
  52 ### Contribution
  53
  54 Unless you explicitly state otherwise, any contribution intentionally submitted
  55 for inclusion in Tower by you, shall be licensed as MIT, without any additional
  56 terms or conditions.