WebSync for .NET Core

A modern, open-source re-implementation of the WebSync real-time messaging library, rebuilt from the ground up for .NET Core. WebSync for .NET Core brings scalable publish/subscribe, channel-based messaging, and real-time event streaming to ASP.NET Core applications — with full support for WebSockets and long-polling fallback.

---

✨ Features

• 📡 Real-time messaging via WebSockets with long-polling fallback
• 📢 Publish / Subscribe channel model — broadcast to many clients with ease
• 🔐 Token-based authentication for securing channels
• 🔁 Auto-reconnect with configurable backoff strategy
• 🧩 Middleware integration — plug directly into ASP.NET Core pipeline
• 🌐 Horizontal scaling support via Redis backplane
• ⚡ High performance — built on System.Net.WebSockets and System.Threading.Channels
• 🧪 Fully testable with clean abstractions and dependency injection support
• 📦 Lightweight — minimal dependencies, no heavy frameworks required

---

📦 Installation

dotnet add package WebSync

Or via the NuGet Package Manager:

Install-Package WebSync

For Redis backplane support (optional, for multi-server deployments):

dotnet add package WebSync.Backplane.Redis

---

🚀 Quick Start

1. Register WebSync in your app

// Program.cs
using WebSync;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddWebSync(options =>
{
    options.HeartbeatInterval = TimeSpan.FromSeconds(30);
    options.MaxMessageSize = 64 * 1024; // 64 KB
});

var app = builder.Build();

app.UseWebSync(); // Maps the WebSync endpoint

app.Run();

2. Publish a message from the server

public class NotificationService
{
    private readonly IWebSyncPublisher _publisher;

    public NotificationService(IWebSyncPublisher publisher)
    {
        _publisher = publisher;
    }

    public async Task NotifyAsync(string channel, object payload)
    {
        await _publisher.PublishAsync(channel, payload);
    }
}

3. Subscribe on the client (JavaScript)

const client = new WebSyncClient("wss://yourapp.com/websync");

client.subscribe("/notifications", (message) => {
    console.log("Received:", message.data);
});

client.connect();

---

⚙️ Configuration

builder.Services.AddWebSync(options =>
{
    options.Endpoint              = "/websync";          // WebSocket endpoint path
    options.HeartbeatInterval     = TimeSpan.FromSeconds(30);
    options.MaxMessageSize        = 65536;               // bytes
    options.AllowedOrigins        = ["https://myapp.com"];
    options.EnableCompression     = true;
    options.AuthenticationScheme  = "Bearer";            // optional auth
});

Redis Backplane (for multi-server / cloud deployments)

builder.Services.AddWebSync()
       .AddRedisBackplane(options =>
       {
           options.ConnectionString = "localhost:6379";
       });

---

🔐 Authentication & Channel Security

WebSync supports token-based channel authorization out of the box:

builder.Services.AddWebSync(options =>
{
    options.OnAuthorizeChannel = (context, channel) =>
    {
        // Return true to allow, false to deny
        return context.User.Identity?.IsAuthenticated == true;
    };
});

---

📖 Documentation

Full documentation, guides, and API reference are available at:

docs.yourproject.com (coming soon)

Topics covered:

• Getting Started
• Channel Patterns
• Authentication
• Redis Backplane
• Client SDK
• Migrating from legacy WebSync

---

🗺️ Roadmap

• JavaScript client SDK (npm package)
• Presence channels (online user tracking)
• Message history / replay
• gRPC transport support
• Azure Service Bus backplane
• Dashboard UI for monitoring channels

---

🤝 Contributing

Contributions are very welcome! Please read CONTRIBUTING.md for guidelines on how to open issues, submit pull requests, and run the test suite.

# Clone the repo
git clone https://github.com/yourusername/websync-dotnet.git
cd websync-dotnet

# Restore and build
dotnet restore
dotnet build

# Run tests
dotnet test

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

🙏 Acknowledgements

This project is a community-driven, open-source re-implementation of the original WebSync library by Frozen Mountain Software, rebuilt for modern .NET Core. It is not affiliated with or endorsed by Frozen Mountain Software.

---

Made with ❤️ for the .NET community