hitbox 0.1.0

Asynchronous caching framework in Rust.
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
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81

# hitbox

[![Build status](https://github.com/hit-box/hitbox/actions/workflows/CI.yml/badge.svg)](https://github.com/hit-box/hitbox/actions?query=workflow)
[![Coverage Status](https://codecov.io/gh/hit-box/hitbox/branch/master/graph/badge.svg?token=tgAm8OBLkY)](https://codecov.io/gh/hit-box/hitbox)

Hitbox is an asynchronous caching framework supporting multiple backends and suitable
for distributed and for single-machine applications.

## Framework integrations
- [x] [Actix](https://github.com/hit-box/hitbox/tree/master/hitbox-actix)
- [ ] Actix-Web

 ## Features
 - [x] Automatic cache key generation.
 - [x] Multiple cache backend implementations:
 - [x] Stale cache mechanics.
 - [ ] Cache locks for [dogpile effect] preventions.
 - [ ] Distributed cache locks.
 - [ ] Detailed metrics out of the box.

## Backend implementations
- [x] [Redis](https://github.com/hit-box/hitbox/tree/master/hitbox-backend)
- [ ] In-memory backend

 ## Feature flags
 * derive - Support for [Cacheable] trait derive macros.
 * metrics - Support for metrics.

 ## Restrictions
 Default cache key implementation based on serde_qs crate
 and have some [restrictions](https://docs.rs/serde_qs/latest/serde_qs/#supported-types).

## Documentation
* [API Documentation](https://docs.rs/hitbox/)
* [Examples](https://github.com/hit-box/hitbox/tree/master/examples/examples)

## Example

Dependencies:

```toml
[dependencies]
hitbox = "0.1"
```

Code:

> **_NOTE:_** Default cache key implementation based on serde_qs crate
> and have some [restrictions](https://docs.rs/serde_qs/latest/serde_qs/#supported-types).

First, you should derive [Cacheable] trait for your struct or enum:

```rust
use hitbox::prelude::*;
use serde::{Deserialize, Serialize};

#[derive(Cacheable, Serialize)] // With features=["derive"]
struct Ping {
    id: i32,
}
```
Or implement that trait manually:

```rust
use hitbox::{Cacheable, CacheError};
struct Ping { id: i32 }
impl Cacheable for Ping {
    fn cache_key(&self) -> Result<String, CacheError> {
        Ok(format!("{}::{}", self.cache_key_prefix(), self.id))
    }

    fn cache_key_prefix(&self) -> String { "Ping".to_owned() }
}
```

[Cacheable]: https://docs.rs/hitbox/latest/hitbox/trait.Cacheable.html
[CacheableResponse]: https://docs.rs/hitbox/trait.CacheableResponse.html
[Backend]: https://docs.rs/hitbox/hitbox_backend/trait.Backend.html
[RedisBackend]: https://docs.rs/hitbox/hitbox_redis/actor/struct.RedisActor.html
[hitbox-actix]: https://docs.rs/hitbox/hitbox_actix/index.html
[dogpile effect]: https://www.sobstel.org/blog/preventing-dogpile-effect/