Documentation ¶
Index ¶
- Constants
- Variables
- func DBigSize(r io.Reader, val interface{}, buf *[8]byte, l uint64) error
- func DBool(r io.Reader, val interface{}, buf *[8]byte, l uint64) error
- func DBytes32(r io.Reader, val interface{}, _ *[8]byte, l uint64) error
- func DBytes33(r io.Reader, val interface{}, _ *[8]byte, l uint64) error
- func DBytes64(r io.Reader, val interface{}, _ *[8]byte, l uint64) error
- func DNOP(io.Reader, interface{}, *[8]byte, uint64) error
- func DPubKey(r io.Reader, val interface{}, _ *[8]byte, l uint64) error
- func DTUint16(r io.Reader, val interface{}, buf *[8]byte, l uint64) error
- func DTUint32(r io.Reader, val interface{}, buf *[8]byte, l uint64) error
- func DTUint64(r io.Reader, val interface{}, buf *[8]byte, l uint64) error
- func DUint16(r io.Reader, val interface{}, buf *[8]byte, l uint64) error
- func DUint32(r io.Reader, val interface{}, buf *[8]byte, l uint64) error
- func DUint64(r io.Reader, val interface{}, buf *[8]byte, l uint64) error
- func DUint8(r io.Reader, val interface{}, buf *[8]byte, l uint64) error
- func DVarBytes(r io.Reader, val interface{}, _ *[8]byte, l uint64) error
- func EBigSize(w io.Writer, val interface{}, buf *[8]byte) error
- func EBool(w io.Writer, val interface{}, buf *[8]byte) error
- func EBoolT(w io.Writer, val bool, buf *[8]byte) error
- func EBytes32(w io.Writer, val interface{}, _ *[8]byte) error
- func EBytes33(w io.Writer, val interface{}, _ *[8]byte) error
- func EBytes64(w io.Writer, val interface{}, _ *[8]byte) error
- func ENOP(io.Writer, interface{}, *[8]byte) error
- func EPubKey(w io.Writer, val interface{}, _ *[8]byte) error
- func ETUint16(w io.Writer, val interface{}, buf *[8]byte) error
- func ETUint16T(w io.Writer, val uint16, buf *[8]byte) error
- func ETUint32(w io.Writer, val interface{}, buf *[8]byte) error
- func ETUint32T(w io.Writer, val uint32, buf *[8]byte) error
- func ETUint64(w io.Writer, val interface{}, buf *[8]byte) error
- func ETUint64T(w io.Writer, val uint64, buf *[8]byte) error
- func EUint16(w io.Writer, val interface{}, buf *[8]byte) error
- func EUint16T(w io.Writer, val uint16, buf *[8]byte) error
- func EUint32(w io.Writer, val interface{}, buf *[8]byte) error
- func EUint32T(w io.Writer, val uint32, buf *[8]byte) error
- func EUint64(w io.Writer, val interface{}, buf *[8]byte) error
- func EUint64T(w io.Writer, val uint64, buf *[8]byte) error
- func EUint8(w io.Writer, val interface{}, buf *[8]byte) error
- func EUint8T(w io.Writer, val uint8, buf *[8]byte) error
- func EVarBytes(w io.Writer, val interface{}, _ *[8]byte) error
- func ReadVarInt(r io.Reader, buf *[8]byte) (uint64, error)
- func RecordsToMap(records []Record) (map[uint64][]byte, error)
- func SizeTUint16(v uint16) uint64
- func SizeTUint32(v uint32) uint64
- func SizeTUint64(v uint64) uint64
- func SortRecords(records []Record)
- func VarIntSize(val uint64) uint64
- func WriteVarInt(w io.Writer, val uint64, buf *[8]byte) error
- type Decoder
- type Encoder
- type ErrTypeForDecoding
- type ErrTypeForEncoding
- type OptionalRecordT
- type Primitive
- type Record
- func MakeBigSizeRecord(typ Type, val interface{}) Record
- func MakeDynamicRecord(typ Type, val interface{}, sizeFunc SizeFunc, encoder Encoder, decoder Decoder) Record
- func MakePrimitiveRecord(typ Type, val interface{}) Record
- func MakeStaticRecord(typ Type, val interface{}, size uint64, encoder Encoder, decoder Decoder) Record
- func MapToRecords(tlvMap map[uint64][]byte) []Record
- type RecordProducer
- type RecordProducerT
- type RecordT
- type SizeFunc
- type Stream
- type TlvType
- type TlvType0
- type TlvType1
- type TlvType10
- type TlvType100
- type TlvType11
- type TlvType12
- type TlvType13
- type TlvType14
- type TlvType15
- type TlvType16
- type TlvType17
- type TlvType18
- type TlvType19
- type TlvType2
- type TlvType20
- type TlvType21
- type TlvType22
- type TlvType23
- type TlvType24
- type TlvType25
- type TlvType26
- type TlvType27
- type TlvType28
- type TlvType29
- type TlvType3
- type TlvType30
- type TlvType31
- type TlvType32
- type TlvType33
- type TlvType34
- type TlvType35
- type TlvType36
- type TlvType37
- type TlvType38
- type TlvType39
- type TlvType4
- type TlvType40
- type TlvType41
- type TlvType42
- type TlvType43
- type TlvType44
- type TlvType45
- type TlvType46
- type TlvType47
- type TlvType48
- type TlvType49
- type TlvType5
- type TlvType50
- type TlvType51
- type TlvType52
- type TlvType53
- type TlvType54
- type TlvType55
- type TlvType56
- type TlvType57
- type TlvType58
- type TlvType59
- type TlvType6
- type TlvType60
- type TlvType61
- type TlvType62
- type TlvType63
- type TlvType64
- type TlvType65
- type TlvType66
- type TlvType67
- type TlvType68
- type TlvType69
- type TlvType7
- type TlvType70
- type TlvType71
- type TlvType72
- type TlvType73
- type TlvType74
- type TlvType75
- type TlvType76
- type TlvType77
- type TlvType78
- type TlvType79
- type TlvType8
- type TlvType80
- type TlvType81
- type TlvType82
- type TlvType83
- type TlvType84
- type TlvType85
- type TlvType86
- type TlvType87
- type TlvType88
- type TlvType89
- type TlvType9
- type TlvType90
- type TlvType91
- type TlvType92
- type TlvType93
- type TlvType94
- type TlvType95
- type TlvType96
- type TlvType97
- type TlvType98
- type TlvType99
- type Type
- type TypeMap
Constants ¶
const MaxRecordSize = 65535 // 65KB
MaxRecordSize is the maximum size of a particular record that will be parsed by a stream decoder. This value is currently chosen to the be equal to the maximum message size permitted by BOLT 1, as no record should be bigger than an entire message.
Variables ¶
var ErrRecordTooLarge = errors.New("record is too large")
ErrRecordTooLarge signals that a decoded record has a length that is too long to parse.
var ErrStreamNotCanonical = errors.New("tlv stream is not canonical")
ErrStreamNotCanonical signals that a decoded stream does not contain records sorting by monotonically-increasing type.
var ErrTUintNotMinimal = errors.New("truncated uint not minimally encoded")
ErrTUintNotMinimal signals that decoding a truncated uint failed because the value was not minimally encoded.
var ErrVarIntNotCanonical = errors.New("decoded varint is not canonical")
ErrVarIntNotCanonical signals that the decoded varint was not minimally encoded.
Functions ¶
func DBigSize ¶ added in v1.0.3
DBigSize decodes an uint32 or an uint64 using BigSize format. An error is returned if val is not either *uint32 or *uint64.
func DBytes32 ¶
DBytes32 is a Decoder for 32-byte arrays. An error is returned if val is not a *[32]byte.
func DBytes33 ¶
DBytes33 is a Decoder for 33-byte arrays. An error is returned if val is not a *[33]byte.
func DBytes64 ¶
DBytes64 is an Decoder for 64-byte arrays. An error is returned if val is not a *[64]byte.
func DPubKey ¶
DPubKey is a Decoder for *btcec.PublicKey values. An error is returned if val is not a **btcec.PublicKey.
func DTUint16 ¶
DTUint16 is an Decoder for truncated uint16 values, where leading zeros will be resurrected. An error is returned if val is not a *uint16.
func DTUint32 ¶
DTUint32 is an Decoder for truncated uint32 values, where leading zeros will be resurrected. An error is returned if val is not a *uint32.
func DTUint64 ¶
DTUint64 is an Decoder for truncated uint64 values, where leading zeros will be resurrected. An error is returned if val is not a *uint64.
func DUint16 ¶
DUint16 is a Decoder for uint16 values. An error is returned if val is not a *uint16.
func DUint32 ¶
DUint32 is a Decoder for uint32 values. An error is returned if val is not a *uint32.
func DUint64 ¶
DUint64 is a Decoder for uint64 values. An error is returned if val is not a *uint64.
func DVarBytes ¶
DVarBytes is a Decoder for variable byte slices. An error is returned if val is not *[]byte.
func EBigSize ¶ added in v1.0.3
EBigSize encodes an uint32 or an uint64 using BigSize format. An error is returned if val is not either *uint32 or *uint64.
func EBoolT ¶ added in v1.1.2
EBoolT encodes a bool val to the provided io.Writer. This method is exposed so that encodings for custom bool-like types can be created without incurring an extra heap allocation.
func EBytes32 ¶
EBytes32 is an Encoder for 32-byte arrays. An error is returned if val is not a *[32]byte.
func EBytes33 ¶
EBytes33 is an Encoder for 33-byte arrays. An error is returned if val is not a *[33]byte.
func EBytes64 ¶
EBytes64 is an Encoder for 64-byte arrays. An error is returned if val is not a *[64]byte.
func EPubKey ¶
EPubKey is an Encoder for *btcec.PublicKey values. An error is returned if val is not a **btcec.PublicKey.
func ETUint16 ¶
ETUint16 is an Encoder for truncated uint16 values, where leading zeros will be omitted. An error is returned if val is not a *uint16.
func ETUint16T ¶ added in v1.0.1
ETUint16T is an Encoder for truncated uint16 values, where leading zeros will be omitted. An error is returned if val is not a *uint16.
func ETUint32 ¶
ETUint32 is an Encoder for truncated uint32 values, where leading zeros will be omitted. An error is returned if val is not a *uint32.
func ETUint32T ¶ added in v1.0.1
ETUint32T is an Encoder for truncated uint32 values, where leading zeros will be omitted. An error is returned if val is not a *uint32.
func ETUint64 ¶
ETUint64 is an Encoder for truncated uint64 values, where leading zeros will be omitted. An error is returned if val is not a *uint64.
func ETUint64T ¶ added in v1.0.1
ETUint64T is an Encoder for truncated uint64 values, where leading zeros will be omitted. An error is returned if val is not a *uint64.
func EUint16 ¶
EUint16 is an Encoder for uint16 values. An error is returned if val is not a *uint16.
func EUint16T ¶
EUint16T encodes a uint16 val to the provided io.Writer. This method is exposed so that encodings for custom uint16-like types can be created without incurring an extra heap allocation.
func EUint32 ¶
EUint32 is an Encoder for uint32 values. An error is returned if val is not a *uint32.
func EUint32T ¶
EUint32T encodes a uint32 val to the provided io.Writer. This method is exposed so that encodings for custom uint32-like types can be created without incurring an extra heap allocation.
func EUint64 ¶
EUint64 is an Encoder for uint64 values. An error is returned if val is not a *uint64.
func EUint64T ¶
EUint64T encodes a uint64 val to the provided io.Writer. This method is exposed so that encodings for custom uint64-like types can be created without incurring an extra heap allocation.
func EUint8T ¶
EUint8T encodes a uint8 val to the provided io.Writer. This method is exposed so that encodings for custom uint8-like types can be created without incurring an extra heap allocation.
func EVarBytes ¶
EVarBytes is an Encoder for variable byte slices. An error is returned if val is not *[]byte.
func ReadVarInt ¶
ReadVarInt reads a variable length integer from r and returns it as a uint64.
func RecordsToMap ¶
RecordsToMap encodes a series of TLV records as raw key-value pairs in the form of a map.
func SizeTUint16 ¶
SizeTUint16 returns the number of bytes remaining in a uint16 after truncating the leading zeros.
func SizeTUint32 ¶
SizeTUint32 returns the number of bytes remaining in a uint32 after truncating the leading zeros.
func SizeTUint64 ¶
SizeTUint64 returns the number of bytes remaining in a uint64 after truncating the leading zeros.
func SortRecords ¶
func SortRecords(records []Record)
SortRecords is a helper function that will sort a slice of records in place according to their type.
func VarIntSize ¶ added in v1.0.1
VarIntSize returns the required number of bytes to encode a var int.
Types ¶
type Decoder ¶
Decoder is a signature for methods that can decode TLV values. An error should be returned if the Decoder cannot support the underlying type of val. The provided scratch buffer must be non-nil.
type Encoder ¶
Encoder is a signature for methods that can encode TLV values. An error should be returned if the Encoder cannot support the underlying type of val. The provided scratch buffer must be non-nil.
func StubEncoder ¶
StubEncoder is a factory function that makes a stub tlv.Encoder out of a raw value. We can use this to make a record that can be encoded when we don't actually know it's true underlying value, and only it serialization.
type ErrTypeForDecoding ¶
type ErrTypeForDecoding struct {
// contains filtered or unexported fields
}
ErrTypeForDecoding signals that an incorrect type was passed to a Decoder or that the expected length of the encoding is different from that required by the expected type.
func NewTypeForDecodingErr ¶
func NewTypeForDecodingErr(val interface{}, expType string, valLength, expLength uint64) ErrTypeForDecoding
NewTypeForDecodingErr creates a new ErrTypeForDecoding given the incorrect val and expected type, or the mismatch in their expected lengths.
func (ErrTypeForDecoding) Error ¶
func (e ErrTypeForDecoding) Error() string
Error returns a human-readable description of the type mismatch.
type ErrTypeForEncoding ¶
type ErrTypeForEncoding struct {
// contains filtered or unexported fields
}
ErrTypeForEncoding signals that an incorrect type was passed to an Encoder.
func NewTypeForEncodingErr ¶
func NewTypeForEncodingErr(val interface{}, expType string) ErrTypeForEncoding
NewTypeForEncodingErr creates a new ErrTypeForEncoding given the incorrect val and the expected type.
func (ErrTypeForEncoding) Error ¶
func (e ErrTypeForEncoding) Error() string
Error returns a human-readable description of the type mismatch.
type OptionalRecordT ¶ added in v1.2.0
OptionalRecordT is a high-order type that represents an optional TLV record. This can be used when a TLV record doesn't always need to be present (ok to be odd).
func SomeRecordT ¶ added in v1.2.1
func SomeRecordT[T TlvType, V any](record RecordT[T, V]) OptionalRecordT[T, V]
SomeRecordT creates a new OptionalRecordT type from a given RecordT type.
func (*OptionalRecordT[T, V]) TlvType ¶ added in v1.2.1
func (t *OptionalRecordT[T, V]) TlvType() Type
TlvType returns the type of the record. This is the value used to identify this type on the wire. This value is bound to the specified TlvType type param.
func (*OptionalRecordT[T, V]) UnwrapOrErrV ¶ added in v1.2.3
func (o *OptionalRecordT[T, V]) UnwrapOrErrV(err error) (V, error)
UnwrapOrErr is used to extract a value from an option, if the option is empty, then the specified error is returned directly. This gives the underlying value of the record, instead of the record itself.
func (*OptionalRecordT[T, V]) UnwrapOrFailV ¶ added in v1.2.3
func (o *OptionalRecordT[T, V]) UnwrapOrFailV(t *testing.T) V
UnwrapOrFailV is used to extract a value from an option within a test context. If the option is None, then the test fails. This gives the underlying value of the record, rather then the record itself.
func (*OptionalRecordT[T, V]) WhenSomeV ¶ added in v1.2.1
func (t *OptionalRecordT[T, V]) WhenSomeV(f func(V))
WhenSomeV executes the given function if the optional record is present. This operates on the inner most type, V, which is the value of the record.
func (*OptionalRecordT[T, V]) Zero ¶ added in v1.2.3
func (t *OptionalRecordT[T, V]) Zero() RecordT[T, V]
Zero returns a zero value of the record type.
type Primitive ¶ added in v1.2.0
type Primitive interface { constraints.Unsigned | ~[]byte | ~[32]byte | ~[33]byte | ~bool | ~*btcec.PublicKey | ~[64]byte }
Primitive is a type constraint that capture the set of "primitive" types, which are the built in stdlib types, and type defs of those types
type Record ¶
type Record struct {
// contains filtered or unexported fields
}
Record holds the required information to encode or decode a TLV record.
func MakeBigSizeRecord ¶ added in v1.0.3
MakeBigSizeRecord creates a tlv record using the BigSize format. The only allowed values are uint64 and uint32.
NOTE: for uint32, we would only gain space reduction if the encoded value is no greater than 65535, which requires at most 3 bytes to encode.
func MakeDynamicRecord ¶
func MakeDynamicRecord(typ Type, val interface{}, sizeFunc SizeFunc, encoder Encoder, decoder Decoder) Record
MakeDynamicRecord creates a record whose size may vary, and will be determined at the time of encoding via sizeFunc.
func MakePrimitiveRecord ¶
MakePrimitiveRecord creates a record for common types.
func MakeStaticRecord ¶
func MakeStaticRecord(typ Type, val interface{}, size uint64, encoder Encoder, decoder Decoder) Record
MakeStaticRecord creates a record for a field of fixed-size
func MapToRecords ¶
MapToRecords encodes the passed TLV map as a series of regular tlv.Record instances. The resulting set of records will be returned in sorted order by their type.
func (*Record) Decode ¶ added in v1.0.1
Decode read in the TLV record from the passed reader. This is useful when a caller wants decode a *single* TLV record, outside the context of the Stream struct.
func (*Record) Encode ¶
Encode writes out the TLV record to the passed writer. This is useful when a caller wants to obtain the raw encoding of a *single* TLV record, outside the context of the Stream struct.
func (*Record) Record ¶ added in v1.2.4
Record (the function) is the trivial implementation of RecordProducer for Record (the type). This makes it seamless to mix primitive and dynamic records together in the same collections.
NOTE: Part of the RecordProducer interface.
type RecordProducer ¶ added in v1.0.1
type RecordProducer interface { // Record returns a Record that can be used to encode or decode the // backing object. Record() Record }
RecorderProducer is an interface for objects that can produce a Record object capable of encoding and/or decoding the RecordProducer as a Record.
type RecordProducerT ¶ added in v1.2.0
type RecordProducerT[T any] interface { RecordProducer *T }
RecordProducerT is a type-aware wrapper around the normal RecordProducer interface.
type RecordT ¶ added in v1.2.0
type RecordT[T TlvType, V any] struct { // val is the value of the underlying record. Go doesn't let us just // embed the type param as a struct field, so we need an intermediate // variable. Val V // contains filtered or unexported fields }
RecordT is a high-order type makes it easy to encode known "primitive" types as TLV records.
func NewPrimitiveRecord ¶ added in v1.2.0
NewPrimitiveRecord creates a new RecordT type from a given primitive type.
func NewRecordT ¶ added in v1.2.0
func NewRecordT[T TlvType, K any, V RecordProducerT[K]]( record K, ) RecordT[T, K]
NewRecordT creates a new RecordT type from a given RecordProducer type. This is useful to wrap a given record in this utility type, which also serves as an extra type annotation. The underlying type of the record is retained.
func ZeroRecordT ¶ added in v1.2.0
ZeroRecordT returns a zero value of the RecordT type.
func (*RecordT[T, V]) Record ¶ added in v1.2.0
Record returns the underlying record interface for the record type.
type SizeFunc ¶
type SizeFunc func() uint64
SizeFunc is a function that can compute the length of a given field. Since the size of the underlying field can change, this allows the size of the field to be evaluated at the time of encoding.
func SizeBigSize ¶ added in v1.0.3
func SizeBigSize(val interface{}) SizeFunc
SizeBigSize returns a SizeFunc that can compute the length of BigSize.
func SizeVarBytes ¶
SizeVarBytes returns a SizeFunc that can compute the length of a byte slice.
type Stream ¶
type Stream struct {
// contains filtered or unexported fields
}
Stream defines a TLV stream that can be used for encoding or decoding a set of TLV Records.
func MustNewStream ¶
MustNewStream creates a new TLV Stream given an encoding codec, a decoding codec, and a set of known records. If an error is encountered in creating the stream, this method will panic instead of returning the error.
func NewStream ¶
NewStream creates a new TLV Stream given an encoding codec, a decoding codec, and a set of known records.
func (*Stream) Decode ¶
Decode deserializes TLV Stream from the passed io.Reader for non-P2P settings. The Stream will inspect each record that is parsed and check to see if it has a corresponding Record to facilitate deserialization of that field. If the record is unknown, the Stream will discard the record's bytes and proceed to the subsequent record.
Each record has the following format:
[varint: type] [varint: length] [length: value]
A series of (possibly zero) records are concatenated into a stream, this example contains two records:
(t: 0x01, l: 0x04, v: 0xff, 0xff, 0xff, 0xff) (t: 0x02, l: 0x01, v: 0x01)
This method asserts that the byte stream is canonical, namely that each record is unique and that all records are sorted in ascending order. An ErrNotCanonicalStream error is returned if the encoded TLV stream is not.
We permit an io.EOF error only when reading the type byte which signals that the last record was read cleanly and we should stop parsing. All other io.EOF or io.ErrUnexpectedEOF errors are returned.
func (*Stream) DecodeP2P ¶ added in v1.1.0
DecodeP2P is identical to Decode except that the maximum record size is capped at 65535.
func (*Stream) DecodeWithParsedTypes ¶ added in v1.0.1
DecodeWithParsedTypes is identical to Decode, but if successful, returns a TypeMap containing the types of all records that were decoded or ignored from the stream.
func (*Stream) DecodeWithParsedTypesP2P ¶ added in v1.1.0
DecodeWithParsedTypesP2P is identical to DecodeWithParsedTypes except that the record size is capped at 65535. This should only be called from a p2p setting where untrusted input is being deserialized.
func (*Stream) Encode ¶
Encode writes a Stream to the passed io.Writer. Each of the Records known to the Stream is written in ascending order of their type so as to be canonical.
The stream is constructed by concatenating the individual, serialized Records where each record has the following format:
[varint: type] [varint: length] [length: value]
An error is returned if the io.Writer fails to accept bytes from the encoding, and nothing else. The ordering of the Records is asserted upon the creation of a Stream, and thus the output will be by definition canonical.
type TlvType ¶ added in v1.2.0
type TlvType interface { // TypeVal returns the integer TLV type that this TlvType struct // instance maps to. TypeVal() Type // contains filtered or unexported methods }
TlvType is an interface used to enable binding the integer type of a TLV record to the type at compile time.
type TlvType100 ¶ added in v1.2.0
type TlvType100 = *tlvType100