acuity-index-api-rs 0.1.2

High-level Rust client for the acuity-index WebSocket API.
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
82
83
84
85
86
87
88
89
90
91
92
93
94
95

# acuity-index-api-rs

High-level Rust client for the `acuity-index` WebSocket API.

Supports scalar custom keys and flat composite custom keys built from ordered
typed scalar values.

The indexer serves JSON-over-WebSocket on `ws://127.0.0.1:8172` by default.

Recent `acuity-index` server versions enforce connection and request limits.
Client integrations should expect connection attempts to fail under overload,
oversized custom keys to be rejected, idle connections to be closed, and
subscription requests beyond the per-connection cap to return a structured
`subscription_limit` server error.

## Quick Start

Add the crate to your `Cargo.toml`, connect to the indexer, and issue typed requests with `IndexerClient`.

Architecture overview: [`ARCHITECTURE.md`](./ARCHITECTURE.md)

Full API reference: [`API.md`](./API.md)

Current server-side limits and failure modes are documented in [`API.md`](./API.md).

```rust
use acuity_index_api_rs::{CustomKey, CustomScalarValue, IndexerClient, Key};

#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = IndexerClient::connect("ws://127.0.0.1:8172").await?;

    let spans = client.status().await?;
    println!("indexed spans: {spans:?}");

    let events = client
        .get_events(
            Key::Custom(CustomKey::composite(
                "item_revision",
                [
                    CustomScalarValue::Bytes32([0x11; 32].into()),
                    CustomScalarValue::U32(7),
                ],
            )),
            Some(100),
            None,
        )
        .await?;

    println!("{} matching events", events.events.len());
    for event_match in events.event_matches() {
        if let Some(decoded) = event_match.decoded_event {
            println!("{}::{}", decoded.pallet_name(), decoded.event_name());
        }
    }
    Ok(())
}
```

## Subscription Example

```rust
use acuity_index_api_rs::{CustomKey, CustomScalarValue, IndexerClient, Key};

#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = IndexerClient::connect("ws://127.0.0.1:8172").await?;

    let spans = client.status().await?;
    println!("indexed spans: {spans:?}");

    let mut subscription = client
        .subscribe_events(Key::Custom(CustomKey::composite(
            "item_revision",
            [
                CustomScalarValue::Bytes32([0x11; 32].into()),
                CustomScalarValue::U32(7),
            ],
        )))
        .await?;

    while let Some(notification) = subscription.next().await {
        let notification = notification?;
        if let Some(decoded) = notification.decoded_event {
            println!("{}::{}", decoded.pallet_name(), decoded.event_name());
        }
        break;
    }

    subscription.unsubscribe().await?;
    Ok(())
}
```

`subscribe_events` and `subscribe_status` return owned subscription handles. Dropping a handle removes only that local receiver. Calling `unsubscribe()` also sends the corresponding unsubscribe request to the server.