stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
fc798a15730f6a0f7c387625984df4d029a198bc
git.stella-ops.org/docs/technical/runtime-transport-client-rules.md
master fc798a1573 Harden remaining runtime transport lifecycles
2026-04-06 00:24:16 +03:00

2.4 KiB
Raw Blame History

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.