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