Skip to main content

Generated from package comments and exported declarations. Edit the Go source, not this file.

providerhealth

import "codeberg.org/hemanta212/playgo/api/providerhealth"

Package providerhealth defines provider probe, canary-account, and health-state contracts.

A probe is a test run against a provider to check it is working. A canary is a small dedicated account used for those tests - named for the canary in a coal mine, it fails first so real players do not have to. Canaries are never real customers.

The types here distinguish read, write, launch, create, and full-system probes; direct-adapter checks from end-to-end checks; and stable canaries from quarantined ones. Those distinctions carry real weight: a read probe only observes, while write and full-system probes move real credits through the real provider path.

The vocabulary is built to preserve redacted provider evidence while still giving operators a health classification they can act on. Note that acknowledging a status is an annotation recording that a human saw it - it never overrides the underlying health.

Package providerhealth defines PlayGo provider-health canary vocabulary.

Constants​

const (
ProviderSafeIdentifierMaxLen = 50
ProviderSafeUsernameMaxLen = 16
ManualCreateUsernameMaxLen = ProviderSafeUsernameMaxLen
)
const (
DefaultReadIntervalHours int32 = 72
MaximumReadIntervalHours int32 = 336
)
const (
DefaultRefillBelowCredits int64 = 200
MaximumRefillBelowCredits int64 = 1000000000
// MaximumNoRefillHours bounds the refill time limit at 30 days.
MaximumNoRefillHours int32 = 720
)

MaximumRefillKeyLength bounds a refill Idempotency-Key.

const MaximumRefillKeyLength = 200

MaximumRefillNoteLength bounds a settings change note.

const MaximumRefillNoteLength = 500

Variables​

var (
ErrInvalidReadInterval = errors.New("invalid provider read interval")
ErrReadSettingsConflict = errors.New("provider read settings changed")
)
var (
ErrInvalidRefillThreshold = errors.New("invalid refill threshold")
ErrRefillSettingsConflict = errors.New("refill settings changed")
// ErrRefillKeyReused is a refill Idempotency-Key the admin already used
// for another store.
ErrRefillKeyReused = errors.New("refill idempotency key reused")
)

func FreshStableCanaryUsernameForKind​

func FreshStableCanaryUsernameForKind(providerCode providers.ProviderCode, accountKind ProbeAccountKind, at time.Time) providers.ProviderUsername

FreshStableCanaryUsernameForKind returns a provider-safe identity scoped to the creation minute. The database makes that account stable after creation; the scoped name prevents stale provider-side accounts from a previous agent or credential generation from colliding with a replacement canary.

func IsStableCanaryUsername​

func IsStableCanaryUsername(providerCode providers.ProviderCode, username providers.ProviderUsername) bool

func ManualCreateUsername​

func ManualCreateUsername(providerCode providers.ProviderCode, at time.Time) providers.ProviderUsername

func ProbeExternalOrderID​

func ProbeExternalOrderID(providerCode providers.ProviderCode, direction ProbeOrderDirection, at time.Time) providers.ExternalOrderID

func ProbeRunExternalOrderID​

func ProbeRunExternalOrderID(providerCode providers.ProviderCode, direction ProbeOrderDirection, at time.Time, runID string) providers.ExternalOrderID

func StableCanaryUsernameForKind​

func StableCanaryUsernameForKind(providerCode providers.ProviderCode, accountKind ProbeAccountKind) providers.ProviderUsername

type BlockedReason​

type BlockedReason string
const (
BlockedReasonMissingCredentials BlockedReason = "missing_credentials"
BlockedReasonMissingAPIKey BlockedReason = "missing_api_key"
BlockedReasonNotWhitelisted BlockedReason = "not_whitelisted"
BlockedReasonZeroProviderAgentBalance BlockedReason = "zero_provider_agent_balance"
BlockedReasonPromoBlocked BlockedReason = "promo_blocked"
BlockedReasonAPITeamPending BlockedReason = "api_team_pending"
BlockedReasonUnsafeProviderRule BlockedReason = "unsafe_provider_rule"
BlockedReasonUnsupportedByProvider BlockedReason = "unsupported_by_provider"
BlockedReasonConfigMissing BlockedReason = "config_missing"
)

type CanaryPolicy​

type CanaryPolicy struct {
ProviderCode providers.ProviderCode
ReadEnabled bool
LaunchEnabled bool
ManualCreateEnabled bool
RequiresForceOffline bool
BaselineCredits providers.ProviderCredits
ProbeAmountCredits providers.ProviderCredits
BlockedReason *BlockedReason
}

func DefaultCanaryPolicy​

func DefaultCanaryPolicy(providerCode providers.ProviderCode) CanaryPolicy

type ProbeAccountKind​

type ProbeAccountKind string
const (
ProbeAccountKindStableRead ProbeAccountKind = "stable_read"
ProbeAccountKindStableWrite ProbeAccountKind = "stable_write"
ProbeAccountKindManualCreateArtifact ProbeAccountKind = "manual_create_artifact"
)

type ProbeAccountStatus​

type ProbeAccountStatus string
const (
ProbeAccountStatusActive ProbeAccountStatus = "active"
ProbeAccountStatusQuarantined ProbeAccountStatus = "quarantined"
ProbeAccountStatusRetired ProbeAccountStatus = "retired"
)

func (ProbeAccountStatus) CanTransitionTo​

func (s ProbeAccountStatus) CanTransitionTo(next ProbeAccountStatus) bool

type ProbeClassification​

type ProbeClassification string
const (
ProbeClassificationPassed ProbeClassification = "passed"
ProbeClassificationFailedProviderBusinessRule ProbeClassification = "failed_provider_business_rule"
ProbeClassificationFailedProviderOpaqueRejection ProbeClassification = "failed_provider_opaque_rejection"
ProbeClassificationFailedTransport ProbeClassification = "failed_transport"
ProbeClassificationFailedAuthOrSignature ProbeClassification = "failed_auth_or_signature"
ProbeClassificationFailedConfigMissing ProbeClassification = "failed_config_missing"
ProbeClassificationUnknownTimeout ProbeClassification = "unknown_timeout"
ProbeClassificationUnsupported ProbeClassification = "unsupported"
ProbeClassificationCapabilityDisabled ProbeClassification = "capability_disabled"
ProbeClassificationDriftDetected ProbeClassification = "drift_detected"
ProbeClassificationRestoreFailed ProbeClassification = "restore_failed"
ProbeClassificationCanaryAccountMissing ProbeClassification = "canary_account_missing"
)

type ProbeLevel​

type ProbeLevel string
const (
ProbeLevelDirectAdapter ProbeLevel = "direct_adapter"
ProbeLevelFullSystem ProbeLevel = "full_system"
)

type ProbeOrderDirection​

type ProbeOrderDirection string
const (
ProbeOrderCredit ProbeOrderDirection = "credit"
ProbeOrderDebit ProbeOrderDirection = "debit"
)

type ProbeType​

type ProbeType string
const (
ProbeTypeAgentBalance ProbeType = "agent_balance"
ProbeTypeRead ProbeType = "read"
ProbeTypeWrite ProbeType = "write"
ProbeTypeLaunch ProbeType = "launch"
ProbeTypeCreate ProbeType = "create"
)

type ReadSettings​

type ReadSettings struct {
ProviderCode providers.ProviderCode
ReadIntervalHours int32
}

type RecordRefillCommand​

RecordRefillCommand records one manual top-up. A retry with the same IdempotencyKey returns the original record.

type RecordRefillCommand struct {
ProviderCode providers.ProviderCode
ActorID uuid.UUID
IdempotencyKey string
}

type Refill​

Refill records that an admin topped up a store's credits outside PlayGo. It restarts the refill time limit; it moves no money.

type Refill struct {
ID uuid.UUID
ProviderCode providers.ProviderCode
RecordedBy uuid.UUID
RecordedAt time.Time
}

type RefillSettings​

RefillSettings are a store's refill alert settings: warn when the agent balance falls below RefillBelowCredits, and, when WarnIfNoRefillWithinHours is set, when no refill has been recorded within that many hours.

type RefillSettings struct {
ProviderCode providers.ProviderCode
RefillBelowCredits int64
WarnIfNoRefillWithinHours *int32
UpdatedBy uuid.UUID
UpdatedAt time.Time
}

type RefillSettingsChangeReason​

RefillSettingsChangeReason is the structured reason for a settings change (ADR 0019).

type RefillSettingsChangeReason string
const (
RefillSettingsChangeOperatingPolicy RefillSettingsChangeReason = "operating_policy"
RefillSettingsChangeCorrection RefillSettingsChangeReason = "correction"
RefillSettingsChangeOther RefillSettingsChangeReason = "other"
)

func (RefillSettingsChangeReason) Valid​

func (r RefillSettingsChangeReason) Valid() bool

type SetReadSettingsCommand​

type SetReadSettingsCommand struct {
ProviderCode providers.ProviderCode
ActorID uuid.UUID
ExpectedReadIntervalHours int32
ReadIntervalHours int32
ReasonCode RefillSettingsChangeReason
Note *string
}

type SetRefillSettingsCommand​

SetRefillSettingsCommand replaces both settings, guarded by the values the operator last saw. A nil time limit is off.

type SetRefillSettingsCommand struct {
ProviderCode providers.ProviderCode
ActorID uuid.UUID
ExpectedRefillBelowCredits int64
RefillBelowCredits int64
ExpectedWarnIfNoRefillWithinHours *int32
WarnIfNoRefillWithinHours *int32
ReasonCode RefillSettingsChangeReason
// Note is optional, except that "other" requires one.
Note *string
}

Generated by gomarkdoc