taggedrlp

README

taggedrlp

Package taggedrlp adds support for tagged alternative types with legacy fallback.

Documentation

Overview

Package taggedrlp adds support for tagged alternative types with legacy fallback support.

A tagged item is encoded and decoded as a signature-tag-value tuple, except an item of the “legacy” type – which has the empty tag – is encoded verbatim without the sig-tag-value envelope. Legacy type support makes it possible to use this package as a drop-in replacement for a non-tagged type.

Index

• Constants
• func PkgPathQualifiedName(name, pkgPath string) string
• func PkgPathQualifiedTypeName(typ reflect.Type) string
• func TypeName(typ reflect.Type) string
• type Envelope
• type Factory
• type InvalidFactoryReturnType
  • func (e InvalidFactoryReturnType) Error() string
• type Registry
  • func NewRegistry() *Registry
  • func (reg *Registry) AddFactory(factory Factory) error
  • func (reg *Registry) Decode(s *rlp.Stream) (interface{}, error)
  • func (reg *Registry) Encode(w io.Writer, d interface{}) error
  • func (reg *Registry) MustAddFactory(factory Factory)
  • func (reg *Registry) MustRegister(tag Tag, prototype interface{})
  • func (reg *Registry) Register(tag Tag, prototype interface{}) error
• type Tag
• type TagAlreadyBoundToType
  • func (e TagAlreadyBoundToType) Error() string
• type TypeAlreadyBoundToTag
  • func (e TypeAlreadyBoundToTag) Error() string
• type TypeAlreadyHasFactory
  • func (e TypeAlreadyHasFactory) Error() string
• type TypeNotRegistered
  • func (e TypeNotRegistered) Error() string
• type UnencodableValue
  • func (e UnencodableValue) Cause() error
  • func (e UnencodableValue) Error() string
• type UnsupportedTag
  • func (e UnsupportedTag) Error() string

Constants

const EnvelopeSignature = "HmnyTgd"

EnvelopeSignature is the first item in a tagged envelope.

Functions

func PkgPathQualifiedName

func PkgPathQualifiedName(name, pkgPath string) string

PkgPathQualifiedName returns a package-path-qualified name. If the package path is empty, it returns just the name; otherwise, it returns a qualified name such as "math/big".Int.

func PkgPathQualifiedTypeName

func PkgPathQualifiedTypeName(typ reflect.Type) string

PkgPathQualifiedTypeName returns a package-path-qualified name of the given type, or an empty string if the type name is not available, e.g. internal or unexported type.

func TypeName

func TypeName(typ reflect.Type) string

TypeName returns a package-path-qualified name of the given type, or a package-name-qualified name if the package path is not available through reflection.

Types

type Envelope

type Envelope struct {
	Sig string
	Tag Tag
	Raw rlp.RawValue
}

Envelope is the tagged envelope type.

type Factory

type Factory = func() interface{}

Factory is a new-instance factory function. A factory is associated with a particular tagged type, and returns a new instance of the type, ready to be filled by RLP decoder. For example, a struct type with a *big.Int pointer field needs a factory to return a new instance with the pointer allocated as the RLP decoder expects the field not to be nil but to point to a valid *big.Int object.

type InvalidFactoryReturnType

type InvalidFactoryReturnType struct {
	Type reflect.Type
}

InvalidFactoryReturnType indicates that the given factory does not return a pointer type.

func (InvalidFactoryReturnType) Error

func (e InvalidFactoryReturnType) Error() string

Error returns a formatted error string.

type Registry

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

Registry maintains a tag-to-type mapping. Tagged alternative types that can be interchangeably used should be registered within the same registry.

func NewRegistry

func NewRegistry() *Registry

NewRegistry creates a new registry.

func (*Registry) AddFactory

func (reg *Registry) AddFactory(factory Factory) error

AddFactory adds the given custom factory function. By default, when an instance of a tagged type is needed when decoding, the decoded calls the new() function with the type to create a zero-valued instance. Sometimes, a zero-valued instance is inadequate, e.g. when the type contains a big.Int field. A custom factory function addresses this limitation by returning a suitably initialized instance ready to be filled in by the RLP decoder.

AddFactory exercises the given factory once to figure out the return value type with which to associate the factory. The returned value must be a pointer to a registered type.

func (*Registry) Decode

func (reg *Registry) Decode(s *rlp.Stream) (interface{}, error)

Decode decodes the given value.

func (*Registry) Encode

func (reg *Registry) Encode(w io.Writer, d interface{}) error

Encode encodes the given value.

func (*Registry) MustAddFactory

func (reg *Registry) MustAddFactory(factory Factory)

MustAddFactory is like AddFactory, but panics on error. Use only in init().

func (*Registry) MustRegister

func (reg *Registry) MustRegister(tag Tag, prototype interface{})

MustRegister is like Register, but panics on error. Use only in init().

func (*Registry) Register

func (reg *Registry) Register(tag Tag, prototype interface{}) error

Register adds a new tagged type to the registry. The type is specified by a prototype value of that type. Its value does not matter, so one can simply pass in a zero value of the right type.

Registering the same tag-type pair is an idempotent operation. However, it is an error to attempt to add the same type under multiple tags, or to add another type for the same tag.

type Tag

type Tag string

Tag is a string used to distinguish alternative types.

const LegacyTag Tag = ""

LegacyTag is a special type tag used to denote legacy type which should be encoded/decoded without envelope.

type TagAlreadyBoundToType

type TagAlreadyBoundToType struct {
	Tag  Tag
	Type reflect.Type
}

TagAlreadyBoundToType indicates that a tag is already bound to a type and cannot be rebound to another type.

func (TagAlreadyBoundToType) Error

func (e TagAlreadyBoundToType) Error() string

Error returns a formatted error string.

type TypeAlreadyBoundToTag

type TypeAlreadyBoundToTag struct {
	Type reflect.Type
	Tag  Tag
}

TypeAlreadyBoundToTag indicates that a type is already bound to a tag and cannot be rebound to another tag.

func (TypeAlreadyBoundToTag) Error

func (e TypeAlreadyBoundToTag) Error() string

Error returns a formatted error string.

type TypeAlreadyHasFactory

type TypeAlreadyHasFactory struct {
	Type reflect.Type
}

TypeAlreadyHasFactory indicates that the given type already has a factory.

func (TypeAlreadyHasFactory) Error

func (e TypeAlreadyHasFactory) Error() string

Error returns a formatted error string.

type TypeNotRegistered

type TypeNotRegistered struct {
	Type reflect.Type
}

TypeNotRegistered indicates that the given type is not registered.

func (TypeNotRegistered) Error

func (e TypeNotRegistered) Error() string

Error returns a formatted error string.

type UnencodableValue

type UnencodableValue struct {
	Value interface{}
	Err   error
}

UnencodableValue indicates that the given value cannot be RLP-encoded.

func (UnencodableValue) Cause

func (e UnencodableValue) Cause() error

Cause returns the underlying encoding error.

func (UnencodableValue) Error

func (e UnencodableValue) Error() string

Error returns a formatted error string.

type UnsupportedTag

type UnsupportedTag struct {
	Tag Tag
}

UnsupportedTag indicates that an unsupported tag was encountered in stream.

func (UnsupportedTag) Error

func (e UnsupportedTag) Error() string

Error returns a formatted error string.