auditor

package
v0.14.1 Latest Latest
Warning

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

Go to latest
Published: Jul 7, 2026 License: Apache-2.0 Imports: 21 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// Pending is the status of a transaction that has been submitted to the ledger
	Pending = auditdb.Pending
	// Confirmed is the status of a transaction that has been confirmed by the ledger
	Confirmed = auditdb.Confirmed
	// Deleted is the status of a transaction that has been deleted due to a failure to commit
	Deleted = auditdb.Deleted
	// Orphan is the status of a transaction that never reached the ledger
	Orphan = auditdb.Orphan
)

Variables

View Source
var TxStatusMessage = auditdb.TxStatusMessage

Functions

This section is empty.

Types

type CheckService

type CheckService interface {
	Check(ctx context.Context) ([]string, error)
}

type CheckServiceProvider

type CheckServiceProvider interface {
	CheckService(id token.TMSID, adb *auditdb.StoreService, tdb *tokens.Service) (CheckService, error)
}

CheckServiceProvider provides check services for auditor validation.

type ConfigProvider

type ConfigProvider interface {
	// IsSet checks if a configuration key exists
	IsSet(key string) bool
	// UnmarshalKey unmarshals a configuration key into the provided struct
	UnmarshalKey(key string, rawVal any) error
}

ConfigProvider is a minimal interface for configuration access needed by LoadLockConfig. This interface allows for easy mocking in tests without depending on the full config.Configuration.

type LockConfig

type LockConfig struct {
	// MaxRetries is the maximum number of retry attempts for lock acquisition
	MaxRetries int
	// InitialBackoff is the initial backoff delay before the first retry
	InitialBackoff time.Duration
	// MaxBackoff is the maximum backoff delay between retries
	MaxBackoff time.Duration
	// BackoffMultiplier is the exponential backoff multiplier
	BackoffMultiplier float64
	// JitterFactor is the randomization factor to prevent thundering herd (0.0 to 1.0)
	JitterFactor float64
}

LockConfig holds the configuration for lock acquisition retry logic

func DefaultLockConfig

func DefaultLockConfig() *LockConfig

DefaultLockConfig returns the default lock configuration

func LoadLockConfig

func LoadLockConfig(cp ConfigProvider) *LockConfig

LoadLockConfig loads lock configuration from the configuration provider. If configuration is not found or invalid, returns default configuration.

func LoadLockConfigFromConfiguration

func LoadLockConfigFromConfiguration(cp *config.Configuration) *LockConfig

LoadLockConfigFromConfiguration is a convenience wrapper that adapts config.Configuration to the ConfigProvider interface and calls LoadLockConfig.

type LockConfigRaw

type LockConfigRaw struct {
	MaxRetries        int     `yaml:"maxRetries"`
	InitialBackoff    string  `yaml:"initialBackoff"`
	MaxBackoff        string  `yaml:"maxBackoff"`
	BackoffMultiplier float64 `yaml:"backoffMultiplier"`
	JitterFactor      float64 `yaml:"jitterFactor"`
}

LockConfigRaw is used to unmarshal lock configuration from YAML

type Metrics

type Metrics struct {
	// AuditDuration is a histogram of the wall-clock time for each Audit()
	// invocation (lock acquisition included), in seconds.
	AuditDuration metrics.Histogram

	// AuditLockConflicts counts calls to Audit() that failed because
	// AcquireLocks returned an error (e.g. contention or timeout).
	AuditLockConflicts metrics.Counter

	// AppendDuration is a histogram of the total wall-clock time for each
	// Append() invocation, in seconds.
	AppendDuration metrics.Histogram

	// AppendErrors counts calls to Append() that failed when writing to the
	// audit database.
	AppendErrors metrics.Counter

	// ReleasesTotal counts all calls to Release(), whether invoked explicitly
	// or via the defer inside Append().
	ReleasesTotal metrics.Counter
}

Metrics holds the instrumentation for the auditor Service.

type NetworkProvider

type NetworkProvider interface {
	GetNetwork(network string, channel string) (*network.Network, error)
}

type Service

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

Service is the interface for the auditor service

func Get

Get returns the Service instance for the passed auditor wallet

func GetByTMSID

func GetByTMSID(sp token.ServiceProvider, tmsID token.TMSID) *Service

GetByTMSID returns the Service instance for the passed auditor wallet

func NewService

func NewService(
	tmsID token.TMSID,
	networkProvider NetworkProvider,
	auditDB *auditdb.StoreService,
	tokenDB *tokens.Service,
	tmsProvider dep.TokenManagementServiceProvider,
	finalityTracer trace.Tracer,
	metricsProvider metrics.Provider,
	checkService CheckService,
	lockConfig *LockConfig,
) *Service

NewService creates a new auditor Service with the provided dependencies. If lockConfig is nil, default lock configuration will be used.

func (*Service) Append

func (a *Service) Append(ctx context.Context, tx Transaction) error

Append adds the passed transaction to the auditor database. It also releases the locks acquired by Audit.

func (*Service) Audit

Audit extracts the list of inputs and outputs from the passed transaction. In addition, the Audit locks the enrollment named ids with retry logic and exponential backoff to prevent livelock conditions. The caller MUST call Release() to unlock these enrollment IDs after processing.

IMPORTANT: The defer Release() statement MUST be placed immediately after checking the error returned by Audit(). This ensures locks are released even if subsequent operations fail. Example:

inputs, outputs, err := auditor.Audit(ctx, tx)
if err != nil {
    return errors.Wrap(err, "audit failed")
}
defer auditor.Release(ctx, tx)

Note: The semaphore-based locking mechanism handles context cancellation during lock acquisition (see PR #1616), ensuring proper cleanup in case of timeouts or cancellations.

func (*Service) Check

func (a *Service) Check(ctx context.Context) ([]string, error)

Check performs a health check on the auditor service and returns any issues found.

func (*Service) GetStatus

func (a *Service) GetStatus(ctx context.Context, txID string) (TxStatus, string, error)

GetStatus return the status of the given transaction id. It returns an error if no transaction with that id is found

func (*Service) GetTokenRequest

func (a *Service) GetTokenRequest(ctx context.Context, txID string) ([]byte, error)

GetTokenRequest returns the token request bound to the passed transaction id, if available.

func (*Service) Release

func (a *Service) Release(ctx context.Context, tx Transaction)

Release releases the lock acquired of the passed transaction.

func (*Service) SetStatus

func (a *Service) SetStatus(ctx context.Context, txID string, status storage.TxStatus, message string) error

SetStatus sets the status of the audit records with the passed transaction id to the passed status

func (*Service) Validate

func (a *Service) Validate(ctx context.Context, request *token.Request) error

Validate validates the passed token request

type ServiceManager

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

ServiceManager handles the services

func NewServiceManager

func NewServiceManager(
	networkProvider NetworkProvider,
	auditStoreServiceManager StoreServiceManager,
	tokensServiceManager TokensServiceManager,
	tmsProvider dep.TokenManagementServiceProvider,
	tracerProvider trace.TracerProvider,
	metricsProvider metrics.Provider,
	checkServiceProvider CheckServiceProvider,
	configService *config.Service,
) *ServiceManager

NewServiceManager creates a new Service manager.

func (*ServiceManager) Auditor

func (cm *ServiceManager) Auditor(tmsID token.TMSID) (*Service, error)

Auditor returns the Service for the given wallet

type StoreServiceManager

type StoreServiceManager = auditdb.StoreServiceManager

StoreServiceManager manages audit database store services.

type TokenManagementServiceProvider

type TokenManagementServiceProvider interface {
	GetManagementService(opts ...token.ServiceOption) (*token.ManagementService, error)
}

TokenManagementServiceProvider provides access to token management services.

type TokensServiceManager

type TokensServiceManager = services.ServiceManager[*tokens.Service]

TokensServiceManager manages token services.

type Transaction

type Transaction interface {
	ID() string
	Network() string
	Channel() string
	Namespace() string
	Request() *token.Request
}

Transaction models a generic token transaction

type TxStatus

type TxStatus = auditdb.TxStatus

TxStatus is the status of a transaction

Directories

Path Synopsis
Code generated by counterfeiter.
Code generated by counterfeiter.

Jump to

Keyboard shortcuts

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