Fix mongodb restore deadlock

Author: helightdev

.idea/dictionaries/project.xml

@@ -1,4 +1,4 @@
-import { defineConfig } from 'vitepress'
+import {defineConfig} from 'vitepress'
 
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
@@ -29,25 +29,17 @@ export default defineConfig({
         text: 'Concepts',
         items: [
           { text: 'Events', link: '/concepts/events' },
-          { text: 'Event Catalog', link: '/concepts/event-catalog' },
-          { text: 'Event Stream Processing', link: '/concepts/event-stream-processing' },
-          { text: 'Event Sources', link: '/concepts/event-sources' },
-          { text: 'Event Sourcing Strategies', link: '/concepts/event-sourcing-strategies' },
-          { text: 'Event Models', link: '/concepts/event-models' },
-          { text: 'Checkpointing', link: '/concepts/checkpointing' }
+          {text: 'Checkpointing', link: '/concepts/checkpointing'},
+          {text: 'Models', link: '/concepts/models'}
         ]
       },
       {
         text: 'Guide',
         items: [
           { text: 'Installation', link: '/guide/installation' },
-          { text: 'Getting Started', link: '/guide/getting-started' },
-          { text: 'Creating Event Models', link: '/guide/creating-event-models' },
-          { text: 'Working with Event Sources', link: '/guide/working-with-event-sources' }
         ]
       }
     ],
-
     socialLinks: [
       { icon: 'github', link: 'https://github.com/helightdev/krescent' }
     ]

docs/.vitepress/config.mts

@@ -2,35 +2,32 @@
 title: Checkpointing
 ---
 
-Checkpointing in Krescent is a crucial optimization mechanism for event models. Its primary purpose is to periodically save the current state of an event model, along with the position (e.g., `StreamingToken`) of the last event processed to reach that state. This avoids the need to reprocess the entire event stream from the beginning every time the model is initialized or restarted.
+Checkpointing in Krescent is a crucial optimization mechanism for event models. Its primary purpose is to periodically
+save the current state of an event model, along with the position (e.g., `StreamingToken`) of the last event processed
+to reach that state. This avoids the need to reprocess the entire event stream from the beginning every time the model
+is initialized or restarted.
 
 ## `CheckpointStrategy`
 
 A `CheckpointStrategy` determines *when* a checkpoint should be taken. Krescent offers several built-in strategies:
 
--   **`FixedEventRateCheckpointStrategy`**: Triggers a checkpoint after a fixed number of events have been processed. For example, checkpoint every 1000 events.
--   **`FixedTimeRateCheckpointStrategy`**: Triggers a checkpoint after a fixed amount of time has elapsed since the last checkpoint. For example, checkpoint every 5 minutes.
--   **`ManualCheckpointStrategy`**: Allows the application to trigger checkpoints programmatically based on custom logic or external signals. This provides the most flexibility but requires explicit management.
+- **`FixedEventRateCheckpointStrategy`**: Triggers a checkpoint after a fixed number of events have been processed. For
+  example, checkpoint every 1000 events.
+- **`FixedTimeRateCheckpointStrategy`**: Triggers a checkpoint after a fixed amount of time has elapsed since the last
+  checkpoint. For example, checkpoint every 5 minutes.
+- **`AlwaysCheckpointStrategy`**: Trigger a checkpoint after every event processed. This is either useful if creating
+  checkpoints is very inexpensive or the projection of a read model represents the latest snapshot with the read model
+  being able to handle transactions and rollbacks.
+- **`ManualCheckpointStrategy`**: Allows the application to trigger checkpoints programmatically based on custom logic
+  or external signals. This provides the most flexibility but requires explicit management.
 
 ## `CheckpointStorage`
 
-The `CheckpointStorage` interface defines *how* and *where* checkpoints are saved and loaded. Implementations of this interface are responsible for serializing the model's state and the associated `StreamingToken`, persisting them to a durable store (like a file system, database, or cloud storage), and retrieving them when needed.
+The `CheckpointStorage` interface defines *how* and *where* checkpoints are saved and loaded. Implementations of this
+interface are responsible for serializing the model's state and the associated `StreamingToken`, persisting them to a
+durable store (like a file system, database, or cloud storage), and retrieving them when needed.
 
 ## `CheckpointSupport`
 
-`CheckpointSupport` is an interface that must be implemented by components (typically event models or parts of them) that can be checkpointed. It defines methods for:
-
--   **`captureCheckpoint()`**: Returns the current state of the component to be saved.
--   **`restoreCheckpoint(state: Any)`**: Restores the component's state from a previously saved checkpoint.
-
-## `CheckpointingEventSourceConsumer`
-
-The `CheckpointingEventSourceConsumer` is the component that orchestrates the checkpointing process for an event model. It works in conjunction with a `CheckpointStrategy` and `CheckpointStorage`. As it consumes events for the model, it monitors the chosen strategy. When the strategy indicates that a checkpoint is due, the consumer:
-
-1.  Pauses event processing temporarily.
-2.  Instructs the event model (which implements `CheckpointSupport`) to capture its current state.
-3.  Retrieves the `StreamingToken` of the last processed event.
-4.  Uses the `CheckpointStorage` to save the model's state and the token.
-5.  Resumes event processing.
-
-When the model is restarted, the `CheckpointingEventSourceConsumer` first attempts to load the latest checkpoint from `CheckpointStorage`. If successful, the model's state is restored, and event processing resumes from the token stored in the checkpoint, significantly reducing startup time.
+`CheckpointSupport` is an interface that must be implemented by components (typically event models or parts of them)
+that can be checkpointed.

docs/concepts/checkpointing.md

@@ -2,34 +2,68 @@
 title: Events
 ---
 
-Events in Krescent are immutable facts that represent something that has happened in the system. They are the primary building blocks of Krescent's event-driven architecture.
+Events in Krescent are immutable facts that represent something that has happened in the system. They are the primary
+building blocks of Krescent's event-driven architecture.
 
-## Base `Event` Class
+## Physical vs Virtual Events
 
-All events in Krescent inherit from a base `Event` class. This class provides common functionality and a consistent structure for all events.
+In Krescent, events can be categorized into three types:
 
-## `EventMetadata`
+- **Physical Events**: These are events that are sourced from an event stream and have a position, id and timestamp.
+  All events in this category must be strictly serializable and are typically defined as Kotlin data classes.
+- **Virtual Events**: These are events created by the framework, a virtual event stream or model extensions and
+  are either derived from physical events or related to the event processing pipelines state.
+- **System Events**: These are just a special case of virtual events which are only emitted by the framework and usually
+  represent internal state changes, notifications or stream state changes.
 
-Every event carries metadata, which is encapsulated in the `EventMetadata` class. This metadata includes:
+#### Example Event Definition
 
-- **id**: A unique identifier for the event.
-- **type**: The type of the event.
-- **timestamp**: The time at which the event occurred.
-- **position**: The position of the event in the event stream.
+```kotlin
+@Serializable
+data class BookAddedEvent(
+  override val bookId: String,
+  val title: String,
+  val author: String,
+  val price: Double,
+  val copies: Int,
+) : Event(), BookEvent
 
-## Physical vs. Virtual Events
+@Serializable
+data class BookPriceChangedEvent(
+  override val bookId: String,
+  val price: Double,
+) : Event(), BookEvent
 
-Krescent distinguishes between two main types of events:
+interface BookEvent {
+  val bookId: String
+}
+```
 
-- **Physical Events**: These represent actual occurrences in the system, such as a user action or a sensor reading.
-- **`VirtualEvent`**: These are events that are derived or generated by the system itself, often as a result of processing physical events.
+## Event Catalog
 
-## `SystemEvent`
+Physical events must be registered in one or more `EventCatalog` instances. The `EventCatalog` is responsible for
+defining and maneging known event types, their serialization and deserialization for the event processing pipeline.
 
-`SystemEvent`s are a special category of events used by Krescent for internal purposes. Some examples include:
+The catalog also defines the type identifier for each event. Naming usually follows domain-based `domain.event`
+naming conventions where the type starts with the namespace of the domain and then ends with the event name.
 
-- **`SystemStreamHeadEvent`**: Indicates the beginning of an event stream.
-- **`SystemStreamTailEvent`**: Indicates the end of an event stream.
-- **`SystemHintCommitTransactionEvent`**: Provides a hint to commit a transaction, often used in scenarios involving transactional event processing.
+```kotlin
+val bookstoreEventCatalog = buildEventCatalog(1) {
+  event<BookAddedEvent>("book.added")
+  event<BookPriceChangedEvent>("book.price_changed")
+  event<BookRemovedEvent>("book.removed")
+  event<BookLentEvent>("book.lent")
+  event<BookReturnedEvent>("book.returned")
+  event<BookCopyAddedEvent>("book.copy_added")
+  event<BookCopyRemovedEvent>("book.copy_removed")
+}
+```
+
+All event catalogs are **versioned** using a revision number. You should increment the revision number **whenever
+breaking changes** are made to the events in the catalog that would **affect serialization or deserialization** or
+**change the meaning** of the events.
+
+> [!IMPORTANT]
+> A change in this revision number will cause all models that use this catalog to discard their checkpoints the next
+> time they are loaded.
 
-These system events help manage and coordinate the flow of events within Krescent.