Enhance activity logging and add game reveal functionality

Updated `ActivityExtensions.cs` to replace `ActivityTagsCollection` with an array of `KeyValuePair<string, object?>` for event tags. Introduced a new `GameRevealedEvent` method for logging game reveal events.

Added `RevealGameAsync` method in `GamesClient.cs` to cancel a game and retrieve its details, with improved error handling and logging. Updated event logging for game moves to include tags.

Expanded `IGamesClient.cs` with XML documentation for the new method and marked `CancelGameAsync` as obsolete.

Enhanced logging capabilities in `LogExtensions.cs` with a new method for revealing game errors.

Updated `readme.md` to reflect new functionality and provide usage examples for `RevealGameAsync`.

Author: christiannagel

src/clients/Codebreaker.GameAPIs.Client/ActivityExtensions.cs

@@ -4,27 +4,39 @@ internal static class ActivityExtensions
 {
     public static void ErrorEvent(this Activity? activity, string message)
     {
-        activity?.AddEvent(new ActivityEvent("Error", tags: new ActivityTagsCollection()
-            {
+        activity?.AddEvent(new ActivityEvent("Error", tags:
+            [
                 new KeyValuePair<string, object?>("otel.status_Code", "Error"),
                 new KeyValuePair<string, object?>("otel.status_description", message)
-            }));
+            ]));
     }
 
     public static void GameCreatedEvent(this Activity? activity, string gameId, string gameType)
     {
         activity?.SetBaggage("gameId", gameId);
         activity?.AddEvent(
             new ActivityEvent("GameCreated", 
-                tags: new ActivityTagsCollection() 
-                { 
+                tags:
+                [
                     new KeyValuePair<string, object?>("gameType", gameType) 
-                }));
+                ]));
     }
 
     public static void GameCanceledEvent(this Activity? activity, string gameId)
     {
         activity?.SetBaggage("gameId", gameId);
         activity?.AddEvent(new ActivityEvent("GameCanceled"));
     }
+    
+    public static void GameRevealedEvent(this Activity? activity, string gameId, string gameType)
+    {
+        activity?.SetBaggage("gameId", gameId);
+        activity?.AddEvent(
+            new ActivityEvent("GameRevealed", 
+                tags:
+                [
+                    new KeyValuePair<string, object?>("gameId", gameId),
+                    new KeyValuePair<string, object?>("gameType", gameType) 
+                ]));
+    }
 }

src/clients/Codebreaker.GameAPIs.Client/GamesClient.cs

@@ -46,7 +46,6 @@ public class GamesClient(HttpClient httpClient, ILogger<GamesClient> logger) : I
         }
     }
 
-
     /// <summary>
     /// Cancels a game.
     /// </summary>
@@ -74,6 +73,44 @@ public async Task CancelGameAsync(Guid id, string playerName, GameType gameType,
         }
     }
 
+    /// <summary>
+    /// Cancels and reveals the details of a game based on the specified parameters.
+    /// </summary>
+    /// <param name="id">The unique identifier of the game to reveal.</param>
+    /// <param name="playerName">The name of the player requesting the game details. Cannot be null or empty.</param>
+    /// <param name="gameType">The type of the game to reveal.</param>
+    /// <param name="cancellationToken">A token to monitor for cancellation requests. Optional.</param>
+    /// <returns>A <see cref="GameInfo"/> object containing the details of the revealed game.</returns>
+    /// <exception cref="HttpRequestException"></exception>
+    /// <exception cref="InvalidOperationException"></exception>
+    public async Task<GameInfo> RevealGameAsync(Guid id, string playerName, GameType gameType, CancellationToken cancellationToken = default)
+    {
+        using Activity? activity = ActivitySource.StartActivity("RevealGameAsync", ActivityKind.Client);
+        try
+        {
+            // First cancel/end the game
+            var request = new UpdateGameRequest(id, gameType, playerName, 0, true);
+            var cancelResponse = await httpClient.PatchAsJsonAsync($"/games/{id}", request, s_jsonOptions, cancellationToken);
+            cancelResponse.EnsureSuccessStatusCode();
+            
+            // Then get the full game details
+            var gameResponse = await httpClient.GetFromJsonAsync<GameInfo>($"/games/{id}", s_jsonOptions, cancellationToken) 
+                ?? throw new InvalidOperationException($"Could not retrieve game with ID {id}");
+            
+            int moveCount = gameResponse.Moves?.Count ?? 0;
+            logger.GameRevealed(id, moveCount);
+            activity?.GameRevealedEvent(id.ToString(), gameType.ToString());
+            
+            return gameResponse;
+        }
+        catch (HttpRequestException ex)
+        {
+            logger.RevealGameError(ex.Message, ex);
+            activity?.ErrorEvent(ex.Message);
+            throw;
+        }
+    }
+
     /// <summary>
     /// Set a game move by supplying guess pegs. This method returns the results of the move (the key pegs), and whether the game ended, and whether the game was won.
     /// </summary>
@@ -101,7 +138,11 @@ public async Task CancelGameAsync(Guid id, string playerName, GameType gameType,
                 ?? throw new InvalidOperationException();
 
             logger.MoveSet(id, moveResponse.MoveNumber);
-            activity?.AddEvent(new ActivityEvent("GameCreated"));
+            activity?.AddEvent(new ActivityEvent("MoveSet", 
+                tags: [ 
+                    new KeyValuePair<string, object?>("gameId", id.ToString()),
+                    new KeyValuePair<string, object?>("moveNumber", moveResponse.MoveNumber)
+                ]));
 
             (_, _, _, bool ended, bool isVictory, string[] results) = moveResponse;
             return (results, ended, isVictory);
@@ -157,8 +198,17 @@ public async Task<IEnumerable<GameInfo>> GetGamesAsync(GamesQuery query, Cancell
         try
         {
             string urlQuery = query.AsUrlQuery();
-            IEnumerable<GameInfo> games = (await httpClient.GetFromJsonAsync<IEnumerable<GameInfo>>($"/games/{urlQuery}", s_jsonOptions, cancellationToken)) ?? Enumerable.Empty<GameInfo>();
-            logger.GamesReceived(urlQuery, games.Count());
+            IEnumerable<GameInfo> games = (await httpClient.GetFromJsonAsync<IEnumerable<GameInfo>>($"/games{urlQuery}", s_jsonOptions, cancellationToken)) ?? [];
+
+            int gameCount = games.Count();
+            logger.GamesReceived(urlQuery, gameCount);
+
+            activity?.AddEvent(new ActivityEvent("GamesReceived",
+                tags: [
+                    new KeyValuePair<string, object?>("count", gameCount),
+                    new KeyValuePair<string, object?>("query", urlQuery)
+                ]));
+
             return games;
         }
         catch (HttpRequestException ex)

src/clients/Codebreaker.GameAPIs.Client/IGamesClient.cs

@@ -1,10 +1,89 @@
 namespace Codebreaker.GameAPIs.Client;
 
+/// <summary>
+/// Defines methods for interacting with games, including retrieving game information, managing game state,  and
+/// performing player actions.
+/// </summary>
+/// <remarks>This interface provides functionality for querying game details, starting new games, making moves, 
+/// and canceling games. It is designed to support various game types and player interactions.</remarks>
 public interface IGamesClient
 {
+    /// <summary>
+    /// Retrieves information about a game by its unique identifier.
+    /// </summary>
+    /// <remarks>Use this method to retrieve detailed information about a specific game. If the game does not
+    /// exist, the method returns <see langword="null"/>. Ensure that the <paramref name="id"/> parameter is valid
+    /// before calling this method.</remarks>
+    /// <param name="id">The unique identifier of the game to retrieve.</param>
+    /// <param name="cancellationToken">A token to monitor for cancellation requests. The default value is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A <see cref="Task{TResult}"/> representing the asynchronous operation. The task result contains a <see
+    /// cref="GameInfo"/> object with details about the game if found; otherwise, <see langword="null"/>.</returns>
     Task<GameInfo?> GetGameAsync(Guid id, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Asynchronously retrieves a collection of games based on the specified query criteria.
+    /// </summary>
+    /// <remarks>Use this method to retrieve game information based on specific filters, such as genre,
+    /// release date, or platform. The query object defines the criteria for filtering the games.</remarks>
+    /// <param name="query">The query parameters used to filter and retrieve the games. Cannot be null.</param>
+    /// <param name="cancellationToken">A token to monitor for cancellation requests. The operation will be canceled if the token is triggered.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains an enumerable collection of  <see
+    /// cref="GameInfo"/> objects that match the query criteria. If no games match, the collection will be empty.</returns>
     Task<IEnumerable<GameInfo>> GetGamesAsync(GamesQuery query, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Processes a player's move in the specified game and returns the results of the move.
+    /// </summary>
+    /// <param name="id">The unique identifier of the game session.</param>
+    /// <param name="playerName">The name of the player making the move.</param>
+    /// <param name="gameType">The type of game being played.</param>
+    /// <param name="moveNumber">The sequential number of the move being made.</param>
+    /// <param name="guessPegs">An array of strings representing the player's guess for the current move.</param>
+    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result is a tuple containing: <list type="bullet">
+    /// <item><description>An array of strings representing the results of the move.</description></item>
+    /// <item><description>A boolean indicating whether the game has ended.</description></item> <item><description>A
+    /// boolean indicating whether the move resulted in a victory.</description></item> </list></returns>
     Task<(string[] Results, bool Ended, bool IsVictory)> SetMoveAsync(Guid id, string playerName, GameType gameType, int moveNumber, string[] guessPegs, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Starts a new game asynchronously and returns the game details.
+    /// </summary>
+    /// <remarks>Use this method to initialize a new game session. The returned game details include the
+    /// configuration and constraints for the game, which can be used to guide gameplay.</remarks>
+    /// <param name="gameType">The type of game to start. This determines the rules and configuration of the game.</param>
+    /// <param name="playerName">The name of the player starting the game. Cannot be null or empty.</param>
+    /// <param name="cancellationToken">A token to monitor for cancellation requests. The default value is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result is a tuple containing: <list type="bullet">
+    /// <item><description><see cref="Guid"/> Id: The unique identifier for the newly created game.</description></item>
+    /// <item><description><see cref="int"/> NumberCodes: The number of codes required to solve the
+    /// game.</description></item> <item><description><see cref="int"/> MaxMoves: The maximum number of moves allowed in
+    /// the game.</description></item> <item><description><see cref="IDictionary{TKey, TValue}"/> FieldValues: A
+    /// dictionary containing field names as keys and their possible values as arrays of strings.</description></item>
+    /// </list></returns>
     Task<(Guid Id, int NumberCodes, int MaxMoves, IDictionary<string, string[]> FieldValues)> StartGameAsync(GameType gameType, string playerName, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Cancels an ongoing game session.
+    /// </summary>
+    /// <remarks>This method cancels the specified game session and may notify other players or systems
+    /// depending on the game type. Ensure the <paramref name="id"/> corresponds to an active game session and that the
+    /// caller has the necessary permissions to cancel the game.</remarks>
+    /// <param name="id">The unique identifier of the game session to cancel.</param>
+    /// <param name="playerName">The name of the player requesting the cancellation. Must not be null or empty.</param>
+    /// <param name="gameType">The type of game being canceled.</param>
+    /// <param name="cancellationToken">A token to monitor for cancellation requests. The default value is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
+    [Obsolete(message: "Use RevealGameAsync instead", error: false)]
     Task CancelGameAsync(Guid id, string playerName, GameType gameType, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Cancels and reveals the details of a game based on the specified parameters.
+    /// </summary>
+    /// <param name="id">The unique identifier of the game to reveal.</param>
+    /// <param name="playerName">The name of the player requesting the game details. Cannot be null or empty.</param>
+    /// <param name="gameType">The type of the game to reveal.</param>
+    /// <param name="cancellationToken">A token to monitor for cancellation requests. Optional.</param>
+    /// <returns>A <see cref="GameInfo"/> object containing the details of the revealed game.</returns>
+    Task<GameInfo> RevealGameAsync(Guid id, string playerName, GameType gameType, CancellationToken cancellationToken = default);
 }

src/clients/Codebreaker.GameAPIs.Client/LogExtensions.cs

@@ -19,6 +19,9 @@ internal static partial class LogExtensions
 
     [LoggerMessage(5005, LogLevel.Error, "CancelGameAsync error {ErrorMessage}", EventName = "CancelGameError")]
     public static partial void CancelGameError(this ILogger logger, string errorMessage, Exception ex);
+    
+    [LoggerMessage(5006, LogLevel.Error, "RevealGameAsync error {ErrorMessage}", EventName = "RevealGameError")]
+    public static partial void RevealGameError(this ILogger logger, string errorMessage, Exception ex);
 
     [LoggerMessage(8001, LogLevel.Information, "Game {GameId} created", EventName = "GameCreated")]
     public static partial void GameCreated(this ILogger logger,Guid gameId);
@@ -34,4 +37,7 @@ internal static partial class LogExtensions
 
     [LoggerMessage(8005, LogLevel.Information, "Game {GameId} canceled", EventName = "GameCanceled")]
     public static partial void GameCanceled(this ILogger logger, Guid gameId);
+    
+    [LoggerMessage(8006, LogLevel.Information, "Game {GameId} revealed with {MoveCount} moves", EventName = "GameRevealed")]
+    public static partial void GameRevealed(this ILogger logger, Guid gameId, int moveCount);
 }

src/clients/Codebreaker.GameAPIs.Client/docs/readme.md

@@ -16,7 +16,7 @@ The `IGamesClient` class is the main contract to be used for communication to pl
 | `SetMoveAsync` | Set guesses for a game move |
 | `GetGameAsync` | Get a game by id with all details and moves |
 | `GetGamesAsync` | Get a list of games with all details and moves (use the `GamesQuery` class to define the filter) |
-
+| `RevealGameAsync` | Ends a game and returns the correct answer |
 
 The `GamesClient` class implements the `IGamesClient` interface. In the constructor, inject the `HttpClient` class. You can use `Microsoft.Extensions.Http` to configure the `HttpClient` class.
 
@@ -50,8 +50,16 @@ Start a game:
 (Guid id, int numberCodes, int maxMoves, IDictionary<string, string[]> fieldValues) = await gamesClient.StartGameAsync("Game6x4", "player1");
 ```
 
+The returned fieldValues contains an array of possible values for code fields, with the key being "colors". With a Game5x5x4 game, the returned fieldValues contains a key "shapes", and a key "colors".
+
 Set a move:
 
 ```csharp
 (string[] result, bool ended, bool isVictory) = await gameClient.SetMoveAsync(id, "Game6x4", [ "Red", "Green", "Blue", "Yellow" ]);
 ```
+
+With a Game5x5x4 game, you can set a move like this:
+
+```csharp
+(string[] result, bool ended, bool isVictory) = await gameClient.SetMoveAsync(id, "Game5x5x4", [ "Circle;Red", "Rectangle;Green", "Triangle;Blue", "Circle;Yellow" ]);
+```