diff --git a/LICENSE b/LICENSE index 6c296be..58fb29a 100644 --- a/LICENSE +++ b/LICENSE @@ -1,4 +1,4 @@ -Copyright (c) 2017 Carl Lerche +Copyright (c) 2018 Carl Lerche Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated diff --git a/README.md b/README.md index e0abc50..1d99948 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,93 @@ -# tower +# Tower -fn(Request) -> Future - -This is not ready for usage yet (unless you are brave). +Tower is a library of modular and reusable components for building robust +networking clients and servers. [![Build Status](https://travis-ci.org/tower-rs/tower.svg?branch=master)](https://travis-ci.org/tower-rs/tower) -More information about this crate can be found in the [crate documentation][dox] +## Overview -[dox]: https://tower-rs.github.io/tower/tower_service +Tower aims to make it as easy as possible to build robust networking clients and +servers. It is protocol agnostic, but is designed around a request / response +pattern. If your protocol is entirely stream based, Tower may not be a good fit. + +## Project Layout + +Tower consists of a number of components, each of which live in their own sub +crates. + +* [`tower-service`]: The foundational traits upon which Tower is built + ([docs][ts-docs]) + +* [`tower-balance`]: A load balancer. Load is balanced across a number of + services ([docs][tb-docs]. + +* [`tower-buffer`]: A buffering middleware. If the inner service is not ready to + handle the next request, `tower-buffer` stores the request in an internal + queue ([docs][tbuf-docs]). + +* [`tower-discover`]: Service discovery abstraction ([docs][td-docs]). + +* [`tower-filter`]: Middleware that conditionally dispatch requests to the inner + service based on a predicate ([docs][tf-docs]); + +* [`tower-in-flight-limit`]: Middleware limiting thee number of requests that + are in-flight for the inner service ([docs][tifl-docs]). + +* [`tower-mock`]: Testing utility for mocking a `Service`. This is useful for + testing middleware implemeentations ([docs][tm-docs]); + +* [`tower-rate-limit`]: Middleware limiting the number of requests to the inner + service over a period of time ([docs][trl-docs]). + +* [`tower-reconnect`]: Middleware that automatically reconnects the inner + service when it becomes degraded ([docs][tr-docs]). + +* [`tower-timeout`]: Middleware that applies a timeout to requests + ([docs][tt-docs]). + +* [`tower-util`]: Miscellaneous additional utilities for Tower + ([docs][tu-docs]). + +* [`tower-watch`]: A middleware that rebinds the inner service each time a watch + is notified ([docs][tw-docs]). + +## Status + +Currently, only [`tower-service`], the foundational trait, has been released to +crates.io. The rest of the library will be following shortly. + +## License + +This project is licensed under the [MIT license](LICENSE). + +### Contribution + +Unless you explicitly state otherwise, any contribution intentionally submitted +for inclusion in Tower by you, shall be licensed as MIT, without any additional +terms or conditions. + +[`tower-service`]: tower-service +[ts-docs]: https://docs.rs/tower-service/ +[`tower-balance`]: tower-balance +[tb-docs]: https://tower-rs.github.io/tower/tower_balance/index.html +[`tower-buffer`]: tower-buffer +[tbuf-docs]: https://tower-rs.github.io/tower/tower_buffer/index.html +[`tower-discover`]: tower-discover +[td-docs]: https://tower-rs.github.io/tower/tower_discover/index.html +[`tower-filter`]: tower-filter +[tf-docs]: https://tower-rs.github.io/tower/tower_filter/index.html +[`tower-in-flight-limit`]: tower-in-flight-limit +[tifl-docs]: https://tower-rs.github.io/tower/tower_in_flight_limit/index.html +[`tower-mock`]: tower-mock +[tm-docs]: https://tower-rs.github.io/tower/tower_mock/index.html +[`tower-rate-limit`]: tower-rate-limit +[trl-docs]: https://tower-rs.github.io/tower/tower_rate_limit/index.html +[`tower-reconnect`]: tower-reconnect +[tr-docs]: https://tower-rs.github.io/tower/tower_reconnect/index.html +[`tower-timeout`]: tower-timeeout +[tt-docs]: https://tower-rs.github.io/tower/tower_timeout/index.html +[`tower-util`]: tower-util +[tu-docs]: https://tower-rs.github.io/tower/tower_util/index.html +[`tower-watch`]: tower-watch +[tw-docs]: https://tower-rs.github.io/tower/tower_watch/index.html diff --git a/tower-service/Cargo.toml b/tower-service/Cargo.toml index 7f9d688..38d3f5a 100644 --- a/tower-service/Cargo.toml +++ b/tower-service/Cargo.toml @@ -1,17 +1,22 @@ [package] name = "tower-service" +# When releasing to crates.io: +# - Update html_root_url. +# - Update CHANGELOG.md. +# - Update documentation URL +# - Create "v0.1.x" git tag. version = "0.1.0" -license = "MIT" authors = ["Carl Lerche "] -description = """ -The core `Service` trait for Tower. -""" -documentation = "https://docs.rs/tower-service" -homepage = "https://github.com/tower-rs/tower" -repository = "https://github.com/tower-rs/tower" +license = "MIT" readme = "README.md" -publish = false +repository = "https://github.com/tower-rs/tower" +homepage = "https://github.com/tower-rs/tower" +documentation = "https://docs.rs/tokio-service/0.1.0" +description = """ +Trait representing an asynchronous, request / response based, client or server. +""" +categories = ["asynchronous", "network-programming"] [dependencies] -futures = "0.1" +futures = "0.1.23" diff --git a/tower-service/LICENSE b/tower-service/LICENSE new file mode 100644 index 0000000..58fb29a --- /dev/null +++ b/tower-service/LICENSE @@ -0,0 +1,25 @@ +Copyright (c) 2018 Carl Lerche + +Permission is hereby granted, free of charge, to any +person obtaining a copy of this software and associated +documentation files (the "Software"), to deal in the +Software without restriction, including without +limitation the rights to use, copy, modify, merge, +publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software +is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice +shall be included in all copies or substantial portions +of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF +ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED +TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT +SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR +IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. diff --git a/tower-service/README.md b/tower-service/README.md index 7d99562..7cb0cd4 100644 --- a/tower-service/README.md +++ b/tower-service/README.md @@ -1,3 +1,36 @@ # Tower Service The foundational `Service` trait that Tower is based on. + +## Overview + +The [`Service`] trait provides the foundation upon which Tower is built. It is a +simple, but powerful trait. At its heart, `Service` is just an asynchronous +function of request to response. + +``` +fn(Request) -> Future +``` + +Implementations of `Service` take a request, the type of which varies per +protocol, and returns a future representing the eventual completion or failure +of the response. + +Services are used to represent both clients and servers. An *instance* of +`Service` is used through a client; a server *implements* `Service`. + +By using standardizing the interface, middleware can be created. Middleware +*implement* `Service` by passing the request to another `Service`. The +middleware may take actions such as modify the request. + +[`Service`]: https://docs.rs/tower-service/0.1/tower_service/trait.Service.html + +## License + +This project is licensed under the [MIT license](LICENSE). + +### Contribution + +Unless you explicitly state otherwise, any contribution intentionally submitted +for inclusion in Tower by you, shall be licensed as MIT, without any additional +terms or conditions. diff --git a/tower-service/src/lib.rs b/tower-service/src/lib.rs index 85ce84e..897dfcc 100644 --- a/tower-service/src/lib.rs +++ b/tower-service/src/lib.rs @@ -1,7 +1,16 @@ -//! Definition of the core `Service` trait to Tower - #![deny(missing_docs)] -#![doc(html_root_url = "https://docs.rs/tower/0.1")] +#![doc(html_root_url = "https://docs.rs/tower/0.1.0")] + +//! Definition of the core `Service` trait to Tower +//! +//! These traits provide the necessary abstractions for defining a request / +//! response clients and servers. They are simple but powerul and are the +//! used as the foundation for the rest of Tower. +//! +//! * [`Service`](trait.Service.html) is the primary trait and defines the request +//! / response exchange. See that trait for more details. +//! * [`NewService`](trait.NewService.html) is essentially a service factory. It +//! is responsible for generating `Service` values on demand. #[macro_use] extern crate futures; @@ -196,11 +205,19 @@ pub trait Service { } /// Future yielding a `Service` once the service is ready to process a request +/// +/// `Ready` values are produced by `Service::ready`. pub struct Ready { inner: Option, } /// Creates new `Service` values. +/// +/// Acts as a service factory. This is useful for cases where new `Service` +/// values must be produced. One case is a TCP servier listener. The listner +/// accepts new TCP streams, obtains a new `Service` value using the +/// `NewService` trait, and uses that new `Service` value to process inbound +/// requests on that new TCP stream. pub trait NewService { /// Requests handled by the service type Request;