encoding

README

Go Encoding

go-encoding is a Go package which abstracts various encoding mechanisms under a unified API.

Requirements

• Go 1.13+

Installation

$ go get github.com/Shopify/go-encoding

Usage

Encodings in this package follow either or both of these interfaces:

type ValueEncoding interface {
    Encode(data interface{}) ([]byte, error)
    Decode(b []byte, data interface{}) error
}

type StreamEncoding interface {
    StreamEncode(data interface{}, w io.Writer) error
    StreamDecode(r io.Reader, data interface{}) error
}

type ByteArrayEncoding interface {
    Encode([]byte) ([]byte, error)
    Decode([]byte) ([]byte, error)
}

type ByteStreamEncoding interface {
    StreamEncode(io.Writer) (io.WriteCloser, error)
    StreamDecode(io.Reader) (io.ReadCloser, error)
}

See example_test.go for how it all fits together.

Encodings

Used to encode arbitrary Go types to a byte array.

Name	ValueEncoding	StreamEncoding	Implementation
Literal	✔		strconv
Json	✔	✔	encoding/json
Gob		✔	encoding/gob

To use a ValueEncoding as a StreamEncoding, you can wrap with NewStreamEncoding.

Or vice-versa by using NewValueEncoding.

Byte Encodings

Used to encode byte arrays to byte arrays, which is useful to do processing like compression, encryption, or base64.

Name	ByteArrayEncoding	ByteStreamEncoding	Implementation
Base32	✔	✔	encoding/base32
Base64	✔	✔	encoding/base64
Flate	✔	✔	compress/flate
Gzip	✔	✔	compress/gzip
Hex	✔	✔	encoding/hex
Noop	✔	✔	passthrough
Zlib	✔	✔	compress/zlib

Documentation

Index

• Variables
• type ByteArrayDecoder
• type ByteArrayEncoder
• type ByteArrayEncoding
  • func NewByteArrayEncrypterEncoding(encrypter ByteArrayEncrypter) ByteArrayEncoding
  • func NewChainByteArrayEncoding(encodings ...ByteArrayEncoding) ByteArrayEncoding
• type ByteArrayEncrypter
• type ByteEncoding
  • func NewBase32Encoding(encoding *base32.Encoding) ByteEncoding
  • func NewBase64Encoding(encoding *base64.Encoding) ByteEncoding
  • func NewFlateEncoding(level int, dict []byte) ByteEncoding
  • func NewGzipEncoding(level int) ByteEncoding
  • func NewHexEncoding() ByteEncoding
  • func NewNoopEncoding() ByteEncoding
  • func NewReadWriteEncoding(builder ReaderWriterBuilder) ByteEncoding
  • func NewZlibEncoding(level int, dict []byte) ByteEncoding
• type ByteStreamDecoder
• type ByteStreamEncoder
• type ByteStreamEncoding
  • func NewChainByteStreamEncoding(encodings ...ByteStreamEncoding) ByteStreamEncoding
• type Encoding
  • func NewJSONEncoding() Encoding
  • func NewStreamEncoding(e ValueEncoding) Encoding
  • func NewValueEncoding(e StreamEncoding) Encoding
• type ReaderWriterBuilder
• type StreamDecoder
• type StreamEncoder
• type StreamEncoding
  • func NewGobEncoding() StreamEncoding
  • func NewWrappedStreamEncoding(encoding StreamEncoding, byteEncodings ...ByteStreamEncoding) StreamEncoding
• type ValueDecoder
• type ValueEncoder
• type ValueEncoding
  • func NewLiteralEncoding(fallback ValueEncoding) ValueEncoding
  • func NewWrappedValueEncoding(encoding ValueEncoding, byteEncodings ...ByteArrayEncoding) ValueEncoding

Examples

• ValueEncoding

Variables

var (
	Base32StdEncoding = NewBase32Encoding(base32.StdEncoding)
	Base32URLEncoding = NewBase32Encoding(base32.HexEncoding)
)

var (
	Base64StdEncoding = NewBase64Encoding(base64.StdEncoding)
	Base64URLEncoding = NewBase64Encoding(base64.URLEncoding)
)

var (
	ErrNotAPointer = errors.New("argument must be a pointer")
)

var FlateEncoding = NewFlateEncoding(flate.DefaultCompression, nil)

var GobEncoding = NewGobEncoding()

var GzipEncoding = NewGzipEncoding(gzip.DefaultCompression)

var HexEncoding = NewHexEncoding()

var JSONEncoding = NewJSONEncoding()

var LiteralEncoding = NewLiteralEncoding(nil)

var NoopEncoding = NewNoopEncoding()

var ZlibEncoding = NewZlibEncoding(zlib.DefaultCompression, nil)

Types

type ByteArrayDecoder

type ByteArrayDecoder interface {
	Decode([]byte) ([]byte, error)
}

type ByteArrayEncoder

type ByteArrayEncoder interface {
	Encode([]byte) ([]byte, error)
}

type ByteArrayEncoding

type ByteArrayEncoding interface {
	ByteArrayEncoder
	ByteArrayDecoder
}

func NewByteArrayEncrypterEncoding

func NewByteArrayEncrypterEncoding(encrypter ByteArrayEncrypter) ByteArrayEncoding

func NewChainByteArrayEncoding

func NewChainByteArrayEncoding(encodings ...ByteArrayEncoding) ByteArrayEncoding

type ByteArrayEncrypter

type ByteArrayEncrypter interface {
	Encrypt([]byte) ([]byte, error)
	Decrypt([]byte) ([]byte, error)
}

ByteArrayEncrypter is provided as a common interface for encryption operations

type ByteEncoding

type ByteEncoding interface {
	ByteArrayEncoding
	ByteStreamEncoding
}

func NewBase32Encoding

func NewBase32Encoding(encoding *base32.Encoding) ByteEncoding

func NewBase64Encoding

func NewBase64Encoding(encoding *base64.Encoding) ByteEncoding

func NewFlateEncoding

func NewFlateEncoding(level int, dict []byte) ByteEncoding

func NewGzipEncoding

func NewGzipEncoding(level int) ByteEncoding

func NewHexEncoding

func NewHexEncoding() ByteEncoding

func NewNoopEncoding

func NewNoopEncoding() ByteEncoding

func NewReadWriteEncoding

func NewReadWriteEncoding(builder ReaderWriterBuilder) ByteEncoding

func NewZlibEncoding

func NewZlibEncoding(level int, dict []byte) ByteEncoding

type ByteStreamDecoder

type ByteStreamDecoder interface {
	StreamDecode(io.Reader) (io.ReadCloser, error)
}

type ByteStreamEncoder

type ByteStreamEncoder interface {
	StreamEncode(io.Writer) (io.WriteCloser, error)
}

type ByteStreamEncoding

type ByteStreamEncoding interface {
	ByteStreamEncoder
	ByteStreamDecoder
}

func NewChainByteStreamEncoding

func NewChainByteStreamEncoding(encodings ...ByteStreamEncoding) ByteStreamEncoding

type Encoding

type Encoding interface {
	ValueEncoding
	StreamEncoding
}

func NewJSONEncoding

func NewJSONEncoding() Encoding

func NewStreamEncoding

func NewStreamEncoding(e ValueEncoding) Encoding

NewStreamEncoding creates an Encoding respecting the StreamEncoding interface from a ValueEncoding

func NewValueEncoding

func NewValueEncoding(e StreamEncoding) Encoding

NewValueEncoding creates an Encoding respecting the ValueEncoding interface from a StreamEncoding

type ReaderWriterBuilder

type ReaderWriterBuilder interface {
	NewReader(io.Reader) (io.ReadCloser, error)
	NewWriter(io.Writer) (io.WriteCloser, error)
}

type StreamDecoder

type StreamDecoder interface {
	StreamDecode(r io.Reader, data interface{}) error
}

type StreamEncoder

type StreamEncoder interface {
	StreamEncode(data interface{}, w io.Writer) error
}

type StreamEncoding

type StreamEncoding interface {
	StreamEncoder
	StreamDecoder
}

func NewGobEncoding

func NewGobEncoding() StreamEncoding

func NewWrappedStreamEncoding

func NewWrappedStreamEncoding(encoding StreamEncoding, byteEncodings ...ByteStreamEncoding) StreamEncoding

type ValueDecoder

type ValueDecoder interface {
	Decode(b []byte, data interface{}) error
}

type ValueEncoder

type ValueEncoder interface {
	Encode(data interface{}) ([]byte, error)
}

type ValueEncoding

type ValueEncoding interface {
	ValueEncoder
	ValueDecoder
}

Example

e := encoding.NewWrappedValueEncoding(encoding.JSONEncoding, encoding.GzipEncoding, encoding.Base64StdEncoding)

enc, _ := e.Encode(123)
var num int
_ = e.Decode(enc, &num)
fmt.Printf("literal number, encoded: %s, decoded: %d\n", enc, num)

enc, _ = e.Encode("123")
var s string
_ = e.Decode(enc, &s)
fmt.Printf("literal string, encoded: %s, decoded: %s\n", enc, s)

enc, _ = e.Encode(map[string]string{"foo": "bar"})
var m map[string]string
_ = e.Decode(enc, &m)
fmt.Printf("json map, encoded: %s, decoded: %+v\n", enc, m)

Output:

literal number, encoded: H4sIAAAAAAAA/zI0MgYEAAD//9JjSIgDAAAA, decoded: 123
literal string, encoded: H4sIAAAAAAAA/1IyNDJWAgQAAP//lwFQMwUAAAA=, decoded: 123
json map, encoded: H4sIAAAAAAAA/6pWSsvPV7JSSkosUqoFBAAA///v9Sv+DQAAAA==, decoded: map[foo:bar]

func NewLiteralEncoding

func NewLiteralEncoding(fallback ValueEncoding) ValueEncoding

NewLiteralEncoding is an encoding that will try its best to store the data as is, but fallback on another encoder if not possible.

func NewWrappedValueEncoding

func NewWrappedValueEncoding(encoding ValueEncoding, byteEncodings ...ByteArrayEncoding) ValueEncoding