codec

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. WithDiscardUnknown makes codecs
	// ignore source members that do not map to v; without it, codecs reject
	// unknown members when their format supports that distinction.
	Decode(r io.Reader, v any, opts ...Option) 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 Option ¶

type Option interface {
	// contains filtered or unexported methods
}

Option configures one Encoder.Decode operation.

func WithDiscardUnknown() Option

type Options ¶

type Options interface {
	// DiscardUnknown reports whether unknown source members are discarded.
	DiscardUnknown() bool
}

Options reports settings resolved for one Encoder.Decode operation.

func Apply(opts ...Option) Options