integrity

package
v1.1.1 Latest Latest
Warning

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

 Go to latest Published: Mar 6, 2026 License: BSD-2-Clause Imports: 20 Imported by: 3

Documentation

Overview

Package integrity provides typed storage with built-in data integrity protection. It automatically computes and verifies hashes and signatures for stored values.

See TypedBuilder for configuration options and Typed for available operations.

Index

Constants

View Source 
const ModRevisionEmpty = 0

ModRevisionEmpty is used to initialize the ModRevision field by default.

Variables

View Source 
var (
	ErrNotFound                  = errors.New("not found")
	ErrMoreThanOneResult         = errors.New("more than one result was returned")
	ErrInvalidPredicateValueType = errors.New("invalid predicate value type")
	ErrNoValueKey                = errors.New("no value key found in generated keys")
	// ErrPredicateFailed is returned by Put or Delete when predicates are specified
	// but the transaction predicate check fails (i.e., the conditions are not met).
	// Use [WithPutPredicates] or [WithDeletePredicates] to specify predicates.
	ErrPredicateFailed = errors.New("predicate check failed")
)
View Source 
var ErrInvalidName = InvalidNameError{/* contains filtered or unexported fields */}

ErrInvalidName is a sentinel error for invalid names.

Functions

func IgnoreMoreThanOneResult 

func IgnoreMoreThanOneResult() options.OptionCallback[getOptions]

IgnoreMoreThanOneResult returns an option that allows Get operation to succeed when multiple results are returned for a single name. By default, Get returns ErrMoreThanOneResult in such cases.

func IgnoreVerificationError 

func IgnoreVerificationError() options.OptionCallback[getOptions]

IgnoreVerificationError returns an option that allows Get and Range operations to return results even if hash or signature verification fails. The returned result will still contain the Error field with verification details.

func WithDeletePredicates added in v1.1.0 

func WithDeletePredicates(predicates ...Predicate) options.OptionCallback[deleteOptions]

WithDeletePredicates configures predicates for conditional Delete operations. The Delete operation will only succeed if all predicates evaluate to true. If predicates are specified but fail, ErrPredicateFailed is returned.

func WithPrefix added in v1.1.0 

func WithPrefix() options.OptionCallback[deleteOptions]

WithPrefix configures the ability to delete keys by a prefix.

func WithPutPredicates added in v1.1.0 

func WithPutPredicates(predicates ...Predicate) options.OptionCallback[putOptions]

WithPutPredicates configures predicates for conditional Put operations. The Put operation will only succeed if all predicates evaluate to true. If predicates are specified but fail, ErrPredicateFailed is returned.

Types

type FailedToComputeHashError 

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

FailedToComputeHashError represents an error when hash computation fails.

func (FailedToComputeHashError) Error 

func (e FailedToComputeHashError) Error() string

Error returns a string representation of the hash computation error.

func (FailedToComputeHashError) Unwrap 

func (e FailedToComputeHashError) Unwrap() error

Unwrap returns the underlying error that caused the hash computation failure.

type FailedToGenerateKeysError 

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

FailedToGenerateKeysError represents an error when key generation fails.

func (FailedToGenerateKeysError) Error 

func (e FailedToGenerateKeysError) Error() string

Error returns a string representation of the key generation error.

func (FailedToGenerateKeysError) Unwrap 

func (e FailedToGenerateKeysError) Unwrap() error

Unwrap returns the underlying error that caused the key generation failure.

type FailedToGenerateSignatureError 

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

FailedToGenerateSignatureError represents an error when signature generation fails.

func (FailedToGenerateSignatureError) Error 

func (e FailedToGenerateSignatureError) Error() string

Error returns a string representation of the signature generation error.

func (FailedToGenerateSignatureError) Unwrap 

func (e FailedToGenerateSignatureError) Unwrap() error

Unwrap returns the underlying error that caused the signature generation failure.

type FailedToMarshalValueError 

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

FailedToMarshalValueError represents an error when value marshalling fails.

func (FailedToMarshalValueError) Error 

func (e FailedToMarshalValueError) Error() string

Error returns a string representation of the marshalling error.

func (FailedToMarshalValueError) Unwrap 

func (e FailedToMarshalValueError) Unwrap() error

Unwrap returns the underlying error that caused the marshalling failure.

type FailedToValidateAggregatedError 

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

FailedToValidateAggregatedError represents aggregated validation errors.

func (*FailedToValidateAggregatedError) Append 

func (e *FailedToValidateAggregatedError) Append(err error)

Append adds an error to the aggregated error.

func (*FailedToValidateAggregatedError) Error 

func (e *FailedToValidateAggregatedError) Error() string

Error returns a string representation of the aggregated error.

func (*FailedToValidateAggregatedError) Finalize 

func (e *FailedToValidateAggregatedError) Finalize() error

Finalize returns nil if there are no errors, otherwise returns error or the aggregated error.

func (*FailedToValidateAggregatedError) Unwrap 

func (e *FailedToValidateAggregatedError) Unwrap() []error

Unwrap returns the underlying slice of errors.

type Generator 

type Generator[T any] struct {
	// contains filtered or unexported fields
}

Generator creates integrity-protected key-value pairs for storage.

func NewGenerator 

func NewGenerator[T any](
	namer namer.Namer,
	marshaller marshaller.TypedMarshaller[T],
	hashers []hasher.Hasher,
	signers []crypto.Signer,
) Generator[T]

NewGenerator creates a new Generator instance.

func (Generator[T]) Generate 

func (g Generator[T]) Generate(name string, value T) ([]kv.KeyValue, error)

Generate creates integrity-protected key-value pairs for the given object.

type ImpossibleError 

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

ImpossibleError represents an error when an integrity operation cannot be performed due to internal problems.

func (ImpossibleError) Error 

func (e ImpossibleError) Error() string

type InvalidNameError 

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

InvalidNameError represents an error when a name is invalid.

func (InvalidNameError) Error 

func (e InvalidNameError) Error() string

Error returns a string representation of the invalid name error.

type NamerConstructor 

type NamerConstructor func(prefix string, hashNames []string, sigNames []string) namer.Namer

type Predicate added in v1.1.0 

type Predicate func(key []byte) predicate.Predicate

type Typed 

type Typed[T any] struct {
	// contains filtered or unexported fields
}

Typed provides integrity-protected storage operations for typed values.

func (*Typed[T]) Delete 

func (t *Typed[T]) Delete(ctx context.Context, name string, vOpts ...options.OptionCallback[deleteOptions]) error

Delete removes a named value with integrity protection. Use WithPrefix to delete all values under a prefix. Use WithDeletePredicates to specify conditions that must be met for the operation to succeed. If predicates are specified but fail, ErrPredicateFailed is returned.

func (*Typed[T]) Get 

func (t *Typed[T]) Get(
	ctx context.Context,
	name string,
	vOpts ...options.OptionCallback[getOptions],
) (ValidatedResult[T], error)

Get retrieves and validates a single named value from storage.

func (*Typed[T]) Put 

func (t *Typed[T]) Put(ctx context.Context, name string, val T, vOpts ...options.OptionCallback[putOptions]) error

Put stores a named value with integrity protection. Use WithPutPredicates to specify conditions that must be met for the operation to succeed. If predicates are specified but fail, ErrPredicateFailed is returned.

func (*Typed[T]) Range 

func (t *Typed[T]) Range(
	ctx context.Context,
	name string,
	vOpts ...options.OptionCallback[getOptions],
) ([]ValidatedResult[T], error)

Range retrieves and validates all values under the given name prefix.

func (*Typed[T]) ValueEqual added in v1.1.0 

func (t *Typed[T]) ValueEqual(value T) (Predicate, error)

ValueEqual creates a predicate that checks if a key's value equals the specified value.

func (*Typed[T]) ValueNotEqual added in v1.1.0 

func (t *Typed[T]) ValueNotEqual(value T) (Predicate, error)

ValueNotEqual creates a predicate that checks if a key's value is not equal to the specified value.

func (*Typed[T]) VersionEqual added in v1.1.0 

func (t *Typed[T]) VersionEqual(value int64) Predicate

VersionEqual creates a predicate that checks if a key's version equals the specified version.

func (*Typed[T]) VersionGreater added in v1.1.0 

func (t *Typed[T]) VersionGreater(value int64) Predicate

VersionGreater creates a predicate that checks if a key's version is greater than the specified version.

func (*Typed[T]) VersionLess added in v1.1.0 

func (t *Typed[T]) VersionLess(value int64) Predicate

VersionLess creates a predicate that checks if a key's version is less than the specified version.

func (*Typed[T]) VersionNotEqual added in v1.1.0 

func (t *Typed[T]) VersionNotEqual(value int64) Predicate

VersionNotEqual creates a predicate that checks if a key's version is not equal to the specified version.

func (*Typed[T]) Watch 

func (t *Typed[T]) Watch(ctx context.Context, name string) (<-chan watch.Event, error)

Watch returns a channel for watching changes to values under the given name prefix.

type TypedBuilder 

type TypedBuilder[T any] struct {
	// contains filtered or unexported fields
}

TypedBuilder builds typed storage instances with integrity protection.

func NewTypedBuilder 

func NewTypedBuilder[T any](storageInstance storage.Storage) TypedBuilder[T]

NewTypedBuilder creates a new TypedBuilder for the given storage instance.

func (TypedBuilder[T]) Build 

func (s TypedBuilder[T]) Build() *Typed[T]

Build creates a new Typed storage instance with the configured options.

func (TypedBuilder[T]) WithHasher 

func (s TypedBuilder[T]) WithHasher(h hasher.Hasher) TypedBuilder[T]

WithHasher adds a hasher to the builder.

func (TypedBuilder[T]) WithMarshaller 

func (s TypedBuilder[T]) WithMarshaller(marshaller marshaller.TypedMarshaller[T]) TypedBuilder[T]

WithMarshaller sets the marshaller for the builder.

func (TypedBuilder[T]) WithNamer 

func (s TypedBuilder[T]) WithNamer(namerFunc NamerConstructor) TypedBuilder[T]

WithNamer sets the namer for the builder using a constructor function. The constructor function will be called during Build() with the current prefix.

func (TypedBuilder[T]) WithPrefix 

func (s TypedBuilder[T]) WithPrefix(prefix string) TypedBuilder[T]

WithPrefix sets the key prefix for the builder.

func (TypedBuilder[T]) WithSigner 

func (s TypedBuilder[T]) WithSigner(signer crypto.Signer) TypedBuilder[T]

WithSigner adds a signer to the builder.

func (TypedBuilder[T]) WithSignerVerifier 

func (s TypedBuilder[T]) WithSignerVerifier(sv crypto.SignerVerifier) TypedBuilder[T]

WithSignerVerifier adds a signer/verifier to the builder.

func (TypedBuilder[T]) WithVerifier 

func (s TypedBuilder[T]) WithVerifier(verifier crypto.Verifier) TypedBuilder[T]

WithVerifier adds a verifier to the builder.

type ValidatedResult 

type ValidatedResult[T any] struct {
	// Name is the object identifier under which the value was stored.
	Name string
	// Value contains the unmarshalled value if decoding succeeded.
	Value option.Generic[T]
	// ModRevision is the storage revision when this value was last modified.
	ModRevision int64
	// Error contains validation errors if integrity verification failed.
	Error error
}

ValidatedResult represents a validated named value.

type ValidationError 

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

ValidationError represents an error when validation fails.

func (ValidationError) Error 

func (e ValidationError) Error() string

Error returns a string representation of the validation error.

func (ValidationError) Unpack 

func (e ValidationError) Unpack() error

type Validator 

type Validator[T any] struct {
	// contains filtered or unexported fields
}

Validator verifies integrity-protected key-value pairs.

func NewValidator 

func NewValidator[T any](
	namer namer.Namer,
	marshaller marshaller.TypedMarshaller[T],
	hashers []hasher.Hasher,
	verifiers []crypto.Verifier,
) Validator[T]

NewValidator creates a new Validator instance.

func (Validator[T]) Validate 

func (v Validator[T]) Validate(kvs []kv.KeyValue) ([]ValidatedResult[T], error)

Validate verifies integrity-protected key-value pairs and returns the validated value.

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.