Documentation ¶
Overview ¶
Package vmux provides utilities that make it easy to implement "version multiplexing" with your Thema lineages.
Version multiplexing is taking an input of []byte expected to represent an object schematized by some Thema lineage, and automatically decoding, validating, and translating it to a single schema version in that lineage. The effect of this is a Go program that "accepts all, sees one" - all historical schema versions are accepted, but the program can be written as though only a single version exists.
The generic utilities in this package reduce version muxing to a single function call. Still, they are pure convenience: this package relies solely on the public interface of github.com/grafana/thema, and can be reimplemented with different tradeoffs elsewhere if needed.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ByteMux ¶
type ByteMux func(b []byte) ([]byte, thema.TranslationLacunas, error)
ByteMux is a version multiplexer that maps a []byte containing data at any schematized version to a []byte containing data at a particular schematized version.
func NewByteMux ¶
NewByteMux creates a ByteMux func from the provided thema.Schema.
When the returned mux func is called, it will:
- Decode the input []byte using the provided Codec, then
- Pass the result to thema.Schema.Validate, then
- Call thema.Instance.Translate on the result, to the version of the provided thema.Schema, then
- Encode the resulting thema.Instance to a []byte, then
- Return the resulting []byte, thema.TranslationLacunas, and error
The returned error may be from any of the above steps.
type Codec ¶
A Codec can decode a []byte in a particular format (e.g. JSON, YAML) into CUE, and decode from a thema.Instance back into a []byte.
It is customary, but not necessary, that a Codec's input and output formats are the same.
func NewJSONCodec ¶
NewJSONCodec creates a Codec that decodes from and encodes to a JSON []byte.
The provided path is used as the CUE source path for each []byte input passed through the decoder. These paths do not affect behavior, but show up in error output (e.g. validation).
func NewYAMLCodec ¶
NewYAMLCodec creates a Codec that decodes from and encodes to a YAML []byte.
The provided path is used as the CUE source path for each []byte input passed through the decoder. These paths do not affect behavior, but show up in error output (e.g. validation).
type Decoder ¶
A Decoder can decode a []byte in a particular format (e.g. JSON, YAML) into a cue.Value, readying it for a call to thema.Schema.Validate.
type Encoder ¶
An Encoder can encode a thema.Instance to a []byte in a particular format (e.g. JSON, YAML).
type TypedMux ¶
type TypedMux[T thema.Assignee] func(b []byte) (*thema.TypedInstance[T], thema.TranslationLacunas, error)
TypedMux is a version multiplexer that maps a []byte containing data at any schematized version to a thema.TypedInstance at a particular schematized version.
func NewTypedMux ¶
NewTypedMux creates a TypedMux func from the provided thema.TypedSchema.
When the returned mux func is called, it will:
- Decode the input []byte using the provided Decoder, then
- Pass the result to thema.TypedSchema.ValidateTyped, then
- Call thema.Instance.Translate on the result, to the version of the provided thema.TypedSchema, then
- Return the resulting thema.TypedInstance, thema.TranslationLacunas, and error
The returned error may be from any of the above steps.
type UntypedMux ¶
UntypedMux is a version multiplexer that maps a []byte containing data at any schematized version to a thema.Instance at a particular schematized version.
func NewUntypedMux ¶
func NewUntypedMux(sch thema.Schema, dec Decoder) UntypedMux
NewUntypedMux creates an UntypedMux from the provided thema.Schema.
When the returned mux func is called, it will:
- Decode the input []byte using the provided Decoder, then
- Pass the result to thema.Schema.Validate, then
- Call thema.Instance.Translate on the result, to the version of the provided thema.Schema, then
- Return the resulting thema.Instance, thema.TranslationLacunas, and error
The returned error may be from any of the above steps.
type ValueMux ¶
ValueMux is a version multiplexer that maps a []byte containing data at any schematized version to a Go var of a type that a particular schematized version is thema.AssignableTo.
func NewValueMux ¶
NewValueMux creates a ValueMux func from the provided thema.TypedSchema.
When the returned mux func is called, it will:
- Decode the input []byte using the provided Decoder, then
- Pass the result to thema.TypedSchema.ValidateTyped, then
- Call thema.Instance.Translate on the result, to the version of the provided thema.TypedSchema, then
- Populate an instance of T by calling thema.TypedInstance.Value on the result, then
- Return the resulting T, thema.TranslationLacunas, and error
The returned error may be from any of the above steps.