patch

Documentation

Overview

Package patch provides a way to patch the contents of a shop. This is a modified version of JSON Patch (rfc6902). We first constraint the operations to "add", "replace", "remove" and then we add the following operations

https://datatracker.ietf.org/doc/html/rfc6902/

Index

• func NextPowerOf2(n uint64) uint64
• func RootHash(patches []Patch) (objects.Hash, massmmr.VerifierTree, error)
• type IndexOutOfBoundsError
  • func (e IndexOutOfBoundsError) Error() string
• type ObjectNotFoundError
  • func (e ObjectNotFoundError) Error() string
• type ObjectType
  • func (obj ObjectType) IsValid() bool
  • func (obj *ObjectType) UnmarshalCBOR(data []byte) error
• type OpString
• type OutOfStockError
  • func (e OutOfStockError) Error() string
• type Patch
• type Patcher
  • func NewPatcher(v *validator.Validate, shop *objects.Shop) *Patcher
  • func (p *Patcher) ApplyPatch(patch Patch) error
• type Path
  • func (p Path) MarshalCBOR() ([]byte, error)
  • func (p *Path) UnmarshalCBOR(data []byte) error
• type SetHeader
• type SignedPatchSet

Functions

func NextPowerOf2

func NextPowerOf2(n uint64) uint64

NextPowerOf2 calculates the smallest power of 2 that is greater than or equal to n. It works by:

• n--: First decrements n by 1. This is done to handle the case where n is already a power of 2.
• The series of bit-shifting operations (|= with right shifts): This sequence "fills" all the bits to the right of the highest set bit with 1s. For example: If n = 00100000, after these operations it becomes 00111111
• n++: Finally increments n by 1, which gives us the next power of 2.

Here's a concrete example: Start with n = 33 (00100001 in binary) After n--, n = 32 (00100000) After bit-shifting operations, n = 00111111 After n++, n = 01000000 (64 in decimal)

func RootHash

func RootHash(patches []Patch) (objects.Hash, massmmr.VerifierTree, error)

RootHash computes the root hash of a list of patches. It returns the root hash, the MMR tree, and an error if one occurs.

Types

type IndexOutOfBoundsError

type IndexOutOfBoundsError struct {
	Index    int
	MaxIndex int
}

IndexOutOfBoundsError is an error that occurs when an index is out of bounds

func (IndexOutOfBoundsError) Error

func (e IndexOutOfBoundsError) Error() string

type ObjectNotFoundError

type ObjectNotFoundError struct {
	ObjectType ObjectType
	Path       Path
}

ObjectNotFoundError is an error that occurs when an object is not found

func (ObjectNotFoundError) Error

func (e ObjectNotFoundError) Error() string

type ObjectType

type ObjectType string

ObjectType is the type of the object TODO: could change to number instead of string..?

const (
	ObjectTypeSchemaVersion ObjectType = "SchemaVersion"
	ObjectTypeManifest      ObjectType = "Manifest"
	ObjectTypeAccount       ObjectType = "Accounts"
	ObjectTypeListing       ObjectType = "Listings"
	ObjectTypeOrder         ObjectType = "Orders"
	ObjectTypeTag           ObjectType = "Tags"
	ObjectTypeInventory     ObjectType = "Inventory"
)

Constants for the object types

func (ObjectType) IsValid

func (obj ObjectType) IsValid() bool

IsValid checks if an object type is valid

func (*ObjectType) UnmarshalCBOR

func (obj *ObjectType) UnmarshalCBOR(data []byte) error

UnmarshalCBOR deserializes an object type

type OpString

type OpString string

OpString is a string representation of an operation TODO: type change to enum/number instead of string?

const (
	AddOp       OpString = "add"
	ReplaceOp   OpString = "replace"
	RemoveOp    OpString = "remove"
	AppendOp    OpString = "append"
	IncrementOp OpString = "increment"
	DecrementOp OpString = "decrement"
)

Definitions of the operation types

type OutOfStockError

type OutOfStockError struct {
	ListingID  objects.ObjectID
	Variations []string
}

OutOfStockError is an error that occurs when an inventory is out of stock

func (OutOfStockError) Error

func (e OutOfStockError) Error() string

Error returns a string representation of the error

type Patch

type Patch struct {
	Op    OpString        `validate:"required,oneof=add append replace remove increment decrement"`
	Path  Path            `validate:"required"`
	Value cbor.RawMessage `validate:"required,gt=0"`
}

Patch is a single patch

type Patcher

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

Patcher is a type that applies patches to a shop

func NewPatcher

func NewPatcher(v *validator.Validate, shop *objects.Shop) *Patcher

NewPatcher creates a new Patcher

func (*Patcher) ApplyPatch

func (p *Patcher) ApplyPatch(patch Patch) error

ApplyPatch applies a patch to the shop

type Path

type Path struct {
	Type ObjectType `validate:"required,notblank"`

	ObjectID    *objects.ObjectID
	AccountAddr *objects.EthereumAddress
	TagName     *string

	Fields []any // extra fields
}

Path encodes as an opaque array of [type, id, fields...] This utility helps getting type and id in the expected types for Go.

Type dictates which ID fields need to be set:

account: EthereumAddress tag: TagName listing: ObjectId order: ObjectId inventory: ObjectId with optional variations as fields

exclusion: manifest, which has no id

func (Path) MarshalCBOR

func (p Path) MarshalCBOR() ([]byte, error)

MarshalCBOR serializes a path

func (*Path) UnmarshalCBOR

func (p *Path) UnmarshalCBOR(data []byte) error

UnmarshalCBOR deserializes a path

type SetHeader

type SetHeader struct {
	// The nonce must be unique for each event a keycard creates.
	// The sequence values need to increase monotonicly.
	KeyCardNonce uint64 `validate:"required,gt=0"`

	// Every signed event must be tied to a shop id. This allows the
	// event to be processed outside the context of the current connection.
	ShopID objects.Uint256 `validate:"required"`

	// The time when this event was created.
	// The relay should reject any events from the future
	Timestamp time.Time `validate:"required"`

	// The merkle root of the patches
	RootHash objects.Hash `validate:"required"`
}

SetHeader is the header of a patch set

type SignedPatchSet

type SignedPatchSet struct {
	// The header of the patch set
	Header SetHeader `validate:"required"` // TODO: dive doesn't work?

	// The signature of the header, containing the merkle root of the patches
	Signature objects.Signature `validate:"required,gt=0,dive"`

	Patches []Patch `validate:"required,gt=0,dive"`
}

SignedPatchSet is a signed set of patches To validate a patchset, construct the merkle tree of the patches and validate the root hash.