Runtime Transport Client Rules

Audience: Stella Ops backend developers writing or reviewing service code that opens PostgreSQL, Valkey/Redis, or HTTP connections.

This document defines the minimum lifecycle and attribution rules for long-lived runtime transport clients in Stella Ops services. The intent is simple: every long-lived connection should be pooled, reused, and attributable in production diagnostics — never an anonymous, per-request client that shows up only as an IP address.

These rules are enforced by the convention test suite (see Static enforcement); the lists of exceptions below are the only sanctioned deviations.

PostgreSQL

• Steady-state runtime code must use named reusable NpgsqlDataSource instances.
• Runtime connection strings must carry stable ApplicationName values.
• Raw new NpgsqlConnection(...) is reserved for explicit CLI/setup, migration, or diagnostic exceptions.
• Any temporary runtime exception that still uses raw NpgsqlConnection must normalize ApplicationName and pooling policy before opening the connection.

Valkey / Redis

• Steady-state runtime ConnectionMultiplexer construction must stamp a stable ClientName.
• Runtime code should build ConfigurationOptions, apply client identity, and then connect.
• Shared factories may provide a module-level default ClientName when the caller does not supply one.
• CLI/setup tooling, smoke tools, and test fixtures are allowed exceptions when they are explicitly allowlisted in convention tests.

HTTP

• Runtime code should use IHttpClientFactory, typed clients, or module-specific wrappers instead of ad hoc new HttpClient().
• When DI-backed wiring is not available yet, compatibility fallbacks must still avoid per-request or per-call new HttpClient() churn.
• Compatibility wrappers may still return per-call HttpClient instances when callers need isolated headers or base addresses, but those wrappers should share the underlying handler/pool rather than constructing default-handler clients repeatedly.
• Plugin loaders that activate runtime components should use service-provider-backed construction when available so named clients and other shared transports can flow into plugins.
• Existing analyzer-based guardrails remain in place for specialized modules, and the shared convention suite now enforces a repo-wide runtime HttpClient allowlist.
• The current explicit runtime HTTP exceptions are: AirGap fallback wrapper, CLI fallback wrapper, ReleaseOrchestrator connector compatibility wrapper, Doctor’s per-probe TLS capture client, and Zastava’s Docker local-socket transport client.

Static enforcement

• src/__Libraries/__Tests/StellaOps.Infrastructure.Postgres.Tests/RuntimePostgresConstructionConventionTests.cs enforces the shared PostgreSQL and Valkey runtime construction rules plus the repo-wide runtime HTTP allowlist.

Operational goal

• Every long-lived runtime transport should be attributable in production diagnostics without relying on IP-only correlation.