Minor documentation improvements (#93)
This commit is contained in:
parent
7b6460dff2
commit
57df4b5b4d
2
LICENSE
2
LICENSE
|
@ -1,4 +1,4 @@
|
||||||
Copyright (c) 2017 Carl Lerche
|
Copyright (c) 2018 Carl Lerche
|
||||||
|
|
||||||
Permission is hereby granted, free of charge, to any
|
Permission is hereby granted, free of charge, to any
|
||||||
person obtaining a copy of this software and associated
|
person obtaining a copy of this software and associated
|
||||||
|
|
94
README.md
94
README.md
|
@ -1,11 +1,93 @@
|
||||||
# tower
|
# Tower
|
||||||
|
|
||||||
fn(Request) -> Future<Response>
|
Tower is a library of modular and reusable components for building robust
|
||||||
|
networking clients and servers.
|
||||||
This is not ready for usage yet (unless you are brave).
|
|
||||||
|
|
||||||
[![Build Status](https://travis-ci.org/tower-rs/tower.svg?branch=master)](https://travis-ci.org/tower-rs/tower)
|
[![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
|
||||||
|
|
|
@ -1,17 +1,22 @@
|
||||||
[package]
|
[package]
|
||||||
|
|
||||||
name = "tower-service"
|
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"
|
version = "0.1.0"
|
||||||
license = "MIT"
|
|
||||||
authors = ["Carl Lerche <me@carllerche.com>"]
|
authors = ["Carl Lerche <me@carllerche.com>"]
|
||||||
description = """
|
license = "MIT"
|
||||||
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"
|
|
||||||
readme = "README.md"
|
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]
|
[dependencies]
|
||||||
futures = "0.1"
|
futures = "0.1.23"
|
||||||
|
|
|
@ -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.
|
|
@ -1,3 +1,36 @@
|
||||||
# Tower Service
|
# Tower Service
|
||||||
|
|
||||||
The foundational `Service` trait that Tower is based on.
|
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<Item = Response>
|
||||||
|
```
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
|
@ -1,7 +1,16 @@
|
||||||
//! Definition of the core `Service` trait to Tower
|
|
||||||
|
|
||||||
#![deny(missing_docs)]
|
#![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]
|
#[macro_use]
|
||||||
extern crate futures;
|
extern crate futures;
|
||||||
|
@ -196,11 +205,19 @@ pub trait Service {
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Future yielding a `Service` once the service is ready to process a request
|
/// Future yielding a `Service` once the service is ready to process a request
|
||||||
|
///
|
||||||
|
/// `Ready` values are produced by `Service::ready`.
|
||||||
pub struct Ready<T> {
|
pub struct Ready<T> {
|
||||||
inner: Option<T>,
|
inner: Option<T>,
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Creates new `Service` values.
|
/// 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 {
|
pub trait NewService {
|
||||||
/// Requests handled by the service
|
/// Requests handled by the service
|
||||||
type Request;
|
type Request;
|
||||||
|
|
Loading…
Reference in New Issue