HoseWatcher

A real-time Bluesky firehose relay built on Cloudflare Workers. This service connects to the Bluesky firehose, processes the AtProto events, and relays them to clients via WebSockets.

## 🚰 What is HoseWatcher?

HoseWatcher is a relay server that streams real-time data from the Bluesky firehose to connected clients. The Bluesky firehose provides a continuous stream of all activities happening on the Bluesky social network (posts, likes, follows, etc.).

This project was inspired by a similar concept that used the Twitter firehose (as mentioned in the code comments referencing a YouTube video).

🛠️ Technical Overview

HoseWatcher is built on:

• Cloudflare Workers for serverless deployment
• WebSockets for real-time communication
• CBOR (Concise Binary Object Representation) for decoding the AtProto events

The service acts as a middleman between clients and the Bluesky firehose:

1. Clients connect to HoseWatcher via WebSocket
2. HoseWatcher maintains a connection to the Bluesky firehose
3. Events from the firehose are decoded from CBOR format
4. Processed events are relayed to clients as JSON

🚀 Getting Started

Prerequisites

• Cloudflare account
• Node.js and npm installed

Installation

1. Clone the repository

git clone https://github.com/v0id-user/hosewatcher.git
cd hosewatcher

2. Install dependencies

npm install

3. Configure environment variables in your wrangler.jsonc:

"vars": {
  "HOSER_ENDPOINT": "your-worker-endpoint",
  "DEBUG": false
}

4. Deploy to Cloudflare

npm run deploy

Usage

1. Connect to the WebSocket endpoint
2. Start receiving real-time events from the Bluesky network

🔍 How It Works

The server handles two main types of connections:

• HTTP requests for basic info
• WebSocket connections for streaming data

When a client connects via WebSocket:

1. The server establishes a connection to the Bluesky firehose
2. The server decodes incoming CBOR-encoded events
3. Decoded events are forwarded to the client in JSON format

🙏 Credits & Inspiration

This project draws inspiration and code from:

• The implementation of a Twitter firehose visualizer from a YouTube video
• ATProto Firehose implementation by kcchu
• The ATProto Documentation for understanding firehose handling
• CBOR specifications for handling the binary data format

👤 Author

Made with ❤️ by @v0id_user
GitHub: https://github.com/v0id-user
Website: https://tree.v0id.me

📝 License

MIT License