# Kanject EventHub

A strongly-typed, serverless event bus on AWS — publish typed events and fan them out to subscribers over SNS + SQS, without hand-writing topic and queue wiring. Deployed into your own account.

> **Package name:** The product is branded **EventHub**, but the NuGet package and namespace are **`Kanject.ServerlessEventHub`** (provider-versioned, e.g. `Kanject.ServerlessEventHub.Provider.AwsSnsV4`). The code samples below use the real names.

> **Note:** Developer guide. For the full feature tour, see the [EventHub product page](https://www.kanject.com/baas/eventhub/).

**You'll learn**

- Provision EventHub into your AWS account
- Register the client with `AddServerlessEventHubClient`
- Publish typed `[HubEvent]` events
- Subscribe with an `IEventHubRequestHandler<T>` bound to an SQS queue

## Provision

```bash
kanject baas deploy eventhub --env dev
```

## Register it in your service

Register the client with `AddServerlessEventHubClient(serviceName, config)`. The `serviceName` scopes this service's topics and queues on the shared bus; the transport is **SNS + SQS fan-out** (EventBridge is used only for scheduled events).

```csharp
using Kanject.ServerlessEventHub.Provider.AwsSnsV4.Extensions;

var builder = WebApplication.CreateBuilder(args);

// serviceName scopes this service's topics/queues on the shared bus.
builder.Services.AddServerlessEventHubClient(
    serviceName: "orders",
    new AwsServerlessEventHubConfiguration { /* region, schema, … */ });

var app = builder.Build();
app.Run();
```

## Publish typed events

Events are C# classes marked with `[HubEvent(Topic, Version)]`. Inject `IServerlessEventHubClient` (or `IPublishEventAction`) and call `PublishAsync` — the event goes to its SNS topic, and subscribed SQS queues fan out from there.

```csharp
using Kanject.ServerlessEventHub.Abstractions.Attributes;

// Events are typed classes, marked with a topic + version.
[HubEvent(Topic = "order.completed", Version = 1)]
public sealed class OrderCompleted
{
    public string OrderId { get; set; } = "";
    public string UserId  { get; set; } = "";
    public decimal Amount { get; set; }
}

// Publish: inject IServerlessEventHubClient (or IPublishEventAction).
public class OrderService(IServerlessEventHubClient hub)
{
    public Task PublishAsync(OrderCompleted evt)
        => hub.PublishAsync(evt);   // → SNS topic; SQS subscribers fan out
}
```

## Subscribe

A subscriber implements `IEventHubRequestHandler<TEventArgs>`. Register it with `AddEventHubHandler<,>()` and bind an SQS queue to the topics it consumes with `SubscribeQueueToTopic` — an explicit infrastructure wiring, not attribute auto-magic.

```csharp
// Subscribe: implement IEventHubRequestHandler<TEventArgs>, then register it
// and bind an SQS queue to the topic(s) it consumes.
public sealed class LedgerProjector : IEventHubRequestHandler<OrderCompletedArgs>
{
    public Task OnIncomingRequest(object sender, EventHubRequestHandlerArgs e)
    {
        // handle the delivered event
        return Task.CompletedTask;
    }
}

// Composition root:
services.AddEventHubHandler<LedgerProjector, OrderCompletedArgs>();
services.SubscribeQueueToTopic("orders-ledger", "order.completed");
```

## What you get

- **Typed events** — a C# class per event, marked `[HubEvent(Topic, Version)]`.
- **SNS + SQS fan-out** — publish to a topic; each subscriber drains its own SQS queue.
- **Explicit subscriptions** — `IEventHubRequestHandler<T>` + `AddEventHubHandler<,>()` + `SubscribeQueueToTopic`.
- **Service scoping** — `serviceName` namespaces each service's topics and queues on the shared bus.
- **Scheduled events** — an EventBridge scheduling extension for time-based publishes.

> **Pitfall:** Subscriptions are explicit infrastructure: a new handler needs both `AddEventHubHandler<,>()` **and** a `SubscribeQueueToTopic` binding, and takes effect on deploy — adding a subscriber is an infra change, not a hot reload.

**Recap**

- Provision with `kanject baas deploy eventhub`; register with `AddServerlessEventHubClient(serviceName, config)`.
- The real package is `Kanject.ServerlessEventHub` (brand: EventHub); transport is SNS + SQS fan-out.
- Publish `[HubEvent]` classes via `IServerlessEventHubClient.PublishAsync`.
- Subscribe with `IEventHubRequestHandler<T>` + `AddEventHubHandler<,>()` + `SubscribeQueueToTopic`.

## Related modules

- **[Insights](https://www.kanject.com/docs/baas-insights/)** — Feed events into analytics.
- **[NotificationHub](https://www.kanject.com/docs/baas-notifications/)** — Notify on events.
- **[Wallet](https://www.kanject.com/docs/baas-wallet/)** — Drive posting profiles from transaction events.

> **Next step:** EventHub is the backbone the other modules plug into — see [NotificationHub](https://www.kanject.com/docs/baas-notifications/), [Insights](https://www.kanject.com/docs/baas-insights/), and [Wallet](https://www.kanject.com/docs/baas-wallet/), or the [BaaS deployment guide](https://www.kanject.com/docs/baas/).

---
_Source: https://www.kanject.com/docs/baas-eventhub/ · Kanject Docs_