Merry: Projections Management with CLI

.github/workflows/release.yml

@@ -1,7 +1,7 @@
 name: Release
 
 env:
-  PRERELEASE_BRANCHES: pippin # Comma separated list of prerelease branch names. 'alpha,rc, ...'
+  PRERELEASE_BRANCHES: merry, pippin
 
 on:
   pull_request:

Documentation/CLI/Runtime/EventHandlers/get.md

@@ -1,6 +1,6 @@
 ---
 title: Get
-description: Gets details of a specific Event Handler currently registered a Client to the Runtime
+description: Gets details of a specific Event Handler currently registered by Clients to the Runtime
 weight: 20
 repository: https://github.com/dolittle/Runtime
 ---
@@ -11,15 +11,15 @@ dolittle runtime eventhandlers get <identifier> [options]
 
 ### Arguments
 
-| Argument | Description                                             |
-|----------|---------------------------------------------------------|
-| `<identifier>`   | The identifier of the Event Handler to get details for. Format: id/alias[:scope] |
+| Argument       | Description                                                                      |
+|----------------|----------------------------------------------------------------------------------|
+| `<identifier>` | The identifier of the Event Handler to get details for. Format: id/alias[:scope] |
 
 ### Options
 
 | Option                  | Description                                                                                              |
 |-------------------------|----------------------------------------------------------------------------------------------------------|
-| `--tenant <id>`         | Only show Event Handler information for the specified Tenant.                                            |
+| `--tenant <id>`         | Only show Stream Processor status for the specified Tenant.                                              |
 | `--runtime host[:port]` | The address to the management endpoint of a Runtime. See [details]({{< ref "../../Runtime#details" >}}). |
 | `--output table\|json`  | Select the format the output of the subcommand. Defaults to table.                                       |
 | `--wide`                | If set, prints more details in table format for a wider output.                                          |

Documentation/CLI/Runtime/EventHandlers/replay.md

@@ -1,6 +1,6 @@
 ---
 title: Replay
-description: Initiates reprocessing of events for a specific Event Handler currently registered a Client to the Runtime
+description: Initiates reprocessing of events for a specific Event Handler currently registered by Clients to the Runtime
 weight: 30
 repository: https://github.com/dolittle/Runtime
 ---
@@ -16,9 +16,9 @@ dolittle runtime eventhandlers replay all <identifier> [options]
 
 ### Arguments
 
-| Argument | Description                                             |
-|----------|---------------------------------------------------------|
-| `<identifier>`   | The identifier of the Event Handler to replay. Format: id/alias[:scope] |
+| Argument       | Description                                                             |
+|----------------|-------------------------------------------------------------------------|
+| `<identifier>` | The identifier of the Event Handler to replay. Format: id/alias[:scope] |
 
 ### Options
 
@@ -39,10 +39,10 @@ dolittle runtime eventhandlers replay from <identifier> <position> [options]
 
 ### Arguments
 
-| Argument     | Description                                                                                                               |
-|--------------|---------------------------------------------------------------------------------------------------------------------------|
-| `<identifier>`   | The identifier of the Event Handler to replay. Format: id/alias[:scope] |
-| `<position>` | The position _in the Event Handler stream_ to star reprocessing events from. Cannot be greater than the current position. |
+| Argument       | Description                                                                                                               |
+|----------------|---------------------------------------------------------------------------------------------------------------------------|
+| `<identifier>` | The identifier of the Event Handler to replay. Format: id/alias[:scope]                                                   |
+| `<position>`   | The position _in the Event Handler stream_ to star reprocessing events from. Cannot be greater than the current position. |
 
 ### Options
 

Documentation/CLI/Runtime/Projections/_index.md

@@ -0,0 +1,21 @@
+---
+title: Projections
+description: Commands related to management of Projections
+weight: 10
+repository: https://github.com/dolittle/Runtime
+---
+
+```shell
+dolittle runtime projections [subcommand]
+```
+
+### Options
+
+| Option                  | Description                                                                                              |
+|-------------------------|----------------------------------------------------------------------------------------------------------|
+| `--runtime host[:port]` | The address to the management endpoint of a Runtime. See [details]({{< ref "../../Runtime#details" >}}). |
+| `--output table\|json`  | Select the format the output of the subcommand. Defaults to table.                                       |
+| `--wide`                | If set, prints more details in table format for a wider output.                                          |
+| `--help`                | Show help information.                                                                                   |
+
+### Subcommands

Documentation/CLI/Runtime/Projections/get.md

@@ -0,0 +1,27 @@
+---
+title: Get
+description: Gets details of a specific Projection currently registered by Clients to the Runtime
+weight: 20
+repository: https://github.com/dolittle/Runtime
+---
+
+```shell
+dolittle runtime projection get <identifier> <scope> [options]
+```
+
+### Arguments
+
+| Argument       | Description                                                                                                             |
+|----------------|-------------------------------------------------------------------------------------------------------------------------|
+| `<identifier>` | The identifier or alias of the Projection to get details for                                                            |
+| `<scope>`      | The scope of the Projection to get details for. Only required when the identifier or alias matches multiple projections |
+
+### Options
+
+| Option                  | Description                                                                                              |
+|-------------------------|----------------------------------------------------------------------------------------------------------|
+| `--tenant <id>`         | Only show Stream Processor status for the specified Tenant.                                              |
+| `--runtime host[:port]` | The address to the management endpoint of a Runtime. See [details]({{< ref "../../Runtime#details" >}}). |
+| `--output table\|json`  | Select the format the output of the subcommand. Defaults to table.                                       |
+| `--wide`                | If set, prints more details in table format for a wider output.                                          |
+| `--help`                | Show help information.                                                                                   |

Documentation/CLI/Runtime/Projections/list.md

@@ -0,0 +1,20 @@
+---
+title: List
+description: Lists all the Projections currently registered by Clients to the Runtime
+weight: 10
+repository: https://github.com/dolittle/Runtime
+---
+
+```shell
+dolittle runtime projections list [options]
+```
+
+### Options
+
+| Option                  | Description                                                                                              |
+|-------------------------|----------------------------------------------------------------------------------------------------------|
+| `--tenant <id>`         | Only show Stream Processor status for the specified Tenant.                                              |
+| `--runtime host[:port]` | The address to the management endpoint of a Runtime. See [details]({{< ref "../../Runtime#details" >}}). |
+| `--output table\|json`  | Select the format the output of the subcommand. Defaults to table.                                       |
+| `--wide`                | If set, prints more details in table format for a wider output.                                          |
+| `--help`                | Show help information.                                                                                   |

Documentation/CLI/Runtime/Projections/replay.md

@@ -0,0 +1,27 @@
+---
+title: Replay
+description: Initiates a replay of a Projection currently registered by Clients to the Runtime
+weight: 30
+repository: https://github.com/dolittle/Runtime
+---
+
+Initiates a replay of all events to rebuild Projection read models. This command drops all persisted read models, and potential copies in MongoDB, and restarts the Projection to build new ones.
+
+```shell
+dolittle runtime projection replay <identifier> <scope> [options]
+```
+
+### Arguments
+
+| Argument       | Description                                                                                                    |
+|----------------|----------------------------------------------------------------------------------------------------------------|
+| `<identifier>` | The identifier or alias of the Projection to replay                                                            |
+| `<scope>`      | The scope of the Projection to replay. Only required when the identifier or alias matches multiple projections |
+
+### Options
+
+| Option                  | Description                                                                                              |
+|-------------------------|----------------------------------------------------------------------------------------------------------|
+| `--tenant <id>`         | Only replay the Projection for the specified Tenant. If not provided, replays for all Tenants            |
+| `--runtime host[:port]` | The address to the management endpoint of a Runtime. See [details]({{< ref "../../Runtime#details" >}}). |
+| `--help`                | Show help information.                                                                                   |

Documentation/CLI/_index.md

@@ -18,6 +18,9 @@ This section helps you learn about how to use the Dolittle CLI tool. If you're n
 | `dolittle runtime eventhandlers get`    | Get details about a running Event Handler           | [Details]({{< ref "Runtime/EventHandlers/get" >}})    |
 | `dolittle runtime eventhandlers replay` | Replay events for a running Event Handler           | [Details]({{< ref "Runtime/EventHandlers/replay" >}}) |
 | `dolittle runtime eventtypes list`      | List all registered Event Types                     | [Details]({{< ref "Runtime/EventTypes/list" >}})      |
+| `dolittle runtime projections list`     | List all running Projections                        | [Details]({{< ref "Runtime/Projections/list" >}})     |
+| `dolittle runtime projections get`      | Get details about a running Projection              | [Details]({{< ref "Runtime/Projections/get" >}})      |
+| `dolittle runtime projections replay`   | Replay a running Projection                         | [Details]({{< ref "Runtime/Projections/replay" >}})   |
 
 ## How to install
 

Source/CLI/CLI.csproj

@@ -28,6 +28,7 @@
 
     <ItemGroup>
         <PackageReference Include="ConsoleTables" Version="$(ConsoleTablesVersion)" />
+        <PackageReference Include="Contrib.Grpc.Core.M1" Version="$(GrpcVersion)" />
         <PackageReference Include="Docker.DotNet" Version="$(DockerDotNetVersion)" />
         <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="$(MicrosoftExtensionsVersion)" />
         <PackageReference Include="McMaster.Extensions.CommandLineUtils" Version="$(McMasterVersion)" />

Source/CLI/Runtime/Command.cs

@@ -11,9 +11,10 @@ namespace Dolittle.Runtime.CLI.Runtime;
 /// The "dolittle runtime" command.
 /// </summary>
 [Command("runtime", Description = "Manage a Runtime")]
-[Subcommand(typeof(EventHandlers.Command))]
 [Subcommand(typeof(Aggregates.Command))]
+[Subcommand(typeof(EventHandlers.Command))]
 [Subcommand(typeof(EventTypes.Command))]
+[Subcommand(typeof(Projections.Command))]
 public class Command : CommandBase
 {
     /// <summary>
@@ -32,4 +33,4 @@ public Command(ICanLocateRuntimes runtimes, IDiscoverEventTypes eventTypesDiscov
     /// <param name="cli">The <see cref="CommandLineApplication"/> that is executed.</param>
     public void OnExecute(CommandLineApplication cli)
         => cli.ShowHelp();
-}
+}

Source/CLI/Runtime/EventHandlers/EventHandlerStatus.cs

@@ -3,6 +3,7 @@
 
 using System.Collections.Generic;
 using Dolittle.Runtime.Artifacts;
+using Dolittle.Runtime.CLI.Runtime.Events.Processing;
 using Dolittle.Runtime.Events.Processing.EventHandlers;
 using Dolittle.Runtime.Events.Store;
 
@@ -32,4 +33,4 @@ public record EventHandlerStatus(
     /// Gets a value indicating whether the Event Handler is in the default Scope.
     /// </summary>
     public bool IsInDefaultScope => Id.Scope.Equals(ScopeId.Default);
-}
+}

Source/CLI/Runtime/EventHandlers/Get/Command.cs

@@ -7,6 +7,7 @@
 using System.Threading.Tasks;
 using Dolittle.Runtime.ApplicationModel;
 using Dolittle.Runtime.CLI.Options;
+using Dolittle.Runtime.CLI.Runtime.Events.Processing;
 using Dolittle.Runtime.CLI.Runtime.EventTypes;
 using Dolittle.Runtime.Serialization.Json;
 using McMaster.Extensions.CommandLineUtils;
@@ -42,14 +43,14 @@ public Command(ICanLocateRuntimes runtimes, IManagementClient client, IResolveEv
     TenantId Tenant { get; init; }
 
     /// <summary>
-    /// The Event Handler identifier argument used to provide the unique identifier of the Event Handler to replay.
+    /// The Event Handler identifier argument used to provide the unique identifier of the Event Handler to get.
     /// </summary>
     [Required]
     [Argument(0, Description = "The Event Handler identifier of the Event Handler to get details for")]
     EventHandlerIdOrAlias EventHandlerIdentifier { get; init; }
 
     /// <summary>
-    /// The entrypoint for the "dolittle runtime eventhandlers list" command.
+    /// The entrypoint for the "dolittle runtime eventhandlers get" command.
     /// </summary>
     /// <param name="cli">The <see cref="CommandLineApplication"/> that is executed.</param>
     public async Task OnExecuteAsync(CommandLineApplication cli)
@@ -83,30 +84,16 @@ Task WriteTableOutput(CommandLineApplication cli, EventHandlerStatus status)
         => Wide
             ? WriteDetailedOutput(cli, status)
             : WriteSimpleOutput(cli, status);
-
-    async Task WriteSimpleOutput(CommandLineApplication cli, EventHandlerStatus status)
-    {
-        if (status.Partitioned)
-        {
-            await WriteOutput(cli, status.States.Cast<PartitionedTenantScopedStreamProcessorStatus>().Select(CreateSimpleStateView)).ConfigureAwait(false);
-        }
-        else
-        {
-            await WriteOutput(cli, status.States.Cast<UnpartitionedTenantScopedStreamProcessorStatus>().Select(CreateSimpleStateView)).ConfigureAwait(false);
-        }
-    }
 
-    async Task WriteDetailedOutput(CommandLineApplication cli, EventHandlerStatus status)
-    {
-        if (status.Partitioned)
-        {
-            await WriteOutput(cli, MergePartitionedStates(status)).ConfigureAwait(false);
-        }
-        else
-        {
-            await WriteOutput(cli, status.States.Cast<UnpartitionedTenantScopedStreamProcessorStatus>().Select(CreateDetailedStateView)).ConfigureAwait(false);
-        }
-    }
+    Task WriteSimpleOutput(CommandLineApplication cli, EventHandlerStatus status)
+        => status.Partitioned
+            ? WriteOutput(cli, status.States.Cast<PartitionedTenantScopedStreamProcessorStatus>().Select(CreateSimpleStateView))
+            : WriteOutput(cli, status.States.Cast<UnpartitionedTenantScopedStreamProcessorStatus>().Select(CreateSimpleStateView));
+
+    Task WriteDetailedOutput(CommandLineApplication cli, EventHandlerStatus status)
+        => status.Partitioned
+            ? WriteOutput(cli, MergePartitionedStates(status))
+            : WriteOutput(cli, status.States.Cast<UnpartitionedTenantScopedStreamProcessorStatus>().Select(CreateDetailedStateView));
 
     static IEnumerable<PartitionedEventHandlerDetailedView> MergePartitionedStates(EventHandlerStatus status)
     {
@@ -150,4 +137,4 @@ static PartitionedEventHandlerDetailedView CreateDetailedStateView(PartitionedTe
             failingPartition?.FailureReason,
             failingPartition?.RetryTime ?? default,
             failingPartition?.ProcessingAttempts ?? 0);
-}
+}

Source/CLI/Runtime/EventHandlers/Get/EventHandlerSimpleView.cs

@@ -6,9 +6,9 @@
 namespace Dolittle.Runtime.CLI.Runtime.EventHandlers.Get;
 
 /// <summary>
-/// Represents a simple view of an Event Handler state.
+/// Represents a simple view of an Event Handler Stream Processor state.
 /// </summary>
 /// <param name="Tenant">The Tenant.</param>
-/// <param name="Position">The stream position-</param>
+/// <param name="Position">The stream position.</param>
 /// <param name="Status">The status.</param>
-public record EventHandlerSimpleView(Guid Tenant, ulong Position, string Status);
+public record EventHandlerSimpleView(Guid Tenant, ulong Position, string Status);

Source/CLI/Runtime/EventHandlers/Get/PartitionedEventHandlerDetailedView.cs

@@ -6,10 +6,10 @@
 namespace Dolittle.Runtime.CLI.Runtime.EventHandlers.Get;
 
 /// <summary>
-/// Represents a detailed view of a partitioned Event Handler state.
+/// Represents a detailed view of a partitioned Event Handler Stream Processor state.
 /// </summary>
 /// <param name="Tenant">The Tenant.</param>
-/// <param name="Position">The stream position-</param>
+/// <param name="Position">The stream position.</param>
 /// <param name="Status">The status.</param>
 /// <param name="LastSuccessfulOrFailedProcessing">When the last event was successfully processed or failed processing.</param>
 /// <param name="Partition">The Partition identifier.</param>
@@ -24,4 +24,4 @@ public record PartitionedEventHandlerDetailedView(
     string Partition,
     string FailureReason,
     DateTimeOffset RetryTime,
-    uint ProcessingAttempts);
+    uint ProcessingAttempts);

Source/CLI/Runtime/EventHandlers/Get/UnpartitionedEventHandlerDetailedView.cs

@@ -6,10 +6,10 @@
 namespace Dolittle.Runtime.CLI.Runtime.EventHandlers.Get;
 
 /// <summary>
-/// Represents a detailed view of an unpartitioned Event Handler state.
+/// Represents a detailed view of an unpartitioned Event Handler Stream Processor state.
 /// </summary>
 /// <param name="Tenant">The Tenant.</param>
-/// <param name="Position">The stream position-</param>
+/// <param name="Position">The stream position.</param>
 /// <param name="Status">The status.</param>
 /// <param name="FailureReason">The reason for failure.</param>
 /// <param name="RetryTime">The retry time.</param>
@@ -22,4 +22,4 @@ public record UnpartitionedEventHandlerDetailedView(
     string FailureReason,
     DateTimeOffset RetryTime,
     uint ProcessingAttempts,
-    DateTimeOffset LastSuccessfullyProcessed);
+    DateTimeOffset LastSuccessfullyProcessed);

Source/CLI/Runtime/EventHandlers/GetOneEventHandlerFailed.cs

@@ -0,0 +1,23 @@
+// Copyright (c) Dolittle. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+using System;
+using Dolittle.Runtime.Events.Processing.EventHandlers;
+
+namespace Dolittle.Runtime.CLI.Runtime.EventHandlers;
+
+/// <summary>
+/// Exception that gets thrown when getting one Event Handler fails.
+/// </summary>
+public class GetOneEventHandlerFailed : Exception
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="GetOneEventHandlerFailed"/> class.
+    /// </summary>
+    /// <param name="eventHandler">The Event Handler that getting one failed for.</param>
+    /// <param name="reason">The reason why getting one Event Handler failed.</param>
+    public GetOneEventHandlerFailed(EventHandlerId eventHandler, string reason)
+        : base($"Could not get event handler {eventHandler.EventHandler} in scope {eventHandler.Scope} because {reason}")
+    {
+    }
+}