providers

package
v0.3.0-beta.16 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 13, 2026 License: MIT Imports: 28 Imported by: 0

Documentation

Overview

Package providers owns provider authentication classification and probes.

Index

Constants

View Source
const DefaultProviderAuthCommandTimeout = 30 * time.Second
View Source
const ProviderAuthNoAuthRequiredMessage = "No auth required."

ProviderAuthNoAuthRequiredMessage is the canonical no-auth provider status.

Variables

This section is empty.

Functions

func ClassifyProbe

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

ClassifyProbe classifies a live provider auth status command outcome.

func DefaultProviderAuthCommandResolver

func DefaultProviderAuthCommandResolver(
	_ context.Context,
	command string,
	env []string,
	dir string,
) (string, error)

DefaultProviderAuthCommandResolver resolves against the final child process environment.

func DiagnosticItem

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

DiagnosticItem builds the canonical provider diagnostic for a classifier result.

func LaunchCommandStatus

func LaunchCommandStatus(
	ctx context.Context,
	provider compozyconfig.ProviderConfig,
	env *ProbeEnv,
) (*providerauth.NativeCLIStatus, error)

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

func NativeCLIStatus

func NativeCLIStatus(
	ctx context.Context,
	provider compozyconfig.ProviderConfig,
	env *ProbeEnv,
) (*providerauth.NativeCLIStatus, error)

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

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 compozyconfig.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 compozyconfig.ProviderConfig,
	outcome ProbeOutcome,
	env *ProbeEnv,
) Classification

ClassifyProbeResult returns the full canonical classifier result.

func ClassifyProbeResultContext

func ClassifyProbeResultContext(
	ctx context.Context,
	provider compozyconfig.ProviderConfig,
	outcome ProbeOutcome,
	env *ProbeEnv,
) Classification

ClassifyProbeResultContext classifies a live probe with a cancelable command resolver.

func MissingCredentialClassification

func MissingCredentialClassification(missing CredentialStatus) Classification

MissingCredentialClassification builds the canonical missing-credential classifier.

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 compozyconfig.ProviderConfig,
	env *ProbeEnv,
) ([]CredentialStatus, error)

CredentialStatuses resolves configured credential slots without reading plaintext secrets.

type PreStartReport

type PreStartReport struct {
	Item  *diagcontract.DiagnosticItem
	Cause error
}

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

type PreStartScope

type PreStartScope struct {
	WorkspaceID       string
	HomeIdentity      string
	SandboxID         string
	SandboxBackend    string
	SandboxProfile    string
	SandboxInstanceID string
}

PreStartScope identifies the non-secret final runtime that owns one pre-start probe result. A missing required field makes a probe non-cacheable.

The values are supplied by the daemon/session composition boundary. HomeIdentity may be the final launch HOME path, which is a non-secret scope identity; no other CommandEnv value, command text, credential, or secret reference belongs in this scope.

type PreStarter

type PreStarter struct {
	// contains filtered or unexported fields
}

PreStarter owns a bounded cache of provider pre-start probe reports for one daemon composition. Entries use LRU eviction; ties are resolved by the explicit comparable key order so eviction stays deterministic.

func NewPreStarter

func NewPreStarter() *PreStarter

NewPreStarter constructs an isolated pre-start probe cache for one daemon.

func (*PreStarter) Clear

func (s *PreStarter) Clear()

Clear drops every cached report owned by this starter. The generation prevents a probe that began before Clear from repopulating the new configuration cache.

func (*PreStarter) PreStart

func (s *PreStarter) PreStart(
	ctx context.Context,
	provider compozyconfig.ProviderConfig,
	env *ProbeEnv,
) PreStartReport

PreStart classifies provider-auth readiness before a provider subprocess is spawned. It caches only final, explicitly scoped probe results.

type ProbeEnv

type ProbeEnv struct {
	ProviderName   string
	HomePaths      compozyconfig.HomePaths
	PreStartScope  PreStartScope
	LookPath       func(string) (string, error)
	LookupEnv      func(string) (string, bool)
	Vault          VaultRefResolver
	CommandEnv     []string
	ResolveCommand ProviderAuthCommandResolver
	// CommandDir is the final working directory shared by local provider probes
	// and the provider process they authorize.
	CommandDir string
	RunCommand ProviderAuthCommandRunner
	// contains filtered or unexported fields
}

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.

func (ProbeEnv) WithLaunchExecutableResolution

func (e ProbeEnv) WithLaunchExecutableResolution(
	resolution subprocess.ExecutableResolution,
) ProbeEnv

WithLaunchExecutableResolution returns a copy carrying one terminal launch identity.

type ProbeOutcome

type ProbeOutcome struct {
	ExitCode int
	Stdout   string
	Stderr   string
}

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

type ProviderAuthCommandResolver

type ProviderAuthCommandResolver func(context.Context, string, []string, string) (string, error)

ProviderAuthCommandResolver resolves a command against its exact child environment.

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
	Executable string
	Args       []string
	Dir        string
	Env        []string
	Timeout    time.Duration
	NoTTY      bool
}

ProviderAuthCommandSpec describes one provider-owned auth command execution.

func PrepareAuthStatusCommand

func PrepareAuthStatusCommand(
	ctx context.Context,
	provider compozyconfig.ProviderConfig,
	env *ProbeEnv,
) (ProviderAuthCommandSpec, error)

PrepareAuthStatusCommand resolves and pins one provider auth-status command identity.

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 ProviderLoginDescriptor

type ProviderLoginDescriptor struct {
	Configured        bool                  `json:"configured"`
	Source            string                `json:"source,omitempty"`
	Executable        string                `json:"executable,omitempty"`
	Presence          ProviderLoginPresence `json:"presence"`
	RecommendedAction ProviderFailureAction `json:"recommended_action,omitempty"`
}

ProviderLoginDescriptor is the only public-safe projection of auth_login_command.

func DescribeProviderLogin

func DescribeProviderLogin(
	provider compozyconfig.ProviderConfig,
	nativeCLI *providerauth.NativeCLIStatus,
	classification Classification,
) ProviderLoginDescriptor

DescribeProviderLogin derives safe login metadata without retaining the command line.

type ProviderLoginPresence

type ProviderLoginPresence string

ProviderLoginPresence is the safe tri-state availability of a configured login executable.

const (
	ProviderLoginPresencePresent ProviderLoginPresence = "present"
	ProviderLoginPresenceMissing ProviderLoginPresence = "missing"
	ProviderLoginPresenceUnknown ProviderLoginPresence = "unknown"
)

type VaultRefResolver

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

VaultRefResolver resolves redacted provider credential metadata.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL