This branch updates the READMEs for all Tower crates.
I've added the lib.rs docs to the `tower` crate's README, and added
crates.io, docs.rs, and updated CI badges to all the crates READMEs.
Since we no longer use Azure Pipelines for CI or Gitter for chat, I've
removed those badges and replaced them with GitHub Actions and Discord
badges, respectively.
I also fixed a typo in the `tower` lib.rs docs that was breaking some of the
RustDoc links, since I noticed it after copying those docs into the README.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
This branch makes the following changes:
* New `lib.rs` docs for `tower`, which should hopefully provide a
better explanation of Tower's core abstractions & their
relationships
* Nicer docs for `ServiceBuilder`
* Added `#[doc(cfg(...))]` attributes for feature flagged APIs
* Example improvements
* Fixing a bunch of broken intra-rustdoc links
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
This branch updates Tower to Tokio 0.3.
Unlike #474, this branch uses Tokio 0.3's synchronization primitives,
rather than continuing to depend on Tokio 0.2. I think that we ought to
try to use Tokio 0.3's channels whenever feasible, because the 0.2
channels have pathological memory usage patterns in some cases (see
tokio-rs/tokio#2637). @LucioFranco let me know what you think of the
approach used here and we can compare notes!
For the most part, this was a pretty mechanical change: updating
versions in Cargo.toml, tracking feature flag changes, renaming
`tokio::time::delay` to `sleep`, and so on. Tokio's channel receivers
also lost their `poll_recv` methods, but we can easily replicate that by
enabling the `"stream"` feature and using `poll_next` instead.
The one actually significant change is that `tokio::sync::mpsc::Sender`
lost its `poll_ready` method, which impacts the way `tower::buffer` is
implemeted. When the buffer's channel is full, we want to exert
backpressure in `poll_ready`, so that callers such as load balancers
could choose to call another service rather than waiting for buffer
capacity. Previously, we did this by calling `poll_ready` on the
underlying channel sender.
Unfortunately, this can't be done easily using Tokio 0.3's bounded MPSC
channel, because it no longer exposes a polling-based interface, only an
`async fn ready`, which borrows the sender. Therefore, we implement our
own bounded MPSC on top of the unbounded channel, using a semaphore to
limit how many items are in the channel.
I factored out the code for polling a semaphore acquire future from
`limit::concurrency` into its own module, and reused it in `Buffer`.
Additionally, the buffer tests needed to be updated, because they
currently don't actually poll the buffer service before calling it. This
violates the `Service` contract, and the new code actually fails as a
result.
Closes#473Closes#474
Co-authored-by: Lucio Franco <luciofranco14@gmail.com>
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
This makes all tower subcrates have the following lints as warn (rather
than allow): `missing_docs`, `rust_2018_idioms`, `unreachable_pub`, and
`missing_debug_implementations`. In addition, it consistently applies
`deny(warning)` *only* under CI so that deprecations and macro changes in minor
version bumps in dependencies will never cause `tower` crates to stop
compiling, and so that tests can be run even if not all warnings have been
dealt with. See also https://github.com/rust-unofficial/patterns/blob/master/anti_patterns/deny-warnings.md
Note that `tower-reconnect` has the `missing_docs` lint disabled for now
since it contained _no_ documentation previously. Also note that this
patch does not add documentation to the various `new` methods, as they
are considered self-explanatory. They are instead marked as
`#[allow(missing_docs)]`.
Calling a method on `Pin<&mut Self>` moves the pin, which means you can't call more methods later. The solution to this is to use `Pin::as_mut`. But it's annoying to have to do that to _every_ call to the `assert_request_eq!` helper macro from `tower-test`, so I made it do it for me.
* update tower-test to std::future
* refactoring tower-test tests
* everything works
* whoops, un-delete the tower dir
* cleanup & update links
* undo changes to tower-filter for this PR
* use pin_utils::unsafe_pinned
* use tokio-test
As described in #286, `Balance` had a few problems:
- it is responsible for driving all inner services to readiness, making
its `poll_ready` O(n) and not O(1);
- the `choose` abstraction was a hinderance. If a round-robin balancer
is needed it can be implemented separately without much duplicate
code; and
- endpoint errors were considered fatal to the balancer.
This changes replaces `Balance` with `p2c::Balance` and removes the
`choose` module.
Endpoint service failures now cause the service to be removed from the
balancer gracefully.
Endpoint selection is now effectively constant time, though it biases
for availability in the case when random selection does not yield an
available endpoint.
`tower-test` had to be updated so that a mocked service could fail after
advertising readiness.
