Skip to content

SAIF.NetCore.DBConnectionClient operations and processes

This page is the operation catalog and cross-operation hub for this library. Each operation's detailed, step-by-step logic lives in its own page under operations/.

Operation catalog

Operation Intent Trigger Inputs Outputs Rules
Construct and configure the client Build a working ConnectionClient instance bound to the DBConnectionAPI. DI factory in ServiceExtensions.RegisterDBConnectionClient, or direct new. IHttpJsonClient, IEnvironmentClient Configured instance BR-DBC-01, BR-DBC-02, BR-DBC-03
Apply service-account credentials Replace the ambient NTLM identity with an explicit service-account credential. Called by ServiceExtensions.RegisterDBConnectionClient after decrypting connectionservicecreds. username, password NTLM credentials applied BR-DBC-03
Get a SQL Server connection string Return a ready-to-use SQL Server connection string. Caller invokes GetSqlServerConnection. server, instance, userName Connection string BR-DBC-04
Get a PostgreSQL connection string Return a ready-to-use PostgreSQL connection string. Caller invokes GetPostgreSqlServerConnection. server, instance, userName Connection string BR-DBC-04, BR-DBC-05
Get an Oracle connection string Return a ready-to-use Oracle connection string. Caller invokes GetOracleConnection. instance, userName Connection string BR-DBC-04
Cached lookup Serve a connection string from the in-memory cache, or populate it. Called internally by every Get*Connection method. connectionName, urlPath Connection string BR-DBC-06
Retrieve with retry Fetch a connection string from the DBConnectionAPI with bounded retry on transient failure. Called internally on a cache miss. connectionName, urlPath Connection string, or DBClientException BR-DBC-07, BR-DBC-08, BR-DBC-09, BR-DBC-10, BR-DBC-11
Legacy special-character decoding Decode legacy placeholder tokens in a returned connection string. Called internally on a successful HTTP response. Raw connection string Decoded connection string BR-DBC-12

Process flow diagram

The following diagram visualizes the primary operational flow across operations.

flowchart TD
    Start(["Caller invokes Get*Connection"]) --> Key[Build engine-prefixed cache key]
    Key --> Cache{Key cached?}
    Cache -->|Yes| Return([Return cached connection string])
    Cache -->|No| Retrieve["Retrieve with retry: GetAsync against DBConnectionAPI"]
    Retrieve --> Outcome{HTTP outcome}
    Outcome -->|Success, non-empty body| Decode[Decode ZSPECIALCHAR tokens]
    Decode --> AddCache[Add to cache]
    AddCache --> Return
    Outcome -->|401/403/404| FailFast(["Throw DBClientException, no retry"])
    Outcome -->|503 or network error| Backoff{Attempts remaining?}
    Backoff -->|Yes| Delay[Delay 2s/3s/5s and retry]
    Delay --> Retrieve
    Backoff -->|No| FailFast
    Outcome -->|Other non-success or empty body| FailFast

Failure and edge-case behavior

  • A denied request (401/403) is never cached, so a later call for the same key hits the API again.
  • A missing retry-configuration invariant (RetrieveBackoffDelays.Length < MaxRetrieveAttempts - 1) throws InvalidOperationException before any HTTP call is made.
  • An empty successful body is treated as a failure ("Database connection string is null"), not as a valid empty connection string.

Note: Statements marked with * were inferred from code structure, naming conventions, or contextual evidence where direct confirmation was not available in source artifacts.

Sources

  • src/SAIF.NetCore.DbConnectionClient/SAIF.NetCore.DBConnectionClient/SAIF.NetCore.DBConnectionClient/ConnectionClient.cs
  • src/SAIF.NetCore.DbConnectionClient/SAIF.NetCore.DBConnectionClient/SAIF.NetCore.DBConnectionClient/ClientException.cs