BsonListSepString is a delimiter for top-level bson lists, which bson does not not normally support. When multiple documents are being sent in a single payload, the unicode SYMBOL FOR RECORD SEPARATOR is used. (http://fileformat.info/info/unicode/char/241e/index.htm)
const BsonListSepString = "\u241E"
BsonListSepBytes is a byte representation of BsonListSepString.
var BsonListSepBytes = []byte(BsonListSepString)
BsonCodecOpts holds options for registering new BSON codecs with SpanEngine.
type BsonCodecOpts struct {
// Type this codec handles encoding / decoding to.
ValueType reflect.Type
// Codec to register for this type.
Codec bsoncodec.ValueCodec
}
ContentEngine details the contract for a content encoding engine. The goal of the content engine is to allow a common decoding and encoding methodology for any supported mimetype, allowing easy support for client-requested payload encodings, and a shared interface for different types of services to add support for various encoding types.
type ContentEngine interface {
// Registers an encoder for a given mimetype.
SetEncoder(mimeType mimetype.MimeType, encoder Encoder)
// Registers a decoder for a given mimetype.
SetDecoder(mimeType mimetype.MimeType, decoder Decoder)
// Returns true if the engine has a registered encoder for the mimetype.
HandlesEncode(mimeType mimetype.MimeType) bool
// Returns true if the engine has a registered decoder for the mimetype.
HandlesDecode(mimeType mimetype.MimeType) bool
// Returns true if the engine has a registered encoder AND decoder for the mimetype.
Handles(mimeType mimetype.MimeType) bool
// Whether the engine will attempt to encode / decode unknown mimetypes.
SniffType() bool
// Decode mimeType content from reader using the decoder for mimeType. Decoded
// content is stored in contentReceiver.
Decode(
mimeType mimetype.MimeType,
contentReceiver interface{},
reader io.Reader,
) (mimetype.MimeType, error)
// Encode content as mimetype using registered mimeType to writer.
Encode(
mimeType mimetype.MimeType,
content interface{},
writer io.Writer,
) (mimetype.MimeType, error)
PickContentMimeType(
mimeType mimetype.MimeType, content interface{}, encoding bool,
) mimetype.MimeType
}
Interface for defining a content decoder.
type Decoder interface {
// To be implemented by content decoder. Implementation is expected to read content
// from reader and unmarshal it into contentReceiver. The content engine which is
// calling Decode is made available through engine, allowing decoders to access
// engine-level settings.
Decode(engine ContentEngine, reader io.Reader, contentReceiver interface{}) error
}
Interface for defining a content encoder.
type Encoder interface {
// To be implemented by content encoder. Implementation is expected to write content
// to writer. The content engine which is calling Encode is made available through
// engine, allowing encoding to access engine-level settings.
Encode(engine ContentEngine, writer io.Writer, content interface{}) error
}
JSONExtensionOpts holds options For Json Handle extension to add to the handle on server setup.
type JSONExtensionOpts struct {
ValueType reflect.Type
ExtInterface codec.InterfaceExt
}
SpanEngine is the default implementation of the ContentEngine interface. Implementation is done through an Interface so that the Engine can be extended through type wrapping.
Use NewContentEngine() to create a new SpanEngine.
• plain/text
• application/json
• application/bson
Object encoding/decoders have been selected to be extensible, and SpanEngine exposes functions to let you add custom type handlers to each.
SpanEngine uses the codec library to encode/decode json (https://godoc.org/github.com/ugorji/go/codec), which allows the definition of extensions. SpanEngine ships with the following types handled:
• UUIDs from "github.com/satori/go.uuid"
• Binary blob data represented as []byte or *[]bytes are represented as a hex string. To signal that this conversion should take place, you must use the named type BinData in the "spantypes" package of this module.
• BSON primitive.Binary data will be decoded as a string for 0x3 subtype (UUID) and a hex string for 0x0 subtype (arbitrary binary data). Other subtypes are not currently supported and will panic.
• BSON raw is converted to a map and THEN encoded to a json object.
Additional json extensions can be registered through the AddJSONExtensions() by passing a slice of JSONExtensionOpts objects.
SpanEngine handles the encoding and decoding of Bson data through the official bson driver (https://godoc.org/go.mongodb.org/mongo-driver).
See information on defining a bson codec here: https://godoc.org/go.mongodb.org/mongo-driver/bson/bsoncodec
The following type extensions ship with SpanEngine:
• primitive.Binary of subtype 0x3 can be decoded to / encoded from UUID objects from "github.com/satori/go.uuid".
• primitive.Binary of subtype 0x0 can be decoded to / encoded from the BinData named type of []byte in the "spantypes" module.
Default Text/Plain Returns
When encoding to plaintext, format.Sprint is used on the passed object, so any type can be sent and represented as text.
If created with "sniffMimeType" set to true, when decoding SpanEngine will attempt to use each decoder until one does not return an error or panic. Because decoders are internally stored in a map, the order of these attempts is not guaranteed to be consistent.
If an encoder or decoder panics during execution, that panic is caught and returned as an error.
type SpanEngine struct {
// contains filtered or unexported fields
}
func NewContentEngine(allowSniff bool) (*SpanEngine, error)
func (engine *SpanEngine) AddBSONCodecs(codecs []*BsonCodecOpts) error
Adds BSON codecs to engine for use when encoding/decoding bson data.
func (engine *SpanEngine) AddJSONExtensions(extensions []*JSONExtensionOpts) error
Adds JSON extensions to handle.
func (engine *SpanEngine) BSONRegistry() *bsoncodec.Registry
Returns the internal bsoncodec.BSONRegistry used by the bson encoder/decoder.
func (engine *SpanEngine) Decode( mimeType mimetype.MimeType, contentReceiver interface{}, reader io.Reader, ) (mimetype.MimeType, error)
func (engine *SpanEngine) Encode( mimeType mimetype.MimeType, content interface{}, writer io.Writer, ) (mimetype.MimeType, error)
func (engine *SpanEngine) Handles(mimeType mimetype.MimeType) bool
Whether the SpanEngine has a registered decoder AND encoder for mimeType.
func (engine *SpanEngine) HandlesDecode(mimeType mimetype.MimeType) bool
Whether the SpanEngine has a registered decoder for mimeType.
func (engine *SpanEngine) HandlesEncode(mimeType mimetype.MimeType) bool
Whether the SpanEngine has a registered encoder for mimeType.
func (engine *SpanEngine) JSONHandle() *codec.JsonHandle
func (engine *SpanEngine) PickContentMimeType( mimeType mimetype.MimeType, content interface{}, encoding bool, ) mimetype.MimeType
Picks the mimetype for encoding / decoding objects when source or target mimetype is unknown.
func (engine *SpanEngine) SetDecoder(mimeType mimetype.MimeType, decoder Decoder)
Register a decoder for a given mimeType
func (engine *SpanEngine) SetEncoder(mimeType mimetype.MimeType, encoder Encoder)
Register an encoder for a given mimeType
func (engine *SpanEngine) SetPassedEngine(newEngine ContentEngine)
Change the engine passed into Encoder.Encode() and decoder.Decode()
func (engine *SpanEngine) SniffType() bool
Whether SpanEngine will attempt to decode UNKNOWN content.