Crate guts_realtime 

Guts Real-time

Real-time WebSocket support for the Guts code collaboration platform.

This crate provides WebSocket-based real-time updates for repository events, enabling live notifications and instant UI updates without page refresh.

Features

• Event Hub: Central management of WebSocket connections
• Subscriptions: Channel-based subscription model
• Event Broadcasting: Efficient event distribution to subscribed clients
• Notifications: User notification system

Channel Types

• repo:owner/name - All events for a repository
• repo:owner/name/prs - Pull request events only
• repo:owner/name/issues - Issue events only
• user:username - User notifications
• org:orgname - Organization events

Example

use guts_realtime::{EventHub, EventKind};
use std::sync::Arc;

// Create the event hub
let hub = Arc::new(EventHub::new());

// Connect a client
let (client, receiver) = hub.connect().unwrap();

// Subscribe to a repository
hub.handle_command(
    &client,
    guts_realtime::ClientCommand::Subscribe {
        channel: "repo:alice/myrepo".to_string(),
    },
).unwrap();

// Emit an event
hub.emit_event(
    "repo:alice/myrepo".to_string(),
    EventKind::Push,
    serde_json::json!({
        "ref": "refs/heads/main",
        "before": "abc123",
        "after": "def456"
    }),
);

WebSocket Protocol

Client -> Server Messages

// Subscribe to a channel
{"type": "subscribe", "channel": "repo:owner/name"}

// Unsubscribe from a channel
{"type": "unsubscribe", "channel": "repo:owner/name"}

// Ping for keepalive
{"type": "ping"}

Server -> Client Messages

// Subscription confirmed
{"type": "subscribed", "channel": "repo:owner/name"}

// Event notification
{"type": "event", "channel": "repo:owner/name", "event": "push", ...}

// Pong response
{"type": "pong"}

Architecture

┌─────────────────────────────────────────┐
│              EventHub                    │
│  ┌─────────────────────────────────┐    │
│  │         Clients Map              │    │
│  │  client_id -> Client            │    │
│  │    └─> subscriptions            │    │
│  │    └─> message sender           │    │
│  └─────────────────────────────────┘    │
│                  │                       │
│  ┌───────────────▼───────────────────┐  │
│  │     Broadcast Channel             │  │
│  │  (for external subscribers)       │  │
│  └───────────────────────────────────┘  │
└─────────────────────────────────────────┘

Re-exports

pub use client::Client;

pub use client::ClientId;

pub use client::ClientReceiver;

pub use error::RealtimeError;

pub use event::CommentEventData;

pub use event::EventKind;

pub use event::IssueEventData;

pub use event::PullRequestEventData;

pub use event::PushEventData;

pub use event::RealtimeEvent;

pub use event::ReviewEventData;

pub use hub::ClientCommand;

pub use hub::EventHub;

pub use hub::HubStats;

pub use hub::ServerMessage;

pub use notification::Notification;

pub use notification::NotificationMetadata;

pub use notification::NotificationPreferences;

pub use notification::NotificationType;

pub use subscription::Channel;

pub use subscription::ChannelType;

pub use subscription::ClientSubscriptions;

pub use subscription::MAX_SUBSCRIPTIONS_PER_CLIENT;

Modules

client

Client connection management.

error

Error types for the real-time module.

event

Real-time event types.

hub

Event hub for managing WebSocket connections and broadcasting.

notification

Notification types for user alerts.

subscription

Subscription management for real-time channels.