Deveel.Events.Publisher.DeadLetter.EntityFramework 1.2.2-pre.2

Deveel Events

Deveel Events is a lightweight, extensible framework for building event-driven .NET applications, built on top of the CloudEvents standard.

The ambition of this framework is to implement a set of common patterns and practices for a simple and efficient event-driven architecture in .NET — from publishing domain events to consuming them, managing subscriptions, and validating event schemas — without reinventing the wheel every time a team needs to integrate across bounded contexts.

The current release focuses on the publishing side: a transport-agnostic layer that broadcasts domain events from a bounded context to any number of downstream consumers. Upcoming releases will introduce consumer adapters, persistent subscription registries, and additional transport channels. See the roadmap for the full plan.

Domain Events and DDD

Domain-Driven Design (DDD) treats domain events as first-class citizens of the model — facts about something that happened inside the domain, named in the ubiquitous language of domain experts (OrderPlaced, InvoiceIssued, UserRegistered).

Key properties of domain events:

• Immutable facts — they describe what happened, not what should happen.
• Decoupled producers and consumers — the producing bounded context does not need to know who is listening.
• Cross-context integration — events are the preferred way to share information across bounded contexts without tight coupling.
• Temporal decoupling — consumers can process events asynchronously, at their own pace.

Deveel Events implements the publishing side of this pattern: a transport-agnostic layer that broadcasts domain events from a bounded context to any number of downstream consumers, without prescribing how you model aggregates or build read models.

Event Schemas as Async API Contracts

Publishing an event is only half the story. Consumers need to know the shape of each event — its properties, types, and constraints — to deserialise it correctly and build reliable integrations. Without a formal contract, field renames silently break consumers and integration knowledge lives only in tribal memory.

Event schemas fill the same role for asynchronous messaging that OpenAPI/Swagger fills for REST APIs. The Deveel.Events.Schema package can derive a schema automatically from annotated data classes and export it as:

• JSON Schema — for schema-registry integration and tooling.
• YAML — for human-readable, version-controlled contract documents.
• AsyncAPI 2.x — a complete, machine-readable async API specification. AsyncAPI tooling can generate documentation sites, client SDKs, and mock servers from it.

Treat schemas as public API contracts: version them, prefer additive changes, and communicate breaking changes in advance.

Motivation

Applications frequently need to notify other parts of the system about domain events. Teams end up rewriting the same boilerplate — serialising payloads, constructing envelopes, wiring up transport clients — over and over again.

Deveel Events provides a single, consistent way to publish events across any transport, so teams can focus on domain logic instead of infrastructure plumbing.

CloudEvents Standard

All events are modelled as CloudEvent objects, ensuring maximum interoperability with cloud platforms and services that implement the CNCF CloudEvents specification.

Requirements

All packages in this solution multi-target the following runtimes:

Note: Deveel.Events.Schema.AsyncApi also requires the ASP.NET Core shared framework (Microsoft.AspNetCore.App), since it integrates with the Saunter AsyncAPI middleware.

Every package requires the Microsoft Dependency Injection infrastructure (Microsoft.Extensions.DependencyInjection). Below are the additional per-package dependencies automatically pulled in as transitive NuGet references:

Packages

Publishing

Package	Description	NuGet (Stable)	GitHub (Unstable)	Downloads
Deveel.Events.Annotations	Attributes for describing event metadata on data classes
Deveel.Events.Publisher	Core publisher infrastructure (EventPublisher, DI helpers)
Deveel.Events.Publisher.AzureServiceBus	Publish events to Azure Service Bus
Deveel.Events.Publisher.DeadLetter	Dead-letter handling, persistent replay abstractions, and replay workers
Deveel.Events.Publisher.DeadLetter.EntityFramework	Entity Framework Core persistence for dead-letter messages
Deveel.Events.Amqp.Annotations	AMQP-specific routing attributes (exchange, routing key)
Deveel.Events.Publisher.RabbitMq	Publish events to a RabbitMQ exchange
Deveel.Events.Publisher.MassTransit	Publish events through a MassTransit bus
Deveel.Events.Publisher.Webhook	Deliver events to HTTP webhook endpoints
Deveel.Events.Publisher.Outbox	Persist events in a transactional outbox for later relay
Deveel.Events.Publisher.Outbox.EntityFramework	Entity Framework Core repository and helpers for the outbox channel

Subscriptions

Package	Description	NuGet (Stable)	GitHub (Unstable)	Downloads
Deveel.Events.Subscriptions	Event dispatcher and subscription management with pluggable resolvers

Schema

Package	Description	NuGet (Stable)	GitHub (Unstable)	Downloads
Deveel.Events.Schema	Schema model, fluent builder, JSON writer, and validation
Deveel.Events.Schema.Yaml	Export an event schema as YAML
Deveel.Events.Schema.AsyncApi	Export schemas as an AsyncAPI 2.x document

Testing

Package	Description	NuGet (Stable)	GitHub (Unstable)	Downloads
Deveel.Events.TestPublisher	In-memory test channel for unit and integration tests

Documentation

The full documentation is published at events.deveel.org — including installation guides, concept references, channel adapters, schema export, and testing utilities.

The source of the documentation is also available in the docs/ folder of this repository | Section | Description | |---------|-------------| | Getting Started | Installation and quick-start guide | | Core Concepts | Publisher, channels, and event annotations | | Publisher Channels | Azure Service Bus, RabbitMQ, MassTransit, Webhook, Outbox, and Dead-Letter Replay | | Event Subscriptions | Event dispatcher, filters, routing, and custom resolvers | | Event Schema | Schema definition, export (JSON / YAML / AsyncAPI), and validation | | Testing | Unit-testing event publishing |

Future Work

The framework is still evolving. See the ROADMAP for the full description of every planned feature and the version milestone in which each is expected to ship.

v1.1 — Routing & Middleware ✅

• Event Subscription & Routing — subscribe to event types with attribute-based filtering and in-process routing
• Event Middleware Pipeline — composable cross-cutting hooks (logging, validation, correlation, tracing)

v1.2 — Reliability

• Event Replay & Dead-Letter Handling — capture and resubmit failed events with configurable retry and back-off
• Outbox Pattern Integration — guaranteed exactly-once publishing via a transactional outbox channel
• Event Scheduler & Deferred Publishing — defer event publishing to a future point in time or after a delay

v1.3 — Observability

• OpenTelemetry & Distributed Tracing Integration — propagate W3C trace context as CloudEvents extensions for end-to-end traces
• Event Store & Audit Log Channel — append-only persistence of every domain event for auditing and read-model rebuilding
• Schema Validation at Publish Time — validate event payloads against their registered schema before channel dispatch
• Publish Delivery Log — per-attempt operational record (channel, outcome, error code, latency, retry count) across pluggable storage backends

v1.4 — Schema Governance

• Event Versioning & Compatibility — breaking-change detection, upcasting pipeline, and version-aware routing
• AsyncAPI & Schema Export Improvements — compile-time auto-discovery, dotnet CLI tool, OpenAPI 3.1 webhook export

v1.5 — New Transports

• CloudEvents HTTP Binding for the Webhook Publisher — bring the existing Webhook publisher into full structured/binary content-mode compliance
• HTTP Publisher Channel — lightweight, sign-free point-to-point delivery to statically-configured endpoints
• gRPC Publisher Channel — low-latency service-to-service delivery using the CloudEvents gRPC protocol binding
• Apache Kafka Publisher Channel — publish CloudEvents to Kafka topics with partition key control and Schema Registry support
• Amazon SQS Publisher Channel — standard and FIFO queue delivery on AWS with batch publish and S3 offload
• Amazon SNS Publisher Channel — fan-out to SQS queues, Lambda functions, and HTTP endpoints via SNS topics
• Google Cloud Pub/Sub Publisher Channel — ordered delivery to GCP Pub/Sub topics with Workload Identity support
• NATS / JetStream Publisher Channel — ultra-low-latency delivery to NATS subjects or durable JetStream streams

v1.6 — Code Generation

• CloudEvent Factory Source Generator — Roslyn incremental generator that emits zero-reflection IEventConvertible.ToCloudEvent() implementations from [Event]-annotated partial classes, with compile-time diagnostics for annotation mistakes
• Schema Registration Source Generator — generator that pre-constructs all EventSchema instances at build time and emits an AddGeneratedEventSchemas(IServiceCollection) DI extension, eliminating startup reflection and enabling schema export without a running host
• Typed Domain Publisher Generator — generator that produces a strongly-typed IXxxEventPublisher interface and implementation per domain group, so services depend on a focused, mockable contract rather than the catch-all IEventPublisher

v2.0 — Event Consumers

• Webhook Consumer for ASP.NET Core — receive inbound CloudEvents over HTTP with HMAC signature verification and automatic routing
• Pre-built Webhook Consumer Adapters — ready-made payload mappers and signature verifiers for Facebook, SendGrid, Twilio, Stripe, GitHub, and Shopify
• RabbitMQ Consumer — consume CloudEvents from RabbitMQ queues and route them through the subscription registry
• Azure Service Bus Consumer — consume CloudEvents from Service Bus queues and topic subscriptions
• MassTransit Consumer Bridge — expose Deveel Events subscriptions as MassTransit consumers and vice versa

v2.1 — Testing & DX

• Expanded Testing Utilities — fluent publish assertions (AssertPublished, AssertNotPublished), in-memory event bus, and consumer-side test helpers
• Local Development Console Sink — zero-configuration channel that pretty-prints CloudEvents to the console during local development, with automatic exclusion in non-development environments
• .NET Aspire Integration — surface publish channels as Aspire resources for dashboard visibility, automatic broker provisioning, and OTLP trace export out of the box
• dotnet event CLI Extension — dotnet global tool adding dotnet event new, schema export, schema validate, schema diff, and channel add sub-commands for event scaffolding and schema governance
• Standalone deveel-events CLI — self-contained cross-platform executable and Docker image exposing the same command surface without requiring the .NET SDK, with GitHub Actions action and machine-readable SARIF output

v2.2 — Subscription Management

• Subscription Management Framework — provider-agnostic ISubscriptionStore abstraction with in-memory default and runtime lifecycle operations
• Relational Registry Provider (Entity Framework Core) — persist subscriptions in SQL Server, PostgreSQL, or SQLite with bundled migrations
• Document Registry Provider (MongoDB) — persist subscriptions as MongoDB documents with real-time change-stream synchronisation
• Subscription Management REST API — secured minimal-API endpoint group with OpenAPI metadata and change-notification webhooks

v2.3 — Framework Integrations

• MediatR Integration — bridge [Event]-annotated INotification types to the CloudEvents publish pipeline and route inbound CloudEvents back as MediatR notifications
• Wolverine Integration — emit CloudEvents as a Wolverine message side-effect and route inbound CloudEvents into the Wolverine runtime via IMessageBus
• Brighter Integration — publish CloudEvents as a post-handler pipeline step for Brighter ICommand / IEvent types and bridge inbound CloudEvents into the Brighter command processor

Monitor the open issues to see what is being actively worked on.

Contributors

Thanks go to all the people who have contributed to this project!

Contributing

We welcome bug reports, feature requests, and pull requests. Please read the Contributing Guidelines before submitting.

License

Released under the MIT License.

Built With

<p> <a href="https://dotnet.microsoft.com"><img align="left" src="https://raw.githubusercontent.com/devicons/devicon/master/icons/dotnetcore/dotnetcore-original.svg" alt=".NET" width="48" height="48"/></a>   <a href="https://github.com"><img align="left" src="https://raw.githubusercontent.com/devicons/devicon/master/icons/github/github-original.svg" alt="GitHub" width="48" height="48"/></a>   <a href="https://www.jetbrains.com/rider/"><img align="left" src="https://raw.githubusercontent.com/devicons/devicon/master/icons/rider/rider-original.svg" alt="Rider" width="48" height="48"/></a>   <a href="https://testcontainers.com"><img align="left" src="https://avatars.githubusercontent.com/u/13393021" alt="Testcontainers" width="48" height="48"/></a> </p>