encoding

type Encoder ¶

type Encoder interface {
	// Encode writes a serialized representation of v to w.
	Encode(w io.Writer, v any) error

	// Decode reads from r and decodes into v.
	Decode(r io.Reader, v any) error
}

Encoder encodes values to a writer and decodes values from a reader.

Encoder is intentionally minimal so multiple concrete encodings (JSON/YAML/TOML/protobuf/gob, etc.) can be used interchangeably.

Encode contract ¶

Encode must serialize v to w. Implementations may require that v satisfies additional interfaces or is of a particular shape (for example a protobuf encoder may require v to implement google.golang.org/protobuf/proto.Message).

Decode contract ¶

Decode must read from r and populate v. In most cases v is expected to be a pointer to the target value so the decoder can mutate it (e.g. *MyStruct). Implementations may return an error if v is not a supported type (for example github.com/alexfalkowski/go-service/v2/encoding/errors.ErrInvalidType).

Structured single-value decoders should reject additional encoded values after the first payload, either by consuming the whole input or by returning github.com/alexfalkowski/go-service/v2/encoding/errors.ErrTrailingData. Stream or passthrough encoders may delegate full-consumption semantics to the concrete value they decode into.

Some implementations buffer the remaining contents of r before decoding. When r contains untrusted input, callers must bound it before calling Decode. Standard go-service HTTP and cache wiring applies those limits before values reach encoders.

Implementations should return any underlying I/O errors and any parse/unmarshal errors produced by their respective codecs.

type Map ¶

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

Map provides lookup and registration of encoders by kind.

This type is a thin convenience around a string-keyed map and is commonly used with configuration to select an encoder at runtime.

Map is not concurrency-safe. If you mutate it via Register, do so during initialization.

func NewMap(params MapParams) *Map

func (f *Map) Get(kind string) Encoder

func (f *Map) Keys() []string

func (f *Map) Register(kind string, enc Encoder)

type MapParams ¶

type MapParams struct {
	di.In

	// JSON is the encoder implementation registered under kind "json".
	JSON *json.Encoder

	// HumanJSON is the encoder implementation registered under kind "hjson".
	HumanJSON *hjson.Encoder

	// YAML is the encoder implementation registered under kinds "yaml" and "yml".
	YAML *yaml.Encoder

	// TOML is the encoder implementation registered under kind "toml".
	TOML *toml.Encoder

	// MessagePack is the encoder implementation registered under kind "msgpack".
	MessagePack *msgpack.Encoder `optional:"true"`

	// ProtoBinary is the encoder implementation registered under common binary kinds
	// (e.g. "proto", "protobuf", "pb", etc.).
	ProtoBinary *proto.Binary

	// ProtoText is the encoder implementation registered under common text kinds
	// (e.g. "prototext", "prototxt", "pbtxt").
	ProtoText *proto.Text

	// ProtoJSON is the encoder implementation registered under common JSON kinds
	// (e.g. "protojson", "pbjson").
	ProtoJSON *proto.JSON

	// GOB is the encoder implementation registered under kind "gob".
	GOB *gob.Encoder

	// Bytes is the passthrough encoder for [io.ReaderFrom]/[io.WriterTo] payloads, registered under kinds
	// like "plain", "octet-stream", and "markdown".
	Bytes *bytes.Encoder
}

MapParams defines the dependencies used to construct an encoding Map.

It is intended for dependency injection (go.uber.org/fx/go.uber.org/dig). The default wiring is provided by Module. NewMap registers these values as supplied; direct callers that leave a field nil will get a nil encoder for that field's registered kind aliases.