providers

Documentation

Overview

Package providers owns provider authentication classification and probes.

Index

• Constants
• func ClassifyProbe(provider aghconfig.ProviderConfig, outcome ProbeOutcome, env *ProbeEnv) (state string, code string, message string)
• func DiagnosticItem(providerName string, classification Classification) diagcontract.DiagnosticItem
• func InvalidatePreStartCache()
• func LaunchCommandStatus(provider aghconfig.ProviderConfig, env *ProbeEnv) (*providerauth.NativeCLIStatus, error)
• func NativeCLIStatus(provider aghconfig.ProviderConfig, env *ProbeEnv) (*providerauth.NativeCLIStatus, error)
• func SuggestedCommand(providerName string, classification Classification) string
• type Classification
  • func ClassifyDeclared(ctx context.Context, provider aghconfig.ProviderConfig, env *ProbeEnv) (Classification, error)
  • func ClassifyError(err error) Classification
  • func ClassifyProbeResult(provider aghconfig.ProviderConfig, outcome ProbeOutcome, env *ProbeEnv) Classification
• type CredentialStatus
  • func CredentialStatuses(ctx context.Context, provider aghconfig.ProviderConfig, env *ProbeEnv) ([]CredentialStatus, error)
• type PreStartReport
  • func PreStart(ctx context.Context, provider aghconfig.ProviderConfig, env *ProbeEnv) PreStartReport
• type ProbeEnv
  • func (e *ProbeEnv) Normalize() ProbeEnv
• type ProbeOutcome
• type ProviderAuthCommandResult
  • func DefaultProviderAuthCommandRunner(ctx context.Context, spec ProviderAuthCommandSpec) (ProviderAuthCommandResult, error)
  • func DefaultProviderAuthLoginRunner(ctx context.Context, spec ProviderAuthCommandSpec) (ProviderAuthCommandResult, error)
• type ProviderAuthCommandRunner
• type ProviderAuthCommandSpec
• type ProviderAuthState
• type ProviderFailureAction
• type ProviderFailureKind
• type VaultRefResolver

Constants

const DefaultProviderAuthCommandTimeout = 30 * time.Second

const ProviderAuthNoAuthRequiredMessage = "No auth required."

ProviderAuthNoAuthRequiredMessage is the canonical no-auth provider status.

Functions

func ClassifyProbe

func ClassifyProbe(
	provider aghconfig.ProviderConfig,
	outcome ProbeOutcome,
	env *ProbeEnv,
) (state string, code string, message string)

ClassifyProbe classifies a live provider auth status command outcome.

func DiagnosticItem

func DiagnosticItem(providerName string, classification Classification) diagcontract.DiagnosticItem

DiagnosticItem builds the canonical provider diagnostic for a classifier result.

func InvalidatePreStartCache

func InvalidatePreStartCache()

InvalidatePreStartCache clears all cached pre-start probe reports.

func LaunchCommandStatus

func LaunchCommandStatus(
	provider aghconfig.ProviderConfig,
	env *ProbeEnv,
) (*providerauth.NativeCLIStatus, error)

LaunchCommandStatus resolves the first token of the launch command used by a session start.

func NativeCLIStatus

func NativeCLIStatus(
	provider aghconfig.ProviderConfig,
	env *ProbeEnv,
) (*providerauth.NativeCLIStatus, error)

NativeCLIStatus resolves the CLI binary used by a native provider-auth probe.

func SuggestedCommand

func SuggestedCommand(providerName string, classification Classification) string

SuggestedCommand returns the canonical operator command for a provider-auth classification.

Types

type Classification

type Classification struct {
	State   ProviderAuthState
	Code    string
	Message string
	Kind    ProviderFailureKind
	Action  ProviderFailureAction
}

Classification is one canonical provider-auth classifier result.

func ClassifyDeclared

func ClassifyDeclared(
	ctx context.Context,
	provider aghconfig.ProviderConfig,
	env *ProbeEnv,
) (Classification, error)

ClassifyDeclared classifies provider readiness without executing a probe.

func ClassifyError

func ClassifyError(err error) Classification

ClassifyError maps provider startup errors onto the canonical auth taxonomy when possible.

func ClassifyProbeResult

func ClassifyProbeResult(
	provider aghconfig.ProviderConfig,
	outcome ProbeOutcome,
	env *ProbeEnv,
) Classification

ClassifyProbeResult returns the full canonical classifier result.

type CredentialStatus

type CredentialStatus struct {
	Name      string
	TargetEnv string
	SecretRef string
	Kind      string
	Required  bool
	Present   bool
	Source    string
}

CredentialStatus reports one provider launch credential slot readiness.

func CredentialStatuses

func CredentialStatuses(
	ctx context.Context,
	provider aghconfig.ProviderConfig,
	env *ProbeEnv,
) ([]CredentialStatus, error)

CredentialStatuses resolves configured credential slots without reading plaintext secrets.

type PreStartReport

type PreStartReport struct {
	Item *diagcontract.DiagnosticItem
}

PreStartReport carries a structured diagnostic when the pre-start probe fails.

func PreStart

func PreStart(
	ctx context.Context,
	provider aghconfig.ProviderConfig,
	env *ProbeEnv,
) PreStartReport

PreStart classifies provider-auth readiness before a provider subprocess is spawned.

type ProbeEnv

type ProbeEnv struct {
	ProviderName string
	HomePaths    aghconfig.HomePaths
	LookPath     func(string) (string, error)
	LookupEnv    func(string) (string, bool)
	Vault        VaultRefResolver
	CommandEnv   []string
	RunCommand   ProviderAuthCommandRunner
}

ProbeEnv supplies process, env, and vault access to provider auth probes.

func (*ProbeEnv) Normalize

func (e *ProbeEnv) Normalize() ProbeEnv

Normalize fills safe defaults without mutating the caller's env.

type ProbeOutcome

type ProbeOutcome struct {
	ExitCode int
	Stdout   string
	Stderr   string
}

ProbeOutcome is the redacted output from one provider auth status command.

type ProviderAuthCommandResult

type ProviderAuthCommandResult struct {
	ExitCode   int    `json:"exit_code"`
	Stdout     string `json:"stdout,omitempty"`
	Stderr     string `json:"stderr,omitempty"`
	DurationMs int64  `json:"duration_ms"`
}

ProviderAuthCommandResult is a redacted provider auth command result.

func DefaultProviderAuthCommandRunner

func DefaultProviderAuthCommandRunner(
	ctx context.Context,
	spec ProviderAuthCommandSpec,
) (ProviderAuthCommandResult, error)

DefaultProviderAuthCommandRunner runs a non-interactive auth status command.

func DefaultProviderAuthLoginRunner

func DefaultProviderAuthLoginRunner(
	ctx context.Context,
	spec ProviderAuthCommandSpec,
) (ProviderAuthCommandResult, error)

DefaultProviderAuthLoginRunner runs an operator-facing auth login command.

type ProviderAuthCommandRunner

type ProviderAuthCommandRunner func(context.Context, ProviderAuthCommandSpec) (ProviderAuthCommandResult, error)

ProviderAuthCommandRunner executes a provider-owned auth command.

type ProviderAuthCommandSpec

type ProviderAuthCommandSpec struct {
	Command string
	Env     []string
	Timeout time.Duration
	NoTTY   bool
}

ProviderAuthCommandSpec describes one provider-owned auth command execution.

type ProviderAuthState

type ProviderAuthState string

ProviderAuthState is the canonical provider authentication state.

const (
	ProviderAuthStateAuthenticated     ProviderAuthState = "authenticated"
	ProviderAuthStateNeedsLogin        ProviderAuthState = "needs_login"
	ProviderAuthStateMissingCLI        ProviderAuthState = "missing_cli"
	ProviderAuthStateMissingCredential ProviderAuthState = "missing_credential"
	ProviderAuthStatePermissionDenied  ProviderAuthState = "permission_denied"
	ProviderAuthStateRateLimited       ProviderAuthState = "rate_limited"
	ProviderAuthStateTransient         ProviderAuthState = "transient"
	ProviderAuthStateNone              ProviderAuthState = "none"
	ProviderAuthStateUnknown           ProviderAuthState = "unknown"
)

type ProviderFailureAction

type ProviderFailureAction string

ProviderFailureAction is the agent-facing recovery class for a provider failure.

const (
	ProviderFailureActionNone       ProviderFailureAction = ""
	ProviderFailureActionInstallCLI ProviderFailureAction = "install_cli"
	ProviderFailureActionLogin      ProviderFailureAction = "login"
	ProviderFailureActionBindSecret ProviderFailureAction = "bind_secret"
	ProviderFailureActionRetry      ProviderFailureAction = "retry"
	ProviderFailureActionInspect    ProviderFailureAction = "inspect"
	ProviderFailureActionNoRetry    ProviderFailureAction = "no_retry"
)

type ProviderFailureKind

type ProviderFailureKind string

ProviderFailureKind identifies a classified provider failure bucket.

const (
	ProviderFailureNone       ProviderFailureKind = ""
	ProviderFailureCLIMissing ProviderFailureKind = "missing_cli"
	// #nosec G101 -- diagnostic enum value, not a credential.
	ProviderFailureCredentialUnresolved ProviderFailureKind = "credential_unresolved"
	ProviderFailureNotAuthenticated     ProviderFailureKind = "not_authenticated"
	ProviderFailurePermissionDenied     ProviderFailureKind = "permission_denied"
	ProviderFailureRateLimited          ProviderFailureKind = "rate_limited"
	ProviderFailureTransient            ProviderFailureKind = "transient"
	ProviderFailureUnknown              ProviderFailureKind = "unknown"
)

type VaultRefResolver

type VaultRefResolver interface {
	GetMetadata(ctx context.Context, ref string) (vault.Metadata, error)
}

VaultRefResolver resolves redacted provider credential metadata.