byteslice

README

byteslice

A thin layer on top of []byte to accomodate base64 encoding used in conjunction with "encoding/json".

When the Go type []byte is used to decode/encode a JSON string, the standard "encoding/json" library assumes base64.StdEncoding (RFC4648 section 3.2). This poses a problem when you want to encode the fields using a different encoding, or if whatever protocol you are using does not very clearly specify which base64 encoding you are supposed to use and you must field multiple, slightly differing base64 encoded string.

While the standard "encoding/json" library only works with a single encoding, if you use byteslice.Buffer, it can decode using any of the pre-defined encodings in "encoding/base64" by default (or specify an alternate *base64.Encoding object), and to specify which encoding to use converting []byte to JSON.

SYNOPSIS

type Foo struct {
  Field byteslice.Buffer `json:"field"`
}

func init() {
  byteslice.SetGlobalB64Encoder(base64.RawURLEncoding)
  byteslice.SetGlobalB64Decoder(base64.RawURLEncoding)
}

var foo Foo
_ = json.Unmarshal(data, &foo)

FAQ

Q: What's with AcceptValue?

AcceptValue is a convenience function for those cases when you do not know the type of source value before hand, but you still would like to attempt to initialize a byteslice.Buffer object. (This happens more often than you may think!)

Documentation

Overview

Package byteslice provides a thin abstraction over `[]byte` types. This package exist to support encoding/decoding `[]byte` slices in JSON serialization/deserialization.

Yes, `encoding/json` supports base64 encoding for `[]byte` fields, but there's no way to customize the way these fields get serialized/deserialized -- e.g. with padding or no padding, which characters to use for padding, etc.

By using byteslice.Buffer as the field instead of `[]byte` you can change the the way this base64 handling is performed.

Index

• func SetGlobalB64Decoder(dec B64Decoder)
• func SetGlobalB64Encoder(enc B64Encoder)
• type B64Decoder
  • func GlobalB64Decoder() B64Decoder
• type B64DecoderFunc
  • func (f B64DecoderFunc) DecodeString(s string) ([]byte, error)
• type B64Encoder
  • func GlobalB64Encoder() B64Encoder
• type B64EncoderFunc
  • func (f B64EncoderFunc) EncodeToString(data []byte) string
• type Buffer
  • func New(data []byte) *Buffer
  • func (b *Buffer) AcceptValue(in interface{}) error
  • func (b *Buffer) B64Decoder() B64Decoder
  • func (b *Buffer) B64Encoder() B64Encoder
  • func (b *Buffer) Bytes() []byte
  • func (b *Buffer) Len() int
  • func (b Buffer) MarshalJSON() ([]byte, error)
  • func (b *Buffer) SetB64Decoder(dec B64Decoder) *Buffer
  • func (b *Buffer) SetBytes(data []byte)
  • func (b *Buffer) SetEncoder(enc B64Encoder) *Buffer
  • func (b *Buffer) UnmarshalJSON(data []byte) error

Functions

func SetGlobalB64Decoder

func SetGlobalB64Decoder(dec B64Decoder)

SetGlobalB64Decoder sets the `B64Decoder` that should be used globally

func SetGlobalB64Encoder

func SetGlobalB64Encoder(enc B64Encoder)

SetGlobalB64Encoder sets the `B64Encoder` that should be used globally

Types

type B64Decoder

type B64Decoder interface {
	DecodeString(string) ([]byte, error)
}

B64Decoder is the interface for objects that can decode base64 encoded strings into `[]byte`

Any `*base64.Encoding` object satisfies this interface.

func GlobalB64Decoder

func GlobalB64Decoder() B64Decoder

GlobalB64Decoder returns the `B64Decoder` that is to be used by default for all `byteslice.Buffer` types. Each instance can be configured to use its own decoder if set individually.

The default decoder uses heuristics to determine which of the `"encoding/base64".Encoding` objects should be used.

• If the incoming payload does NOT contain a '=' at the end of the string, it is considered to be a "raw" base64 encoding (i.e. no padding)
• If the incoming payload does NOT contain either '+' or '/', it is considered to be a "url" encoding

By combining these two, we decide which of `base64.URLEncoding`, `base64.StdEncoding`, `base64.RawURLEncoding`, or `base64.RawStdEncoding` we should be using to decode the JSON string

type B64DecoderFunc

type B64DecoderFunc func(string) ([]byte, error)

B64DecoderFunc is an instance of B64Decoder that is based on a function.

func (B64DecoderFunc) DecodeString

func (f B64DecoderFunc) DecodeString(s string) ([]byte, error)

DecodeString implements the B64Decoder interface

type B64Encoder

type B64Encoder interface {
	EncodeToString([]byte) string
}

B64Encoder is the interface for objects that can encode `[]byte` into base64 encoded string

Any `*base64.Encoding` object satisfies this interface.

func GlobalB64Encoder

func GlobalB64Encoder() B64Encoder

GlobalB64Encoder returns the `B64Encoder` that is to be used by default for all `byteslice.Buffer` types. Each instance can be configured to use its own encoder if set individually.

The default encoder uses the same encoder as the standard library's "encoding/json", which is the `base64.StdEncoding`

type B64EncoderFunc

type B64EncoderFunc func([]byte) string

B64EncoderFunc is an instance of B64Encoder that is based on a function.

func (B64EncoderFunc) EncodeToString

func (f B64EncoderFunc) EncodeToString(data []byte) string

EncodeString implements the B64Encoder interface

type Buffer

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

Buffer represents a byte slice. Its only purpose is to act as a thing layer on top of a `[]byte` and provide flexibly JSON serialization/deserialization capabilities

It is safe to use the zero value of the `Buffer` object, but the object is not explicitly synchronized. The user must make sure to apply any synchronization if need be.

You should not copy a `Buffer` object by reference

func New

func New(data []byte) *Buffer

New creates a new buffer. Using the data provided to call SetBytes(). You may pass `nil` to the argument to create an uninitialized `Buffer` object.

If you do not need explicit initialization, it is safe to use the zero value of the `Buffer` object.

func (*Buffer) AcceptValue

func (b *Buffer) AcceptValue(in interface{}) error

AcceptValue is used in by some consumers to assign the value whose type is not known before hand.

Values can be either one of the following types: `*byteslice.Buffer`, `[]byte`, or `string`.

If the value is a `*byteslice.Buffer`, a copy of the underlying is created, and assigned to receiver.

If the value is a `[]byte`, it is the same as calling `SetBytes()`

IF the value is a `string`, the string is assumed to be a base64-encoded string. Unlike in the case of `UnmarshalJSON`, the string does not need to be quoted.

func (*Buffer) B64Decoder

func (b *Buffer) B64Decoder() B64Decoder

B64Decoder returns the B64Decoder associated with this object. If uninitialized, it will use the global decoder via byteslice.GlobalB64Decoder()

func (*Buffer) B64Encoder

func (b *Buffer) B64Encoder() B64Encoder

B64Encoder returns the B64Encoder associated with this object. If uninitialized, will use the global decoder via byteslice.GlobalB64Encoder()

func (*Buffer) Bytes

func (b *Buffer) Bytes() []byte

Bytes returns the raw bytes stored in the `Buffer` object.

Users need to take care of synchronization or acting upon on the returned buffer, as it will affect the actual stored `[]byte` field in the `Buffer` object.

func (*Buffer) Len

func (b *Buffer) Len() int

Len returns the length of the internal `[]byte` buffer

func (Buffer) MarshalJSON

func (b Buffer) MarshalJSON() ([]byte, error)

MarshalJSON implements `"encoding/json".Marshaler, and provides a method to serialize a `[]byte` string to a base64 encoded JSON string.

The JSON string will be parsed using the B64Encoder object associated with this object (or the global one, if not specified).

func (*Buffer) SetB64Decoder

func (b *Buffer) SetB64Decoder(dec B64Decoder) *Buffer

SetB64Decoder assigns a B64Decoder for this object.

func (*Buffer) SetBytes

func (b *Buffer) SetBytes(data []byte)

SetBytes copies the `data` byte slice to the internal buffer

func (*Buffer) SetEncoder

func (b *Buffer) SetEncoder(enc B64Encoder) *Buffer

SetB64Encoder assigns a B64Encoder for this object.

func (*Buffer) UnmarshalJSON

func (b *Buffer) UnmarshalJSON(data []byte) error

UnmarshalJSON implements `"encoding/json".Unmarshaler`, and provides a method to deserialize a `[]byte` string from a base64 encoded JSON string.

The JSON string will be parsed using the B64Decoder object associated with this object (or the global one, if not specified).