PushStream.Core 0.1.0-alpha

PushStream

Real-time server push without the complexity.

PushStream is an opinionated abstraction over Server-Sent Events (SSE) that makes implementing real-time server-to-client updates simple, safe, and maintainable.

Why PushStream?

Most real-time features only need one-way communication — the server pushing updates to clients:

• Task progress notifications
• Background job status
• AI/ML processing events
• Live activity feeds

Yet developers often reach for WebSockets or SignalR, introducing unnecessary complexity for simple push scenarios.

PushStream gives you real-time behavior without real-time complexity.

Quick Start

Server (ASP.NET Core)

// 1. Register PushStream services
builder.Services.AddPushStream();

// 2. Map an SSE endpoint
app.MapEventStream("/events");

// 3. Publish events from anywhere
public class TaskService
{
    private readonly IEventPublisher _publisher;

    public TaskService(IEventPublisher publisher)
    {
        _publisher = publisher;
    }

    public async Task ProcessTaskAsync(string taskId)
    {
        await _publisher.PublishAsync("task.started", new { taskId });
        
        // ... do work ...
        
        await _publisher.PublishAsync("task.progress", new { taskId, percentage = 50 });
        
        // ... complete work ...
        
        await _publisher.PublishAsync("task.completed", new { taskId, result = "Success" });
    }
}

Client (JavaScript/TypeScript)

import { EventClient } from 'pushstream-js';

const client = new EventClient('/events');

client.on('task.started', (data) => {
  console.log(`Task ${data.taskId} started`);
});

client.on('task.progress', (data) => {
  console.log(`Progress: ${data.percentage}%`);
});

client.on('task.completed', (data) => {
  console.log(`Completed: ${data.result}`);
});

client.connect();

That's it. No connection management. No reconnection logic. No heartbeat handling.

Features

When to Use PushStream

✅ Use PushStream when:

• Updates flow only from server to client
• You need instant feedback for long-running operations
• You want real-time without managing WebSocket complexity

❌ Don't use PushStream when:

• You need bi-directional messaging (use SignalR/WebSockets)
• You're building a chat application with client-to-client messaging
• You need request-response patterns over the same connection

Documentation

Project Structure

PushStream/
├── src/
│   ├── server/
│   │   ├── AbstractedSse/      # Core library
│   │   └── DemoApi/            # Sample API
│   └── client/
│       └── abstracted-sse-js/  # JavaScript client
├── docs/                       # Documentation
└── README.md

License

MIT

Contributing

Contributions are welcome! Please read the documentation first to understand the design philosophy and non-goals of the project.