# Pipey
A lightweight HTTP → WebSocket event delivery service written in Rust.
Pipey lets applications publish realtime events over HTTP and instantly deliver them to connected WebSocket clients.
Built with **Actix Web**, **WebSockets**, **Redis**, and **Arifa**.
> Pipey is under active development.
## Features
- HTTP → WebSocket event delivery
- User-targeted messaging
- Redis-backed routing
- Automatic heartbeat
- Automatic client cleanup
- Low latency
- Async-first
- Lightweight
- Production-ready architecture
## Architecture
```text
HTTP POST
│
▼
Pipey Server
│
Redis + Arifa
│
▼
WebSocket Client
```
## API
### Open a Pipe
Connect a WebSocket for a specific user.
```http
GET /api/v1/ws/pipey?user_id=<uuid>
```
Example
```text
ws://localhost:8080/api/v1/ws/pipey?user_id=550e8400-e29b-41d4-a716-446655440000
```
## Publish an Event
```http
POST /api/v1/pipey/publish
Content-Type: application/json
```
Request Body
```json
{
"recipient": "550e8400-e29b-41d4-a716-446655440000",
"payload": {
"message": "Hello Pipey!"
}
}
```
### Success Response
**200 OK**
```json
{
"success": true,
"message": "Event published"
}
```
### Recipient Offline
If the recipient has no active WebSocket connection, Pipey will not publish the event.
**404 Not Found**
```json
{
"success": false,
"message": "Recipient is offline"
}
```
### Server Error
If Redis or the event router is unavailable.
**500 Internal Server Error**
```json
{
"success": false,
"message": "Failed to publish event"
}
```
## JavaScript Example
```javascript
const socket = new WebSocket(
"ws://localhost:8080/api/v1/ws/pipey?user_id=550e8400-e29b-41d4-a716-446655440000"
);
socket.onmessage = ({ data }) => {
const event = JSON.parse(data);
console.log(event);
};
```
Publish an event
```bash
curl -X POST http://localhost:8080/api/v1/pipey/publish \
-H "Content-Type: application/json" \
-d '{
"recipient":"550e8400-e29b-41d4-a716-446655440000",
"payload":{
"message":"Hello from Pipey!"
}
}'
```
## How It Works
1. A client opens a WebSocket connection to Pipey.
2. Pipey subscribes the client to its private user channel.
3. Your backend sends an HTTP request to `/api/v1/pipey/publish`.
4. Pipey checks whether the recipient is online.
5. If the user is online, the event is routed through Redis and delivered instantly.
6. If the user is offline, Pipey returns a `404 Recipient is offline` response and nothing is published.
## Tech Stack
- Rust
- Actix Web
- Actix WebSocket
- Redis
- Arifa