runtime

package
v0.0.2 Latest Latest
Warning

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

 Go to latest Published: Mar 17, 2022 License: BSD-3-Clause Imports: 17 Imported by: 42

README

k8s.io/apimachinery/pkg/runtime

Documentation

Index

Constants

View Source 
const (
	PathType   = "path"
	QueryType  = "query"
	HeaderType = "header"
)
View Source 
const (
	ContentTypeJSON     string = "application/json"
	ContentTypeYAML     string = "application/yaml"
	ContentTypeProtobuf string = "application/vnd.kubernetes.protobuf"
)
View Source 
const (
	// APIVersionInternal may be used if you are registering a type that should not
	// be considered stable or serialized - it is a convention only and has no
	// special behavior in this package.
	APIVersionInternal = "__internal"
)

Variables

View Source 
var DefaultFramer = defaultFramer{}

DefaultFramer is valid for any stream that can read objects serially without any separation in the stream.

Functions

func CheckCodec 

func CheckCodec(c Codec, internalType Object) error

CheckCodec makes sure that the codec can encode objects like internalType, decode all of the external types listed, and also decode them into the given object. (Will modify internalObject.) (Assumes JSON serialization.) TODO: verify that the correct external version is chosen on encode...

func Convert_runtime_Object_To_runtime_RawExtension 

func Convert_runtime_Object_To_runtime_RawExtension(in *Object, out *RawExtension) error

func Convert_runtime_RawExtension_To_runtime_Object 

func Convert_runtime_RawExtension_To_runtime_Object(in *RawExtension, out *Object) error

func DecodeInto 

func DecodeInto(d Decoder, data []byte, into Object) error

DecodeInto performs a Decode into the provided object.

func DecodeList 

func DecodeList(objects []Object, decoders ...Decoder) []error

DecodeList alters the list in place, attempting to decode any objects found in the list that have the Unknown type. Any errors that occur are returned after the entire list is processed. Decoders are tried in order.

func Encode 

func Encode(e Encoder, obj Object) ([]byte, error)

Encode is a convenience wrapper for encoding to a []byte from an Encoder

func EncodeList 

func EncodeList(e Encoder, objects []Object) error

EncodeList ensures that each object in an array is converted to a Unknown{} in serialized form. TODO: accept a content type.

func EncodeOrDie 

func EncodeOrDie(e Encoder, obj Object) string

EncodeOrDie is a version of Encode which will panic instead of returning an error. For tests.

func EnforcePtr 

func EnforcePtr(obj interface{}) (reflect.Value, error)

EnforcePtr ensures that obj is a pointer of some sort. Returns a reflect.Value of the dereferenced pointer, ensuring that it is settable/addressable. Returns an error if this is not possible.

func Field 

func Field(v reflect.Value, fieldName string, dest interface{}) error

Field puts the value of fieldName, which must be a member of v, into dest, which must be a variable to which this field's value can be assigned.

func FieldPtr 

func FieldPtr(v reflect.Value, fieldName string, dest interface{}) error

FieldPtr puts the address of fieldName, which must be a member of v, into dest, which must be an address of a variable to which this field's address can be assigned.

func IsMissingKind 

func IsMissingKind(err error) bool

IsMissingKind returns true if the error indicates that the provided object is missing a 'Kind' field.

func IsMissingVersion 

func IsMissingVersion(err error) bool

IsMissingVersion returns true if the error indicates that the provided object is missing a 'Version' field.

func IsNotRegisteredError 

func IsNotRegisteredError(err error) bool

IsNotRegisteredError returns true if the error indicates the provided object or input data is not registered.

func IsStrictDecodingError 

func IsStrictDecodingError(err error) bool

IsStrictDecodingError returns true if the error indicates that the provided object strictness violations.

func NewMissingKindErr 

func NewMissingKindErr(data string) error

func NewMissingVersionErr 

func NewMissingVersionErr(data string) error

func NewNotRegisteredErrForKind 

func NewNotRegisteredErrForKind(schemeName string) error

func NewNotRegisteredErrForTarget 

func NewNotRegisteredErrForTarget(schemeName string, t reflect.Type) error

func NewNotRegisteredErrForType 

func NewNotRegisteredErrForType(schemeName string, t reflect.Type) error

func NewNotRegisteredGVKErrForTarget 

func NewNotRegisteredGVKErrForTarget(schemeName string) error

func NewStrictDecodingError 

func NewStrictDecodingError(message string, data string) error

NewStrictDecodingError creates a new strictDecodingError object.

func SetField 

func SetField(src interface{}, v reflect.Value, fieldName string) error

SetField puts the value of src, into fieldName, which must be a member of v. The value of src must be assignable to the field.

func SetZeroValue 

func SetZeroValue(objPtr Object) error

SetZeroValue would set the object of objPtr to zero value of its type.

Types

type CacheableObject 

type CacheableObject interface {
	// CacheEncode writes an object to a stream. The <encode> function will
	// be used in case of cache miss. The <encode> function takes ownership
	// of the object.
	// If CacheableObject is a wrapper, then deep-copy of the wrapped object
	// should be passed to <encode> function.
	// CacheEncode assumes that for two different calls with the same <id>,
	// <encode> function will also be the same.
	CacheEncode(id Identifier, encode func(Object, io.Writer) error, w io.Writer) error
	// GetObject returns a deep-copy of an object to be encoded - the caller of
	// GetObject() is the owner of returned object. The reason for making a copy
	// is to avoid bugs, where caller modifies the object and forgets to copy it,
	// thus modifying the object for everyone.
	// The object returned by GetObject should be the same as the one that is supposed
	// to be passed to <encode> function in CacheEncode method.
	// If CacheableObject is a wrapper, the copy of wrapped object should be returned.
	GetObject() Object
}

CacheableObject allows an object to cache its different serializations to avoid performing the same serialization multiple times.

type ClientNegotiator 

type ClientNegotiator interface {
	// Encoder returns the appropriate encoder for the provided contentType (e.g. application/json)
	// and any optional mediaType parameters (e.g. pretty=1), or an error. If no serializer is found
	// a NegotiateError will be returned. The current client implementations consider params to be
	// optional modifiers to the contentType and will ignore unrecognized parameters.
	Encoder(contentType string, params map[string]string) (Encoder, error)
	// Decoder returns the appropriate decoder for the provided contentType (e.g. application/json)
	// and any optional mediaType parameters (e.g. pretty=1), or an error. If no serializer is found
	// a NegotiateError will be returned. The current client implementations consider params to be
	// optional modifiers to the contentType and will ignore unrecognized parameters.
	Decoder(contentType string, params map[string]string) (Decoder, error)
	// StreamDecoder returns the appropriate stream decoder for the provided contentType (e.g.
	// application/json) and any optional mediaType parameters (e.g. pretty=1), or an error. If no
	// serializer is found a NegotiateError will be returned. The Serializer and Framer will always
	// be returned if a Decoder is returned. The current client implementations consider params to be
	// optional modifiers to the contentType and will ignore unrecognized parameters.
	StreamDecoder(contentType string, params map[string]string) (Decoder, Serializer, Framer, error)
}

ClientNegotiator handles turning an HTTP content type into the appropriate encoder. Use NewClientNegotiator or NewVersionedClientNegotiator to create this interface from a NegotiatedSerializer.

func NewClientNegotiator 

func NewClientNegotiator(serializer NegotiatedSerializer) ClientNegotiator

NewClientNegotiator will attempt to retrieve the appropriate encoder, decoder, or stream decoder for a given content type. Does not perform any conversion, but will encode the object to the desired group, version, and kind. Use when creating a client.

type Codec 

type Codec Serializer

Codec is a Serializer that deals with the details of versioning objects. It offers the same interface as Serializer, so this is a marker to consumers that care about the version of the objects they receive.

func NewCodec 

func NewCodec(e Encoder, d Decoder) Codec

NewCodec creates a Codec from an Encoder and Decoder.

type Decoder 

type Decoder interface {
	// Decode attempts to deserialize the provided data using either the innate typing of the scheme or the
	// default kind, group, and version provided. It returns a decoded object as well as the kind, group, and
	// version from the serialized data, or an error. If into is non-nil, it will be used as the target type
	// and implementations may choose to use it rather than reallocating an object. However, the object is not
	// guaranteed to be populated. The returned object is not guaranteed to match into. If defaults are
	// provided, they are applied to the data by default. If no defaults or partial defaults are provided, the
	// type of the into may be used to guide conversion decisions.
	Decode(data []byte, into Object) (Object, error)
}

Decoder attempts to load an object from data.

type Encoder 

type Encoder interface {
	// Encode writes an object to a stream. Implementations may return errors if the versions are
	// incompatible, or if no conversion is defined.
	Encode(obj Object, w io.Writer) error
	// Identifier returns an identifier of the encoder.
	// Identifiers of two different encoders should be equal if and only if for every input
	// object it will be encoded to the same representation by both of them.
	//
	// Identifier is intended for use with CacheableObject#CacheEncode method. In order to
	// correctly handle CacheableObject, Encode() method should look similar to below, where
	// doEncode() is the encoding logic of implemented encoder:
	//   func (e *MyEncoder) Encode(obj Object, w io.Writer) error {
	//     if co, ok := obj.(CacheableObject); ok {
	//       return co.CacheEncode(e.Identifier(), e.doEncode, w)
	//     }
	//     return e.doEncode(obj, w)
	//   }
	Identifier() Identifier
}

Encoder writes objects to a serialized form

type Framer 

type Framer interface {
	NewFrameReader(r io.ReadCloser) io.ReadCloser
	NewFrameWriter(w io.Writer) io.Writer
}

Framer is a factory for creating readers and writers that obey a particular framing pattern.

type Identifier 

type Identifier string

Identifier represents an identifier. Identitier of two different objects should be equal if and only if for every input the output they produce is exactly the same.

type NegotiateError 

type NegotiateError struct {
	ContentType string
	Stream      bool
}

NegotiateError is returned when a ClientNegotiator is unable to locate a serializer for the requested operation.

func (NegotiateError) Error 

func (e NegotiateError) Error() string

type NegotiatedSerializer 

type NegotiatedSerializer interface {
	// SupportedMediaTypes is the media types supported for reading and writing single objects.
	SupportedMediaTypes() []SerializerInfo

	// EncoderForVersion returns an encoder that ensures objects being written to the provided
	// serializer are in the provided group version.
	EncoderForVersion(serializer Encoder) Encoder
	// DecoderForVersion returns a decoder that ensures objects being read by the provided
	// serializer are in the provided group version by default.
	DecoderToVersion(serializer Decoder) Decoder
}

NegotiatedSerializer is an interface used for obtaining encoders, decoders, and serializers for multiple supported media types. This would commonly be accepted by a server component that performs HTTP content negotiation to accept multiple formats.

func NewSimpleNegotiatedSerializer 

func NewSimpleNegotiatedSerializer(info SerializerInfo) NegotiatedSerializer

type NestedObjectDecoder 

type NestedObjectDecoder interface {
	DecodeNestedObjects(d Decoder) error
}

NestedObjectDecoder is an optional interface that objects may implement to be given an opportunity to decode any nested Objects / RawExtensions during serialization.

type NestedObjectEncoder 

type NestedObjectEncoder interface {
	EncodeNestedObjects(e Encoder) error
}

NestedObjectEncoder is an optional interface that objects may implement to be given an opportunity to encode any nested Objects / RawExtensions during serialization.

type NoopDecoder 

type NoopDecoder struct {
	Encoder
}

NoopDecoder converts an Encoder to a Serializer or Codec for code that expects them but only uses encoding.

func (NoopDecoder) Decode 

func (n NoopDecoder) Decode(data []byte, into Object) (Object, error)

type NoopEncoder 

type NoopEncoder struct {
	Decoder
}

NoopEncoder converts an Decoder to a Serializer or Codec for code that expects them but only uses decoding.

func (NoopEncoder) Encode 

func (n NoopEncoder) Encode(obj Object, w io.Writer) error

func (NoopEncoder) Identifier 

func (n NoopEncoder) Identifier() Identifier

Identifier implements runtime.Encoder interface.

type Object 

type Object interface{}

Object interface must be supported by all API types registered with Scheme. Since objects in a scheme are expected to be serialized to the wire, the interface an Object must provide to the Scheme allows serializers to set the kind, version, and group the object is represented as. An Object may choose to return a no-op ObjectKindAccessor in cases where it is not expected to be serialized.

func Decode 

func Decode(d Decoder, data []byte, into Object) (Object, error)

Decode is a convenience wrapper for decoding data into an Object.

func NewEncodable 

func NewEncodable(e Encoder, obj Object) Object

NewEncodable creates an object that will be encoded with the provided codec on demand. Provided as a convenience for test cases dealing with internal objects.

func NewEncodableList 

func NewEncodableList(e Encoder, objects []Object) []Object

NewEncodableList creates an object that will be encoded with the provided codec on demand. Provided as a convenience for test cases dealing with internal objects.

type ObjectConvertor 

type ObjectConvertor interface {
	// Convert attempts to convert one object into another, or returns an error. This
	// method does not mutate the in object, but the in and out object might share data structures,
	// i.e. the out object cannot be mutated without mutating the in object as well.
	// The context argument will be passed to all nested conversions.
	Convert(in, out, context interface{}) error
	// ConvertToVersion takes the provided object and converts it the provided version. This
	// method does not mutate the in object, but the in and out object might share data structures,
	// i.e. the out object cannot be mutated without mutating the in object as well.
	// This method is similar to Convert() but handles specific details of choosing the correct
	// output version.
	ConvertToVersion(in Object) (out Object, err error)
	ConvertFieldLabel(label, value string) (string, string, error)
}

ObjectConvertor converts an object to a different version.

type ObjectDefaulter 

type ObjectDefaulter interface {
	// Default takes an object (must be a pointer) and applies any default values.
	// Defaulters may not error.
	Default(in Object)
}

type ObjectVersioner 

type ObjectVersioner interface {
	ConvertToVersion(in Object) (out Object, err error)
}

type ParameterCodec 

type ParameterCodec interface {
	// DecodeParameters takes the given url.Values in the specified group version and decodes them
	// into the provided object, or returns an error.
	DecodeParameters(parameter *Parameters, into Object) error
	// EncodeParameters encodes the provided object as query parameters or returns an error.
	EncodeParameters(obj Object) (*Parameters, error)

	RouteBuilderParameters(rb *restful.RouteBuilder, obj Object)
}

ParameterCodec defines methods for serializing and deserializing API objects to url.Values and performing any necessary conversion. Unlike the normal Codec, query parameters are not self describing and the desired version must be specified.

func NewParameterCodec 

func NewParameterCodec() ParameterCodec

NewParameterCodec creates a ParameterCodec capable of transforming url values into versioned objects and back.

type Parameters 

type Parameters struct {
	Header http.Header
	Query  url.Values
	Path   map[string]string
}

func NewParameters 

func NewParameters() *Parameters

type RawExtension 

type RawExtension struct {
	// Raw is the underlying serialization of this object.
	//
	// TODO: Determine how to detect ContentType and ContentEncoding of 'Raw' data.
	Raw []byte `json:"-" protobuf:"bytes,1,opt,name=raw"`
	// Object can hold a representation of this extension - useful for working with versioned
	// structs.
	Object Object `json:"-"`
}

RawExtension is used to hold extensions in external versions.

To use this, make a field which has RawExtension as its type in your external, versioned struct, and Object in your internal struct. You also need to register your various plugin types.

// Internal package: 

type MyAPIObject struct {
	runtime.TypeMeta `json:",inline"`
	MyPlugin runtime.Object `json:"myPlugin"`
}

type PluginA struct {
	AOption string `json:"aOption"`
}

// External package: 

type MyAPIObject struct {
	runtime.TypeMeta `json:",inline"`
	MyPlugin runtime.RawExtension `json:"myPlugin"`
}

type PluginA struct {
	AOption string `json:"aOption"`
}

// On the wire, the JSON will look something like this: 

{
	"kind":"MyAPIObject",
	"apiVersion":"v1",
	"myPlugin": {
		"kind":"PluginA",
		"aOption":"foo",
	},
}

So what happens? Decode first uses json or yaml to unmarshal the serialized data into your external MyAPIObject. That causes the raw JSON to be stored, but not unpacked. The next step is to copy (using pkg/conversion) into the internal struct. The runtime package's DefaultScheme has conversion functions installed which will unpack the JSON stored in RawExtension, turning it into the correct object type, and storing it in the Object. (TODO: In the case where the object is of an unknown type, a runtime.Unknown object will be created and stored.)

+k8s:deepcopy-gen=true +protobuf=true +k8s:openapi-gen=true

func (RawExtension) MarshalJSON 

func (re RawExtension) MarshalJSON() ([]byte, error)

MarshalJSON may get called on pointers or values, so implement MarshalJSON on value. http://stackoverflow.com/questions/21390979/custom-marshaljson-never-gets-called-in-go

func (*RawExtension) UnmarshalJSON 

func (re *RawExtension) UnmarshalJSON(in []byte) error

type Serializer 

type Serializer interface {
	Encoder
	Decoder
}

Serializer is the core interface for transforming objects into a serialized format and back. Implementations may choose to perform conversion of the object, but no assumptions should be made.

func NewBase64Serializer 

func NewBase64Serializer(e Encoder, d Decoder) Serializer

type SerializerInfo 

type SerializerInfo struct {
	// MediaType is the value that represents this serializer over the wire.
	MediaType string
	// MediaTypeType is the first part of the MediaType ("application" in "application/json").
	MediaTypeType string
	// MediaTypeSubType is the second part of the MediaType ("json" in "application/json").
	MediaTypeSubType string
	// EncodesAsText indicates this serializer can be encoded to UTF-8 safely.
	EncodesAsText bool
	// Serializer is the individual object serializer for this media type.
	Serializer Serializer
	// PrettySerializer, if set, can serialize this object in a form biased towards
	// readability.
	PrettySerializer Serializer
	// StreamSerializer, if set, describes the streaming serialization format
	// for this media type.
	StreamSerializer *StreamSerializerInfo
}

SerializerInfo contains information about a specific serialization format

func SerializerInfoForMediaType 

func SerializerInfoForMediaType(types []SerializerInfo, mediaType string) (SerializerInfo, bool)

SerializerInfoForMediaType returns the first info in types that has a matching media type (which cannot include media-type parameters), or the first info with an empty media type, or false if no type matches.

type StorageSerializer 

type StorageSerializer interface {
	// SupportedMediaTypes are the media types supported for reading and writing objects.
	SupportedMediaTypes() []SerializerInfo

	// UniversalDeserializer returns a Serializer that can read objects in multiple supported formats
	// by introspecting the data at rest.
	UniversalDeserializer() Decoder

	// EncoderForVersion returns an encoder that ensures objects being written to the provided
	// serializer are in the provided group version.
	EncoderForVersion(serializer Encoder) Encoder
	// DecoderForVersion returns a decoder that ensures objects being read by the provided
	// serializer are in the provided group version by default.
	DecoderToVersion(serializer Decoder) Decoder
}

StorageSerializer is an interface used for obtaining encoders, decoders, and serializers that can read and write data at rest. This would commonly be used by client tools that must read files, or server side storage interfaces that persist restful objects.

type StreamSerializerInfo 

type StreamSerializerInfo struct {
	// EncodesAsText indicates this serializer can be encoded to UTF-8 safely.
	EncodesAsText bool
	// Serializer is the top level object serializer for this type when streaming
	Serializer
	// Framer is the factory for retrieving streams that separate objects on the wire
	Framer
}

StreamSerializerInfo contains information about a specific stream serialization format

type TypeMeta 

type TypeMeta struct {
	// +optional
	APIVersion string `json:"apiVersion,omitempty" yaml:"apiVersion,omitempty" protobuf:"bytes,1,opt,name=apiVersion"`
	// +optional
	Kind string `json:"kind,omitempty" yaml:"kind,omitempty" protobuf:"bytes,2,opt,name=kind"`
}

TypeMeta is shared by all top level objects. The proper way to use it is to inline it in your type, like this: 

type MyAwesomeAPIObject struct {
     runtime.TypeMeta    `json:",inline"`
     ... // other fields
}

func (obj *MyAwesomeAPIObject) SetGroupVersionKind(gvk *metav1.GroupVersionKind) { metav1.UpdateTypeMeta(obj,gvk) }; GroupVersionKind() *GroupVersionKind

TypeMeta is provided here for convenience. You may use it directly from this package or define your own with the same fields.

+k8s:deepcopy-gen=false +protobuf=true +k8s:openapi-gen=true

type Unknown 

type Unknown struct {
	TypeMeta `json:",inline" protobuf:"bytes,1,opt,name=typeMeta"`
	// Raw will hold the complete serialized object which couldn't be matched
	// with a registered type. Most likely, nothing should be done with this
	// except for passing it through the system.
	Raw []byte `protobuf:"bytes,1,opt,name=raw"`
	// ContentEncoding is encoding used to encode 'Raw' data.
	// Unspecified means no encoding.
	ContentEncoding string `protobuf:"bytes,2,opt,name=contentEncoding"`
	// ContentType  is serialization method used to serialize 'Raw'.
	// Unspecified means ContentTypeJSON.
	ContentType string `protobuf:"bytes,3,opt,name=contentType"`
}

Unknown allows api objects with unknown types to be passed-through. This can be used to deal with the API objects from a plug-in. Unknown objects still have functioning TypeMeta features-- kind, version, etc. TODO: Make this object have easy access to field based accessors and settors for metadata and field mutatation.

+k8s:deepcopy-gen=true +k8s:deepcopy-gen:interfaces=github.com/yubo/golib/runtime.Object +protobuf=true +k8s:openapi-gen=true

func (*Unknown) DeepCopy 

func (in *Unknown) DeepCopy() *Unknown

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new Unknown.

func (*Unknown) DeepCopyInto 

func (in *Unknown) DeepCopyInto(out *Unknown)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (Unknown) MarshalJSON 

func (e Unknown) MarshalJSON() ([]byte, error)

Marshal may get called on pointers or values, so implement MarshalJSON on value. http://stackoverflow.com/questions/21390979/custom-marshaljson-never-gets-called-in-go

func (*Unknown) UnmarshalJSON 

func (e *Unknown) UnmarshalJSON(in []byte) error

type Unstructured 

type Unstructured interface {
	Object
	// NewEmptyInstance returns a new instance of the concrete type containing only kind/apiVersion and no other data.
	// This should be called instead of reflect.New() for unstructured types because the go type alone does not preserve kind/apiVersion info.
	NewEmptyInstance() Unstructured
	// UnstructuredContent returns a non-nil map with this object's contents. Values may be
	// []interface{}, map[string]interface{}, or any primitive type. Contents are typically serialized to
	// and from JSON. SetUnstructuredContent should be used to mutate the contents.
	UnstructuredContent() map[string]interface{}
	// SetUnstructuredContent updates the object content to match the provided map.
	SetUnstructuredContent(map[string]interface{})
	// IsList returns true if this type is a list or matches the list convention - has an array called "items".
	IsList() bool
	// EachListItem should pass a single item out of the list as an Object to the provided function. Any
	// error should terminate the iteration. If IsList() returns false, this method should return an error
	// instead of calling the provided function.
	EachListItem(func(Object) error) error
}

Unstructured objects store values as map[string]interface{}, with only values that can be serialized to JSON allowed.

type Validator 

type Validator interface {
	Validate() error
}

type WithVersionEncoder 

type WithVersionEncoder struct {
	//Version GroupVersioner
	Encoder
}

WithVersionEncoder serializes an object and ensures the GVK is set.

func (WithVersionEncoder) Encode 

func (e WithVersionEncoder) Encode(obj Object, stream io.Writer) error

Encode does not do conversion. It sets the gvk during serialization.

type WithoutVersionDecoder 

type WithoutVersionDecoder struct {
	Decoder
}

WithoutVersionDecoder clears the group version kind of a deserialized object.

func (WithoutVersionDecoder) Decode 

func (d WithoutVersionDecoder) Decode(data []byte, into Object) (Object, error)

Decode does not do conversion. It removes the gvk during deserialization.

Source Files

View all Source files

Directories

Path Synopsis
json
recognizer
streaming
Package streaming implements encoder and decoder for streams of runtime.Objects over io.Writer/Readers.
 Package streaming implements encoder and decoder for streams of runtime.Objects over io.Writer/Readers.
versioning
yaml

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.