Merge pull request #2576 from Cratis:feature/read-models

einari · web-flow · commit 2b6993154230 · 2026-02-04T17:30:21.000+01:00
Up and running with the ability to get read model instances as collection and project multiple events not bound to an event source id
diff --git a/.github/workflows/dotnet-build.yml b/.github/workflows/dotnet-build.yml
@@ -116,6 +116,7 @@ jobs:
           - 'for_JobsManager'
           - 'for_Reactors'
           - 'for_Reducers'
+          - 'for_ReadModels'
           - 'for_Webhooks'
           - 'Jobs'
           - 'Projections'
diff --git a/Documentation/clients/dotnet/aggregates/aggregate-root.md b/Documentation/clients/dotnet/aggregates/aggregate-root.md
@@ -0,0 +1,5 @@
+# Aggregate Root
+
+Documentation for aggregate root patterns.
+
+TODO: Add content.
diff --git a/Documentation/clients/dotnet/connection-strings.md b/Documentation/clients/dotnet/connection-strings.md
@@ -309,7 +309,7 @@ var options = new ChronicleOptions
 };
 ```
 
-See the [TLS Configuration](../../tls-configuration.md) documentation for more details on certificate setup.
+See the [TLS Configuration](../../tls-hosting/configuration.md) documentation for more details on certificate setup.
 
 ## Best Practices
 
@@ -378,6 +378,6 @@ If you encounter TLS errors:
 
 ## See Also
 
-- [TLS Configuration](../../tls-configuration.md)
+- [TLS Configuration](../../tls-hosting/configuration.md)
 - [Namespaces](namespaces.md)
 - [Getting Started](../../get-started/index.md)
diff --git a/Documentation/hosting/encryption-certificate.md b/Documentation/hosting/encryption-certificate.md
@@ -192,7 +192,7 @@ Ensure you have configured the certificate path and password as described above.
 
 ## Next Steps
 
-- [Local Certificates](local-certificates.md) - TLS certificate setup for development
-- [Production Hosting](production.md) - Production deployment requirements
-- [Configuration](configuration.md) - Complete configuration reference
+- [Local Certificates](hosting/local-certificates.md) - TLS certificate setup for development
+- [Production Hosting](hosting/production.md) - Production deployment requirements
+- [Configuration](hosting/configuration.md) - Complete configuration reference
 
diff --git a/Documentation/hosting/index.md b/Documentation/hosting/index.md
@@ -4,9 +4,9 @@ Chronicle provides multiple deployment options to suit different environments an
 
 ## Deployment Options
 
-- **[Production](production.md)** - Docker-based production deployment with MongoDB
-- **[Configuration](configuration.md)** - Complete configuration reference
-- **[Local Certificates](local-certificates.md)** - Generate and configure TLS certificates for local development
+- **[Production](hosting/production.md)** - Docker-based production deployment with MongoDB
+- **[Configuration](hosting/configuration.md)** - Complete configuration reference
+- **[Local Certificates](hosting/local-certificates.md)** - Generate and configure TLS certificates for local development
 - **Development** - Local development setup with MongoDB
 - **Docker Compose** - Multi-container setup for development and testing
 
@@ -17,7 +17,7 @@ All Chronicle hosting environments require:
 - **.NET 9 Runtime** - Chronicle is built on .NET 9
 - **MongoDB** - Primary storage backend for events and projections
 - **Network Access** - Chronicle exposes multiple ports for different services
-- **Configuration** - See [Configuration](configuration.md) for details
+- **Configuration** - See [Configuration](hosting/configuration.md) for details
 
 ## Architecture Overview
 
diff --git a/Documentation/hosting/local-certificates.md b/Documentation/hosting/local-certificates.md
@@ -246,5 +246,5 @@ If the client cannot connect:
 
 ## Next Steps
 
-- [Production Hosting](production.md) - Learn about production certificate requirements
-- [Configuration](configuration.md) - Complete configuration reference
+- [Production Hosting](hosting/production.md) - Learn about production certificate requirements
+- [Configuration](hosting/configuration.md) - Complete configuration reference
diff --git a/Documentation/hosting/production.md b/Documentation/hosting/production.md
@@ -18,7 +18,7 @@ docker pull cratis/chronicle:1.0.0
 
 ## Configuration
 
-Chronicle requires configuration to define its runtime behavior. For complete configuration details, see the [Configuration](configuration.md) guide.
+Chronicle requires configuration to define its runtime behavior. For complete configuration details, see the [Configuration](hosting/configuration.md) guide.
 
 The configuration file must be mounted into the container at `/app/chronicle.json`, or you can use environment variables with the `Cratis__Chronicle__` prefix.
 
@@ -80,11 +80,11 @@ volumes:
 1. **Use specific version tags** instead of `latest` for production deployments
 2. **Mount configuration as read-only** (`-v /path/to/chronicle.json:/app/chronicle.json:ro`)
 3. **Use environment-specific connection strings** for MongoDB
-4. **Configure appropriate timeouts** based on your infrastructure (see [Configuration](configuration.md))
+4. **Configure appropriate timeouts** based on your infrastructure (see [Configuration](hosting/configuration.md))
 5. **Enable health checks** for container orchestration
 6. **Set up monitoring** for all exposed ports
 7. **Use secrets management** for sensitive configuration values
-8. **Enable TLS** with proper certificates (see [TLS Configuration](../tls-configuration.md))
+8. **Enable TLS** with proper certificates (see [TLS Configuration](../tls-hosting/configuration.md))
 
 ## Health Checks
 
@@ -95,7 +95,7 @@ HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
   CMD curl -f http://localhost:8080/health || exit 1
 ```
 
-> **Note**: The health check endpoint path is configurable. See [Configuration](configuration.md#health-check-endpoint) for details.
+> **Note**: The health check endpoint path is configurable. See [Configuration](hosting/configuration.md#health-check-endpoint) for details.
 
 ## Security Considerations
 
@@ -104,7 +104,7 @@ HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
 - **Access Control**: Implement proper firewall rules for exposed ports
 - **Secrets Management**: Use external secret management for sensitive configuration
 - **Regular Updates**: Keep Chronicle and MongoDB images updated
-- **TLS Certificates**: Configure valid TLS certificates for production (see [TLS Configuration](../tls-configuration.md))
+- **TLS Certificates**: Configure valid TLS certificates for production (see [TLS Configuration](../tls-hosting/configuration.md))
 
 ## Scaling
 
diff --git a/Integration/DotNET.InProcess/for_ReadModels/AnotherEvent.cs b/Integration/DotNET.InProcess/for_ReadModels/AnotherEvent.cs
@@ -0,0 +1,9 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+using Cratis.Chronicle.Events;
+
+namespace Cratis.Chronicle.InProcess.Integration.for_ReadModels;
+
+[EventType("2d1f20ee-f0fd-5b82-cfa9-cf6eefb23c63")]
+public record AnotherEvent(string Value);
diff --git a/Integration/DotNET.InProcess/for_ReadModels/SomeEvent.cs b/Integration/DotNET.InProcess/for_ReadModels/SomeEvent.cs
@@ -0,0 +1,9 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+using Cratis.Chronicle.Events;
+
+namespace Cratis.Chronicle.InProcess.Integration.for_ReadModels;
+
+[EventType("1c0f19dd-e9fc-4a71-bfa8-bf5eefb12b52")]
+public record SomeEvent(int Number);
diff --git a/Integration/DotNET.InProcess/for_ReadModels/SomeProjection.cs b/Integration/DotNET.InProcess/for_ReadModels/SomeProjection.cs
@@ -0,0 +1,15 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+namespace Cratis.Chronicle.InProcess.Integration.for_ReadModels;
+
+public class SomeProjection : IProjectionFor<SomeReadModel>
+{
+    public ProjectionId Identifier => "some-projection";
+
+    public void Define(IProjectionBuilderFor<SomeReadModel> builder) => builder
+        .From<SomeEvent>(e => e
+            .Set(m => m.Number).To(e => e.Number))
+        .From<AnotherEvent>(e => e
+            .Set(m => m.Value).To(e => e.Value));
+}
diff --git a/Integration/DotNET.InProcess/for_ReadModels/SomeReadModel.cs b/Integration/DotNET.InProcess/for_ReadModels/SomeReadModel.cs
@@ -0,0 +1,6 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+namespace Cratis.Chronicle.InProcess.Integration.for_ReadModels;
+
+public record SomeReadModel(int Number, string Value);
diff --git a/Integration/DotNET.InProcess/for_ReadModels/given/a_projection_with_events.cs b/Integration/DotNET.InProcess/for_ReadModels/given/a_projection_with_events.cs
@@ -0,0 +1,29 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+using Cratis.Chronicle.Events;
+
+namespace Cratis.Chronicle.InProcess.Integration.for_ReadModels.given;
+
+public class a_projection_with_events(ChronicleInProcessFixture chronicleInProcessFixture) : Specification(chronicleInProcessFixture)
+{
+    public EventSourceId EventSourceId;
+    public SomeEvent FirstEvent;
+    public AnotherEvent SecondEvent;
+
+    public override IEnumerable<Type> EventTypes => [typeof(SomeEvent), typeof(AnotherEvent)];
+    public override IEnumerable<Type> Projections => [typeof(SomeProjection)];
+
+    protected void Establish()
+    {
+        EventSourceId = "some-source";
+        FirstEvent = new SomeEvent(42);
+        SecondEvent = new AnotherEvent("test-value");
+    }
+
+    protected async Task AppendEvents()
+    {
+        await EventStore.EventLog.Append(EventSourceId, FirstEvent);
+        await EventStore.EventLog.Append(EventSourceId, SecondEvent);
+    }
+}
diff --git a/Integration/DotNET.InProcess/for_ReadModels/when_getting_instance_with_unspecified_key/and_events_exist.cs b/Integration/DotNET.InProcess/for_ReadModels/when_getting_instance_with_unspecified_key/and_events_exist.cs
@@ -0,0 +1,25 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+using Cratis.Chronicle.ReadModels;
+using context = Cratis.Chronicle.InProcess.Integration.for_ReadModels.when_getting_instance_with_unspecified_key.and_events_exist.context;
+
+namespace Cratis.Chronicle.InProcess.Integration.for_ReadModels.when_getting_instance_with_unspecified_key;
+
+[Collection(ChronicleCollection.Name)]
+public class and_events_exist(context context) : Given<context>(context)
+{
+    public class context(ChronicleInProcessFixture chronicleInProcessFixture) : given.a_projection_with_events(chronicleInProcessFixture)
+    {
+        public SomeReadModel Result;
+
+        async Task Because()
+        {
+            await AppendEvents();
+            Result = await EventStore.ReadModels.GetInstanceById<SomeReadModel>(ReadModelKey.Unspecified);
+        }
+    }
+
+    [Fact] void should_have_number_from_first_event() => Context.Result.Number.ShouldEqual(Context.FirstEvent.Number);
+    [Fact] void should_have_value_from_second_event() => Context.Result.Value.ShouldEqual(Context.SecondEvent.Value);
+}
diff --git a/Integration/DotNET.InProcess/for_ReadModels/when_getting_instance_with_unspecified_key/and_multiple_event_sources_exist.cs b/Integration/DotNET.InProcess/for_ReadModels/when_getting_instance_with_unspecified_key/and_multiple_event_sources_exist.cs
@@ -0,0 +1,38 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+using Cratis.Chronicle.Events;
+using Cratis.Chronicle.ReadModels;
+using context = Cratis.Chronicle.InProcess.Integration.for_ReadModels.when_getting_instance_with_unspecified_key.and_multiple_event_sources_exist.context;
+
+namespace Cratis.Chronicle.InProcess.Integration.for_ReadModels.when_getting_instance_with_unspecified_key;
+
+[Collection(ChronicleCollection.Name)]
+public class and_multiple_event_sources_exist(context context) : Given<context>(context)
+{
+    public class context(ChronicleInProcessFixture chronicleInProcessFixture) : given.a_projection_with_events(chronicleInProcessFixture)
+    {
+        public EventSourceId SecondEventSourceId;
+        public SomeEvent ThirdEvent;
+        public AnotherEvent FourthEvent;
+        public SomeReadModel Result;
+
+        void Establish()
+        {
+            SecondEventSourceId = "another-source";
+            ThirdEvent = new SomeEvent(100);
+            FourthEvent = new AnotherEvent("another-value");
+        }
+
+        async Task Because()
+        {
+            await AppendEvents();
+            await EventStore.EventLog.Append(SecondEventSourceId, ThirdEvent);
+            await EventStore.EventLog.Append(SecondEventSourceId, FourthEvent);
+            Result = await EventStore.ReadModels.GetInstanceById<SomeReadModel>(ReadModelKey.Unspecified);
+        }
+    }
+
+    [Fact] void should_have_number_from_last_event() => Context.Result.Number.ShouldEqual(Context.ThirdEvent.Number);
+    [Fact] void should_have_value_from_last_event() => Context.Result.Value.ShouldEqual(Context.FourthEvent.Value);
+}
diff --git a/Integration/DotNET.InProcess/for_ReadModels/when_getting_instances/with_limited_event_count.cs b/Integration/DotNET.InProcess/for_ReadModels/when_getting_instances/with_limited_event_count.cs
@@ -0,0 +1,25 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+using context = Cratis.Chronicle.InProcess.Integration.for_ReadModels.when_getting_instances.with_limited_event_count.context;
+
+namespace Cratis.Chronicle.InProcess.Integration.for_ReadModels.when_getting_instances;
+
+[Collection(ChronicleCollection.Name)]
+public class with_limited_event_count(context context) : Given<context>(context)
+{
+    public class context(ChronicleInProcessFixture chronicleInProcessFixture) : given.a_projection_with_events(chronicleInProcessFixture)
+    {
+        public IEnumerable<SomeReadModel> Results;
+
+        async Task Because()
+        {
+            await AppendEvents();
+            Results = await EventStore.ReadModels.GetInstances<SomeReadModel>(1);
+        }
+    }
+
+    [Fact] void should_return_single_instance() => Context.Results.Count().ShouldEqual(1);
+    [Fact] void should_have_number_from_first_event() => Context.Results.First().Number.ShouldEqual(Context.FirstEvent.Number);
+    [Fact] void should_not_have_value_from_second_event() => Context.Results.First().Value.ShouldBeNull();
+}
diff --git a/Integration/DotNET.InProcess/for_ReadModels/when_getting_instances/with_multiple_event_sources.cs b/Integration/DotNET.InProcess/for_ReadModels/when_getting_instances/with_multiple_event_sources.cs
@@ -0,0 +1,40 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+using Cratis.Chronicle.Events;
+using context = Cratis.Chronicle.InProcess.Integration.for_ReadModels.when_getting_instances.with_multiple_event_sources.context;
+
+namespace Cratis.Chronicle.InProcess.Integration.for_ReadModels.when_getting_instances;
+
+[Collection(ChronicleCollection.Name)]
+public class with_multiple_event_sources(context context) : Given<context>(context)
+{
+    public class context(ChronicleInProcessFixture chronicleInProcessFixture) : given.a_projection_with_events(chronicleInProcessFixture)
+    {
+        public EventSourceId SecondEventSourceId;
+        public SomeEvent ThirdEvent;
+        public AnotherEvent FourthEvent;
+        public IEnumerable<SomeReadModel> Results;
+
+        void Establish()
+        {
+            SecondEventSourceId = "another-source";
+            ThirdEvent = new SomeEvent(100);
+            FourthEvent = new AnotherEvent("another-value");
+        }
+
+        async Task Because()
+        {
+            await AppendEvents();
+            await EventStore.EventLog.Append(SecondEventSourceId, ThirdEvent);
+            await EventStore.EventLog.Append(SecondEventSourceId, FourthEvent);
+            Results = await EventStore.ReadModels.GetInstances<SomeReadModel>();
+        }
+    }
+
+    [Fact] void should_return_two_instances() => Context.Results.Count().ShouldEqual(2);
+    [Fact] void should_have_first_instance_with_first_events() => Context.Results.First().Number.ShouldEqual(Context.FirstEvent.Number);
+    [Fact] void should_have_first_instance_value() => Context.Results.First().Value.ShouldEqual(Context.SecondEvent.Value);
+    [Fact] void should_have_second_instance_with_second_events() => Context.Results.Last().Number.ShouldEqual(Context.ThirdEvent.Number);
+    [Fact] void should_have_second_instance_value() => Context.Results.Last().Value.ShouldEqual(Context.FourthEvent.Value);
+}
diff --git a/Integration/DotNET.InProcess/for_ReadModels/when_getting_instances/without_event_count.cs b/Integration/DotNET.InProcess/for_ReadModels/when_getting_instances/without_event_count.cs
@@ -0,0 +1,25 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+using context = Cratis.Chronicle.InProcess.Integration.for_ReadModels.when_getting_instances.without_event_count.context;
+
+namespace Cratis.Chronicle.InProcess.Integration.for_ReadModels.when_getting_instances;
+
+[Collection(ChronicleCollection.Name)]
+public class without_event_count(context context) : Given<context>(context)
+{
+    public class context(ChronicleInProcessFixture chronicleInProcessFixture) : given.a_projection_with_events(chronicleInProcessFixture)
+    {
+        public IEnumerable<SomeReadModel> Results;
+
+        async Task Because()
+        {
+            await AppendEvents();
+            Results = await EventStore.ReadModels.GetInstances<SomeReadModel>();
+        }
+    }
+
+    [Fact] void should_return_single_instance() => Context.Results.Count().ShouldEqual(1);
+    [Fact] void should_have_number_from_first_event() => Context.Results.First().Number.ShouldEqual(Context.FirstEvent.Number);
+    [Fact] void should_have_value_from_second_event() => Context.Results.First().Value.ShouldEqual(Context.SecondEvent.Value);
+}
diff --git a/Source/Clients/DotNET/Events/EventCount.cs b/Source/Clients/DotNET/Events/EventCount.cs
@@ -0,0 +1,39 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+namespace Cratis.Chronicle.Events;
+
+/// <summary>
+/// Represents a count of events.
+/// </summary>
+/// <param name="Value">The actual count.</param>
+public record EventCount(ulong Value) : ConceptAs<ulong>(Value)
+{
+    /// <summary>
+    /// The value representing an unlimited count.
+    /// </summary>
+    public static readonly EventCount Unlimited = ulong.MaxValue;
+
+    /// <summary>
+    /// The value representing zero.
+    /// </summary>
+    public static readonly EventCount Zero = 0L;
+
+    /// <summary>
+    /// Implicitly convert from <see cref="ulong"/> to <see cref="EventCount"/>.
+    /// </summary>
+    /// <param name="value">Value to convert from.</param>
+    public static implicit operator EventCount(ulong value) => new(value);
+
+    /// <summary>
+    /// Implicitly convert from <see cref="long"/> to <see cref="EventCount"/>.
+    /// </summary>
+    /// <param name="value">Value to convert from.</param>
+    public static implicit operator EventCount(long value) => new((ulong)value);
+
+    /// <summary>
+    /// Implicitly convert from <see cref="int"/> to <see cref="EventCount"/>.
+    /// </summary>
+    /// <param name="value">Value to convert from.</param>
+    public static implicit operator EventCount(int value) => new((ulong)value);
+}
diff --git a/Source/Clients/DotNET/ReadModels/IReadModels.cs b/Source/Clients/DotNET/ReadModels/IReadModels.cs
diff --git a/Source/Clients/DotNET/ReadModels/ReadModels.cs b/Source/Clients/DotNET/ReadModels/ReadModels.cs
diff --git a/Source/Kernel/Contracts/ReadModels/GetAllInstancesRequest.cs b/Source/Kernel/Contracts/ReadModels/GetAllInstancesRequest.cs
diff --git a/Source/Kernel/Contracts/ReadModels/GetAllInstancesResponse.cs b/Source/Kernel/Contracts/ReadModels/GetAllInstancesResponse.cs
diff --git a/Source/Kernel/Contracts/ReadModels/IReadModels.cs b/Source/Kernel/Contracts/ReadModels/IReadModels.cs
diff --git a/Source/Kernel/Services/ReadModels/ReadModels.cs b/Source/Kernel/Services/ReadModels/ReadModels.cs
