interactive

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: 16 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// DefaultMaxAttempts is the default number of times a certification request
	// is retried before giving up and pushing the tokens back to the queue.
	DefaultMaxAttempts = 3
	// DefaultWaitTime is the default backoff duration between retry attempts.
	DefaultWaitTime = 10 * time.Second
	// DefaultBatchSize is the default maximum number of tokens per certification batch.
	DefaultBatchSize = 10
	// DefaultBufferSize is the default capacity of the incoming token channel.
	DefaultBufferSize = 1000
	// DefaultFlushInterval is the default period after which a partial batch is
	// flushed to the worker pool even if it has not reached BatchSize.
	DefaultFlushInterval = 5 * time.Second
	// DefaultWorkers is the default number of worker goroutines processing certification batches.
	DefaultWorkers = 1
	// DefaultResponseTimeout is the maximum time the client waits for the certifier
	// to respond before treating the request as failed.
	DefaultResponseTimeout = 60 * time.Second

	// MaxTokensPerRequest is the maximum number of token IDs accepted in a single
	// certification request. Requests exceeding this limit are rejected to prevent
	// resource exhaustion on the certifier node.
	MaxTokensPerRequest = 500

	// MaxRequestBytes is the maximum byte-length of the cryptographic request payload
	// in a CertificationRequest. Requests exceeding this limit are rejected to prevent
	// memory exhaustion on the certifier node.
	MaxRequestBytes = 1 << 20 // 1 MiB
)

Default operational parameters for the CertificationClient.

View Source
const (
	ConfigurationKey = "certification.interactive"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Backend

type Backend interface {
	Load(context view.Context, cr *CertificationRequest) ([][]byte, error)
}

type BackendFactory

type BackendFactory func(tms *token.ManagementService, wallet string) (Backend, error)

type Certification

type Certification struct {
	// IDs lists the endpoint identifiers of the remote certifier nodes.
	IDs []string `yaml:"ids,omitempty"`

	// MaxAttempts is the maximum number of times a certification request is
	// retried before the batch is discarded. Zero uses DefaultMaxAttempts.
	MaxAttempts int `yaml:"maxAttempts,omitempty"`

	// WaitTime is the backoff duration between retry attempts.
	// Zero uses DefaultWaitTime.
	WaitTime time.Duration `yaml:"waitTime,omitempty"`

	// BatchSize is the maximum number of tokens assembled into a single
	// certification request. Zero uses DefaultBatchSize.
	BatchSize int `yaml:"batchSize,omitempty"`

	// BufferSize is the capacity of the incoming token channel. Tokens are
	// dropped (and counted) when the buffer is full. Zero uses DefaultBufferSize.
	BufferSize int `yaml:"bufferSize,omitempty"`

	// FlushInterval is the maximum time a partial batch waits before being
	// dispatched to the worker pool. Zero uses DefaultFlushInterval.
	FlushInterval time.Duration `yaml:"flushInterval,omitempty"`

	// Workers is the number of concurrent goroutines that process certification
	// batches. Zero uses DefaultWorkers.
	Workers int `yaml:"workers,omitempty"`

	// ResponseTimeout is the maximum time the client waits for the certifier to
	// respond before treating the request as failed. Zero uses DefaultResponseTimeout.
	ResponseTimeout time.Duration `yaml:"responseTimeout,omitempty"`
}

Certification holds the configuration for the interactive certifier, parsed from the TMS configuration under the "certification.interactive" key.

type CertificationClient

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

CertificationClient scans the vault for tokens not yet certified and requests certification. It batches incoming token IDs, dispatches them to a configurable worker pool, and retries on failure. Callers must invoke Start() before using the client and Stop() to release resources.

func NewCertificationClient

func NewCertificationClient(
	ctx context.Context,
	network string,
	channel string,
	namespace string,
	qe QueryEngine,
	cm CertificationStorage,
	fm ViewManager,
	certifiers []view.Identity,
	notifier events.Subscriber,
	maxAttempts int,
	waitTime time.Duration,
	batchSize int,
	bufferSize int,
	flushInterval time.Duration,
	workers int,
	responseTimeout time.Duration,
	metricsProvider metrics.Provider,
) *CertificationClient

func (*CertificationClient) IsCertified

func (cc *CertificationClient) IsCertified(ctx context.Context, id *token.ID) bool

func (*CertificationClient) OnReceive

func (cc *CertificationClient) OnReceive(event events.Event)

OnReceive handles a token-added event and enqueues the token for certification. It is non-blocking: if the input buffer is full, the token is dropped and counted.

func (*CertificationClient) RequestCertification

func (cc *CertificationClient) RequestCertification(ctx context.Context, ids ...*token.ID) error

func (*CertificationClient) Scan

func (cc *CertificationClient) Scan() error

Scan checks the vault for uncertified tokens and requests certification.

func (*CertificationClient) Start

func (cc *CertificationClient) Start()

Start launches the accumulator goroutine and the worker pool. It must be called before the client processes any tokens.

func (*CertificationClient) Stop

func (cc *CertificationClient) Stop()

Stop signals the client to shut down and waits for all goroutines to finish. In-flight certification requests are completed before returning.

type CertificationRequest

type CertificationRequest struct {
	Network, Channel, Namespace string
	IDs                         []*token.ID
	Request                     []byte
}

func (*CertificationRequest) String

func (cr *CertificationRequest) String() string

type CertificationRequestView

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

func NewCertificationRequestView

func NewCertificationRequestView(network, channel, ns string, certifier view.Identity, ids ...*token.ID) *CertificationRequestView

func (*CertificationRequestView) Call

func (i *CertificationRequestView) Call(context view.Context) (any, error)

type CertificationService

type CertificationService struct {
	ResponderRegistry ResponderRegistry
	// contains filtered or unexported fields
}

func NewCertificationService

func NewCertificationService(responderRegistry ResponderRegistry, mp metrics.Provider, backend Backend) *CertificationService

func (*CertificationService) Call

func (c *CertificationService) Call(context view.Context) (any, error)

func (*CertificationService) SetWallet

func (c *CertificationService) SetWallet(tms *token2.ManagementService, wallet string)

func (*CertificationService) Start

func (c *CertificationService) Start() error

Start registers the certification responder exactly once. It returns an error if the underlying registry call fails.

type CertificationStorage

type CertificationStorage interface {
	Exists(ctx context.Context, id *token.ID) bool
	Store(ctx context.Context, certifications map[*token.ID][]byte) error
}

type ChaincodeBackend

type ChaincodeBackend struct{}

func (*ChaincodeBackend) Load

func (c *ChaincodeBackend) Load(context view.Context, cr *CertificationRequest) ([][]byte, error)

type ClientMetrics

type ClientMetrics struct {
	// RequestDuration is a histogram of end-to-end certification batch durations.
	RequestDuration metrics.Histogram
	// Errors counts failed certification request attempts.
	Errors metrics.Counter
	// PendingTokens is a gauge tracking how many tokens are waiting in the input buffer.
	PendingTokens metrics.Gauge
	// DroppedTokens counts tokens dropped because the input buffer was full.
	DroppedTokens metrics.Counter
}

ClientMetrics holds the instrumentation for the CertificationClient (client side).

type Driver

type Driver struct {
	BackendFactory    BackendFactory
	Resolver          Resolver
	Subscriber        Subscriber
	ViewManager       ViewManager
	ResponderRegistry ResponderRegistry
	MetricsProvider   metrics.Provider

	Sync                 sync.Mutex
	CertificationClients map[string]*CertificationClient
	CertificationService *CertificationService
}

func NewDriver

func NewDriver(backendFactory BackendFactory, resolver Resolver, subscriber Subscriber, viewManager ViewManager, responderRegistry ResponderRegistry, metricsProvider metrics.Provider) *Driver

func (*Driver) NewCertificationClient

func (d *Driver) NewCertificationClient(ctx context.Context, tms *token.ManagementService) (driver.CertificationClient, error)

func (*Driver) NewCertificationService

func (d *Driver) NewCertificationService(tms *token.ManagementService, wallet string) (driver.CertificationService, error)

type Metrics

type Metrics struct {
	CertifiedTokens metrics.Counter
}

Metrics holds the instrumentation for the CertificationService (server side).

func NewMetrics

func NewMetrics(p metrics.Provider) *Metrics

type Op

type Op uint8
const (
	Add Op = iota
)

type QueryEngine

type QueryEngine interface {
	UnspentTokensIterator(ctx context.Context) (*token2.UnspentTokensIterator, error)
}

type Resolver

type Resolver interface {
	ResolveIdentities(endpoints ...string) ([]view.Identity, error)
}

type ResponderRegistry

type ResponderRegistry interface {
	RegisterResponder(responder view.View, initiatedBy any) error
}

type Subscriber

type Subscriber = events.Subscriber

type ViewManager

type ViewManager interface {
	InitiateView(view view.View) (any, error)
}

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