codec

Documentation

Index

• type Decoder
• type Encoder
• type JSONDecoder
  • func (decoder JSONDecoder) Decode(data io.Reader, out any) error
  • func (decoder JSONDecoder) DecodeValues(values url.Values, out any) error
• type JSONEncoder
  • func (encoder JSONEncoder) ContentType() string
  • func (encoder JSONEncoder) Encode(writer io.Writer, value any) error
  • func (encoder JSONEncoder) EncodeValues(value any) url.Values
• type NopDecoder
  • func (NopDecoder) Decode(_ io.Reader, _ any) error
  • func (NopDecoder) DecodeValues(_ map[string][]string, _ any) error
• type NopEncoder
  • func (NopEncoder) ContentType() string
  • func (NopEncoder) Encode(_ io.Writer, _ any) error
• type Registry
  • func New() Registry
  • func (reg Registry) Decoder(contentTypes ...string) Decoder
  • func (reg Registry) DefaultDecoder() Decoder
  • func (reg Registry) DefaultEncoder() Encoder
  • func (reg Registry) DefaultValueDecoder() ValueDecoder
  • func (reg Registry) DefaultValueEncoder() ValueEncoder
  • func (reg Registry) Encoder(contentTypes ...string) Encoder
  • func (reg Registry) ValueDecoder(contentTypes ...string) ValueDecoder
  • func (reg Registry) ValueEncoder(contentTypes ...string) ValueEncoder
• type ValueDecoder
• type ValueEncoder

Types

type Decoder

type Decoder interface {
	// Decode will unmarshal the reader data onto the 'out' value.
	Decode(data io.Reader, out any) error
}

Decoder describes a mechanism used to decode streams of JSON/whatever data onto your service structs. The DecodeValues operation also lets you apply individual values to the struct using similar semantics.

type Encoder

type Encoder interface {
	// ContentType returns the MIME encoding type descriptor for the underlying data type
	// that this encoder expects to work with (e.g. "application/json").
	ContentType() string
	// Encode converts the value into the implementation's target data format and writes
	// the raw bytes to the given writer.
	Encode(writer io.Writer, value any) error
}

Encoder is used to encode streams of JSON/whatever given raw service structs.

type JSONDecoder

type JSONDecoder struct {
	Loose bool
}

JSONDecoder creates the default codec that uses encoding/json to apply body/path/query data to service request models. This unifies the processing so that every source of values is decoded using the same semantics. The goal is that whether a value comes in from the body or the path or the query string, if you supplied a custom UnmarshalJSON() function for a type, that will work.

It assumes that reader/body data is JSON, naturally. Path and query values, however, get massaged into JSON so that we can use the standard library's JSON package to unmarshal that data onto your out value. For example, let's assume that we have the following query string:

?first=Bob&last=Smith&age=39&address.city=Seattle&enabled=true

This decoder will first create 5 separate JSON objects:

{ "first": "Bob" }
{ "last": "Smith" }
{ "age": 39 }
{ "address": { "city": "Seattle" } }     <-- notice how we handle nested values separated by "."
{ "enabled": true }

After generating each value, the decoder will feed the massaged JSON to a 'json.Decoder' and standard JSON marshaling rules will overlay each one onto your 'out' value.

func (JSONDecoder) Decode

func (decoder JSONDecoder) Decode(data io.Reader, out any) error

Decode simply uses standard encoding/json to populate your 'out' value w/ JSON from the reader.

func (JSONDecoder) DecodeValues

func (decoder JSONDecoder) DecodeValues(values url.Values, out any) error

DecodeValues accepts key/value mappings like "User.ID":"123" and uses JSON-style decoding to fill your 'out' value with that data.

type JSONEncoder

type JSONEncoder struct{}

JSONEncoder simply uses the standard 'encoding/json' package to convert raw service structs into their equivalent JSON.

func (JSONEncoder) ContentType

func (encoder JSONEncoder) ContentType() string

ContentType returns "application/json", the expected MIME content type this encoder handles.

func (JSONEncoder) Encode

func (encoder JSONEncoder) Encode(writer io.Writer, value any) error

Encode uses the standard encoding/json package to encode the value's JSON onto the writer.

func (JSONEncoder) EncodeValues

func (encoder JSONEncoder) EncodeValues(value any) url.Values

EncodeValues encodes converts a raw Go object into a list of key/value pairs. For instance {"User.ID":"123", "User.ContactInfo.Email":"me@you.com"}.

type NopDecoder

type NopDecoder struct{}

NopDecoder satisfies the Decoder interface, but does not actually do any work.

func (NopDecoder) Decode

func (NopDecoder) Decode(_ io.Reader, _ any) error

Decode just returns nil. It does not read anything from your io.Reader, either.

func (NopDecoder) DecodeValues

func (NopDecoder) DecodeValues(_ map[string][]string, _ any) error

DecodeValues just returns nil to quietly complete.

type NopEncoder

type NopEncoder struct{}

NopEncoder satisfies the Encoder interface, but does not actually do any work. It doesn't look at your input values and will not write anything to the writers you provide.

func (NopEncoder) ContentType

func (NopEncoder) ContentType() string

ContentType returns "" to indicate that there's no specific encoding.

func (NopEncoder) Encode

func (NopEncoder) Encode(_ io.Writer, _ any) error

Encode does nothing and writes nothing. It simply returns nil to avoid making noise.

type Registry

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

Registry helps you wrangle a collection of encoders/decoders such that you can choose specific ones at runtime. For instance, at runtime you can decide if you want to use a JSON encoder or an XML one (ew...).

func New

func New() Registry

func (Registry) Decoder

func (reg Registry) Decoder(contentTypes ...string) Decoder

Decoder will return the Decoder for the first content type that we have a valid decoder for.

func (Registry) DefaultDecoder

func (reg Registry) DefaultDecoder() Decoder

DefaultDecoder returns the decoder that you should use if you have no specific preference.

func (Registry) DefaultEncoder

func (reg Registry) DefaultEncoder() Encoder

DefaultEncoder returns the encoder that you should use if you have no specific preference.

func (Registry) DefaultValueDecoder

func (reg Registry) DefaultValueDecoder() ValueDecoder

DefaultValueDecoder returns the ValueDecoder that you should use if you have no specific preference.

func (Registry) DefaultValueEncoder

func (reg Registry) DefaultValueEncoder() ValueEncoder

DefaultValueEncoder returns the ValueEncoder that you should use if you have no specific preference.

func (Registry) Encoder

func (reg Registry) Encoder(contentTypes ...string) Encoder

Encoder will return the Encoder for the first content type that we have a valid encoder for.

func (Registry) ValueDecoder

func (reg Registry) ValueDecoder(contentTypes ...string) ValueDecoder

ValueDecoder will return the ValueDecoder for the first content type that we have a valid decoder for.

func (Registry) ValueEncoder

func (reg Registry) ValueEncoder(contentTypes ...string) ValueEncoder

ValueEncoder will return the ValueEncoder for the first content type that we have a valid encoder for.

type ValueDecoder

type ValueDecoder interface {
	// DecodeValues will unmarshal all of the individual values onto the 'out' value.
	DecodeValues(values url.Values, out any) error
}

ValueDecoder accepts URL encoded values (e.g. "User.ContactInfo.Email"->"foo@bar.com") and can unmarshal them onto the out value of your choice.

type ValueEncoder

type ValueEncoder interface {
	// EncodeValues accepts a raw Go value and turns it into a map of individual values
	// such as "User.ContactInfo.Email"->"foo@bar.com".
	EncodeValues(value any) url.Values
}

ValueEncoder describes a component capable of taking a raw Go value and turning into a map of values such as "User.ContactInfo.Email"->"foo@bar.com".