blob: 699ff13e04f312de77599c15f1db1673771de68b [file] [log] [blame]
sslobodrd046be82019-01-16 10:02:22 -05001/*
2Copyright 2014 The Kubernetes Authors.
3
4Licensed under the Apache License, Version 2.0 (the "License");
5you may not use this file except in compliance with the License.
6You may obtain a copy of the License at
7
8 http://www.apache.org/licenses/LICENSE-2.0
9
10Unless required by applicable law or agreed to in writing, software
11distributed under the License is distributed on an "AS IS" BASIS,
12WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13See the License for the specific language governing permissions and
14limitations under the License.
15*/
16
17package runtime
18
19import (
20 "io"
21 "net/url"
22
23 "k8s.io/apimachinery/pkg/runtime/schema"
24)
25
26const (
27 // APIVersionInternal may be used if you are registering a type that should not
28 // be considered stable or serialized - it is a convention only and has no
29 // special behavior in this package.
30 APIVersionInternal = "__internal"
31)
32
33// GroupVersioner refines a set of possible conversion targets into a single option.
34type GroupVersioner interface {
35 // KindForGroupVersionKinds returns a desired target group version kind for the given input, or returns ok false if no
36 // target is known. In general, if the return target is not in the input list, the caller is expected to invoke
37 // Scheme.New(target) and then perform a conversion between the current Go type and the destination Go type.
38 // Sophisticated implementations may use additional information about the input kinds to pick a destination kind.
39 KindForGroupVersionKinds(kinds []schema.GroupVersionKind) (target schema.GroupVersionKind, ok bool)
40}
41
42// Encoder writes objects to a serialized form
43type Encoder interface {
44 // Encode writes an object to a stream. Implementations may return errors if the versions are
45 // incompatible, or if no conversion is defined.
46 Encode(obj Object, w io.Writer) error
47}
48
49// Decoder attempts to load an object from data.
50type Decoder interface {
51 // Decode attempts to deserialize the provided data using either the innate typing of the scheme or the
52 // default kind, group, and version provided. It returns a decoded object as well as the kind, group, and
53 // version from the serialized data, or an error. If into is non-nil, it will be used as the target type
54 // and implementations may choose to use it rather than reallocating an object. However, the object is not
55 // guaranteed to be populated. The returned object is not guaranteed to match into. If defaults are
56 // provided, they are applied to the data by default. If no defaults or partial defaults are provided, the
57 // type of the into may be used to guide conversion decisions.
58 Decode(data []byte, defaults *schema.GroupVersionKind, into Object) (Object, *schema.GroupVersionKind, error)
59}
60
61// Serializer is the core interface for transforming objects into a serialized format and back.
62// Implementations may choose to perform conversion of the object, but no assumptions should be made.
63type Serializer interface {
64 Encoder
65 Decoder
66}
67
68// Codec is a Serializer that deals with the details of versioning objects. It offers the same
69// interface as Serializer, so this is a marker to consumers that care about the version of the objects
70// they receive.
71type Codec Serializer
72
73// ParameterCodec defines methods for serializing and deserializing API objects to url.Values and
74// performing any necessary conversion. Unlike the normal Codec, query parameters are not self describing
75// and the desired version must be specified.
76type ParameterCodec interface {
77 // DecodeParameters takes the given url.Values in the specified group version and decodes them
78 // into the provided object, or returns an error.
79 DecodeParameters(parameters url.Values, from schema.GroupVersion, into Object) error
80 // EncodeParameters encodes the provided object as query parameters or returns an error.
81 EncodeParameters(obj Object, to schema.GroupVersion) (url.Values, error)
82}
83
84// Framer is a factory for creating readers and writers that obey a particular framing pattern.
85type Framer interface {
86 NewFrameReader(r io.ReadCloser) io.ReadCloser
87 NewFrameWriter(w io.Writer) io.Writer
88}
89
90// SerializerInfo contains information about a specific serialization format
91type SerializerInfo struct {
92 // MediaType is the value that represents this serializer over the wire.
93 MediaType string
94 // EncodesAsText indicates this serializer can be encoded to UTF-8 safely.
95 EncodesAsText bool
96 // Serializer is the individual object serializer for this media type.
97 Serializer Serializer
98 // PrettySerializer, if set, can serialize this object in a form biased towards
99 // readability.
100 PrettySerializer Serializer
101 // StreamSerializer, if set, describes the streaming serialization format
102 // for this media type.
103 StreamSerializer *StreamSerializerInfo
104}
105
106// StreamSerializerInfo contains information about a specific stream serialization format
107type StreamSerializerInfo struct {
108 // EncodesAsText indicates this serializer can be encoded to UTF-8 safely.
109 EncodesAsText bool
110 // Serializer is the top level object serializer for this type when streaming
111 Serializer
112 // Framer is the factory for retrieving streams that separate objects on the wire
113 Framer
114}
115
116// NegotiatedSerializer is an interface used for obtaining encoders, decoders, and serializers
117// for multiple supported media types. This would commonly be accepted by a server component
118// that performs HTTP content negotiation to accept multiple formats.
119type NegotiatedSerializer interface {
120 // SupportedMediaTypes is the media types supported for reading and writing single objects.
121 SupportedMediaTypes() []SerializerInfo
122
123 // EncoderForVersion returns an encoder that ensures objects being written to the provided
124 // serializer are in the provided group version.
125 EncoderForVersion(serializer Encoder, gv GroupVersioner) Encoder
126 // DecoderForVersion returns a decoder that ensures objects being read by the provided
127 // serializer are in the provided group version by default.
128 DecoderToVersion(serializer Decoder, gv GroupVersioner) Decoder
129}
130
131// StorageSerializer is an interface used for obtaining encoders, decoders, and serializers
132// that can read and write data at rest. This would commonly be used by client tools that must
133// read files, or server side storage interfaces that persist restful objects.
134type StorageSerializer interface {
135 // SupportedMediaTypes are the media types supported for reading and writing objects.
136 SupportedMediaTypes() []SerializerInfo
137
138 // UniversalDeserializer returns a Serializer that can read objects in multiple supported formats
139 // by introspecting the data at rest.
140 UniversalDeserializer() Decoder
141
142 // EncoderForVersion returns an encoder that ensures objects being written to the provided
143 // serializer are in the provided group version.
144 EncoderForVersion(serializer Encoder, gv GroupVersioner) Encoder
145 // DecoderForVersion returns a decoder that ensures objects being read by the provided
146 // serializer are in the provided group version by default.
147 DecoderToVersion(serializer Decoder, gv GroupVersioner) Decoder
148}
149
150// NestedObjectEncoder is an optional interface that objects may implement to be given
151// an opportunity to encode any nested Objects / RawExtensions during serialization.
152type NestedObjectEncoder interface {
153 EncodeNestedObjects(e Encoder) error
154}
155
156// NestedObjectDecoder is an optional interface that objects may implement to be given
157// an opportunity to decode any nested Objects / RawExtensions during serialization.
158type NestedObjectDecoder interface {
159 DecodeNestedObjects(d Decoder) error
160}
161
162///////////////////////////////////////////////////////////////////////////////
163// Non-codec interfaces
164
165type ObjectDefaulter interface {
166 // Default takes an object (must be a pointer) and applies any default values.
167 // Defaulters may not error.
168 Default(in Object)
169}
170
171type ObjectVersioner interface {
172 ConvertToVersion(in Object, gv GroupVersioner) (out Object, err error)
173}
174
175// ObjectConvertor converts an object to a different version.
176type ObjectConvertor interface {
177 // Convert attempts to convert one object into another, or returns an error. This
178 // method does not mutate the in object, but the in and out object might share data structures,
179 // i.e. the out object cannot be mutated without mutating the in object as well.
180 // The context argument will be passed to all nested conversions.
181 Convert(in, out, context interface{}) error
182 // ConvertToVersion takes the provided object and converts it the provided version. This
183 // method does not mutate the in object, but the in and out object might share data structures,
184 // i.e. the out object cannot be mutated without mutating the in object as well.
185 // This method is similar to Convert() but handles specific details of choosing the correct
186 // output version.
187 ConvertToVersion(in Object, gv GroupVersioner) (out Object, err error)
188 ConvertFieldLabel(gvk schema.GroupVersionKind, label, value string) (string, string, error)
189}
190
191// ObjectTyper contains methods for extracting the APIVersion and Kind
192// of objects.
193type ObjectTyper interface {
194 // ObjectKinds returns the all possible group,version,kind of the provided object, true if
195 // the object is unversioned, or an error if the object is not recognized
196 // (IsNotRegisteredError will return true).
197 ObjectKinds(Object) ([]schema.GroupVersionKind, bool, error)
198 // Recognizes returns true if the scheme is able to handle the provided version and kind,
199 // or more precisely that the provided version is a possible conversion or decoding
200 // target.
201 Recognizes(gvk schema.GroupVersionKind) bool
202}
203
204// ObjectCreater contains methods for instantiating an object by kind and version.
205type ObjectCreater interface {
206 New(kind schema.GroupVersionKind) (out Object, err error)
207}
208
209// ResourceVersioner provides methods for setting and retrieving
210// the resource version from an API object.
211type ResourceVersioner interface {
212 SetResourceVersion(obj Object, version string) error
213 ResourceVersion(obj Object) (string, error)
214}
215
216// SelfLinker provides methods for setting and retrieving the SelfLink field of an API object.
217type SelfLinker interface {
218 SetSelfLink(obj Object, selfLink string) error
219 SelfLink(obj Object) (string, error)
220
221 // Knowing Name is sometimes necessary to use a SelfLinker.
222 Name(obj Object) (string, error)
223 // Knowing Namespace is sometimes necessary to use a SelfLinker
224 Namespace(obj Object) (string, error)
225}
226
227// Object interface must be supported by all API types registered with Scheme. Since objects in a scheme are
228// expected to be serialized to the wire, the interface an Object must provide to the Scheme allows
229// serializers to set the kind, version, and group the object is represented as. An Object may choose
230// to return a no-op ObjectKindAccessor in cases where it is not expected to be serialized.
231type Object interface {
232 GetObjectKind() schema.ObjectKind
233 DeepCopyObject() Object
234}
235
236// Unstructured objects store values as map[string]interface{}, with only values that can be serialized
237// to JSON allowed.
238type Unstructured interface {
239 Object
240 // UnstructuredContent returns a non-nil map with this object's contents. Values may be
241 // []interface{}, map[string]interface{}, or any primitive type. Contents are typically serialized to
242 // and from JSON. SetUnstructuredContent should be used to mutate the contents.
243 UnstructuredContent() map[string]interface{}
244 // SetUnstructuredContent updates the object content to match the provided map.
245 SetUnstructuredContent(map[string]interface{})
246 // IsList returns true if this type is a list or matches the list convention - has an array called "items".
247 IsList() bool
248 // EachListItem should pass a single item out of the list as an Object to the provided function. Any
249 // error should terminate the iteration. If IsList() returns false, this method should return an error
250 // instead of calling the provided function.
251 EachListItem(func(Object) error) error
252}