29 lines
2.4 KiB
Markdown
29 lines
2.4 KiB
Markdown
# Runtime Transport Client Rules
|
|
|
|
This document defines the minimum lifecycle and attribution rules for long-lived runtime transport clients in Stella Ops services.
|
|
|
|
## 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 covers the scoped host-owned HTTP hotspot waves across Integrations, ReleaseOrchestrator connector helpers plus the broadened SCM/settings-store/registry connector set, and OCI fallback publishers.
|
|
|
|
## Static Enforcement
|
|
- `src/__Libraries/__Tests/StellaOps.Infrastructure.Postgres.Tests/RuntimePostgresConstructionConventionTests.cs` enforces the shared PostgreSQL and Valkey runtime construction rules plus the scoped HTTP hotspot regression checks.
|
|
|
|
## Operational Goal
|
|
- Every long-lived runtime transport should be attributable in production diagnostics without relying on IP-only correlation.
|