Reimaginate.ProcessingLockService 3.1.0

Reimaginate.ProcessingLockService

Runtime processing lock service implementation, dependency injection registration, and in-memory or Redis-backed repositories for coordinating exclusive processing work.

Optional contention diagnostics (3.1.0)

Contention diagnostics collect evidence about slow WaitForLockAsync, WaitForLocksAsync, WaitForTenantLockAsync and WaitForTenantLocksAsync calls. They do not change acquisition, ownership, renewal, release, polling, cancellation or timeout semantics. Direct acquisition calls are observed only when they are part of one of these wait operations.

Diagnostics are disabled by default. Existing constructors, interfaces, custom repositories and AddProcessingLockService registrations continue working. Both packages are 3.1.0, following the repository's coordinated release process; the Abstractions API is unchanged. Both assembly versions remain 3.0.0.0 for compiled callers.

QPAC application configuration

Bind configuration in the QPAC application, using its existing repository configuration:

builder.Services.AddProcessingLockService(options =>
{
    // Keep QPAC's existing repository and lock/wait timeout configuration here.
    // For example: options.WithRedisRepository(existingRedisClient);
    builder.Configuration.GetSection("ProcessingLocks:ContentionDiagnostics")
        .Bind(options.ContentionDiagnostics);
});

The existing registration uses the host's ILoggerFactory when available. Direct construction can supply ProcessingLockServiceOptions.LoggerFactory. A factory is optional: without one, locking still works and no diagnostic observer starts. The library does not own or dispose the logger factory.

Example configuration for a shared tenant-aware instance:

{
  "ProcessingLocks": {
    "ContentionDiagnostics": {
      "Enabled": true,
      "TenantIds": ["<QPAC tenant ID as passed to the tenant-aware API>"],
      "SlowWaitThreshold": "00:01:00",
      "ProgressThresholds": ["00:01:00", "00:03:00"],
      "MaxEventsPerWait": 3,
      "MaxSampledLocks": 3,
      "IncludeGuidOwnerIds": false
    }
  },
  "Logging": {
    "LogLevel": { "Default": "Error" },
    "Console": {
      "LogLevel": {
        "Default": "Error",
        "Reimaginate.ProcessingLockService.Contention": "Information"
      }
    }
  }
}

Also supply ProcessingLocks__ContentionDiagnostics__FingerprintKey through QPAC's secret configuration. It must be a base64-encoded random secret of at least 32 bytes. Generate it once using a cryptographic random generator and keep it stable for the investigation; never commit it to application settings or log it. Rotating it changes all fingerprints.

For a service instance used exclusively by QPAC, use "TenantIds": [] to enable collection for that entire instance, including the legacy APIs. An empty list is instance-wide; use an explicit allowlist whenever the instance serves multiple customers. Matching is ordinal and case-sensitive. Legacy APIs use ProcessingLockTenants.LegacyGlobal (__legacy_global__), so an allowlist containing only an explicit tenant does not enable legacy calls. If several customers share legacy calls on one instance, those calls cannot be distinguished by tenant: use separate instances or the existing tenant-aware API.

Options are snapshotted at service construction; changing configuration requires recreating the service (normally an application restart). Enabled: false is the collection kill switch. It causes no diagnostic logging, repository reads, worker startup or timer work. A logging override controls visibility independently and does not enable collection. When logging is filtered out, there are still no diagnostic Redis reads; an enabled observer may still run.

Limits and delivery

Invalid enabled configuration fails at construction without exposing the secret value. Disabled configuration is not validated and does not require logging or a fingerprint key. Thresholds use monotonic elapsed time; they are approximate and subject to scheduling delays. Missed thresholds are coalesced instead of producing a burst. Fast waits emit no events. For the defaults, a slow wait can enqueue progress at 60 and 180 seconds and one final event.

Each enabled wait has one one-shot timer, only while further progress events are possible. Cancellation and completion stop it, including cancellation while a repository ignores its token. This does not force the repository operation itself to stop or shorten its timeout.

Log delivery runs outside request processing and the acquisition semaphore. Each enabled service has at most one logging worker and a queue bounded to 128 events. A full queue drops new events instead of delaying locking. Throwing providers are isolated; a blocked provider can stall this worker but cannot block acquisition, release or disposal. Delivery is best effort: queue pressure, process exit or provider failure can lose progress or final events. Dispose closes the queue for a best effort drain without waiting for a provider. The library does not automatically enable console logging or change any host-wide logging settings.

Logging category and event schema

Category: Reimaginate.ProcessingLockService.Contention. Both events use Information:

The structured fields are:

Each blocker sample contains KeyHash, HoldingOwnerId, StoredTimestampUtc, AgeMilliseconds and EstimatedExpiryUtc. Times are UTC; age is milliseconds at ObservedAtUtc. Missing/default timestamps or unavailable expiry are null. The stored timestamp resets on renewal in both built-in repositories: it is not necessarily the original acquisition time. Expiry is estimated as stored timestamp plus duration, not an independently read Redis TTL; clock differences can affect these estimates.

The final event retains the last observed blockers, even if acquisition subsequently succeeds. Use ObservedAtUtc to judge freshness. Null blocker counts mean unknown, not zero. The built-in repositories provide full conflict counts and sampled holder metadata in their existing acquisition results. Custom providers may supply less metadata. No inventory scans, extra repository reads, acquisition attempts or renewals are performed for diagnostics.

The outcome is observational and does not replace public result semantics. In particular, contention expiry can still return InUse, and cancellation still returns TimeOut. An acquisition that succeeds after cancellation or after the wait deadline retains success and logs acquired, matching existing behaviour. The wait timeout is not a hard deadline on semaphore or repository calls; this feature does not introduce one.

Safe correlation

Keep existing lock owner/lockedBy values and ownership semantics. By default, all owners are emitted as hmac: plus an owner fingerprint; absent owners remain null. If QPAC confirms its GUID owner values are safe request/job correlation IDs, it may explicitly set IncludeGuidOwnerIds: true. Only then are owners formatted as GUIDs (32 hexadecimal digits or standard 36-character hyphenated form) logged verbatim for direct joins with job/API logs. A GUID alone does not prove an owner is safe: it could identify a customer. Other owner strings always remain fingerprinted. An owner is caller-supplied and need not identify a unique request. If ownership does not already identify requests, the library cannot reconstruct the holding request's correlation ID; WaitId still groups wait events.

Fingerprints are uppercase hexadecimal HMAC-SHA256 using the configured secret over the UTF-8 System.Text.Json serialization of [kind, tenantId, value]. Kinds are key, owner or tenant; tenant fingerprints use an empty string for value. QPAC can compute the same owner fingerprint when correlating existing non-GUID owner IDs. Tenant scoping prevents identical keys or owner values from being joined across customers. Explicitly opted-in GUID correlation IDs remain verbatim by design.

No raw lock keys, tenant IDs, lock tokens, credentials, payloads, failure-detail strings or exception objects/messages are emitted. Configure host enrichers separately if they add request scopes or other sensitive fields to logs.

These events provide investigation evidence. Lock durations, retry policy and lock clearing must be considered separately once that evidence is available.