BrighterCommand / BrighterCommand/Brighter

Consolidate Provider Packages (Inbox, Outbox, MessagingGateway, Locking, Luggage) for v11

Open
#4,216 0 comments 0 reactions 0 assignees View on GitHub
.NET 0 - Backlog Breaking Change V11
Dominant language
C#
Stars
2.5k
Forks
296
Avg merge
1d 11h
Merged PRs (30d)
21

Description

### Problem Statement
Brighter's current NuGet package ecosystem is highly fragmented across **five dimensions**: Inbox, Outbox, MessagingGateway, Locking, and Luggage. For a single provider, developers often need to install 3–5 separate micro-packages that share the same underlying client SDKs, connection logic, and configuration patterns.

This creates:
- **Cognitive overload** — discovering and managing dozens of tiny packages.
- **Version mismatch risk** — ensuring `Inbox.DynamoDB.V4`, `Outbox.DynamoDB.V4`, and `Locking.DynamoDB.V4` all align.
- **Unnecessary package proliferation** — many packages contain only a handful of types.

### Scope
This proposal targets **Brighter v11** as a breaking change. Rather than maintaining parallel deprecated packages across v10.x, we take advantage of the major version bump to restructure the package layout cleanly.

### Current State (Fragmented)

| Provider | Inbox | Outbox | Messaging Gateway | Locking | Luggage |
|----------|-------|--------|-------------------|---------|---------|
| **PostgreSQL** | `Paramore.Brighter.Inbox.PostgreSql` | `Paramore.Brighter.Outbox.PostgreSql` | — | `Paramore.Brighter.Locking.PostgresSql` | — |
| **MySQL** | `Paramore.Brighter.Inbox.MySql` | `Paramore.Brighter.Outbox.MySql` | — | `Paramore.Brighter.Locking.MySql` | — |
| **MsSql** | `Paramore.Brighter.Inbox.MsSql` | `Paramore.Brighter.Outbox.MsSql` | `Paramore.Brighter.MessagingGateway.MsSql` | — | — |
| **DynamoDB** | `Paramore.Brighter.Inbox.DynamoDB` / `.V4` | `Paramore.Brighter.Outbox.DynamoDB` / `.V4` | — | `Paramore.Brighter.Locking.DynamoDB` / `.V4` | — |
| **MongoDB** | `Paramore.Brighter.Inbox.MongoDB` | `Paramore.Brighter.Outbox.MongoDB` | — | `Paramore.Brighter.Locking.MongoDb` | — |
| **Spanner** | `Paramore.Brighter.Inbox.Spanner` | `Paramore.Brighter.Outbox.Spanner` | — | — | — |
| **RabbitMQ** | — | — | `Paramore.Brighter.MessagingGateway.RMQ` / `.RMQ.Async` | — | — |
| **Kafka** | — | — | `Paramore.Brighter.MessagingGateway.Kafka` | — | — |
| **Azure Service Bus** | — | — | `Paramore.Brighter.MessagingGateway.AzureServiceBus` | `Paramore.Brighter.Locking.Azure` | — |
| **AWS SQS** | — | — | `Paramore.Brighter.MessagingGateway.AWSSQS` / `.V4` | — | — |
| **GCP Pub/Sub** | — | — | `Paramore.Brighter.MessagingGateway.GcpPubSub` | — | — |
| **Redis** | — | — | `Paramore.Brighter.MessagingGateway.Redis` | — | — |

Additionally, **Luggage** (ClaimCheck) stores are split by storage backend (S3, GCS, Azure Blob), further multiplying the package count.

### Proposed Consolidation for v11
Group all implementations **per service** into single packages. When two implementations of the same service rely on **different underlying SDKs or dependency trees**, they remain as separate packages to avoid forcing unwanted transitive dependencies on consumers.

#### v11 Consolidated Package Structure

| New v11 Package | Contains (previously separate packages) |
|-----------------|---------------------------------------|
| `Paramore.Brighter.PostgreSql` | Inbox, Outbox, Locking, connection/transaction providers |
| `Paramore.Brighter.MySql` | Inbox, Outbox, Locking, connection/transaction providers |
| `Paramore.Brighter.MsSql` | Inbox, Outbox, Locking, MessagingGateway, connection/transaction providers |
| `Paramore.Brighter.DynamoDB` | Inbox, Outbox, Locking *(v3 SDK)* |
| `Paramore.Brighter.DynamoDB.V4` | Inbox, Outbox, Locking *(v4 SDK)* |
| `Paramore.Brighter.MongoDB` | Inbox, Outbox, Locking |
| `Paramore.Brighter.Spanner` | Inbox, Outbox |
| `Paramore.Brighter.Firestore` | Inbox, Outbox, Locking |
| `Paramore.Brighter.RabbitMQ` | `MessagingGateway.RMQ` *(sync)* |
| `Paramore.Brighter.RabbitMQ.Async` | `MessagingGateway.RMQ.Async` *(async)* |
| `Paramore.Brighter.Kafka` | MessagingGateway.Kafka |
| `Paramore.Brighter.AzureServiceBus` | MessagingGateway.AzureServiceBus, Locking.Azure |
| `Paramore.Brighter.AWSSQS` | MessagingGateway.AWSSQS *(v3 SDK)* |
| `Paramore.Brighter.AWSSQS.V4` | MessagingGateway.AWSSQS.V4 *(v4 SDK)* |
| `Paramore.Brighter.GcpPubSub` | MessagingGateway.GcpPubSub |
| `Paramore.Brighter.Redis` | MessagingGateway.Redis |
| `Paramore.Brighter.S3` | Luggage.S3 |
| `Paramore.Brighter.GCS` | Luggage.GCS |
| `Paramore.Brighter.AzureBlob` | Luggage.AzureBlob |

#### Why This Structure?
- **Shared SDK dependencies**: All DynamoDB v3 packages depend on the same AWS SDK v3. All PostgreSQL packages depend on `Npgsql`. Consolidating eliminates redundant dependency declarations.
- **Different SDKs stay separate**: When a service has two implementations targeting different major SDK versions (e.g., AWS SDK v3 vs v4) or different runtime models (sync vs async RabbitMQ with different dependency trees), they remain independent so consumers only pull in what they use.
- **Cloud services stay decoupled**: A developer using AWS SQS for messaging but PostgreSQL for storage only pulls in what they need. No forced references to DynamoDB or S3 just because they're on AWS.
- **Discoverability**: A developer using DynamoDB v4 only needs one package: `Paramore.Brighter.DynamoDB.V4`.

### Benefits
1. **Dramatically reduced package surface area** — from ~40+ provider-specific packages to ~19 consolidated ones.
2. **Simpler versioning** — one version per service (per SDK variant). No more "did I update the inbox but not the outbox?"
3. **Reduced maintenance** — fewer `.csproj` files, fewer NuGet pushes, fewer release notes to manage.
4. **Better alignment with .NET ecosystem norms** — e.g., `Npgsql.EntityFrameworkCore.PostgreSQL` bundles everything for PostgreSQL.
5. **Easier onboarding** — new users don't need a spreadsheet to figure out which 5 packages they need for a DynamoDB-backed microservice.

Contributor guide

Open the contributing guide

Research direction

Start by inventorying the existing provider .csproj files and the fragmented NuGet packages listed in the issue, then map their implementations and dependencies to the proposed v11 package boundaries. Done means the consolidated packages, including separate SDK and sync/async variants, build and preserve the listed provider capabilities without unwanted dependencies.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp
Domain
build-system, developer-experience
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.