tower-batch 0.2.0

`tower-batch` is a Tower middleware that allows you to buffer requests for batch processing until the buffer reaches a maximum size OR a maximum duration elapses.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

# tower-batch

[![CI Build](https://github.com/chmodas/tower-batch/actions/workflows/ci.yml/badge.svg)](https://github.com/chmodas/tower-batch/actions/workflows/ci.yml)
[![codecov](https://codecov.io/github/chmodas/tower-batch/graph/badge.svg?token=GLA3M3GGQC)](https://codecov.io/github/chmodas/tower-batch)

A [Tower] middleware that buffers requests and flushes them in batches. Use it when the downstream system is more efficient with bulk writes – databases, message brokers, object stores, etc. The middleware collects individual requests as `BatchControl::Item(R)` and, once the buffer reaches a maximum size **or** a maximum duration elapses, signals the inner service with `BatchControl::Flush` so it can process the accumulated batch.

## Quick start

Add the dependency to your `Cargo.toml`:

```toml
[dependencies]
tower-batch = { version = "0.2.0" }
```

Create a batch service and start sending requests:

```rust
use std::time::Duration;
use tower_batch::Batch;

// `my_service` implements `Service<BatchControl<MyRequest>>`
let batch = Batch::new(my_service, 100, Duration::from_millis(250));
```

If you prefer the [Tower layer] pattern:

```rust
use tower_batch::BatchLayer;

let layer = BatchLayer::new(100, Duration::from_millis(250));
```

## How it works

Your inner service must implement `Service<BatchControl<R>>` where `R` is the request type. The middleware sends two kinds of calls:

- **`BatchControl::Item(request)`** – buffer this request. Typically, you just push it onto a `Vec` and return `Ok(())`.
- **`BatchControl::Flush`** – process everything you have buffered, then return the result.

`Batch::new` spawns a background worker that owns the inner service. It forwards each incoming request as an `Item`, and triggers a `Flush` when the batch is full or the timer fires. `Batch` handles are cheap to clone – each clone shares the same worker, so you can hand them to multiple tasks.

## Examples

See the [`examples/`](examples/) directory:

- **[`sqlite_batch`](examples/sqlite_batch.rs)** – batch-insert rows into an in-memory SQLite database using the rarray virtual table.

Run an example with:

```sh
cargo run --example sqlite_batch
```

## License

This project is licensed under the [MIT](LICENSE) license.

### Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in `tower-batch` by you, shall be licensed as MIT, without any additional terms or conditions.

[Tower]: https://docs.rs/tower
[Tower layer]: https://docs.rs/tower/latest/tower/trait.Layer.html