Table of Contents

v1.3.1 "Seigō" - Precision & Reliability

Release Date: July 26, 2025
Code Name: "Seigō" (精確 - Precision/Accuracy)
Type: Patch Release

🎯 Overview

Version 1.3.1 addresses critical SignalR serialization issues and enhances logging capabilities for better debugging and monitoring. This patch release ensures reliable WebSocket communication by fixing serialization problems and providing comprehensive diagnostic information.

🛠️ Technical Details

SignalR Serialization Fixes

This release resolves compatibility issues with SignalR's System.Text.Json serialization by:

  • Non-Serializable Type Removal: Eliminated Dictionary<string, Type> and TimeSpan properties that caused serialization failures
  • Compatible Type Substitution: Replaced problematic types with STJ-compatible alternatives
  • Response Flow Reliability: Ensured all request/response DTOs can be properly serialized and transmitted

Enhanced Logging Infrastructure

Comprehensive logging improvements across all SignalR operations:

  • Detailed Request/Response Logging: Full serialization of request and response objects with structured logging
  • Error Tracking: Exception details captured for all failed operations
  • Handler Registration Monitoring: Warnings when event handlers are not properly configured
  • Performance Diagnostics: Timing and success/failure tracking for all WebSocket events

🔧 Fixes

Critical Serialization Issues

  • CommandMetadata.Parameters: Changed from Dictionary<string, Type> to Dictionary<string, string> to fix CommandsMetadataRequested event serialization failures
  • ConfigurationSection.Values: Changed from Dictionary<string, object> to Dictionary<string, string> for reliable configuration transmission
  • ConfigResponse.Uptime: Changed from TimeSpan to double UptimeSeconds to ensure proper serialization

Enhanced SignalR Extensions

  • Null Handler Detection: Added warnings when event handlers are null, preventing silent failures
  • Exception Handling: Comprehensive try-catch blocks with detailed error logging for all handler types
  • Request/Response Serialization: Full object serialization in logs using structured logging ({@Request}, {@Response})
  • Handler Registration Confirmation: Debug-level logs confirming successful event handler registration

💻 Technical Changes

SignalRStreamExtensions Improvements

// Enhanced error handling and logging
public static void OnRequest<TRequest, TResponse>(
    this HubConnection hubConnection,
    string eventName,
    Func<TRequest, Task<TResponse>> handler,
    ILogger? logger = null,
    Func<TRequest, object>? requestIdSelector = null)
{
    if (handler == null)
    {
        logger?.LogWarning("Event handler for {EventName} is null - requests will not be processed", eventName);
        return;
    }

    hubConnection.On<TRequest, TResponse>(eventName, async request =>
    {
        var requestId = requestIdSelector?.Invoke(request);
        logger?.LogInformation("{EventName} received: {RequestId}, Request: {@Request}", eventName, requestId, request);
        
        try
        {
            var response = await handler(request);
            logger?.LogInformation("{EventName} handled successfully: {RequestId}, Response: {@Response}", eventName, requestId, response);
            return response;
        }
        catch (Exception ex)
        {
            logger?.LogError(ex, "{EventName} handler failed: {RequestId}", eventName, requestId);
            throw;
        }
    });
    
    logger?.LogDebug("Event handler registered for {EventName}", eventName);
}

Data Model Changes

// Before v1.3.1 - Causes serialization failures
public class CommandMetadata
{
    public Dictionary<string, Type> Parameters { get; set; } = new();
}

public class ConfigResponse : TrackedObject
{
    public TimeSpan Uptime { get; set; }
}

// After v1.3.1 - SignalR STJ compatible
public class CommandMetadata
{
    public Dictionary<string, string> Parameters { get; set; } = new();
}

public class ConfigResponse : TrackedObject
{
    public double UptimeSeconds { get; set; }
}

🐛 Bug Fixes

  • CommandsMetadataRequested Event: Fixed serialization failure that prevented client responses from reaching the server
  • Configuration Transmission: Resolved issues with complex configuration object serialization
  • Silent Handler Failures: Added logging to detect when event handlers are not properly configured
  • Response Acknowledgment: Ensured all client responses are properly serialized and transmitted to server

🔍 Debugging Improvements

  • Structured Logging: All request/response objects now use structured logging for better log analysis
  • Handler Lifecycle Tracking: Complete visibility into handler registration and execution
  • Serialization Diagnostics: Clear error messages when serialization issues occur
  • Performance Monitoring: Request processing time and success rate tracking

🚀 Deployment

Non-Breaking Changes

This patch release maintains API compatibility while fixing critical serialization issues:

  • Property Name Changes: TimeSpan Uptime → double UptimeSeconds
  • Type Parameter Changes: Dictionary<string, Type> → Dictionary<string, string>
  • Enhanced Logging: More detailed log output (configure log levels as needed)

Migration Notes

// Configuration response handling
// Before: TimeSpan-based uptime
var uptime = configResponse.Uptime;

// After: Seconds-based uptime  
var uptime = TimeSpan.FromSeconds(configResponse.UptimeSeconds);

// Command metadata handling
// Before: Type objects in parameters
var paramType = commandMetadata.Parameters["param1"]; // Type object

// After: Type names as strings
var paramTypeName = commandMetadata.Parameters["param1"]; // "System.String"
var paramType = Type.GetType(paramTypeName); // Convert back to Type if needed

🔧 Configuration

Enhanced Logging Configuration

To take advantage of the improved logging, configure your logging levels:

{
  "Logging": {
    "LogLevel": {
      "Jiro.Shared.Extensions.SignalRStreamExtensions": "Information",
      "Microsoft.AspNetCore.SignalR": "Information"
    }
  }
}

Note: This patch release resolves critical serialization issues affecting WebSocket communication reliability. The enhanced logging will provide better visibility into SignalR operations and help diagnose any remaining issues. No breaking API changes are introduced.

Edit this page