Merge branch 'development'

Author: HaikAsatryan

.gitignore

@@ -486,4 +486,5 @@ $RECYCLE.BIN/
 # Added by me
 logs
 LocalFileStorage
-*.db*
+*.db*
+**.claude

CLAUDE.md

@@ -0,0 +1,125 @@
+# Pandatech.SharedKernel
+
+Opinionated ASP.NET Core 10 infrastructure kernel. Not a general-purpose NuGet — meant to be forked and customized per project.
+
+## Build & Test
+
+```bash
+dotnet build src/SharedKernel/SharedKernel.csproj
+dotnet test test/SharedKernel.Tests/SharedKernel.Tests.csproj
+```
+
+- .NET 10 SDK required (see `global.json` for exact version)
+- C# 14 features used: extension members, collection expressions, primary constructors
+- CI publishes to NuGet on push to `main` via GitHub Actions
+
+## Project Structure
+
+```
+src/SharedKernel/          # Library source
+  Constants/               # EndpointConstants (/above-board base path)
+  Extensions/              # DI registration & middleware extension methods
+  Helpers/                 # AssemblyRegistry, ValidationHelper, PhoneUtil, etc.
+  JsonConverters/          # Enum-as-string, DateOnly format converters
+  Logging/                 # Serilog setup + HTTP request/response logging middleware
+    Middleware/             # RequestLoggingMiddleware, OutboundLoggingHandler, RedactionHelper
+  Maintenance/             # Distributed maintenance mode (HybridCache + poller)
+  OpenApi/                 # Multi-document Swagger/Scalar UI + config
+  Resilience/              # Polly retry, circuit breaker, timeout pipelines
+  ValidatorAndMediatR/     # CQRS interfaces (ICommand/IQuery) + FluentValidation pipeline
+    Behaviors/             # MediatR validation pipeline behaviors
+    Validators/            # String, file, XSS validators + file presets
+test/SharedKernel.Tests/   # xUnit tests (PhoneUtil, ValidationHelper, TimeZone)
+SharedKernel.Demo/         # Working reference implementation showing full setup
+```
+
+## Key Conventions
+
+### Startup Registration Order
+
+Builder phase (`WebApplicationBuilder`):
+1. `LogStartAttempt()` + `AssemblyRegistry.Add()`
+2. `.ConfigureWithPandaVault()` (secrets, non-Local only)
+3. `.AddSerilog(LogBackend.*)` (logging)
+4. `.AddResponseCrafter()` (exception standardization)
+5. `.AddOpenApi()`, `.AddMaintenanceMode()`, `.AddOpenTelemetry()`
+6. `.AddMinimalApis()`, `.AddControllers()`, `.AddMediatrWithBehaviors()` (all take assemblies)
+7. `.AddResilienceDefaultPipeline()`, `.AddSignalR()` or `.AddDistributedSignalR()`
+8. `.AddCors()`, `.AddOutboundLoggingHandler()`, `.AddHealthChecks()`
+
+App phase (`WebApplication`) — middleware order matters:
+1. `.UseRequestLogging()` (must be first to capture full request lifecycle)
+2. `.UseMaintenanceMode()` (before ResponseCrafter)
+3. `.UseResponseCrafter()`
+4. `.UseCors()`
+5. `.MapMinimalApis()`, `.MapHealthCheckEndpoints()`, `.MapPrometheusExporterEndpoints()`
+6. `.EnsureHealthy()` (blocks startup if unhealthy)
+7. `.ClearAssemblyRegistry()` (frees memory)
+8. `.UseOpenApi()`, `.MapControllers()`
+
+### CQRS Pattern
+
+Use `ICommand<T>` / `ICommand` for writes, `IQuery<T>` / `IQuery` for reads. Handlers: `ICommandHandler<,>`, `IQueryHandler<,>`. FluentValidation validators are auto-discovered and run as MediatR pipeline behaviors.
+
+### Reserved Paths
+
+All infrastructure endpoints live under `/above-board/`:
+- `GET /above-board/ping` — returns "pong"
+- `GET /above-board/health` — full health check JSON
+- `GET /above-board/prometheus` — metrics scrape
+- `PUT /above-board/maintenance` — set maintenance mode
+
+These paths are excluded from request logging and pass through maintenance mode.
+
+### Environment Conventions
+
+- `IsLocal()` — developer machine, console-only logging, PandaVault skipped
+- `IsDevelopment()` — console + file logging
+- `IsQa()`, `IsStaging()` — file logging, PandaVault enabled
+- `IsProduction()` — file logging only, restricted CORS origins
+
+### Configuration (appsettings.json)
+
+Required keys:
+- `RepositoryName` — used for log file paths
+- `ConnectionStrings:PersistentStorage` — base path for log files
+- `Security:AllowedCorsOrigins` — comma/semicolon-separated origins (production only)
+- `DefaultTimeZone` — e.g. "Caucasus Standard Time"
+- `OpenApi` section — documents, security schemes, contact info
+
+Optional:
+- `OTEL_EXPORTER_OTLP_ENDPOINT` env var — enables OTLP export
+
+### Logging
+
+- Request/response bodies captured up to 16KB, with automatic sensitive-key redaction
+- Redaction is key-based: headers and JSON property names containing `auth`, `token`, `pass`, `secret`, `cookie`, `pan`, `cvv`, `ssn`, etc. are redacted
+- Log backends: `ElasticSearch` (ECS format), `Loki` (Grafana JSON), `CompactJson`
+- Paths ignored: `/swagger`, `/openapi`, `/above-board/*`, `/favicon.ico`
+- OutboundLoggingHandler logs HttpClient calls with same redaction rules
+
+### Resilience
+
+Two pipeline variants sharing the same configuration constants:
+- **General** (`ResiliencePipelineProvider<string>`) — for non-HttpClient use
+- **HTTP** (`IHttpClientBuilder.AddResilienceDefaultPipeline()`) — respects Retry-After headers
+
+Policies: 429 retry (5 attempts), 5xx/408 retry (7 attempts), circuit breaker (50% failure / 30s window / 200 min requests), 8s timeout per attempt.
+
+### Maintenance Mode
+
+Three modes: `Disabled`, `EnabledForClients` (blocks non-admin routes), `EnabledForAll` (blocks everything except `/above-board/*`). State synchronized across instances via HybridCache + background poller (7s interval). Admin routes are identified by `/api/admin` and `/hub/admin` path prefixes.
+
+## Dependency Notes
+
+- **MediatR** pinned to `[12.5.0]` — last free version (13+ is commercial)
+- **Pandatech.\*** packages are internal PandaTech libraries (ResponseCrafter, DistributedCache, Crypto, PandaVaultClient, etc.)
+- Analyzers (Pandatech.Analyzers, SonarAnalyzer) are build-only, not shipped to consumers
+
+## Code Style
+
+- 3-space indentation
+- File-scoped namespaces
+- C# 14 extension members for clean builder APIs
+- `partial class` + `[LoggerMessage]` for high-performance structured logging
+- `FrozenSet<T>` for static lookup data

README.md

@@ -72,13 +72,15 @@ app
    .UseResponseCrafter()
    .UseCors()
    .MapMinimalApis()
-   .EnsureHealthy()
    .MapHealthCheckEndpoints()
    .MapPrometheusExporterEndpoints()
+   .EnsureHealthy()
    .ClearAssemblyRegistry()
    .UseOpenApi()
    .MapControllers();
 
+app.MapMaintenanceEndpoint();
+
 app.LogStartSuccess();
 app.Run();
 ```
@@ -87,8 +89,8 @@ app.Run();
 
 ## Assembly Registry
 
-`AssemblyRegistry` is a thread-safe static list used to pass your project's assemblies from the builder phase to the
-app phase without repeating `typeof(Program).Assembly` everywhere.
+`AssemblyRegistry` is a thread-safe static collection used to pass your project's assemblies from the builder phase to
+the app phase without repeating `typeof(Program).Assembly` everywhere.
 
 ```csharp
 // Add once at startup
@@ -105,8 +107,8 @@ app.ClearAssemblyRegistry();
 
 ## OpenAPI
 
-Wraps `Microsoft.AspNetCore.OpenApi` with SwaggerUI and Scalar, supporting multiple API documents, custom security
-schemes, and enum string descriptions.
+Wraps `Microsoft.AspNetCore.OpenApi` with SwaggerUI and Scalar, generating **OpenAPI 3.1** specs. Supports multiple API
+documents, custom security schemes, and enum string descriptions (including nullable enums).
 
 ### Registration
 
@@ -208,7 +210,7 @@ builder.AddSerilog(
 ### Log Backends
 
 | Value           | Output format                                     |
-|-----------------|---------------------------------------------------|
+|-----------------|----------------------------------------------------|
 | `None`          | Console only, no file output                      |
 | `ElasticSearch` | ECS JSON to file (forward with Filebeat/Logstash) |
 | `Loki`          | Loki JSON to file (forward with Promtail)         |
@@ -251,10 +253,13 @@ every 12 hours and deletes files older than `daysToRetain`.
 app.UseRequestLogging();  // logs method, path, status code, elapsed ms, redacted headers/body
 ```
 
-Paths under `/swagger`, `/openapi`, `/above-board`, and `/favicon.ico` are silently skipped. Sensitive header names
-(auth, token, cookie, pan, cvv, etc.) and matching JSON properties are redacted automatically. Bodies over 16 KB are
+Paths under `/swagger`, `/openapi`, `/above-board`, and `/favicon.ico` are silently skipped. Bodies over 16 KB are
 omitted.
 
+**Redaction is key-based:** header names and JSON property names containing sensitive keywords (`auth`, `token`,
+`pass`, `secret`, `cookie`, `pan`, `cvv`, `ssn`, `tin`, `iban`, etc.) are automatically replaced with `[REDACTED]`.
+Values are never inspected — only the property/header name determines whether redaction applies.
+
 ### Outbound logging
 
 Captures outbound `HttpClient` requests with the same redaction rules:
@@ -283,6 +288,8 @@ app.LogStartSuccess();        // prints success banner with elapsed init time
 Registers MediatR with a validation pipeline behavior that runs all FluentValidation validators before the handler.
 Validation failures throw `BadRequestException` from `Pandatech.ResponseCrafter`.
 
+> **Note:** MediatR is pinned to version 12.5.0 — the last MIT-licensed release.
+
 ### Registration
 
 ```csharp
@@ -311,6 +318,7 @@ RuleFor(x => x.Phone).IsPhoneNumber();           // Panda format: (374)91123456
 RuleFor(x => x.Contact).IsEmailOrPhoneNumber();
 RuleFor(x => x.Payload).IsValidJson();
 RuleFor(x => x.Content).IsXssSanitized();
+RuleFor(x => x.Card).IsCreditCardNumber();
 ```
 
 **Single file (`IFormFile`)**
@@ -371,8 +379,11 @@ The list accepts comma- or semicolon-separated URLs. Invalid entries are logged
 
 ## Resilience Pipelines
 
-Built on Polly via `Microsoft.Extensions.Http.Resilience`. Provides retry, circuit breaker, and timeout policies for
-`HttpClient` calls.
+Built on Polly via `Microsoft.Extensions.Http.Resilience`. Two pipeline variants share the same configuration constants
+from a single source of truth:
+
+- **General pipeline** — registered globally via `AddResilienceDefaultPipeline()` on the builder, or used manually via `ResiliencePipelineProvider<string>`
+- **HTTP pipeline** — attached per-client via `AddResilienceDefaultPipeline()` on an `IHttpClientBuilder`, with additional `Retry-After` header support for 429 responses
 
 ### Options
 
@@ -404,12 +415,15 @@ public class MyService(ResiliencePipelineProvider<string> provider)
 
 ### Default pipeline policies
 
-| Policy          | Configuration                                          |
-|-----------------|--------------------------------------------------------|
-| Retry (429)     | 5 retries, exponential backoff, respects `Retry-After` |
-| Retry (5xx/408) | 7 retries, exponential backoff from 800ms              |
-| Circuit breaker | Opens at 50% failure rate over 30 s, min 200 requests  |
-| Timeout         | 8 seconds per attempt                                  |
+| Policy          | Configuration                                                               |
+|-----------------|-----------------------------------------------------------------------------|
+| Retry (429)     | 5 retries, exponential backoff with jitter, respects `Retry-After` header   |
+| Retry (5xx/408) | 7 retries, exponential backoff from 800 ms with jitter                      |
+| Circuit breaker | Opens at 50% failure rate over 30 s (min 200 requests), 45 s break duration |
+| Timeout         | 8 seconds per attempt                                                       |
+
+The circuit breaker only trips on transient failures (`HttpRequestException`, `TaskCanceledException`) and non-success
+HTTP status codes. Programming errors like `ArgumentException` will not open the circuit.
 
 ---
 
@@ -481,8 +495,8 @@ Set the following in your environment config or as an environment variable to en
 ```csharp
 builder.AddHealthChecks();
 
-app.EnsureHealthy();           // runs health checks at startup; throws if anything is unhealthy
 app.MapHealthCheckEndpoints(); // registers /above-board/ping and /above-board/health
+app.EnsureHealthy();           // runs health checks at startup; throws if anything is unhealthy
 ```
 
 `EnsureHealthy` skips MassTransit bus checks during startup (those take time to connect). The ping endpoint returns
@@ -507,9 +521,12 @@ Three-mode global switch. Requires `Pandatech.DistributedCache` to synchronize s
 
 ```csharp
 builder.AddMaintenanceMode();
-app.UseMaintenanceMode();       // place before UseResponseCrafter and UseCors
+app.UseMaintenanceMode();       // place after UseRequestLogging and before UseResponseCrafter
 ```
 
+All calls are idempotent and safe to call multiple times. Registration state is tracked via DI, so
+multiple `WebApplicationFactory` test hosts in the same process work correctly.
+
 ### Controlling maintenance mode
 
 Map the built-in endpoint and protect it with your own authorization:
@@ -542,7 +559,7 @@ public class AdminService(MaintenanceState state)
 
 ### ValidationHelper
 
-Static regex-based validators with a 50ms timeout per expression.
+Static regex-based validators with a 50 ms timeout per expression.
 
 ```csharp
 ValidationHelper.IsEmail("user@example.com");
@@ -685,4 +702,4 @@ is used unchanged.
 
 ## License
 
-MIT
+MIT

SharedKernel.Demo/LoggingTestEndpoints.cs

@@ -175,37 +175,6 @@ public void AddRoutes(IEndpointRouteBuilder app)
          })
          .WithSummary("Outbound FormUrlEncodedContent");
 
-      grp.MapGet("/outbound/form-as-string", async (IHttpClientFactory factory) =>
-         {
-            var client = factory.CreateClient("RandomApiClient");
-      
-            // Use FormUrlEncodedContent instead of StringContent for proper form encoding
-            var formContent = new FormUrlEncodedContent(new Dictionary<string, string>
-            {
-               ["grant_type"] = "password",
-               ["username"] = "testuser",
-               ["password"] = "secret123",
-               ["scope"] = "openid"
-            });
-
-            var response = await client.PostAsync("tests/form-urlencoded", formContent);
-      
-            // Handle non-success responses gracefully
-            if (!response.IsSuccessStatusCode)
-            {
-               var errorBody = await response.Content.ReadAsStringAsync();
-               return Results.Json(new { 
-                  success = false, 
-                  statusCode = (int)response.StatusCode,
-                  error = errorBody 
-               });
-            }
-      
-            return Results.Ok(await response.Content.ReadFromJsonAsync<FormUrlDto>());
-         })
-         .WithSummary("Outbound form-urlencoded - now using FormUrlEncodedContent for proper binding");
-
-
       grp.MapGet("/outbound/multipart", async (IHttpClientFactory factory) =>
          {
             var client = factory.CreateClient("RandomApiClient");