Merge pull request #115 from mizrael/feature/docs-github-pages

feat: migrate docs from GitBook to GitHub Pages

Author: mizrael

.github/workflows/docs.yml

@@ -0,0 +1,47 @@
+name: Deploy Docs to GitHub Pages
+
+on:
+  push:
+    branches: [develop]
+    paths:
+      - 'docs/**'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Build with Jekyll
+        uses: actions/jekyll-build-pages@v1
+        with:
+          source: ./docs
+          destination: ./_site
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

docs/.gitignore

@@ -0,0 +1,5 @@
+_site/
+.jekyll-cache/
+.jekyll-metadata
+Gemfile.lock
+.sass-cache/

docs/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+gem "jekyll", "~> 4.3"
+gem "just-the-docs", "~> 0.10"

docs/_config.yml

@@ -0,0 +1,21 @@
+source: "."
+title: OpenSleigh
+description: A distributed Saga management library for .NET Core
+baseurl: "/OpenSleigh"
+url: "https://mizrael.github.io"
+
+theme: just-the-docs
+
+color_scheme: light
+
+nav_enabled: true
+search_enabled: true
+
+heading_anchors: true
+
+back_to_top: true
+back_to_top_text: "Back to top"
+
+exclude:
+  - plans/
+  - Gemfile.lock

docs/assets/images/opensleigh-banner.png

@@ -0,0 +1,102 @@
+---
+layout: default
+title: First Steps
+parent: How-To
+nav_order: 2
+---
+
+# First Steps
+
+OpenSleigh is intended to be flexible and developer-friendly. It makes use of Dependency Injection for its own initialization and the setup of the dependencies.
+
+## Configure Transport and Persistence
+
+The first step, once you have installed the [Core library](https://www.nuget.org/packages/OpenSleigh/), is to add OpenSleigh to the Services collection:
+
+```csharp
+Host.CreateDefaultBuilder(args)
+    .ConfigureServices((hostContext, services) => {
+                services.AddOpenSleigh(cfg =>{ ... });
+    });
+```
+
+OpenSleigh needs to be configured to point to a specific Transport bus and a Persistence mechanism for the Saga States:
+
+```csharp
+Host.CreateDefaultBuilder(args)
+    .ConfigureServices((hostContext, services) => {
+        services.AddOpenSleigh(cfg =>{
+            var rabbitSection = hostContext.Configuration.GetSection("Rabbit");
+            var rabbitCfg = new RabbitConfiguration(rabbitSection["HostName"],
+                rabbitSection["UserName"],
+                rabbitSection["Password"]);
+
+            cfg.UseRabbitMQTransport(rabbitCfg);
+
+            var mongoSection = hostContext.Configuration.GetSection("Mongo");
+            var mongoCfg = new MongoConfiguration(mongoSection["ConnectionString"],
+                mongoSection["DbName"],
+                MongoSagaStateRepositoryOptions.Default);
+
+            cfg.UseMongoPersistence(mongoCfg);
+        });
+    });
+```
+
+In this example, the system is configured to use RabbitMQ as message bus and MongoDB to persist the data.
+
+**IMPORTANT**: for detailed instructions on each Transport and Persistence mechanism, please refer to the library's documentation.
+
+## Adding a Saga
+
+A Saga is a simple class inheriting from the base [`Saga`](https://github.com/mizrael/OpenSleigh/blob/develop/src/OpenSleigh/Saga.cs) class:
+
+```csharp
+public record MyAwesomeSagaState { }
+
+public class MyAwesomeSaga : Saga
+{
+    private readonly ILogger<MyAwesomeSaga> _logger;
+
+    public MyAwesomeSaga(ILogger<MyAwesomeSaga> logger)
+    {
+        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+    }
+}
+```
+
+Dependency injection can be used to provide services to a Saga.
+
+Now, all you have to do is register and configure the Saga:
+
+```csharp
+services.AddOpenSleigh(cfg =>{
+    cfg.AddSaga<MyAwesomeSaga>();
+});
+```
+
+Sagas can also hold some _state_. In this case, we need to define its shape by creating a `class` or a `record` and setting it on the Saga:
+
+```csharp
+public record MySagaState
+{
+    public int Foo = 42;
+    public string Bar = "71";
+};
+
+public class SagaWithState : Saga<MySagaState> {
+
+}
+```
+
+Now you can register it this way:
+
+```csharp
+services.AddOpenSleigh(cfg =>{
+    cfg.AddSaga<SagaWithState, MySagaState>();
+});
+```
+
+The State can be accessed later on via `this.Context.State` and is also persisted automatically after a message is processed. For more details, check the [Handling Messages]({% link how-to/handling-messages.md %}) page.
+
+**IMPORTANT**: each Saga should have its own State class. Don't reuse State classes!

docs/how-to/first-steps.md

@@ -0,0 +1,76 @@
+---
+layout: default
+title: Handling Messages
+parent: How-To
+nav_order: 3
+---
+
+# Handling Messages
+
+## Starting a Saga
+
+In order to start a Saga, we need to tell OpenSleigh which message type can be used as "initiator". To do that, we need to add the [`IStartedBy<>`](https://github.com/mizrael/OpenSleigh/blob/develop/src/OpenSleigh/Transport/IStartedBy.cs) interface to the Saga and implement it:
+
+```csharp
+public class MyAwesomeSaga :
+    Saga,
+    IStartedBy<StartMyAwesomeSaga>
+{
+    public async ValueTask HandleAsync(
+        IMessageContext<StartMyAwesomeSaga> context,
+        CancellationToken cancellationToken = default)
+    {
+        _logger.LogInformation($"starting saga '{context.Message.CorrelationId}'...");
+    }
+}
+```
+
+Messages are simple POCO classes (or records), implementing the [`IMessage`](https://github.com/mizrael/OpenSleigh/blob/develop/src/OpenSleigh/Transport/IMessage.cs) interface:
+
+```csharp
+public record StartMyAwesomeSaga() : IMessage { }
+```
+
+## Handling messages
+
+In order to handle more message types, it is necessary to add and implement the [`IHandleMessage<>`](https://github.com/mizrael/OpenSleigh/blob/develop/src/OpenSleigh/Transport/IHandleMessage.cs) interface on the Saga:
+
+```csharp
+public class MyAwesomeSaga :
+    Saga,
+    IStartedBy<StartMyAwesomeSaga>,
+    IHandleMessage<MyAwesomeSagaCompleted>
+{
+    // code omitted for brevity
+
+    public async ValueTask HandleAsync(
+        IMessageContext<MyAwesomeSagaCompleted> context,
+        CancellationToken cancellationToken = default)
+    {
+        _logger.LogInformation($"saga '{context.Message.CorrelationId}' completed!");
+    }
+}
+```
+
+## Stopping a Saga
+
+A Saga can be marked as completed by calling the `MarkAsCompleted()` on its state:
+
+```csharp
+public class MyAwesomeSaga :
+    Saga,
+    IStartedBy<StartMyAwesomeSaga>,
+    IHandleMessage<MyAwesomeSagaCompleted>
+{
+    // code omitted for brevity
+
+    public async ValueTask HandleAsync(
+        IMessageContext<MyAwesomeSagaCompleted> context,
+        CancellationToken cancellationToken = default)
+    {
+        this.Context.MarkAsCompleted();
+    }
+}
+```
+
+This step is completely optional but signals OpenSleigh to stop sending messages to that Saga instance.

docs/how-to/handling-messages.md

@@ -0,0 +1,28 @@
+---
+layout: default
+title: Idempotency
+parent: How-To
+nav_order: 5
+---
+
+# Idempotency
+
+By design, OpenSleigh uses the [Outbox pattern](https://www.davidguida.net/improving-microservices-reliability-part-2-outbox-pattern/) to ensure at-least-once delivery. This guarantees the reliability of the publisher side, but we still need to rely on the transport mechanism to deliver the message.
+
+On the receiver side, we can expect messages to be processed as they arrive. But what happens when the same message is published more than once?
+
+OpenSleigh assigns an ID to each outgoing message, which is then used on the receiver side to ensure at-most-once processing. When a message is received, OpenSleigh fetches the metadata of the desired Saga, locks it so no other service instance can access it, and compares the message ID against the list of all the messages processed so far.
+
+Normally, this message ID is a simple [GUID v7](https://learn.microsoft.com/en-us/dotnet/api/system.guid.createversion7?view=net-9.0), but it is also possible to customize the ID generation by having your message class implement [`IIdempotentMessage`](https://github.com/mizrael/OpenSleigh/blob/develop/src/OpenSleigh/Transport/IIdempotentMessage.cs) instead of [`IMessage`](https://github.com/mizrael/OpenSleigh/blob/develop/src/OpenSleigh/Transport/IMessage.cs):
+
+```csharp
+public record IdempotentMessage(string RequestId, int Foo) : IIdempotentMessage
+{
+    public IEnumerable<object> GetIdempotencyComponents()
+    {
+        yield return this.Foo;
+    }
+}
+```
+
+The `GetIdempotencyComponents` property helps OpenSleigh pick which elements of the message have to be utilized to build the _idempotency key_ that will later on be used as message ID.

docs/how-to/idempotency.md

@@ -0,0 +1,17 @@
+---
+layout: default
+title: How-To
+nav_order: 3
+has_children: true
+---
+
+# How-To
+
+This section contains step-by-step guides to help you get started with OpenSleigh and make the most of its features.
+
+- [Installation]({% link how-to/installation.md %}) — Install the NuGet packages
+- [First Steps]({% link how-to/first-steps.md %}) — Configure transport, persistence, and your first Saga
+- [Handling Messages]({% link how-to/handling-messages.md %}) — Start, handle, and stop Sagas
+- [Publishing Messages]({% link how-to/publishing-messages.md %}) — Publish messages and use publish-only mode
+- [Idempotency]({% link how-to/idempotency.md %}) — Ensure at-most-once message processing
+- [Logging Levels]({% link how-to/logging-levels.md %}) — Configure logging for OpenSleigh

docs/how-to/index.md

@@ -0,0 +1,26 @@
+---
+layout: default
+title: Installation
+parent: How-To
+nav_order: 1
+---
+
+# Installation
+
+OpenSleigh Core, Persistence, and Transport libraries are all available as NuGet packages:
+
+## Core
+
+- [Core library](https://www.nuget.org/packages/OpenSleigh/)
+- [In-Memory](https://www.nuget.org/packages/OpenSleigh.InMemory/) (useful for local dev)
+
+## Persistence
+
+- [MongoDB](https://www.nuget.org/packages/OpenSleigh.Persistence.Mongo/)
+- [MSSQL](https://www.nuget.org/packages/OpenSleigh.Persistence.SQLServer/)
+- [PostgreSQL](https://www.nuget.org/packages/OpenSleigh.Persistence.PostgreSQL/)
+
+## Transport
+
+- [RabbitMQ](https://www.nuget.org/packages/OpenSleigh.Transport.RabbitMQ/)
+- [Kafka](https://www.nuget.org/packages/OpenSleigh.Transport.Kafka/)