From 892913735382963c0bb65c46ab9a57e1a7b1f7b5 Mon Sep 17 00:00:00 2001 From: danielle9897 Date: Tue, 13 Aug 2024 19:01:16 +0300 Subject: [PATCH] RavenDB-22791 Akka.Persistence.RavenDB - enhance readme --- README.md | 228 +++++++++--------- .../RavenDbConfiguration.cs | 2 - src/Akka.Persistence.RavenDB/reference.conf | 37 ++- 3 files changed, 136 insertions(+), 131 deletions(-) diff --git a/README.md b/README.md index 42a9099..272aa9b 100644 --- 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= [""] -akka.persistence.journal.ravendb.name = "" -``` - -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= [""] -akka.persistence.snapshot-store.ravendb.name = "" -``` +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 index d4c021f..35dce7c 100644 --- 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; /// /// Flag determining whether the database should be automatically initialized. /// @@ -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 index 1c745a2..51a68c5 100644 --- a/src/Akka.Persistence.RavenDB/reference.conf +++ b/src/Akka.Persistence.RavenDB/reference.conf @@ -1,23 +1,23 @@ akka.persistence { journal { 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,7 +30,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 } @@ -38,23 +38,23 @@ akka.persistence { snapshot-store { 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 +67,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 +79,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 }