common

Common

Purpose

pkg/handler/common defines shared handler dependencies and Identity allocation delegation for the region handler layer.

ClientArgs is a pragmatic package-level contract for the ambient capabilities that most handlers need.

Those capabilities are:

• cached Kubernetes access
• process namespace
• provider lookup
• outbound identity API access
• Identity allocation create, update, and delete delegation

This package keeps handler construction uniform. It does not hide runtime dependencies in context.Context or require a separate handler runtime object.

Main Component

ClientArgs

ClientArgs is the shared constructor shape used by most region handlers and their helper clients.

It also delegates Identity allocation create, update, and delete calls. Concrete handlers keep their allocation requirements, compensation, and error handling.

It carries:

• client.Client for cached Kubernetes access
• Namespace for process-local namespace scoping
• providers.Providers for provider lookup
• identityapi.ClientWithResponsesInterface for identity-side RBAC and tenancy interactions

The struct is intentionally made of interfaces and scalars so handlers remain easy to unit test and do not need to construct their own ambient clients ad hoc.

Invariants And Guard Rails

• This package owns shared wiring and Identity allocation delegation. It does not own resource-specific allocation requirements or lifecycle behavior.
• ClientArgs is a shared handler-layer constructor contract with wide fan-out across concrete handler packages and top-level server wiring.
• The dependency bundle is intentionally coarse-grained for practicality, but it should still stay limited to ambient capabilities that are genuinely shared across the handler layer.
• Provider access is injected as the lookup façade in pkg/providers, not as concrete provider implementations.
• Identity access is treated as a normal ambient dependency of region handlers, not something each handler should construct independently.

Caveats

• The package name common is broader than the actual responsibility. This is really a handler wiring/dependency contract package.
• ClientArgs is a pragmatic compromise, not an ideal architectural endpoint. It exists because:
  • hiding these dependencies in context.Context would be worse
  • pushing a dedicated runtime object through every constructor would have been more disruptive than the codebase needed at the time
• Not every consumer uses every field. The bundle is broader than any one handler because it is optimized for uniform construction rather than perfect per-handler minimalism.
• Because the struct has wide fan-out, casual field churn here would fragment constructor conventions across the handler layer quickly.

Cross-Package Context

• ../README.md aggregates the concrete handlers built on this dependency bundle
• ../../providers provides the provider lookup façade injected through ClientArgs
• identity/pkg/handler/common provides identity-specific handler helpers that many concrete region handlers also depend on alongside this package