From a3b7489f1679a0539f9fafe2c8c340928c0b051c Mon Sep 17 00:00:00 2001 From: Mercurial Date: Sat, 20 Jun 2026 23:40:07 +0800 Subject: [PATCH] =?UTF-8?q?docs(readme):=20fix=20package-split=20drift=20?= =?UTF-8?q?=E2=80=94=20EF/Postgres=20is=20its=20own=20package?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The getting-started and project-layout sections still claimed the Postgres/EF backend ships inside core Argus.Sync, contradicting the migration table (which already documents the split). Aligned them to the example project: - install: add Argus.Sync.EntityFramework (core is storage-agnostic now) - DbContext example: using Argus.Sync.Data -> Argus.Sync.EntityFramework (where CardanoDbContext lives) - register example: add the Argus.Sync.EntityFramework using for AddCardanoPostgresIndexer - Storage Backends: 'The default' -> 'Add the package'; per-branch -> batched - Project Layout: corrected core's description + added the Argus.Sync.EntityFramework row - pack commands: added Argus.Sync.EntityFramework - minor 1.2 terminology (pipeline -> graph processor, branch -> batch) Co-Authored-By: Claude Opus 4.8 --- README.md | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index dbbde24..eafda80 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,7 @@ Argus is a .NET library that turns the Cardano blockchain into structured, query | Component | Role | | --------- | ---- | | **Chain Provider** | Connects to a Cardano node and streams roll-forward / roll-backward events (`N2CProvider`, `U5CProvider`, `N2NProvider`). | -| **`CardanoIndexWorker`** | The hosted service that drives synchronization: builds the reducer dependency graph, manages connections, and feeds blocks into the pipeline. | +| **`CardanoIndexWorker`** | The hosted service that drives synchronization: builds the reducer dependency graph, manages connections, and feeds blocks into each root's graph processor. | | **`ReducerGraphProcessor`** | One per root reducer. Runs the root and all its dependents in topological order (parents first) through a bounded `System.Threading.Channels` inbox, accumulating blocks into a batch. Backpressure is automatic. | | **`IReducer`** | Your transformation logic — `RollForwardAsync` / `RollBackwardAsync`. | | **`IBlockUnitOfWork`** | A framework-managed transactional unit shared by the whole graph for one batch. Reducers register writes against it; the framework commits all of them **and** every reducer's checkpoint together, atomically, when a batch trigger fires. | @@ -78,14 +78,15 @@ Argus is a .NET library that turns the Cardano blockchain into structured, query ### 1️⃣ Install ```bash -# Core library (PostgreSQL backend included) +# Core library (storage-agnostic) dotnet add package Argus.Sync -# EF Core tooling for migrations + the Postgres provider +# PostgreSQL backend (Entity Framework Core) + EF tooling for migrations +dotnet add package Argus.Sync.EntityFramework dotnet add package Microsoft.EntityFrameworkCore.Design dotnet add package Npgsql.EntityFrameworkCore.PostgreSQL -# Optional: MongoDB backend +# Or, instead: MongoDB backend dotnet add package Argus.Sync.MongoDb ``` @@ -109,7 +110,7 @@ public record BlockInfo( Extend `CardanoDbContext` and expose your models. Argus manages its own `ReducerStates` table on the same context. ```csharp -using Argus.Sync.Data; +using Argus.Sync.EntityFramework; using Microsoft.EntityFrameworkCore; public class MyDbContext( @@ -153,7 +154,7 @@ public class BlockReducer : IReducer ulong slot = block.Header().HeaderBody().Slot(); db.Blocks.Add(new BlockInfo(hash, height, slot, DateTime.UtcNow)); - return Task.CompletedTask; // the framework commits this branch atomically + return Task.CompletedTask; // the framework commits the batch atomically } public Task RollBackwardAsync(ulong slot, IBlockUnitOfWork uow, CancellationToken ct) @@ -200,7 +201,8 @@ public class BlockReducer : IReducer ### 6️⃣ Register services ```csharp -using Argus.Sync.Extensions; +using Argus.Sync.EntityFramework; // AddCardanoPostgresIndexer + CardanoDbContext +using Argus.Sync.Extensions; // AddReducers WebApplicationBuilder builder = WebApplication.CreateBuilder(args); @@ -279,11 +281,11 @@ public class TransactionReducer : IReducer ## 💾 Storage Backends -A backend is one implementation of `IBlockUnitOfWorkFactory` (create a per-branch transactional unit + read a reducer's checkpoint). Reducers stay backend-agnostic by calling `uow.GetStorage()`. +A backend is one implementation of `IBlockUnitOfWorkFactory` (create a batched transactional unit + read a reducer's checkpoint). Reducers stay backend-agnostic by calling `uow.GetStorage()`. ### PostgreSQL (Entity Framework Core) -The default. Your `CardanoDbContext`-derived context *is* the storage handle: +Add the `Argus.Sync.EntityFramework` package. Your `CardanoDbContext`-derived context *is* the storage handle: ```csharp builder.Services.AddCardanoPostgresIndexer(builder.Configuration); @@ -400,8 +402,9 @@ dotnet test dotnet test --filter "Category!=Integration" # Pack the NuGet packages -dotnet pack src/Argus.Sync --configuration Release -dotnet pack src/Argus.Sync.MongoDb --configuration Release +dotnet pack src/Argus.Sync --configuration Release +dotnet pack src/Argus.Sync.EntityFramework --configuration Release +dotnet pack src/Argus.Sync.MongoDb --configuration Release ``` Integration tests run against a real preprod/preview node and a local PostgreSQL (and, for the Mongo suite, a MongoDB replica set); they self-skip when those aren't reachable. The end-to-end suite under `src/Argus.Sync.Tests/EndToEnd` exercises the worker, the dependency graph, whole-graph atomicity, batch commits, crash-recovery, N2N pipelining, the single-instance lock, and both storage backends against real Conway-era blocks. @@ -410,7 +413,8 @@ Integration tests run against a real preprod/preview node and a local PostgreSQL | Project | Purpose | | ------- | ------- | -| `src/Argus.Sync` | Core library: worker, pipeline, reducers, EF/Postgres backend. | +| `src/Argus.Sync` | Core library (storage-agnostic): worker, reducer graph, unit-of-work seam, chain providers. | +| `src/Argus.Sync.EntityFramework` | PostgreSQL / EF Core backend (`AddCardanoPostgresIndexer`, `CardanoDbContext`). | | `src/Argus.Sync.MongoDb` | MongoDB storage backend (`AddCardanoMongoIndexer`). | | `src/Argus.Sync.Example` | Runnable reference app with example models and reducers. | | `src/Argus.Sync.Tests` | Unit + end-to-end tests. |