Documentation
¶
Overview ¶
Package hostname resolves a user-supplied hostname selector (e.g. "cluster-01") into a concrete endpoint URL for an auth handler at login time.
Resolution precedence, highest to lowest:
- The selector is already a concrete http(s):// URL -> returned unchanged.
- No hostname config exists for the handler -> selector returned unchanged (preserves plain-hostname handlers such as GitHub Enterprise).
- A static alias (auth.handlers.<name>.hostname.aliases) matches -> its URL.
- A dynamic resolver (auth.handlers.<name>.hostname.resolver) fetches an inventory, normalizes it with an org-owned CEL transform into a list of {name, url} entries, and the selector is looked up by name.
Resolve returns just the endpoint URL. ResolveEntry returns the full Entry, including optional per-cluster OIDC metadata (audience, authType, caData, defaultHandler, consoleUrl, insecureSkipTls) that a config-driven inventory can surface for kube login.
scafctl core stays shape-blind: all inventory normalization lives in the org-owned CEL transform. The host only validates that the transform yields the canonical list<{name, url}> contract.
Index ¶
- Variables
- func AliasForURL(aliases map[string]string, rawURL string) (string, bool)
- func DisplayHostFromURL(rawURL string) string
- func Resolve(ctx context.Context, handler, selector string) (string, error)
- func ResolveWith(ctx context.Context, cfg *config.HostnameConfig, handler, selector string, ...) (string, error)
- type Deps
- type Entry
- func AllCachedInventoryEntries() []Entry
- func CachedInventory(ctx context.Context, rc *config.HostnameResolverConfig, handler string, ...) ([]Entry, bool)
- func ResolveEntry(ctx context.Context, handler, selector string) (*Entry, error)
- func ResolveEntryWith(ctx context.Context, cfg *config.HostnameConfig, handler, selector string, ...) (*Entry, error)
- func ResolveInventory(ctx context.Context, rc *config.HostnameResolverConfig, handler string, ...) ([]Entry, error)
- type FetchFunc
- type InventoryCache
- type TokenFunc
- type TransformFunc
Constants ¶
This section is empty.
Variables ¶
var ( // ErrSelectorNotFound indicates the hostname selector was not found in the // static aliases or the resolved inventory. ErrSelectorNotFound = errors.New("hostname: selector not found") // ErrResolverLoop indicates the resolver's source auth provider is the same // handler being resolved, which would recurse. ErrResolverLoop = errors.New("hostname: resolver loop detected") // ErrTransformShape indicates the CEL transform did not produce a list of // {name, url} entries. ErrTransformShape = errors.New("hostname: transform did not produce a list of {name, url} entries") // ErrNoCredentials indicates the resolver's auth provider is set but no // cached credentials are available. The host never triggers an interactive // login to satisfy a resolver. ErrNoCredentials = errors.New("hostname: no cached credentials for resolver auth provider") )
Sentinel errors returned by the resolver. Callers map these to exit codes: selector/loop/shape errors are invalid-input; credential/fetch errors are general failures.
Functions ¶
func AliasForURL ¶ added in v0.32.0
AliasForURL reverse-maps a concrete endpoint URL back to its configured alias selector. Aliases is the static selector->URL map from auth.handlers.<name>.hostname.aliases. Matching is by normalized host (scheme, port, and path are ignored). When several selectors map to the same host it returns the lexicographically-first one for deterministic output. It returns ("", false) when no alias matches.
func DisplayHostFromURL ¶ added in v0.32.0
DisplayHostFromURL trims a URL down to a compact host label for display, stripping the scheme, port, and any path. A bare hostname is returned lower-cased; an unparseable value is returned trimmed but otherwise unchanged.
func Resolve ¶
Resolve turns a hostname selector into a concrete endpoint URL for the given handler, pulling config and collaborators from the context. It returns the selector unchanged when it is already a URL or when the handler has no hostname config.
func ResolveWith ¶
func ResolveWith(ctx context.Context, cfg *config.HostnameConfig, handler, selector string, deps Deps) (string, error)
ResolveWith is the dependency-injected core of Resolve. It is exported for tests and embedders that supply their own collaborators.
Types ¶
type Deps ¶
type Deps struct {
Fetch FetchFunc
Token TokenFunc
Transform TransformFunc
Cache InventoryCache
}
Deps carries injectable collaborators. Zero-valued fields fall back to the production defaults (httpc fetch, tokenprovider token, celexp transform).
func DefaultDeps ¶ added in v0.31.0
func DefaultDeps() Deps
DefaultDeps returns the production collaborators used by Resolve/ResolveEntry: httpc fetch, tokenprovider token, celexp transform, and an on-disk inventory cache. Callers that resolve an inventory outside the auth-handler config path (for example kube cluster resolution) can reuse the same engine via ResolveEntryWith with these deps.
type Entry ¶
type Entry struct {
// Name is the selector used to look up this entry (required).
Name string `json:"name"`
// URL is the concrete endpoint the selector resolves to (required).
URL string `json:"url"`
// Audience is the OIDC audience/client ID a token for this cluster targets.
Audience string `json:"audience,omitempty"`
// AuthType is the login method for this cluster: "" (auto), "oauth", or
// "oidc". It mirrors kube.AuthType.
AuthType string `json:"authType,omitempty"`
// DefaultHandler is the auth handler used to authenticate to this cluster
// when the caller does not pass an explicit --handler. It lets a fleet
// inventory drive `kube login <cluster>` without naming a handler.
DefaultHandler string `json:"defaultHandler,omitempty"`
// CAData is a PEM-encoded CA bundle for the endpoint (preferred over
// InsecureSkipTLS).
CAData string `json:"caData,omitempty"`
// ConsoleURL is an optional web console URL for the cluster.
ConsoleURL string `json:"consoleUrl,omitempty"`
// InsecureSkipTLS disables endpoint TLS verification (dev only).
InsecureSkipTLS bool `json:"insecureSkipTls,omitempty"`
}
Entry is one normalized inventory record. The CEL transform must yield a list of these. Only name and url are required; the remaining fields carry optional per-cluster OIDC metadata that mirrors kube.ClusterInfo so a config-driven inventory can feed both auth login and kube login.
func AllCachedInventoryEntries ¶ added in v0.32.0
func AllCachedInventoryEntries() []Entry
AllCachedInventoryEntries returns the union of inventory entries from every resolver cache on disk, ignoring TTL expiry and without evicting anything. It is a display-only, network-free helper for reverse-mapping a cluster URL back to its short selector when the caller does not know which resolver produced the cache -- for example `auth status` labeling a cluster that was resolved via `kube login` under a different cache key. Returns nil when nothing is cached.
func CachedInventory ¶ added in v0.31.0
func CachedInventory(ctx context.Context, rc *config.HostnameResolverConfig, handler string, deps Deps) ([]Entry, bool)
CachedInventory returns the inventory entries already cached for the resolver config, without triggering a network fetch. ok is false when nothing is cached (or caching is disabled). It lets latency-sensitive callers such as shell completion enumerate previously-resolved entries without blocking on I/O. The handler must match the one used at resolution time so the cache key aligns.
func ResolveEntry ¶
ResolveEntry resolves a hostname selector into a full inventory Entry (the endpoint URL plus any optional per-cluster OIDC metadata) for the given handler, pulling config and collaborators from the context. For concrete URLs and handlers without hostname config it returns an Entry whose Name and URL are the selector itself.
func ResolveEntryWith ¶
func ResolveEntryWith(ctx context.Context, cfg *config.HostnameConfig, handler, selector string, deps Deps) (*Entry, error)
ResolveEntryWith is the dependency-injected core of ResolveEntry. It is exported for tests and embedders that supply their own collaborators.
func ResolveInventory ¶ added in v0.31.0
func ResolveInventory(ctx context.Context, rc *config.HostnameResolverConfig, handler string, deps Deps) ([]Entry, error)
ResolveInventory fetches, transforms, and caches the endpoint inventory for the given resolver config and returns all entries. It is the list-all counterpart to ResolveEntryWith's single-selector lookup, for callers that enumerate entries (e.g. kube cluster-name shell completion). The handler namespaces the cache key and guards against a resolver depending on the handler it resolves; pass a stable non-auth-handler token (e.g. "kube") for non-auth callers.
type FetchFunc ¶
type FetchFunc func(ctx context.Context, src config.HostnameResolverSource, bearer string) ([]byte, error)
FetchFunc retrieves the raw inventory body from the resolver source. The bearer token is empty for unauthenticated sources.
type InventoryCache ¶
type InventoryCache interface {
Get(ctx context.Context, key string) ([]Entry, bool)
Set(ctx context.Context, key string, entries []Entry, ttl time.Duration)
}
InventoryCache caches resolved inventories across invocations. A nil cache disables caching.
Source Files