feat: event metadata (#8)

* wip

* feat: event metadata

* metadata need not be Deserialize

Cargo.toml

@@ -26,5 +26,6 @@ trait-variant = { version = "0.1" }
 sqlx                   = { version = "0.7", features = [ "uuid" ] }
 testcontainers         = { version = "0.17" }
 testcontainers-modules = { version = "0.5", features = [ "postgres" ] }
+time                   = { version = "0.3", features = [ "serde-human-readable" ] }
 tokio                  = { version = "1", features = [ "macros" ] }
 uuid                   = { version = "1.8", features = [ "serde", "v7" ] }

README.md

@@ -8,11 +8,11 @@
 [license-badge]: https://img.shields.io/github/license/hseeberger/evented
 [license-url]: https://github.com/hseeberger/evented/blob/main/LICENSE
 
-evented is a library for [Event Sourcing](https://martinfowler.com/eaaDev/EventSourcing.html) where state changes are persisted as events. It originated from [eventsourced](https://github.com/hseeberger/eventsourced), but offers additional strong consistency features by tightly coupling to [PostgreSQL](https://www.postgresql.org/).
+evented is a library for [Event Sourcing](https://martinfowler.com/eaaDev/EventSourcing.html) where state changes are persisted as events. It originated from [eventsourced](https://github.com/hseeberger/eventsourced), but offers additional strong consistency features by tightly coupling to [PostgreSQL](https://www.postgresql.org/) as well as other features like event metadata.
 
 The core abstraction of evented is an `EventSourcedEntity` which can be identified via an ID: an `Entity` implementation defines its state and event handling and associated `Command` implementations define its command handling.
 
-When an event-sourced entity receives a command, the respective command handler is called, which either returns a sequence of to be persisted events or a rejection. If events are returned, these are transactionally persisted, thereby also invoking an optional `EventListener`. Concurrency is handled by optimistic locking via per event sequence numbers.
+When an event-sourced entity receives a command, the respective command handler is called, which either returns a sequence of to be persisted events plus metadata or a rejection. If events are returned, these are transactionally persisted, thereby also invoking an optional `EventListener`. Concurrency is handled by optimistic locking via per event sequence numbers.
 
 When creating an event-sourced entity, its events are loaded and its state is conctructed by applying them to its event handler. This state is then used by the command handlers to decide whether a command should be accepted – resulting in events to be persisted and applied – or rejected.
 
@@ -25,6 +25,7 @@ pub struct Counter(u64);
 impl Entity for Counter {
     type Id = Uuid;
     type Event = Event;
+    type Metadata = Metadata;
 
     const TYPE_NAME: &'static str = "counter";
 
@@ -53,12 +54,26 @@ impl Command for Increase {
         self,
         id: &<Self::Entity as Entity>::Id,
         entity: &Self::Entity,
-    ) -> Result<Vec<<Self::Entity as Entity>::Event>, Self::Rejection> {
+    ) -> Result<
+        Vec<
+            impl Into<
+                EventWithMetadata<
+                    <Self::Entity as Entity>::Event,
+                    <Self::Entity as Entity>::Metadata,
+                >,
+            >,
+        >,
+        Self::Rejection,
+    > {
         let Increase(inc) = self;
         if entity.0 > u64::MAX - inc {
             Err(Overflow)
         } else {
-            Ok(vec![Event::Increased { id: *id, inc }])
+            let increased = Event::Increased { id: *id, inc };
+            let metadata = Metadata {
+                timestamp: OffsetDateTime::now_utc(),
+            };
+            Ok(vec![increased.with_metadata(metadata)])
         }
     }
 }
@@ -77,19 +92,38 @@ impl Command for Decrease {
         self,
         id: &<Self::Entity as Entity>::Id,
         entity: &Self::Entity,
-    ) -> Result<Vec<<Self::Entity as Entity>::Event>, Self::Rejection> {
+    ) -> Result<
+        Vec<
+            impl Into<
+                EventWithMetadata<
+                    <Self::Entity as Entity>::Event,
+                    <Self::Entity as Entity>::Metadata,
+                >,
+            >,
+        >,
+        Self::Rejection,
+    > {
         let Decrease(dec) = self;
         if entity.0 < dec {
-            Err(Underflow)
+            Err::<Vec<_>, Underflow>(Underflow)
         } else {
-            Ok(vec![Event::Decreased { id: *id, dec }])
+            let decreased = Event::Decreased { id: *id, dec };
+            let metadata = Metadata {
+                timestamp: OffsetDateTime::now_utc(),
+            };
+            Ok(vec![decreased.with_metadata(metadata)])
         }
     }
 }
 
 #[derive(Debug, PartialEq, Eq)]
 pub struct Underflow;
 
+#[derive(Debug, Serialize, Deserialize)]
+pub struct Metadata {
+    timestamp: OffsetDateTime,
+}
+
 struct Listener;
 
 impl EventListener<Event> for Listener {

sql/create_event_log_uuid.sql

@@ -4,5 +4,6 @@ CREATE TABLE
     seq_no bigint,
     type text,
     event bytea,
+    metadata jsonb,
     PRIMARY KEY (id, seq_no)
   );