WART-Core 6.0.0

WART - WebApi Real Time

<img src="https://github.com/engineering87/WART/blob/develop/wart_logo.jpg" width="300">

WART is a lightweight C# .NET library that extends your Web API controllers to forward incoming calls directly to a SignalR Hub.
The Hub broadcasts rich, structured events containing request and response details in real-time.
Supports JWT and Cookie Authentication for secure communication.

📑 Table of Contents

• Features
• Installation
• How It Works
• Usage
  • Basic Setup
  • Using JWT Authentication
  • Custom Hub Names
  • Multiple Hubs
  • Client Example
• Supported Authentication Modes
• Excluding APIs from Event Propagation
• Group-based Event Dispatching
• NuGet
• Contributing
• License
• Contact

✨ Features

• Converts REST API calls into SignalR events, enabling real-time communication.
• Provides controllers (WartController, WartControllerJwt, WartControllerCookie) for automatic SignalR event broadcasting.
• Supports JWT authentication for SignalR hub connections.
• Allows API exclusion from event broadcasting with [ExcludeWart] attribute.
• Enables group-specific event dispatching with [GroupWart("group_name")].
• Configurable middleware (AddWartMiddleware) for flexible integration.

📦 Installation

Install from NuGet

dotnet add package WART-Core

⚙️ How it works

WART overrides OnActionExecuting and OnActionExecuted in a custom base controller. For every API request/response:

1. Captures request and response data.
2. Wraps them in a WartEvent.
3. Publishes it through a SignalR Hub to all connected clients.

🚀 Usage

Basic Setup

Extend your API controllers from WartController:

using WART_Core.Controllers;
using WART_Core.Hubs;

[ApiController]
[Route("api/[controller]")]
public class TestController : WartController
{
    public TestController(IHubContext<WartHub> hubContext, ILogger<WartController> logger)
        : base(hubContext, logger) { }
}

Register WART in Startup.cs:

using WART_Core.Middleware;

public void ConfigureServices(IServiceCollection services)
{
    services.AddWartMiddleware(); // No authentication
}

public void Configure(IApplicationBuilder app)
{
    app.UseWartMiddleware();
}

Using JWT Authentication

services.AddWartMiddleware(hubType: HubType.JwtAuthentication, tokenKey: "your_secret_key");
app.UseWartMiddleware(HubType.JwtAuthentication);

Extend from WartControllerJwt:

public class TestController : WartControllerJwt
{
    public TestController(IHubContext<WartHubJwt> hubContext, ILogger<WartControllerJwt> logger)
        : base(hubContext, logger) { }
}

Custom Hub Names

You can specify custom hub routes:

app.UseWartMiddleware("customhub");

Multiple Hubs

You can configure multiple hubs at once by passing a list of hub names:

var hubs = new[] { "orders", "products", "notifications" };

app.UseWartMiddleware(hubs);

This is useful for separating traffic by domain.

Client Example

Without authentication:

var hubConnection = new HubConnectionBuilder()
    .WithUrl("http://localhost:5000/warthub")
    .Build();

hubConnection.On<string>("Send", data =>
{
    // 'data' is a WartEvent JSON
});

await hubConnection.StartAsync();

With JWT authentication:

var hubConnection = new HubConnectionBuilder()
    .WithUrl("http://localhost:5000/warthub", options =>
    {
        options.AccessTokenProvider = () => Task.FromResult(GenerateToken());
    })
    .WithAutomaticReconnect()
    .Build();

hubConnection.On<string>("Send", data =>
{
    // Handle WartEvent JSON
});

await hubConnection.StartAsync();

🔐 Supported Authentication Modes

⚙️ Authentication mode is selected through the HubType configuration in the application startup.

🚫 Excluding APIs from Event Propagation

There might be scenarios where you want to exclude specific APIs from propagating events to connected clients. This can be particularly useful when certain endpoints should not trigger updates, notifications, or other real-time messages through SignalR. To achieve this, you can use a custom filter called ExcludeWartAttribute. By decorating the desired API endpoints with this attribute, you can prevent them from being included in the SignalR event propagation logic, for example:

[HttpGet("{id}")]
[ExcludeWart]
public ActionResult<TestEntity> Get(int id)
{
    var item = Items.FirstOrDefault(x => x.Id == id);
    if (item == null)
    {
        return NotFound();
    }
    return item;
}

👥 Group-based Event Dispatching

WART enables sending API events to specific groups in SignalR by specifying the group name in the query string. This approach allows for flexible and targeted event broadcasting, ensuring that only the intended group of clients receives the event. By decorating an API method with [GroupWart("group_name")], it is possible to specify the SignalR group name to which the dispatch of specific events for that API is restricted. This ensures that only the clients subscribed to the specified group ("SampleGroupName") will receive the related events, allowing for targeted, group-based communication in a SignalR environment.

[HttpPost]
[GroupWart("SampleGroupName")]
public ActionResult<TestEntity> Post([FromBody] TestEntity entity)
{
    Items.Add(entity);
    return entity;
}

By appending ?WartGroup=group_name to the URL, the library enables dispatching events from individual APIs to a specific SignalR group, identified by group_name. This allows for granular control over which clients receive the event, leveraging SignalR’s built-in group functionality.

📦 NuGet

The library is available on NuGet.

🤝 Contributing

Contributions are welcome! Steps to get started:

• Setting up Git
• Fork the repository
• Open an issue if you encounter a bug or have a suggestion for improvements/features
• Submit a Pull Request.

📄 License

WART source code is available under MIT License, see license in the source.

📬 Contact

Please contact at francesco.delre[at]protonmail.com for any details.