observability

package
v0.26.0 Latest Latest
Warning

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

 Go to latest Published: Oct 26, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Overview

Package observability provides injectable decorators, metrics collection, and circuit breaker protection for Token-API interfaces (such as WalletService, OwnerWallet, and IssuerWallet).

Index

Constants

View Source 
const CircuitBreakerConfigKey = "circuitBreaker"

CircuitBreakerConfigKey is the configuration key used to look up circuit breaker settings in the TMS configuration.

Variables

View Source 
var ErrCircuitOpen = errors.New("circuit breaker is open: back-pressure signal")

ErrCircuitOpen is returned when a call is rejected because the circuit breaker is open.

Functions

This section is empty.

Types

type AuditorWalletDecorator 

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

AuditorWalletDecorator decorates a driver.AuditorWallet with metrics and circuit breaker protection.

func NewAuditorWalletDecorator 

func NewAuditorWalletDecorator(base driver.AuditorWallet, m *WalletMetrics, cb *CircuitBreaker) *AuditorWalletDecorator

NewAuditorWalletDecorator constructs a new AuditorWalletDecorator with a single circuit breaker.

func NewAuditorWalletDecoratorWithGetter 

func NewAuditorWalletDecoratorWithGetter(base driver.AuditorWallet, m *WalletMetrics, cbGetter func(string) *CircuitBreaker) *AuditorWalletDecorator

NewAuditorWalletDecoratorWithGetter constructs a new AuditorWalletDecorator with per-method circuit breaker dispatch.

func (*AuditorWalletDecorator) Contains 

func (w *AuditorWalletDecorator) Contains(ctx context.Context, identity driver.Identity) bool

Contains delegates to the base wallet.

func (*AuditorWalletDecorator) ContainsToken 

func (w *AuditorWalletDecorator) ContainsToken(ctx context.Context, t *token.UnspentToken) bool

ContainsToken delegates to the base wallet.

func (*AuditorWalletDecorator) GetAuditorIdentity 

func (w *AuditorWalletDecorator) GetAuditorIdentity() (driver.Identity, error)

GetAuditorIdentity delegates to the base wallet with circuit breaker protection.

func (*AuditorWalletDecorator) GetSigner 

func (w *AuditorWalletDecorator) GetSigner(ctx context.Context, identity driver.Identity) (driver.Signer, error)

GetSigner delegates to the base wallet.

func (*AuditorWalletDecorator) ID 

func (w *AuditorWalletDecorator) ID() string

ID returns the wallet ID.

type CertifierWalletDecorator 

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

CertifierWalletDecorator decorates a driver.CertifierWallet with metrics and circuit breaker protection.

func NewCertifierWalletDecorator 

func NewCertifierWalletDecorator(base driver.CertifierWallet, m *WalletMetrics, cb *CircuitBreaker) *CertifierWalletDecorator

NewCertifierWalletDecorator constructs a new CertifierWalletDecorator with a single circuit breaker.

func NewCertifierWalletDecoratorWithGetter 

func NewCertifierWalletDecoratorWithGetter(base driver.CertifierWallet, m *WalletMetrics, cbGetter func(string) *CircuitBreaker) *CertifierWalletDecorator

NewCertifierWalletDecoratorWithGetter constructs a new CertifierWalletDecorator with per-method circuit breaker dispatch.

func (*CertifierWalletDecorator) Contains 

func (w *CertifierWalletDecorator) Contains(ctx context.Context, identity driver.Identity) bool

Contains delegates to the base wallet.

func (*CertifierWalletDecorator) ContainsToken 

func (w *CertifierWalletDecorator) ContainsToken(ctx context.Context, t *token.UnspentToken) bool

ContainsToken delegates to the base wallet.

func (*CertifierWalletDecorator) GetCertifierIdentity 

func (w *CertifierWalletDecorator) GetCertifierIdentity() (driver.Identity, error)

GetCertifierIdentity delegates to the base wallet with circuit breaker protection.

func (*CertifierWalletDecorator) GetSigner 

func (w *CertifierWalletDecorator) GetSigner(ctx context.Context, identity driver.Identity) (driver.Signer, error)

GetSigner delegates to the base wallet.

func (*CertifierWalletDecorator) ID 

func (w *CertifierWalletDecorator) ID() string

ID returns the wallet ID.

type CircuitBreaker 

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

CircuitBreaker guards service execution by detecting error bursts and fast-failing calls.

func NewCircuitBreaker 

func NewCircuitBreaker(cfg CircuitBreakerConfig) *CircuitBreaker

NewCircuitBreaker creates a new CircuitBreaker with the provided configuration.

func (*CircuitBreaker) Allow 

func (cb *CircuitBreaker) Allow() error

Allow checks whether a call is permitted to execute. Returns ErrCircuitOpen if blocked. Allow is the authoritative gating call for request execution.

func (*CircuitBreaker) Execute 

func (cb *CircuitBreaker) Execute(fn func() error) (err error)

Execute wraps a function execution with circuit breaker check and result recording. It ensures RecordResult is always invoked even if fn panics, preventing halfOpenInFlight or failure state from being wedged.

func (*CircuitBreaker) RecordResult 

func (cb *CircuitBreaker) RecordResult(err error)

RecordResult updates the breaker state based on whether the call succeeded or failed.

func (*CircuitBreaker) State 

func (cb *CircuitBreaker) State() State

State returns the current State of the CircuitBreaker. It is a pure read-only query using an RLock that does not mutate internal state.

type CircuitBreakerConfig 

type CircuitBreakerConfig struct {
	// Disabled controls whether circuit breaking is active.
	// If true, calls pass through without circuit breaker gating.
	Disabled bool
	// MaxConsecutiveFailures is the number of consecutive errors that trips the breaker.
	MaxConsecutiveFailures uint32
	// CooldownTimeout is the duration the breaker stays Open before entering HalfOpen state.
	CooldownTimeout time.Duration
	// ProbeTimeout is the timeout duration for a trial probe in HalfOpen state before admitting a new probe.
	ProbeTimeout time.Duration
	// MaxWalletBreakers bounds the number of per-wallet circuit breakers kept in memory.
	MaxWalletBreakers int
	// IsFailure customizes error classification. If nil, defaultIsFailure is used.
	IsFailure func(error) bool
}

CircuitBreakerConfig defines configuration parameters for a CircuitBreaker.

func DefaultCircuitBreakerConfig 

func DefaultCircuitBreakerConfig() CircuitBreakerConfig

DefaultCircuitBreakerConfig returns default settings for a CircuitBreaker. Circuit breaking is disabled by default (opt-in).

func LoadCircuitBreakerConfig 

func LoadCircuitBreakerConfig(cp ConfigProvider) CircuitBreakerConfig

LoadCircuitBreakerConfig loads circuit breaker configuration from the provider. It inspects CircuitBreakerConfigKey ("circuitBreaker") on the TMS-scoped configuration provider. If not found or invalid, default values (with Disabled=true) are preserved.

type ConfigProvider 

type ConfigProvider interface {
	IsSet(key string) bool
	UnmarshalKey(key string, rawVal any) error
}

ConfigProvider is the minimal configuration interface needed to read circuit breaker settings. It is satisfied by driver.Configuration.

type IssuerWalletDecorator 

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

IssuerWalletDecorator decorates a driver.IssuerWallet with metrics and circuit breaker protection.

func NewIssuerWalletDecorator 

func NewIssuerWalletDecorator(base driver.IssuerWallet, m *WalletMetrics, cb *CircuitBreaker) *IssuerWalletDecorator

NewIssuerWalletDecorator constructs a new IssuerWalletDecorator with a single circuit breaker.

func NewIssuerWalletDecoratorWithGetter 

func NewIssuerWalletDecoratorWithGetter(base driver.IssuerWallet, m *WalletMetrics, cbGetter func(string) *CircuitBreaker) *IssuerWalletDecorator

NewIssuerWalletDecoratorWithGetter constructs a new IssuerWalletDecorator with per-method circuit breaker dispatch.

func (*IssuerWalletDecorator) Balance 

func (w *IssuerWalletDecorator) Balance(ctx context.Context, opts *driver.IssuerBalanceOptions) (*big.Int, error)

Balance delegates to the base wallet with metrics and circuit breaker protection.

func (*IssuerWalletDecorator) Contains 

func (w *IssuerWalletDecorator) Contains(ctx context.Context, identity driver.Identity) bool

Contains delegates to the base wallet.

func (*IssuerWalletDecorator) ContainsToken 

func (w *IssuerWalletDecorator) ContainsToken(ctx context.Context, t *token.UnspentToken) bool

ContainsToken delegates to the base wallet.

func (*IssuerWalletDecorator) GetIssuerIdentity 

func (w *IssuerWalletDecorator) GetIssuerIdentity(tokenType token.Type) (driver.Identity, error)

GetIssuerIdentity delegates to the base wallet with circuit breaker protection.

func (*IssuerWalletDecorator) GetSigner 

func (w *IssuerWalletDecorator) GetSigner(ctx context.Context, identity driver.Identity) (driver.Signer, error)

GetSigner delegates to the base wallet.

func (*IssuerWalletDecorator) HistoryTokens 

func (w *IssuerWalletDecorator) HistoryTokens(ctx context.Context, opts *driver.ListTokensOptions) (*token.IssuedTokens, error)

HistoryTokens delegates to the base wallet with metrics and circuit breaker protection.

func (*IssuerWalletDecorator) ID 

func (w *IssuerWalletDecorator) ID() string

ID returns the wallet ID.

func (*IssuerWalletDecorator) IssuedBalance 

func (w *IssuerWalletDecorator) IssuedBalance(ctx context.Context, opts *driver.IssuerBalanceOptions) (*big.Int, error)

IssuedBalance delegates to the base wallet with metrics and circuit breaker protection.

func (*IssuerWalletDecorator) RedeemedBalance 

func (w *IssuerWalletDecorator) RedeemedBalance(ctx context.Context, opts *driver.IssuerBalanceOptions) (*big.Int, error)

RedeemedBalance delegates to the base wallet with metrics and circuit breaker protection.

type OwnerWalletDecorator 

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

OwnerWalletDecorator decorates a driver.OwnerWallet with metrics and circuit breaker protection.

func NewOwnerWalletDecorator 

func NewOwnerWalletDecorator(base driver.OwnerWallet, m *WalletMetrics, cb *CircuitBreaker) *OwnerWalletDecorator

NewOwnerWalletDecorator constructs a new OwnerWalletDecorator with a single circuit breaker.

func NewOwnerWalletDecoratorWithGetter 

func NewOwnerWalletDecoratorWithGetter(base driver.OwnerWallet, m *WalletMetrics, cbGetter func(string) *CircuitBreaker) *OwnerWalletDecorator

NewOwnerWalletDecoratorWithGetter constructs a new OwnerWalletDecorator with per-method circuit breaker dispatch.

func (*OwnerWalletDecorator) Balance 

func (w *OwnerWalletDecorator) Balance(ctx context.Context, opts *driver.ListTokensOptions) (*big.Int, error)

Balance delegates to the base wallet with metrics and circuit breaker protection.

func (*OwnerWalletDecorator) Contains 

func (w *OwnerWalletDecorator) Contains(ctx context.Context, identity driver.Identity) bool

Contains delegates to the base wallet.

func (*OwnerWalletDecorator) ContainsToken 

func (w *OwnerWalletDecorator) ContainsToken(ctx context.Context, t *token.UnspentToken) bool

ContainsToken delegates to the base wallet.

func (*OwnerWalletDecorator) EnrollmentID 

func (w *OwnerWalletDecorator) EnrollmentID() string

EnrollmentID returns the wallet enrollment ID.

func (*OwnerWalletDecorator) GetAuditInfo 

func (w *OwnerWalletDecorator) GetAuditInfo(ctx context.Context, id driver.Identity) ([]byte, error)

GetAuditInfo delegates to the base wallet.

func (*OwnerWalletDecorator) GetRecipientData 

func (w *OwnerWalletDecorator) GetRecipientData(ctx context.Context) (*driver.RecipientData, error)

GetRecipientData delegates to the base wallet with circuit breaker protection.

func (*OwnerWalletDecorator) GetRecipientIdentity 

func (w *OwnerWalletDecorator) GetRecipientIdentity(ctx context.Context) (driver.Identity, error)

GetRecipientIdentity delegates to the base wallet with circuit breaker protection.

func (*OwnerWalletDecorator) GetSigner 

func (w *OwnerWalletDecorator) GetSigner(ctx context.Context, identity driver.Identity) (driver.Signer, error)

GetSigner delegates to the base wallet.

func (*OwnerWalletDecorator) GetTokenMetadata 

func (w *OwnerWalletDecorator) GetTokenMetadata(id driver.Identity) ([]byte, error)

GetTokenMetadata delegates to the base wallet.

func (*OwnerWalletDecorator) GetTokenMetadataAuditInfo 

func (w *OwnerWalletDecorator) GetTokenMetadataAuditInfo(id driver.Identity) ([]byte, error)

GetTokenMetadataAuditInfo delegates to the base wallet.

func (*OwnerWalletDecorator) ID 

func (w *OwnerWalletDecorator) ID() string

ID returns the wallet ID.

func (*OwnerWalletDecorator) ListTokens 

func (w *OwnerWalletDecorator) ListTokens(ctx context.Context, opts *driver.ListTokensOptions) (*token.UnspentTokens, error)

ListTokens delegates to the base wallet with metrics and circuit breaker protection.

func (*OwnerWalletDecorator) ListTokensIterator 

func (w *OwnerWalletDecorator) ListTokensIterator(ctx context.Context, opts *driver.ListTokensOptions) (driver.UnspentTokensIterator, error)

ListTokensIterator delegates to the base wallet.

func (*OwnerWalletDecorator) RegisterRecipient 

func (w *OwnerWalletDecorator) RegisterRecipient(ctx context.Context, data *driver.RecipientData) error

RegisterRecipient delegates to the base wallet with circuit breaker protection.

func (*OwnerWalletDecorator) Remote 

func (w *OwnerWalletDecorator) Remote() bool

Remote returns whether the wallet is remote.

type State 

type State int

State represents the operational state of a circuit breaker. 

const (
	// StateClosed allows all calls to pass through normally.
	StateClosed State = iota
	// StateOpen rejects calls immediately with ErrCircuitOpen to signal back-pressure.
	StateOpen
	// StateHalfOpen permits a single trial probe to test if the underlying service has recovered.
	StateHalfOpen
)

type WalletMetrics 

type WalletMetrics struct {
	// RequestCount tracks the total number of service invocations.
	RequestCount metrics.Counter
	// ErrorCount tracks the total number of errors returned by service invocations.
	ErrorCount metrics.Counter
	// Latency tracks the execution duration of service operations.
	Latency metrics.Histogram
	// InFlight tracks the number of currently active in-flight service requests.
	InFlight metrics.Gauge
	// RejectionsTotal tracks the number of requests rejected by the circuit breaker.
	RejectionsTotal metrics.Counter
	// State tracks the current circuit breaker state (0=Closed, 1=Open, 2=HalfOpen).
	State metrics.Gauge
}

WalletMetrics holds metrics collectors for Token-API / WalletService operations.

func NewWalletMetrics 

func NewWalletMetrics(p metrics.Provider) *WalletMetrics

NewWalletMetrics constructs a new WalletMetrics instance using the provided metrics.Provider. If provider is nil, the FSC no-op disabled.Provider is used so callers never get a nil panic.

func (*WalletMetrics) Observe 

func (m *WalletMetrics) Observe(method, walletID string, start time.Time, err error)

Observe records execution latency, increments request count, updates error count, and records circuit breaker rejections if err is ErrCircuitOpen. Circuit-breaker rejections are recorded in RejectionsTotal but excluded from ErrorCount and Latency so they are not double-counted and do not pollute the latency histogram.

func (*WalletMetrics) RecordState 

func (m *WalletMetrics) RecordState(method, walletID string, s State)

RecordState records the current circuit breaker state for a method and wallet.

type WalletServiceDecorator 

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

WalletServiceDecorator decorates a driver.WalletService with metrics collection and circuit breaking.

Each wallet returned by OwnerWallet, IssuerWallet, AuditorWallet, and CertifierWallet receives an independent, cached CircuitBreaker per wallet ID so that failures in one wallet do not trip the breaker for unrelated wallets or wallet types. Per-wallet breakers are managed in a bounded LRU cache.

func NewWalletServiceDecorator 

func NewWalletServiceDecorator(base driver.WalletService, provider metrics.Provider, cb *CircuitBreaker) *WalletServiceDecorator

NewWalletServiceDecorator constructs a new WalletServiceDecorator wrapping the provided base service. cb is an optional circuit breaker used for WalletService-level operations. If cb is nil, independent per-method circuit breakers are created from DefaultCircuitBreakerConfig. Each wallet returned by OwnerWallet/IssuerWallet/AuditorWallet/CertifierWallet receives its own independent circuit breaker cached per wallet ID in a bounded LRU cache.

func NewWalletServiceDecoratorWithConfig 

func NewWalletServiceDecoratorWithConfig(base driver.WalletService, provider metrics.Provider, cfg CircuitBreakerConfig) *WalletServiceDecorator

NewWalletServiceDecoratorWithConfig constructs a new WalletServiceDecorator wrapping the provided base service using the given circuit breaker configuration.

func (*WalletServiceDecorator) AuditorWallet 

func (d *WalletServiceDecorator) AuditorWallet(ctx context.Context, id driver.WalletLookupID) (driver.AuditorWallet, error)

AuditorWallet delegates to the base service, wrapping the returned wallet with metrics and an independent circuit breaker cached per wallet ID and method.

func (*WalletServiceDecorator) CertifierWallet 

func (d *WalletServiceDecorator) CertifierWallet(ctx context.Context, id driver.WalletLookupID) (driver.CertifierWallet, error)

CertifierWallet delegates to the base service, wrapping the returned wallet with metrics and an independent circuit breaker cached per wallet ID and method.

func (*WalletServiceDecorator) Done 

func (d *WalletServiceDecorator) Done() error

Done delegates to the base service without circuit breaking or metrics. It signals the end of a local transaction or session lifecycle and is a local cleanup operation.

func (*WalletServiceDecorator) GetAuditInfo 

func (d *WalletServiceDecorator) GetAuditInfo(ctx context.Context, id driver.Identity) ([]byte, error)

GetAuditInfo delegates to the base service with metrics collection.

Note: GetAuditInfo operates outside the circuit breaker. Auditing and cross-party transaction verification routinely query audit info for identities that belong to other parties or are not locally registered (resulting in benign "not found" misses). Gating GetAuditInfo with a shared circuit breaker would allow routine lookup misses to trip the breaker and block valid lookups for known identities.

func (*WalletServiceDecorator) GetEIDAndRH 

func (d *WalletServiceDecorator) GetEIDAndRH(ctx context.Context, identity driver.Identity, auditInfo []byte) (string, string, error)

GetEIDAndRH delegates to the base service with metrics collection. It operates outside the circuit breaker as it is a CPU-only deserialization operation.

func (*WalletServiceDecorator) GetEnrollmentID 

func (d *WalletServiceDecorator) GetEnrollmentID(ctx context.Context, identity driver.Identity, auditInfo []byte) (string, error)

GetEnrollmentID delegates to the base service with metrics collection. It operates outside the circuit breaker as it is a CPU-only deserialization operation.

func (*WalletServiceDecorator) GetRevocationHandle 

func (d *WalletServiceDecorator) GetRevocationHandle(ctx context.Context, identity driver.Identity, auditInfo []byte) (string, error)

GetRevocationHandle delegates to the base service with metrics collection. It operates outside the circuit breaker as it is a CPU-only deserialization operation.

func (*WalletServiceDecorator) IssuerWallet 

func (d *WalletServiceDecorator) IssuerWallet(ctx context.Context, id driver.WalletLookupID) (driver.IssuerWallet, error)

IssuerWallet delegates to the base service, wrapping the returned wallet with per-method circuit breakers. Each issuer wallet gets independent breakers cached per wallet ID and method so failures are isolated.

func (*WalletServiceDecorator) OwnerWallet 

func (d *WalletServiceDecorator) OwnerWallet(ctx context.Context, id driver.WalletLookupID) (driver.OwnerWallet, error)

OwnerWallet delegates to the base service, wrapping the returned wallet with its own circuit breaker. Note: OwnerWallet lookup itself must remain outside the circuit breaker. WalletBasedAuthorization.IsMine (and related authorization checks) treats any OwnerWallet error as "not mine". Gating wallet lookup behind a breaker would cause IsMine to falsely report not-mine on unrelated transient failures, permanently dropping token tracking. Instead, the returned wallet is decorated with independent circuit breakers cached per wallet ID and method.

func (*WalletServiceDecorator) OwnerWalletIDs 

func (d *WalletServiceDecorator) OwnerWalletIDs(ctx context.Context) ([]string, error)

OwnerWalletIDs delegates to the base service with metrics and circuit breaker protection.

func (*WalletServiceDecorator) RegisterIssuerIdentity 

func (d *WalletServiceDecorator) RegisterIssuerIdentity(ctx context.Context, config driver.IdentityConfiguration) error

RegisterIssuerIdentity delegates to the base service with circuit breaker protection.

func (*WalletServiceDecorator) RegisterOwnerIdentity 

func (d *WalletServiceDecorator) RegisterOwnerIdentity(ctx context.Context, config driver.IdentityConfiguration) error

RegisterOwnerIdentity delegates to the base service with circuit breaker protection.

func (*WalletServiceDecorator) RegisterRecipientIdentity 

func (d *WalletServiceDecorator) RegisterRecipientIdentity(ctx context.Context, data *driver.RecipientData) error

RegisterRecipientIdentity delegates to the base service with metrics and circuit breaker protection.

func (*WalletServiceDecorator) SpendIDs 

func (d *WalletServiceDecorator) SpendIDs(ids ...*token.ID) ([]string, error)

SpendIDs delegates to the base service without circuit breaking or metrics. It is an in-memory key formatting transformation that does not perform external network or database calls.

func (*WalletServiceDecorator) Wallet 

func (d *WalletServiceDecorator) Wallet(ctx context.Context, identity driver.Identity) driver.Wallet

Wallet delegates to the base service without circuit breaking or metrics. It is a transient in-memory identity-to-wallet translation lookup that does not perform storage or network operations.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.