hyperstack-server 0.3.0

WebSocket server and projection handlers for HyperStack streaming pipelines
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
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

# hyperstack-server

[![crates.io](https://img.shields.io/crates/v/hyperstack-server.svg)](https://crates.io/crates/hyperstack-server)
[![docs.rs](https://docs.rs/hyperstack-server/badge.svg)](https://docs.rs/hyperstack-server)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

WebSocket server and projection handlers for HyperStack streaming pipelines.

## Overview

This crate provides a builder API for creating HyperStack servers that:

- Process Solana blockchain data via Yellowstone gRPC
- Parse and transform data using generated IDL parsers and the HyperStack VM
- Stream entity updates over WebSockets to connected clients
- Support multiple streaming modes (State, List, Append)
- Monitor stream health and connectivity status

## Installation

```toml
[dependencies]
hyperstack-server = "0.2"
```

## Quick Start

```rust
use hyperstack_server::{Server, Spec};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    Server::builder()
        .spec(my_spec())
        .websocket()
        .bind("[::]:8877".parse()?)
        .health_monitoring()
        .start()
        .await
}
```

### With Configuration

```rust
use hyperstack_server::{Server, WebSocketConfig, HealthConfig};
use std::time::Duration;

Server::builder()
    .spec(my_spec())
    .websocket_config(WebSocketConfig {
        bind_addr: "[::]:8877".into(),
        max_clients: 1000,
        message_queue_size: 100,
    })
    .health_config(HealthConfig::new()
        .with_heartbeat_interval(Duration::from_secs(30))
        .with_health_check_timeout(Duration::from_secs(10)))
    .start()
    .await
```

## Architecture

```
┌─────────────────────┐
│  Yellowstone gRPC   │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│  Vixen Runtime      │  ← Generated from IDL
└──────────┬──────────┘
           │
           ▼
┌──────────────────────┐
│  HyperStack VM       │  ← Processes bytecode
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│  Projector           │  ← Mutations → Frames
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│  BusManager          │  ← Pub/Sub routing
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│  WebSocket Server    │  ← Streams to clients
└──────────────────────┘
```

## Feature Flags

| Feature | Default | Description |
|---------|---------|-------------|
| `otel` | No | OpenTelemetry integration for metrics and distributed tracing |

## Health Monitoring

Built-in health monitoring tracks stream connectivity and detects issues:

- **Connection Status Tracking** - Monitors stream states (Connected, Disconnected, Reconnecting, Error)
- **Event Staleness Detection** - Warns when connected but not receiving events
- **Error Counting** - Tracks and logs error frequency for alerting
- **Connection Duration** - Records uptime for debugging stability issues

## Module Structure

```
hyperstack-server/
├── src/
│   ├── lib.rs              # Server & ServerBuilder API
│   ├── bus.rs              # Event bus manager
│   ├── config.rs           # Configuration types
│   ├── runtime.rs          # Runtime orchestrator
│   ├── projector.rs        # Mutation → Frame transformation
│   ├── health.rs           # Health monitoring
│   ├── view/               # View registry & specs
│   └── websocket/          # WebSocket infrastructure
├── Cargo.toml
└── README.md
```

## Dependencies

- `tokio` - Async runtime
- `tokio-tungstenite` - WebSocket support
- `yellowstone-vixen` - Yellowstone gRPC integration
- `hyperstack-interpreter` - HyperStack VM and bytecode

## License

Apache-2.0