serializer

package
v0.0.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 21, 2020 License: Apache-2.0 Imports: 22 Imported by: 11

Documentation

Index

Constants

View Source 
const (
	// ContentTypeJSON specifies usage of JSON as the content type.
	// It is an alias for k8s.io/apimachinery/pkg/runtime.ContentTypeJSON
	ContentTypeJSON = ContentType(runtime.ContentTypeJSON)

	// ContentTypeYAML specifies usage of YAML as the content type.
	// It is an alias for k8s.io/apimachinery/pkg/runtime.ContentTypeYAML
	ContentTypeYAML = ContentType(runtime.ContentTypeYAML)
)

Variables

View Source 
var (
	// TODO: Investigate if we can just depend on `metav1.Object` interface compliance instead of needing to explicitly
	//  embed the `metav1.ObjectMeta` struct.
	ErrNoObjectMeta     = errors.New("the given object cannot store comments, it is not metav1.ObjectMeta compliant")
	ErrNoStoredComments = errors.New("the given object does not have stored comments")
)
View Source 
var ErrUnsupportedContentType = errors.New("unsupported content type")

ErrUnsupportedContentType is returned if the specified content type isn't supported

View Source 
var (
	// FrameOverflowErr is returned from FrameReader.ReadFrame when one frame exceeds the
	// maximum size of 16 MB.
	FrameOverflowErr = errors.New("frame was larger than maximum allowed size")
)

Functions

func GVKForObject added in v0.0.3 

func GVKForObject(scheme *runtime.Scheme, obj runtime.Object) (schema.GroupVersionKind, error)

func GetCommentSource added in v0.0.2 

func GetCommentSource(obj runtime.Object) (*yaml.RNode, error)

GetCommentSource retrieves the YAML tree used as the source for transferring comments for the given runtime.Object. This may be used externally to implement e.g. re-parenting of the comment source tree when moving structs around.

func SetCommentSource added in v0.0.2 

func SetCommentSource(obj runtime.Object, source *yaml.RNode) error

SetCommentSource sets the given YAML tree as the source for transferring comments for the given runtime.Object. This may be used externally to implement e.g. re-parenting of the comment source tree when moving structs around.

func WriteFrameList 

func WriteFrameList(fw FrameWriter, frameList FrameList) error

WriteFrameList is a convenience method that writes a set of frames to a FrameWriter

Types

type CRDConversionError 

type CRDConversionError struct {
	GVK   schema.GroupVersionKind
	Cause CRDConversionErrorCause
	Err   error
}

CRDConversionError describes an error that occurred when converting CRD types

func NewCRDConversionError 

func NewCRDConversionError(gvk *schema.GroupVersionKind, cause CRDConversionErrorCause, err error) *CRDConversionError

NewCRDConversionError creates a new CRDConversionError error

func (*CRDConversionError) Error 

func (e *CRDConversionError) Error() string

Error implements the error interface

func (*CRDConversionError) GroupVersionKind 

func (e *CRDConversionError) GroupVersionKind() schema.GroupVersionKind

GroupVersionKind returns the GroupVersionKind for the error

func (*CRDConversionError) Unwrap 

func (e *CRDConversionError) Unwrap() error

Unwrap allows the standard library unwrap the underlying error

type CRDConversionErrorCause 

type CRDConversionErrorCause string

CRDConversionErrorCause is a typed string, describing the error cause for 

const (
	// CRDConversionErrorCauseConvertTo describes an error that was caused by ConvertTo failing
	CRDConversionErrorCauseConvertTo CRDConversionErrorCause = "ConvertTo"

	// CRDConversionErrorCauseConvertTo describes an error that was caused by ConvertFrom failing
	CRDConversionErrorCauseConvertFrom CRDConversionErrorCause = "ConvertFrom"

	// CRDConversionErrorCauseConvertTo describes an error that was caused by that the scheme wasn't properly set up
	CRDConversionErrorCauseSchemeSetup CRDConversionErrorCause = "SchemeSetup"

	// CRDConversionErrorCauseInvalidArgs describes an error that was caused by that conversion targets weren't Hub and Convertible
	CRDConversionErrorCauseInvalidArgs CRDConversionErrorCause = "InvalidArgs"
)

type ContentType 

type ContentType string

ContentType specifies a content type for Encoders, Decoders, FrameWriters and FrameReaders

type ContentTyped 

type ContentTyped interface {
	// ContentType returns the ContentType (usually ContentTypeYAML or ContentTypeJSON) for the given object.
	ContentType() ContentType
}

ContentTyped is an interface for objects that are specific to a set ContentType.

type Converter 

type Converter interface {
	// Convert converts in directly into out. out should be an empty object of the destination type.
	// Both objects must be of the same kind and either have autogenerated conversions registered, or
	// be controller-runtime CRD-style implementers of the sigs.k8s.io/controller-runtime/pkg/conversion.Hub
	// and Convertible interfaces. In the case of CRD Convertibles and Hubs, there must be one Convertible and
	// one Hub given in the in and out arguments. No defaulting is performed.
	Convert(in, out runtime.Object) error

	// ConvertIntoNew creates a new object for the specified groupversionkind, uses Convert(in, out)
	// under the hood, and returns the new object. No defaulting is performed.
	ConvertIntoNew(in runtime.Object, gvk schema.GroupVersionKind) (runtime.Object, error)

	// ConvertToHub converts the given in object to either the internal version (for API machinery "classic")
	// or the sigs.k8s.io/controller-runtime/pkg/conversion.Hub for the given conversion.Convertible object in
	// the "in" argument. No defaulting is performed.
	ConvertToHub(in runtime.Object) (runtime.Object, error)
}

Converter is an interface that allows access to object conversion capabilities

type Decoder 

type Decoder interface {
	// Decode returns the decoded object from the next document in the FrameReader stream.
	// If there are multiple documents in the underlying stream, this call will read one
	// 	document and return it. Decode might be invoked for getting new documents until it
	// 	returns io.EOF. When io.EOF is reached in a call, the stream is automatically closed.
	// If the decoded object is for an unrecognized group, or version, UnrecognizedGroupError
	// 	or UnrecognizedVersionError might be returned.
	// If opts.Default is true, the decoded object will be defaulted.
	// If opts.Strict is true, the YAML/JSON will be parsed in strict mode, returning a specific error
	// 	if the input contains duplicate or unknown fields or formatting errors. You can check whether
	// 	a returned failed because of the strictness using k8s.io/apimachinery/pkg/runtime.IsStrictDecodingError.
	// If opts.ConvertToHub is true, the decoded external object will be converted into its internal representation.
	// 	Otherwise, the decoded object will be left in the external representation.
	// If opts.DecodeUnknown is true, any type with an unrecognized apiVersion/kind will be returned as a
	// 	*runtime.Unknown object instead of returning a UnrecognizedTypeError.
	// opts.DecodeListElements is not applicable in this call.
	Decode(fr FrameReader) (runtime.Object, error)

	// DecodeInto decodes the next document in the FrameReader stream into obj if the types are matching.
	// If there are multiple documents in the underlying stream, this call will read one
	// 	document and return it. Decode might be invoked for getting new documents until it
	// 	returns io.EOF. When io.EOF is reached in a call, the stream is automatically closed.
	// The decoded object will automatically be converted into the target one (i.e. one can supply an
	// 	internal object to this function).
	// If the decoded object is for an unrecognized group, or version, UnrecognizedGroupError
	// 	or UnrecognizedVersionError might be returned.
	// If opts.Default is true, the decoded object will be defaulted.
	// If opts.Strict is true, the YAML/JSON will be parsed in strict mode, returning a specific error
	// 	if the input contains duplicate or unknown fields or formatting errors. You can check whether
	// 	a returned failed because of the strictness using k8s.io/apimachinery/pkg/runtime.IsStrictDecodingError.
	// opts.DecodeListElements is not applicable in this call.
	// opts.ConvertToHub is not applicable in this call.
	// opts.DecodeUnknown is not applicable in this call. In case you want to decode an object into a
	// 	*runtime.Unknown, just create a runtime.Unknown object and pass the pointer as obj into DecodeInto
	// 	and it'll work.
	DecodeInto(fr FrameReader, obj runtime.Object) error

	// DecodeAll returns the decoded objects from all documents in the FrameReader stream. The underlying
	// stream is automatically closed on io.EOF. io.EOF is never returned from this function.
	// If any decoded object is for an unrecognized group, or version, UnrecognizedGroupError
	// 	or UnrecognizedVersionError might be returned.
	// If opts.Default is true, the decoded objects will be defaulted.
	// If opts.Strict is true, the YAML/JSON will be parsed in strict mode, returning a specific error
	// 	if the input contains duplicate or unknown fields or formatting errors. You can check whether
	// 	a returned failed because of the strictness using k8s.io/apimachinery/pkg/runtime.IsStrictDecodingError.
	// If opts.ConvertToHub is true, the decoded external object will be converted into their internal representation.
	// 	Otherwise, the decoded objects will be left in their external representation.
	// If opts.DecodeListElements is true and the underlying data contains a v1.List,
	// 	the items of the list will be traversed and decoded into their respective types, which are
	// 	added into the returning slice. The v1.List will in this case not be returned.
	// If opts.DecodeUnknown is true, any type with an unrecognized apiVersion/kind will be returned as a
	// 	*runtime.Unknown object instead of returning a UnrecognizedTypeError.
	DecodeAll(fr FrameReader) ([]runtime.Object, error)
}

Decoder is a high-level interface for decoding Kubernetes API Machinery objects read from a FrameWriter. The decoder can be customized by passing some options (e.g. WithDecodingOptions) to this call.

type DecodingOptions 

type DecodingOptions struct {
	// Not applicable for Decoder.DecodeInto(). If true, the decoded external object
	// will be converted into its hub (or internal, where applicable) representation. Otherwise, the decoded
	// object will be left in its external representation. (Default: false)
	ConvertToHub *bool

	// Parse the YAML/JSON in strict mode, returning a specific error if the input
	// contains duplicate or unknown fields or formatting errors. (Default: true)
	Strict *bool

	// Automatically default the decoded object. (Default: false)
	Default *bool

	// Only applicable for Decoder.DecodeAll(). If the underlying data contains a v1.List,
	// the items of the list will be traversed, decoded into their respective types, and
	// appended to the returned slice. The v1.List will in this case not be returned.
	// This conversion does NOT support preserving comments. If the given scheme doesn't
	// recognize the v1.List, before using it will be registered automatically. (Default: true)
	DecodeListElements *bool

	// Whether to preserve YAML comments internally. This only works for objects embedding metav1.ObjectMeta.
	// Only applicable to ContentTypeYAML framers.
	// Using any other framer will be silently ignored. Usage of this option also requires setting
	// the PreserveComments in EncodingOptions, too. (Default: false)
	PreserveComments *bool

	// DecodeUnknown specifies whether decode objects with an unknown GroupVersionKind into a
	// *runtime.Unknown object when running Decode(All) (true value) or to return an error when
	// any unrecognized type is found (false value). (Default: false)
	DecodeUnknown *bool
}

type DecodingOptionsFunc 

type DecodingOptionsFunc func(*DecodingOptions)

func WithCommentsDecode 

func WithCommentsDecode(comments bool) DecodingOptionsFunc

func WithConvertToHubDecode 

func WithConvertToHubDecode(convert bool) DecodingOptionsFunc

func WithDecodingOptions 

func WithDecodingOptions(newOpts DecodingOptions) DecodingOptionsFunc

func WithDefaultsDecode 

func WithDefaultsDecode(defaults bool) DecodingOptionsFunc

func WithListElementsDecoding 

func WithListElementsDecoding(listElements bool) DecodingOptionsFunc

func WithStrictDecode 

func WithStrictDecode(strict bool) DecodingOptionsFunc

func WithUnknownDecode 

func WithUnknownDecode(unknown bool) DecodingOptionsFunc

type Defaulter 

type Defaulter interface {
	// Default runs the registered defaulting functions in the scheme on the given objects, one-by-one.
	// If the given object is internal, it will be automatically defaulted using the preferred external
	// version's defaults (i.e. converted to the preferred external version, defaulted there, and converted
	// back to internal).
	// Important to note here is that the TypeMeta information is NOT applied automatically.
	Default(objs ...runtime.Object) error

	// NewDefaultedObject returns a new, defaulted object. It is essentially scheme.New() and
	// scheme.Default(obj), but with extra logic to cover also internal versions.
	// Important to note here is that the TypeMeta information is NOT applied automatically.
	NewDefaultedObject(gvk schema.GroupVersionKind) (runtime.Object, error)
}

Defaulter is a high-level interface for accessing defaulting functions in a scheme

type Encoder 

type Encoder interface {
	// Encode encodes the given objects and writes them to the specified FrameWriter.
	// The FrameWriter specifies the ContentType. This encoder will automatically convert any
	// internal object given to the preferred external groupversion. No conversion will happen
	// if the given object is of an external version.
	Encode(fw FrameWriter, obj ...runtime.Object) error

	// EncodeForGroupVersion encodes the given object for the specific groupversion. If the object
	// is not of that version currently it will try to convert. The output bytes are written to the
	// FrameWriter. The FrameWriter specifies the ContentType.
	EncodeForGroupVersion(fw FrameWriter, obj runtime.Object, gv schema.GroupVersion) error
}

Encoder is a high-level interface for encoding Kubernetes API Machinery objects and writing them to a FrameWriter.

type EncodingOptions 

type EncodingOptions struct {
	// Use pretty printing when writing to the output. (Default: true)
	// TODO: Fix that sometimes omitempty fields aren't respected
	Pretty *bool
	// Whether to preserve YAML comments internally. This only works for objects embedding metav1.ObjectMeta.
	// Only applicable to ContentTypeYAML framers.
	// Using any other framer will be silently ignored. Usage of this option also requires setting
	// the PreserveComments in DecodingOptions, too. (Default: false)
	// TODO: Make this a BestEffort & Strict mode
	PreserveComments *bool
}

type EncodingOptionsFunc 

type EncodingOptionsFunc func(*EncodingOptions)

func WithCommentsEncode 

func WithCommentsEncode(comments bool) EncodingOptionsFunc

func WithEncodingOptions 

func WithEncodingOptions(newOpts EncodingOptions) EncodingOptionsFunc

func WithPrettyEncode 

func WithPrettyEncode(pretty bool) EncodingOptionsFunc

type FrameList 

type FrameList [][]byte

FrameList is a list of frames (byte arrays), used for convenience functions

func ReadFrameList 

func ReadFrameList(fr FrameReader) (FrameList, error)

ReadFrameList is a convenience method that reads all available frames from the FrameReader into a returned FrameList

type FrameReader 

type FrameReader interface {
	ContentTyped
	io.Closer

	// ReadFrame reads frames from the underlying ReadCloser and returns them for consumption.
	// When io.EOF is reached, the stream is closed automatically.
	ReadFrame() ([]byte, error)
}

FrameReader is a content-type specific reader of a given ReadCloser. The FrameReader reads frames from the underlying ReadCloser and returns them for consumption. When io.EOF is reached, the stream is closed automatically.

func NewFrameReader 

func NewFrameReader(contentType ContentType, rc ReadCloser) FrameReader

NewFrameReader returns a FrameReader for the given ContentType and data in the ReadCloser. The Reader is automatically closed in io.EOF. ReadFrame is called once each Decoder.Decode() or Decoder.DecodeInto() call. When Decoder.DecodeAll() is called, the FrameReader is read until io.EOF, upon where it is closed.

func NewJSONFrameReader 

func NewJSONFrameReader(rc ReadCloser) FrameReader

NewJSONFrameReader returns a FrameReader that supports both JSON. Objects are read from the stream one-by-one, each object making up its own frame.

This call is the same as NewFrameReader(ContentTypeJSON, rc)

func NewYAMLFrameReader 

func NewYAMLFrameReader(rc ReadCloser) FrameReader

NewYAMLFrameReader returns a FrameReader that supports both YAML and JSON. Frames are separated by "---\n"

This call is the same as NewFrameReader(ContentTypeYAML, rc)

type FrameWriter 

type FrameWriter interface {
	ContentTyped
	Writer
}

FrameWriter is a ContentType-specific io.Writer that writes given frames in an applicable way to an underlying io.Writer stream

func NewFrameWriter 

func NewFrameWriter(contentType ContentType, w Writer) FrameWriter

NewFrameWriter returns a new FrameWriter for the given Writer and ContentType

func NewJSONFrameWriter 

func NewJSONFrameWriter(w Writer) FrameWriter

NewJSONFrameWriter returns a FrameWriter that writes JSON frames without separation (i.e. "{ ... }{ ... }{ ... }" on the wire)

This call is the same as NewFrameWriter(ContentTypeYAML, w)

func NewYAMLFrameWriter 

func NewYAMLFrameWriter(w Writer) FrameWriter

NewYAMLFrameWriter returns a FrameWriter that writes YAML frames separated by "---\n"

This call is the same as NewFrameWriter(ContentTypeYAML, w)

type ReadCloser 

type ReadCloser io.ReadCloser

ReadCloser in this package is an alias for io.ReadCloser. It helps in Godoc to locate helpers in this package which returns writers (i.e. FromFile and FromBytes)

func FromBytes 

func FromBytes(content []byte) ReadCloser

FromBytes returns a ReadCloser from the given byte content.

func FromFile 

func FromFile(filePath string) ReadCloser

FromFile returns a ReadCloser from the given file, or a ReadCloser which returns the given file open error when read.

type Serializer 

type Serializer interface {
	// Decoder is a high-level interface for decoding Kubernetes API Machinery objects read from
	// a FrameWriter. The decoder can be customized by passing some options (e.g. WithDecodingOptions)
	// to this call.
	// The decoder supports both "classic" API Machinery objects and controller-runtime CRDs
	Decoder(optsFn ...DecodingOptionsFunc) Decoder

	// Encoder is a high-level interface for encoding Kubernetes API Machinery objects and writing them
	// to a FrameWriter. The encoder can be customized by passing some options (e.g. WithEncodingOptions)
	// to this call.
	// The encoder supports both "classic" API Machinery objects and controller-runtime CRDs
	Encoder(optsFn ...EncodingOptionsFunc) Encoder

	// Converter is a high-level interface for converting objects between different versions
	// The converter supports both "classic" API Machinery objects and controller-runtime CRDs
	Converter() Converter

	// Defaulter is a high-level interface for accessing defaulting functions in a scheme
	Defaulter() Defaulter

	// Scheme provides access to the underlying runtime.Scheme, may be used for low-level access to
	// the "type universe" and advanced conversion/defaulting features
	Scheme() *runtime.Scheme

	// Codecs provides access to the underlying serializer.CodecFactory, may be used if low-level access
	// is needed for encoding and decoding
	Codecs() *k8sserializer.CodecFactory
}

Serializer is an interface providing high-level decoding/encoding functionality for types registered in a *runtime.Scheme

func NewSerializer 

func NewSerializer(scheme *runtime.Scheme, codecs *k8sserializer.CodecFactory) Serializer

NewSerializer constructs a new serializer based on a scheme, and optionally a codecfactory

type UnrecognizedTypeError 

type UnrecognizedTypeError struct {
	GVK   schema.GroupVersionKind
	Cause UnrecognizedTypeErrorCause
	Err   error
	// contains filtered or unexported fields
}

UnrecognizedTypeError describes that no such group, version and/or kind was registered in the scheme

func NewUnrecognizedGroupError 

func NewUnrecognizedGroupError(gvk schema.GroupVersionKind, err error) *UnrecognizedTypeError

NewUnrecognizedGroupError returns information about that the encountered group was unknown

func NewUnrecognizedKindError 

func NewUnrecognizedKindError(gvk schema.GroupVersionKind, err error) *UnrecognizedTypeError

NewUnrecognizedKindError returns information about that the encountered kind (in a known group & version) was unknown

func NewUnrecognizedVersionError 

func NewUnrecognizedVersionError(allGVs []schema.GroupVersion, gvk schema.GroupVersionKind, err error) *UnrecognizedTypeError

NewUnrecognizedVersionError returns information about that the encountered version (in a known group) was unknown

func (*UnrecognizedTypeError) Error 

func (e *UnrecognizedTypeError) Error() string

Error implements the error interface

func (*UnrecognizedTypeError) GroupVersionKind 

func (e *UnrecognizedTypeError) GroupVersionKind() schema.GroupVersionKind

GroupVersionKind returns the GroupVersionKind for the error

func (*UnrecognizedTypeError) Unwrap 

func (e *UnrecognizedTypeError) Unwrap() error

Unwrap allows the standard library unwrap the underlying error

type UnrecognizedTypeErrorCause 

type UnrecognizedTypeErrorCause string

UnrecognizedTypeErrorCause is a typed string, describing the error cause for 

const (
	// UnrecognizedTypeErrorCauseUnknownGroup describes that an unknown API group was encountered
	UnrecognizedTypeErrorCauseUnknownGroup UnrecognizedTypeErrorCause = "UnknownGroup"

	// UnrecognizedTypeErrorCauseUnknownVersion describes that an unknown API version for a known group was encountered
	UnrecognizedTypeErrorCauseUnknownVersion UnrecognizedTypeErrorCause = "UnknownVersion"

	// UnrecognizedTypeErrorCauseUnknownKind describes that an unknown kind for a known group and version was encountered
	UnrecognizedTypeErrorCauseUnknownKind UnrecognizedTypeErrorCause = "UnknownKind"
)

type Writer 

type Writer io.Writer

Writer in this package is an alias for io.Writer. It helps in Godoc to locate helpers in this package which returns writers (i.e. ToBytes)

func ToBytes 

func ToBytes(p []byte) Writer

ToBytes returns a Writer which can be passed to NewFrameWriter. The Writer writes directly to an underlying byte array. The byte array must be of enough length in order to write.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.