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

          HTTP POST
              │
              ▼
          Pipey Server
              │
          Redis + Arifa
              │
              ▼
        WebSocket Client

API

Open a Pipe

Connect a WebSocket for a specific user.

GET /api/v1/ws/pipey?user_id=<uuid>

Example

ws://localhost:8080/api/v1/ws/pipey?user_id=550e8400-e29b-41d4-a716-446655440000

Publish an Event

POST /api/v1/pipey/publish
Content-Type: application/json

Request Body

{
  "recipient": "550e8400-e29b-41d4-a716-446655440000",
  "payload": {
    "message": "Hello Pipey!"
  }
}

Success Response

200 OK

{
  "success": true,
  "message": "Event published"
}

Recipient Offline

If the recipient has no active WebSocket connection, Pipey will not publish the event.

404 Not Found

{
  "success": false,
  "message": "Recipient is offline"
}

Server Error

If Redis or the event router is unavailable.

500 Internal Server Error

{
  "success": false,
  "message": "Failed to publish event"
}

JavaScript Example

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

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