Documentation
¶
Overview ¶
Package encoding provides value encoding/decoding helpers and DI wiring used by go-service.
This package provides a registry (Map) that selects github.com/alexfalkowski/go-service/v2/encoding/codec.Encoder implementations by kind at runtime.
Registry ¶
Map is a kind-to-github.com/alexfalkowski/go-service/v2/encoding/codec.Encoder lookup. It is commonly used by configuration loading and transport layers to choose a decoder/encoder based on either:
- a file extension (for example "yaml", "toml", "json"), or
- a content kind / media subtype (for example "protobuf", "bytes").
Map registers each encoder under exactly one canonical kind; callers that need to accept alternate spellings (such as HTTP media subtype aliases "pb" or "octet-stream") translate them to the canonical kind before calling Map.Get rather than relying on this registry to know every alias.
Callers typically obtain a *Map via DI and then use Map.Get to select an encoder, often falling back to a default when the requested kind is not registered.
Decode options ¶
Decoding rejects unknown members by default where the format supports that distinction. Callers at a forward-compatible API boundary can pass github.com/alexfalkowski/go-service/v2/encoding/codec.WithDiscardUnknown to github.com/alexfalkowski/go-service/v2/encoding/codec.Encoder.Decode; framing, syntax, and type validation remain unchanged.
Partial options ¶
Encoding and decoding both reject messages with missing required fields by default where the format supports that distinction (currently the protobuf variants). Callers can pass github.com/alexfalkowski/go-service/v2/encoding/codec.WithAllowPartial to github.com/alexfalkowski/go-service/v2/encoding/codec.Encoder.Encode or github.com/alexfalkowski/go-service/v2/encoding/codec.Encoder.Decode to encode or decode such a message instead of returning an error. It may be combined with WithDiscardUnknown.
Wiring ¶
NewMap constructs a *Map that registers default encoders under common kinds used throughout go-service, including:
- JSON, HJSON, YAML, TOML, MessagePack
- protobuf binary/text/JSON variants
- gob
- "bytes" passthrough for io.ReaderFrom/io.WriterTo payloads
Module provides the default *Map for Fx applications.
Start with Map, NewMap, Module, and github.com/alexfalkowski/go-service/v2/encoding/codec.Encoder.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Module = di.Module( di.Constructor(NewMap), )
Module provides the default encoder registry as a *Map.
Functions ¶
This section is empty.
Types ¶
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 ¶
func NewMap() *Map
NewMap constructs a Map with the default encoders.
The returned registry includes these kinds, each registered under exactly one canonical name (no aliases, matching github.com/alexfalkowski/go-service/v2/encoding/stream.Map's design): "json", "hjson", "yaml", "toml", "msgpack", "protobuf", "prototext", "protojson", "gob", "bytes".
Callers that need to accept alternate spellings of these kinds (for example HTTP media subtypes such as "pb" or "octet-stream") are expected to translate them to the canonical kind above before calling Map.Get; see github.com/alexfalkowski/go-service/v2/net/http/content/unary's unaryKind.
Callers can add additional kinds or override existing kinds via Map.Register.
func (*Map) Get ¶
Get returns the encoder registered for kind.
If no encoder is registered for kind, or if kind was registered with a nil encoder, Get returns nil. Callers typically treat nil as "unknown or unavailable kind" and fall back to a default encoder elsewhere.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package base64 provides encoding helpers and adapters used by go-service.
|
Package base64 provides encoding helpers and adapters used by go-service. |
|
Package bytes provides byte-oriented encoding helpers and adapters used by go-service.
|
Package bytes provides byte-oriented encoding helpers and adapters used by go-service. |
|
Package codec defines the common contract implemented by supported encodings.
|
Package codec defines the common contract implemented by supported encodings. |
|
Package errors provides encoding error values and helpers used by go-service.
|
Package errors provides encoding error values and helpers used by go-service. |
|
Package gob provides Gob encoding helpers and adapters used by go-service.
|
Package gob provides Gob encoding helpers and adapters used by go-service. |
|
Package hjson provides HJSON encoding helpers and adapters used by go-service.
|
Package hjson provides HJSON encoding helpers and adapters used by go-service. |
|
Package json provides the go-service JSON import path.
|
Package json provides the go-service JSON import path. |
|
Package msgpack provides MessagePack encoding helpers and adapters used by go-service.
|
Package msgpack provides MessagePack encoding helpers and adapters used by go-service. |
|
Package proto provides Protocol Buffers (protobuf) encoding helpers and adapters used by go-service.
|
Package proto provides Protocol Buffers (protobuf) encoding helpers and adapters used by go-service. |
|
Package stream provides streaming (multi-value) encode/decode interfaces used by go-service.
|
Package stream provides streaming (multi-value) encode/decode interfaces used by go-service. |
|
gob
Package gob provides a streaming gob github.com/alexfalkowski/go-service/v2/encoding/stream.Encoder/ github.com/alexfalkowski/go-service/v2/encoding/stream.Decoder pair used by go-service.
|
Package gob provides a streaming gob github.com/alexfalkowski/go-service/v2/encoding/stream.Encoder/ github.com/alexfalkowski/go-service/v2/encoding/stream.Decoder pair used by go-service. |
|
json
Package json provides a streaming JSON github.com/alexfalkowski/go-service/v2/encoding/stream.Encoder/ github.com/alexfalkowski/go-service/v2/encoding/stream.Decoder pair used by go-service.
|
Package json provides a streaming JSON github.com/alexfalkowski/go-service/v2/encoding/stream.Encoder/ github.com/alexfalkowski/go-service/v2/encoding/stream.Decoder pair used by go-service. |
|
msgpack
Package msgpack provides a streaming MessagePack github.com/alexfalkowski/go-service/v2/encoding/stream.Encoder/ github.com/alexfalkowski/go-service/v2/encoding/stream.Decoder pair used by go-service.
|
Package msgpack provides a streaming MessagePack github.com/alexfalkowski/go-service/v2/encoding/stream.Encoder/ github.com/alexfalkowski/go-service/v2/encoding/stream.Decoder pair used by go-service. |
|
yaml
Package yaml provides a streaming YAML github.com/alexfalkowski/go-service/v2/encoding/stream.Encoder/ github.com/alexfalkowski/go-service/v2/encoding/stream.Decoder pair used by go-service.
|
Package yaml provides a streaming YAML github.com/alexfalkowski/go-service/v2/encoding/stream.Encoder/ github.com/alexfalkowski/go-service/v2/encoding/stream.Decoder pair used by go-service. |
|
Package toml provides TOML encoding helpers and adapters used by go-service.
|
Package toml provides TOML encoding helpers and adapters used by go-service. |
|
Package yaml provides YAML encoding helpers and adapters used by go-service.
|
Package yaml provides YAML encoding helpers and adapters used by go-service. |