Roadmap: Deep Storage Dedup (RelationalMessageStore<T>)

Priority: High (maintainability) Production tier: Not shipped: internal refactor only; no consumer-facing API change when done correctly Status: Planned (post v6.0 Core GA)

Summary

v6 introduced folder-level shared storage helpers under src/LiteBus.Storage.EntityFrameworkCore/Stores/ and src/LiteBus.Storage.PostgreSql/Stores/. Inbox and outbox adapters still carry large, parallel implementations (PostgreSqlInboxStore, PostgreSqlOutboxStore, EfCoreInboxStore, EfCoreOutboxStore).

This roadmap item tracks a deep dedup: collapse the shared lease, persist, batch idempotency, and query paths into generic relational store cores, while axis-specific packages remain thin typed facades and public store interfaces stay unchanged.

Problem

Deep dedup mirrors what v6 already did for processors in LiteBus.Messaging/Processing/: one engine, two thin shells.

Goal

Introduce internal generic store cores (working names below) inside existing layer-3 packages: no new NuGet package IDs:

LiteBus.Storage.PostgreSql/Stores/
  RelationalPostgreSqlMessageStore<TEnvelope, TRowMapper>
  (existing helpers: WorkSignal, batch idempotency, UUID parameters)

LiteBus.Storage.EntityFrameworkCore/Stores/
  RelationalEfCoreMessageStore<TEntity, TEnvelope, TMapper>
  (existing helpers: bulk update capabilities, provider-specific lease SQL)

LiteBus.Inbox.Storage.PostgreSql/   to thin PostgreSqlInboxStore facade
LiteBus.Outbox.Storage.PostgreSql/  to thin PostgreSqlOutboxStore facade
LiteBus.Inbox.Storage.EntityFrameworkCore/  to thin EfCoreInboxStore facade
LiteBus.Outbox.Storage.EntityFrameworkCore/ to thin EfCoreOutboxStore facade

Public surfaces (IInboxStore, IOutboxStore, IInboxProcessingStore, IOutboxProcessingStore, module builders, options types) must not break. Consumers continue to install the same adapter packages.

Non-Goals

• Merging inbox and outbox into one package or one table
• A LiteBus.Storage.Core meta-package (forbidden by v6 packaging policy)
• Changing persisted envelope field semantics or schema version
• InMemory store dedup beyond small shared helpers (InMemory stores are already small)
• SQL Server-specific storage adapters (separate roadmap item in Roadmap)

Design Constraints

Follow Dependency graph dependency role rules:

Proposed Architecture

flowchart TB
  subgraph abstractions [Durable contracts]
    IInboxStore[IInboxStore / IInboxProcessingStore]
    IOutboxStore[IOutboxStore / IOutboxProcessingStore]
  end

  subgraph adapters [Feature bridges thin facades]
    PgInbox[PostgreSqlInboxStore]
    PgOutbox[PostgreSqlOutboxStore]
    EfInbox[EfCoreInboxStore]
    EfOutbox[EfCoreOutboxStore]
  end

  subgraph shared [Technology adapter Stores folder]
    PgCore[RelationalPostgreSqlMessageStore TEnvelope]
    EfCore[RelationalEfCoreMessageStore TEntity TEnvelope]
    Helpers[BatchIdempotency WorkSignal BulkUpdate]
  end

  IInboxStore --> PgInbox
  IOutboxStore --> PgOutbox
  IInboxStore --> EfInbox
  IOutboxStore --> EfOutbox
  PgInbox --> PgCore
  PgOutbox --> PgCore
  EfInbox --> EfCore
  EfOutbox --> EfCore
  PgCore --> Helpers
  EfCore --> Helpers

Port Interfaces (Internal)

Define small internal ports in the technology adapter, implemented by axis mappers in feature bridges:

PostgreSQL and EF paths share orchestration (lease batch, persist with owner guard, requeue, retention queries); they do not share SQL text or EF entity types.

Phased Delivery

Phase 1: PostgreSQL Core (Highest Duplication)

1. Extract RelationalPostgreSqlMessageStore<TEnvelope> with lease, persist, add batch, requeue, diagnostics count.
2. Reduce PostgreSqlInboxStore and PostgreSqlOutboxStore to mapper + options wiring.
3. Run full InboxStoreContractTests and OutboxStoreContractTests on PostgreSQL adapters.
4. Target >=50% line reduction in the two PG store files (deferred from v6 integration).

Estimate: one focused PR; Docker PostgreSQL integration required in CI.

Phase 2: EF Core Core

1. Extract RelationalEfCoreMessageStore<TEntity, TEnvelope> using existing EfCoreBulkUpdateCapabilities and lease SQL components.
2. Thin EfCoreInboxStore / EfCoreOutboxStore.
3. Extend concurrent persist contract tests to both axes after refactor.
4. Add the MySQL Pomelo concurrent lease contract recorded in Integration Tests if the Pomelo test container is available.

Estimate: one PR; depends on Phase 1 patterns.

Phase 3: Documentation and Graph

1. Update Dependency graph with Stores/ layout (deferred from v6 integration).
2. Cross-link from Custom stores and dispatchers for adapter authors.
3. Record the completed refactor and its validation commands in Changelog.

Acceptance Criteria

Risks and Mitigations

Relationship to Other Work

When to Schedule

Schedule after v6.0 Core GA tag. Do not block GA on this refactor: runtime behavior and contract tests already satisfy Core GA. Prioritize when:

• A second storage correctness fix would require duplicate edits in inbox and outbox stores, or
• A new storage provider (for example SQL Server) would copy a third large facade.

Tracking

See Also

• Roadmap: future work index
• Custom stores and dispatchers: adapter author guide
• PostgreSQL schema management: current schema invariants
• Integration Tests: storage regression suites