#websocket-server #hyperstack #streaming

hyperstack-server

WebSocket server and projection handlers for HyperStack streaming pipelines

34 releases

new 0.4.3 Feb 3, 2026
0.4.2 Feb 1, 2026
0.4.0 Jan 31, 2026
0.3.15 Jan 31, 2026
0.1.11 Jan 14, 2026

#368 in Magic Beans


Used in hyperstack

Custom license

660KB
15K SLoC

hyperstack-server

crates.io docs.rs 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

[dependencies]
hyperstack-server = "0.2"

Quick Start

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

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

Dependencies

~26–50MB
~702K SLoC