RavenDB-22791 Akka.Persistence.RavenDB - enhance readme

ravendb · Aug 13, 2024 · 62c245c · 62c245c
1 parent aa991bd
commit 62c245c
Show file tree

Hide file tree

Showing 3 changed files with 138 additions and 131 deletions.
diff --git a/README.md b/README.md
@@ -1,133 +1,141 @@
 # Akka.Persistence.RavenDB
 
-Akka Persistence journal and snapshot store backed by RavenDB database.
+Akka.Persistence.RavenDB is a persistence plugin for Akka.NET that integrates RavenDB as a durable storage backend.  
+It allows persisting journal events and snapshots of your Akka.NET actors to a RavenDB database.  
+Querying is supported through the Akka.Persistence query interface, with RavenDB serving as the underlying storage engine.  
 
-### Setup
+## Configuration
 
-To activate the journal plugin, add the following lines to actor system configuration file:
+To activate and use the Akka.Persistence.RavenDB plugin, you have the following configuration options:
+  * Configure using Akka.Hosting (the easy way)
+  * Configure directly in your actor system configuration file using HOCON (the classic way).
 
-```
-akka.persistence.journal.plugin = "akka.persistence.journal.ravendb"
-akka.persistence.journal.ravendb.urls= ["<urls to the ravendb instace>"]
-akka.persistence.journal.ravendb.name = "<database name for journals>"
-```
-
-Similar configuration may be used to setup a RavenDB snapshot store:
-
-```
-akka.persistence.snapshot-store.plugin = "akka.persistence.snapshot-store.ravendb"
-akka.persistence.snapshot-store.ravendb.urls= ["<urls to the ravendb instace>"]
-akka.persistence.snapshot-store.ravendb.name = "<database name for snapshots>"
-```
+Note:  
+When configuring the plugin using both Akka.Hosting and HOCON, in cases where parameters overlap,  
+the configuration provided via Akka.Hosting take precedence and will override the corresponding HOCON settings.
 
-The `urls` and the `name` can be identical but the configuration must be provided separately to Journal and Snapshot Store.
+### Configure with `Akka.Hosting`
 
-### Configuration
+Using _Akka.Hosting_, you can easily set up the plugin within your application's startup configuration.  
+Here is a basic example:  
 
-Both journal and snapshot store share the same configuration keys (however they resides in separate scopes, so they are definied distinctly for either journal or snapshot store):
-
-## The Easy Way, Using `Akka.Hosting`
 ```csharp
-var host = new HostBuilder()
-    .ConfigureServices((context, services) => {
-        services.AddAkka("my-system-name", (builder, provider) =>
-        {
-            builder.WithRavenDbPersistence(
-                urls: new[] { "http://localhost:8080" },
-                databaseName: "AkkaStorage");
-        });
-    })
+using Akka.Hosting;
+using Akka.Persistence;
+using Akka.Persistence.Hosting;
+using Akka.Persistence.RavenDb.Hosting;
+
+var host = new HostBuilder().ConfigureServices((context, services) => {
+    services.AddAkka("my-actor-system-name", (builder, provider) =>
+    {
+        builder.WithRavenDbPersistence(
+            urls: new[] { "http://localhost:8080" },
+            databaseName: "AkkaStorage");
+    });
+})
+
+var app = builder.Build();
+app.Run();
 ```
 
-## The Classic Way, Using HOCON
+### Configure with `HOCON`
+
+While both the journal and snapshot-store have the same configuration keys, they reside in separate scopes.  
+So when configuring using _HOCON_, the settings for the journal and snapshot-store must be provided separately.  
+For example, properties `urls` and `name` can have the same values for both stores, but they still need to be defined distinctly within their respective sections.
+
 ```hocon
 akka.persistence {
-	journal {
-		ravendb {
-			# qualified type name of the RavenDB persistence journal actor
-			class = "Akka.Persistence.RavenDb.Journal.RavenDbJournal, Akka.Persistence.RavenDb"
-
-			# dispatcher used to drive journal actor
-			plugin-dispatcher = "akka.actor.default-dispatcher"
-
-			# urls to the ravendb cluster
-			urls = ["http://localhost:8080"]
-
-			# database name where journal events will be stored
-			name = "AkkaStorage"
-
-			# create the database if it doesn't exists
-			auto-initialize = false
-
-			# Location of a client certificate to access a secure RavenDB database
-			# if password required it should be stored in `RAVEN_CERTIFICATE_PASSWORD` env variable
-			#certificate-path = "\\path\\to\\cert.pfx"
-
-			# Timeout for 'save' requests sent to RavenDB, such as writing or deleting
-			# as opposed to stream operations which may take longer and have a different timeout (12h).
-			# Client will fail requests that take longer than this.
-			# default: 30s
-			#save-changes-timeout = 30s
-
-			# Http version for the RavenDB client to use in communication with the server
-			# default: 2.0
-			#http-version = "2.0"
-
-			# Determines whether to compress the data sent in the clinet-server TCP communication
-			# default: false
-			#disable-tcp-compression = false
-		}
-	}
-
-	snapshot-store {
-		ravendb {
-			# qualified type name of the RavenDB persistence snapshot actor
-			class = "Akka.Persistence.RavenDb.Snapshot.RavenDbSnapshotStore, Akka.Persistence.RavenDb"
-
-			# dispatcher used to drive snapshot storage actor
-			plugin-dispatcher = "akka.actor.default-dispatcher"
-
-			# urls to the ravendb cluster
-			urls = ["http://localhost:8080"]
-
-			# database name where snapshots will be stored
-			name = "AkkaStorage"
-
-			# create the database if it doesn't exists
-			auto-initialize = false
-
-			# Location of a client certificate to access a secure RavenDB database
-			# if password required it should be stored in `RAVEN_CERTIFICATE_PASSWORD` env variable
-			#certificate-path = "\\path\\to\\cert.pfx"
-
-			# Timeout for 'save' requests sent to RavenDB, such as writing or deleting
-			# as opposed to stream operations which may take longer and have a different timeout (12h).
-			# Client will fail requests that take longer than this.
-			# default: 30s
-			#save-changes-timeout = 30s
-
-			# Http version for the RavenDB client to use in communication with the server
-			# default: 2.0
-			#http-version = "2.0"
-
-			# Determines whether to compress the data sent in the clinet-server TCP communication
-			# default: false
-			#disable-tcp-compression = false
-		}
-	}
-
-	query {
+    # Setup the RavenDB journal store:
+    journal {
+        plugin = "akka.persistence.journal.ravendb"
+        ravendb {
+            # Qualified type name of the RavenDB persistence journal actor
+            class = "Akka.Persistence.RavenDb.Journal.RavenDbJournal, Akka.Persistence.RavenDb" 
+
+            # Dispatcher used to drive journal actor
+            plugin-dispatcher = "akka.actor.default-dispatcher"
+
+            # URLs to the RavenDB cluster
+            urls = ["http://localhost:8080"]
+            
+            # Database name where journal events will be stored
+            name = "AkkaStorage"
+            
+            # Create the database if it doesn't exist
+            auto-initialize = false
+
+            # Location of a client certificate to access a secure RavenDB database.
+            # If a password is required, it should be stored in the `RAVEN_CERTIFICATE_PASSWORD` env variable.
+            #certificate-path = "\\path\\to\\cert.pfx"
+
+            # Timeout for 'save' requests sent to RavenDB, such as writing or deleting
+            # as opposed to stream operations which may take longer and have a different timeout (12h).
+            # Client will fail requests that take longer than this.
+            # default: 30s
+            #save-changes-timeout = 30s
+
+            # Http version for the RavenDB client to use in communication with the server
+            # default: 2.0
+            #http-version = "2.0"
+
+            # Determines whether to compress the data sent in the client-server TCP communication
+            # default: false
+            #disable-tcp-compression = false
+        }
+    }
+    
+    # Setup the RavenDB snapshot store:
+    snapshot-store {
+        plugin = "akka.persistence.snapshot-store.ravendb"
+        ravendb {
+            # Qualified type name of the RavenDB persistence snapshot actor
+            class = "Akka.Persistence.RavenDb.Snapshot.RavenDbSnapshotStore, Akka.Persistence.RavenDb"
+
+            # Dispatcher used to drive snapshot storage actor
+            plugin-dispatcher = "akka.actor.default-dispatcher"
+
+            # URLs to the RavenDB cluster
+            urls = ["http://localhost:8080"]
+            
+            # Database name where snapshots will be stored
+            name = "AkkaStorage"
+            
+            # Create the database if it doesn't exist
+            auto-initialize = false
+
+            # Location of a client certificate to access a secure RavenDB database.
+            # If a password is required, it should be stored in the `RAVEN_CERTIFICATE_PASSWORD` env variable.
+            #certificate-path = "\\path\\to\\cert.pfx"
+
+            # Timeout for 'save' requests sent to RavenDB, such as writing or deleting
+            # as opposed to stream operations which may take longer and have a different timeout (12h).
+            # Client will fail requests that take longer than this.
+            # default: 30s
+            #save-changes-timeout = 30s
+
+            # Http version for the RavenDB client to use in communication with the server
+            # default: 2.0
+            #http-version = "2.0"
+
+            # Determines whether to compress the data sent in the client-server TCP communication
+            # default: false
+            #disable-tcp-compression = false
+        }
+    }
+    
+    query {
+        # Configure RavenDB as the underlying storage engine for querying:
         ravendb {
             # Implementation class of the EventStore ReadJournalProvider
             class = "Akka.Persistence.RavenDb.Query.RavenDbReadJournalProvider, Akka.Persistence.RavenDb"
 
             # The interval at which to check for new ids/events
-			# deafult: 3s
+            # default: 3s
             #refresh-interval = 3s
   
-            # The number of events to keep buffered while querying until they
-            # are delivered downstreams.
-			# default: 65536
+            # The number of events to keep buffered while querying until they are delivered downstream.
+            # default: 65536
             #max-buffer-size = 65536
         }
     }

diff --git a/src/Akka.Persistence.RavenDB/RavenDbConfiguration.cs b/src/Akka.Persistence.RavenDB/RavenDbConfiguration.cs
@@ -12,7 +12,6 @@ public abstract class RavenDbConfiguration
         public readonly Version? HttpVersion;
         public readonly bool? DisableTcpCompression;
         public readonly TimeSpan SaveChangesTimeout;
-        public readonly TimeSpan ReadTimeout;
         /// <summary>
         /// Flag determining whether the database should be automatically initialized.
         /// </summary>
@@ -38,7 +37,6 @@ protected RavenDbConfiguration(Config config)
 
             DisableTcpCompression = config.GetBoolean("disable-tcp-compression");
             SaveChangesTimeout = config.GetTimeSpan("save-changes-timeout", TimeSpan.FromSeconds(30));
-            ReadTimeout = config.GetTimeSpan("read-timeout", TimeSpan.FromSeconds(60));
         }
 
         public DocumentConventions ToDocumentConventions()

diff --git a/src/Akka.Persistence.RavenDB/reference.conf b/src/Akka.Persistence.RavenDB/reference.conf
@@ -1,23 +1,24 @@
 akka.persistence {
 	journal {
+	    plugin = "akka.persistence.journal.ravendb"
 		ravendb {
-			# qualified type name of the RavenDB persistence journal actor
+			# Qualified type name of the RavenDB persistence journal actor
 			class = "Akka.Persistence.RavenDb.Journal.RavenDbJournal, Akka.Persistence.RavenDb"
 
-			# dispatcher used to drive journal actor
+			# Dispatcher used to drive journal actor
 			plugin-dispatcher = "akka.actor.default-dispatcher"
 
-			# urls to the ravendb cluster
+			# URLs to the ravendb cluster
 			urls = ["http://localhost:8080"]
 
-			# database name where journal events will be stored
+			# Database name where journal events will be stored
 			name = "AkkaStorage"
 
-			# create the database if it doesn't exists
+			# Create the database if it doesn't exist
 			auto-initialize = false
 
-			# Location of a client certificate to access a secure RavenDB database
-			# if password required it should be stored in `RAVEN_CERTIFICATE_PASSWORD` env variable
+			# Location of a client certificate to access a secure RavenDB database.
+			# If a password is required, it should be stored in the `RAVEN_CERTIFICATE_PASSWORD` env variable.
 			#certificate-path = "\\path\\to\\cert.pfx"
 
 			# Timeout for 'save' requests sent to RavenDB, such as writing or deleting
@@ -30,31 +31,32 @@ akka.persistence {
 			# default: 2.0
 			#http-version = "2.0"
 
-			# Determines whether to compress the data sent in the clinet-server TCP communication
+			# Determines whether to compress the data sent in the client-server TCP communication
 			# default: false
 			#disable-tcp-compression = false
 		}
 	}
 
 	snapshot-store {
+	    plugin = "akka.persistence.snapshot-store.ravendb"
 		ravendb {
-			# qualified type name of the RavenDB persistence snapshot actor
+			# Qualified type name of the RavenDB persistence snapshot actor
 			class = "Akka.Persistence.RavenDb.Snapshot.RavenDbSnapshotStore, Akka.Persistence.RavenDb"
 
-			# dispatcher used to drive snapshot storage actor
+			# Dispatcher used to drive snapshot storage actor
 			plugin-dispatcher = "akka.actor.default-dispatcher"
 
-			# urls to the ravendb cluster
+			# URLs to the ravendb cluster
 			urls = ["http://localhost:8080"]
 
-			# database name where snapshots will be stored
+			# Database name where snapshots will be stored
 			name = "AkkaStorage"
 
-			# create the database if it doesn't exists
+			# Create the database if it doesn't exist
 			auto-initialize = false
 
-			# Location of a client certificate to access a secure RavenDB database
-			# if password required it should be stored in `RAVEN_CERTIFICATE_PASSWORD` env variable
+			# Location of a client certificate to access a secure RavenDB database.
+			# If a password is required, it should be stored in the `RAVEN_CERTIFICATE_PASSWORD` env variable.
 			#certificate-path = "\\path\\to\\cert.pfx"
 
 			# Timeout for 'save' requests sent to RavenDB, such as writing or deleting
@@ -67,7 +69,7 @@ akka.persistence {
 			# default: 2.0
 			#http-version = "2.0"
 
-			# Determines whether to compress the data sent in the clinet-server TCP communication
+			# Determines whether to compress the data sent in the client-server TCP communication
 			# default: false
 			#disable-tcp-compression = false
 		}
@@ -79,11 +81,10 @@ akka.persistence {
             class = "Akka.Persistence.RavenDb.Query.RavenDbReadJournalProvider, Akka.Persistence.RavenDb"
 
             # The interval at which to check for new ids/events
-			# deafult: 3s
+			# default: 3s
             #refresh-interval = 3s
 
-            # The number of events to keep buffered while querying until they
-            # are delivered downstreams.
+            # The number of events to keep buffered while querying until they are delivered downstream.
 			# default: 65536
             #max-buffer-size = 65536
         }