Debian Codegraph @

pkg/registry/rest/rest.go

raw
1 /*
2 Copyright 2014 The Kubernetes Authors.
3
4 Licensed under the Apache License, Version 2.0 (the "License");
5 you may not use this file except in compliance with the License.
6 You may obtain a copy of the License at
7
8 http://www.apache.org/licenses/LICENSE-2.0
9
10 Unless required by applicable law or agreed to in writing, software
11 distributed under the License is distributed on an "AS IS" BASIS,
12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 See the License for the specific language governing permissions and
14 limitations under the License.
15 */
16
17 package rest
18
19 import (
20 "context"
21 "io"
22 "net/http"
23 "net/url"
24
25 "sigs.k8s.io/structured-merge-diff/v4/fieldpath"
26
27 metainternalversion "k8s.io/apimachinery/pkg/apis/meta/internalversion"
28 metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
29 "k8s.io/apimachinery/pkg/runtime"
30 "k8s.io/apimachinery/pkg/runtime/schema"
31 "k8s.io/apimachinery/pkg/watch"
32 )
33
34 //TODO:
35 // Storage interfaces need to be separated into two groups; those that operate
36 // on collections and those that operate on individually named items.
37 // Collection interfaces:
38 // (Method: Current -> Proposed)
39 // GET: Lister -> CollectionGetter
40 // WATCH: Watcher -> CollectionWatcher
41 // CREATE: Creater -> CollectionCreater
42 // DELETE: (n/a) -> CollectionDeleter
43 // UPDATE: (n/a) -> CollectionUpdater
44 //
45 // Single item interfaces:
46 // (Method: Current -> Proposed)
47 // GET: Getter -> NamedGetter
48 // WATCH: (n/a) -> NamedWatcher
49 // CREATE: (n/a) -> NamedCreater
50 // DELETE: Deleter -> NamedDeleter
51 // UPDATE: Update -> NamedUpdater
52
53 // Storage is a generic interface for RESTful storage services.
54 // Resources which are exported to the RESTful API of apiserver need to implement this interface. It is expected
55 // that objects may implement any of the below interfaces.
56 //
57 // Consider using StorageWithReadiness whenever possible.
58 type Storage interface {
59 // New returns an empty object that can be used with Create and Update after request data has been put into it.
60 // This object must be a pointer type for use with Codec.DecodeInto([]byte, runtime.Object)
61 New() runtime.Object
62
63 // Destroy cleans up its resources on shutdown.
64 // Destroy has to be implemented in thread-safe way and be prepared
65 // for being called more than once.
66 Destroy()
67 }
68
69 // StorageWithReadiness extends Storage interface with the readiness check.
70 type StorageWithReadiness interface {
71 Storage
72
73 // ReadinessCheck allows for checking storage readiness.
74 ReadinessCheck() error
75 }
76
77 // Scoper indicates what scope the resource is at. It must be specified.
78 // It is usually provided automatically based on your strategy.
79 type Scoper interface {
80 // NamespaceScoped returns true if the storage is namespaced
81 NamespaceScoped() bool
82 }
83
84 // KindProvider specifies a different kind for its API than for its internal storage. This is necessary for external
85 // objects that are not compiled into the api server. For such objects, there is no in-memory representation for
86 // the object, so they must be represented as generic objects (e.g. runtime.Unknown), but when we present the object as part of
87 // API discovery we want to present the specific kind, not the generic internal representation.
88 type KindProvider interface {
89 Kind() string
90 }
91
92 // ShortNamesProvider is an interface for RESTful storage services. Delivers a list of short names for a resource. The list is used by kubectl to have short names representation of resources.
93 type ShortNamesProvider interface {
94 ShortNames() []string
95 }
96
97 // CategoriesProvider allows a resource to specify which groups of resources (categories) it's part of. Categories can
98 // be used by API clients to refer to a batch of resources by using a single name (e.g. "all" could translate to "pod,rc,svc,...").
99 type CategoriesProvider interface {
100 Categories() []string
101 }
102
103 // SingularNameProvider returns singular name of resources. This is used by kubectl discovery to have singular
104 // name representation of resources. In case of shortcut conflicts(with CRD shortcuts) singular name should always map to this resource.
105 type SingularNameProvider interface {
106 GetSingularName() string
107 }
108
109 // GroupVersionKindProvider is used to specify a particular GroupVersionKind to discovery. This is used for polymorphic endpoints
110 // which generally point to foreign versions. Scale refers to Scale.v1beta1.extensions for instance.
111 // This trumps KindProvider since it is capable of providing the information required.
112 // TODO KindProvider (only used by federation) should be removed and replaced with this, but that presents greater risk late in 1.8.
113 type GroupVersionKindProvider interface {
114 GroupVersionKind(containingGV schema.GroupVersion) schema.GroupVersionKind
115 }
116
117 // GroupVersionAcceptor is used to determine if a particular GroupVersion is acceptable to send to an endpoint.
118 // This is used for endpoints which accept multiple versions (which is extremely rare).
119 // The only known instance is pods/evictions which accepts policy/v1, but also policy/v1beta1 for backwards compatibility.
120 type GroupVersionAcceptor interface {
121 AcceptsGroupVersion(gv schema.GroupVersion) bool
122 }
123
124 // Lister is an object that can retrieve resources that match the provided field and label criteria.
125 type Lister interface {
126 // NewList returns an empty object that can be used with the List call.
127 // This object must be a pointer type for use with Codec.DecodeInto([]byte, runtime.Object)
128 NewList() runtime.Object
129 // List selects resources in the storage which match to the selector. 'options' can be nil.
130 List(ctx context.Context, options *metainternalversion.ListOptions) (runtime.Object, error)
131 // TableConvertor ensures all list implementers also implement table conversion
132 TableConvertor
133 }
134
135 // Getter is an object that can retrieve a named RESTful resource.
136 type Getter interface {
137 // Get finds a resource in the storage by name and returns it.
138 // Although it can return an arbitrary error value, IsNotFound(err) is true for the
139 // returned error value err when the specified resource is not found.
140 Get(ctx context.Context, name string, options *metav1.GetOptions) (runtime.Object, error)
141 }
142
143 // GetterWithOptions is an object that retrieve a named RESTful resource and takes
144 // additional options on the get request. It allows a caller to also receive the
145 // subpath of the GET request.
146 type GetterWithOptions interface {
147 // Get finds a resource in the storage by name and returns it.
148 // Although it can return an arbitrary error value, IsNotFound(err) is true for the
149 // returned error value err when the specified resource is not found.
150 // The options object passed to it is of the same type returned by the NewGetOptions
151 // method.
152 // TODO: Pass metav1.GetOptions.
153 Get(ctx context.Context, name string, options runtime.Object) (runtime.Object, error)
154
155 // NewGetOptions returns an empty options object that will be used to pass
156 // options to the Get method. It may return a bool and a string, if true, the
157 // value of the request path below the object will be included as the named
158 // string in the serialization of the runtime object. E.g., returning "path"
159 // will convert the trailing request scheme value to "path" in the map[string][]string
160 // passed to the converter.
161 NewGetOptions() (runtime.Object, bool, string)
162 }
163
164 type TableConvertor interface {
165 ConvertToTable(ctx context.Context, object runtime.Object, tableOptions runtime.Object) (*metav1.Table, error)
166 }
167
168 // GracefulDeleter knows how to pass deletion options to allow delayed deletion of a
169 // RESTful object.
170 type GracefulDeleter interface {
171 // Delete finds a resource in the storage and deletes it.
172 // The delete attempt is validated by the deleteValidation first.
173 // If options are provided, the resource will attempt to honor them or return an invalid
174 // request error.
175 // Although it can return an arbitrary error value, IsNotFound(err) is true for the
176 // returned error value err when the specified resource is not found.
177 // Delete *may* return the object that was deleted, or a status object indicating additional
178 // information about deletion.
179 // It also returns a boolean which is set to true if the resource was instantly
180 // deleted or false if it will be deleted asynchronously.
181 Delete(ctx context.Context, name string, deleteValidation ValidateObjectFunc, options *metav1.DeleteOptions) (runtime.Object, bool, error)
182 }
183
184 // MayReturnFullObjectDeleter may return deleted object (instead of a simple status) on deletion.
185 type MayReturnFullObjectDeleter interface {
186 DeleteReturnsDeletedObject() bool
187 }
188
189 // CollectionDeleter is an object that can delete a collection
190 // of RESTful resources.
191 type CollectionDeleter interface {
192 // DeleteCollection selects all resources in the storage matching given 'listOptions'
193 // and deletes them. The delete attempt is validated by the deleteValidation first.
194 // If 'options' are provided, the resource will attempt to honor them or return an
195 // invalid request error.
196 // DeleteCollection may not be atomic - i.e. it may delete some objects and still
197 // return an error after it. On success, returns a list of deleted objects.
198 DeleteCollection(ctx context.Context, deleteValidation ValidateObjectFunc, options *metav1.DeleteOptions, listOptions *metainternalversion.ListOptions) (runtime.Object, error)
199 }
200
201 // Creater is an object that can create an instance of a RESTful object.
202 type Creater interface {
203 // New returns an empty object that can be used with Create after request data has been put into it.
204 // This object must be a pointer type for use with Codec.DecodeInto([]byte, runtime.Object)
205 New() runtime.Object
206
207 // Create creates a new version of a resource.
208 Create(ctx context.Context, obj runtime.Object, createValidation ValidateObjectFunc, options *metav1.CreateOptions) (runtime.Object, error)
209 }
210
211 // NamedCreater is an object that can create an instance of a RESTful object using a name parameter.
212 type NamedCreater interface {
213 // New returns an empty object that can be used with Create after request data has been put into it.
214 // This object must be a pointer type for use with Codec.DecodeInto([]byte, runtime.Object)
215 New() runtime.Object
216
217 // Create creates a new version of a resource. It expects a name parameter from the path.
218 // This is needed for create operations on subresources which include the name of the parent
219 // resource in the path.
220 Create(ctx context.Context, name string, obj runtime.Object, createValidation ValidateObjectFunc, options *metav1.CreateOptions) (runtime.Object, error)
221 }
222
223 // SubresourceObjectMetaPreserver adds configuration options to a Creater for subresources.
224 type SubresourceObjectMetaPreserver interface {
225 // PreserveRequestObjectMetaSystemFieldsOnSubresourceCreate indicates that a
226 // handler should preserve fields of ObjectMeta that are managed by the system.
227 PreserveRequestObjectMetaSystemFieldsOnSubresourceCreate() bool
228 }
229
230 // UpdatedObjectInfo provides information about an updated object to an Updater.
231 // It requires access to the old object in order to return the newly updated object.
232 type UpdatedObjectInfo interface {
233 // Returns preconditions built from the updated object, if applicable.
234 // May return nil, or a preconditions object containing nil fields,
235 // if no preconditions can be determined from the updated object.
236 Preconditions() *metav1.Preconditions
237
238 // UpdatedObject returns the updated object, given a context and old object.
239 // The only time an empty oldObj should be passed in is if a "create on update" is occurring (there is no oldObj).
240 UpdatedObject(ctx context.Context, oldObj runtime.Object) (newObj runtime.Object, err error)
241 }
242
243 // ValidateObjectFunc is a function to act on a given object. An error may be returned
244 // if the hook cannot be completed. A ValidateObjectFunc may NOT transform the provided
245 // object.
246 type ValidateObjectFunc func(ctx context.Context, obj runtime.Object) error
247
248 // ValidateAllObjectFunc is a "admit everything" instance of ValidateObjectFunc.
249 func ValidateAllObjectFunc(ctx context.Context, obj runtime.Object) error {
250 return nil
251 }
252
253 // ValidateObjectUpdateFunc is a function to act on a given object and its predecessor.
254 // An error may be returned if the hook cannot be completed. An UpdateObjectFunc
255 // may NOT transform the provided object.
256 type ValidateObjectUpdateFunc func(ctx context.Context, obj, old runtime.Object) error
257
258 // ValidateAllObjectUpdateFunc is a "admit everything" instance of ValidateObjectUpdateFunc.
259 func ValidateAllObjectUpdateFunc(ctx context.Context, obj, old runtime.Object) error {
260 return nil
261 }
262
263 // Updater is an object that can update an instance of a RESTful object.
264 type Updater interface {
265 // New returns an empty object that can be used with Update after request data has been put into it.
266 // This object must be a pointer type for use with Codec.DecodeInto([]byte, runtime.Object)
267 New() runtime.Object
268
269 // Update finds a resource in the storage and updates it. Some implementations
270 // may allow updates creates the object - they should set the created boolean
271 // to true.
272 Update(ctx context.Context, name string, objInfo UpdatedObjectInfo, createValidation ValidateObjectFunc, updateValidation ValidateObjectUpdateFunc, forceAllowCreate bool, options *metav1.UpdateOptions) (runtime.Object, bool, error)
273 }
274
275 // CreaterUpdater is a storage object that must support both create and update.
276 // Go prevents embedded interfaces that implement the same method.
277 type CreaterUpdater interface {
278 Creater
279 Update(ctx context.Context, name string, objInfo UpdatedObjectInfo, createValidation ValidateObjectFunc, updateValidation ValidateObjectUpdateFunc, forceAllowCreate bool, options *metav1.UpdateOptions) (runtime.Object, bool, error)
280 }
281
282 // CreaterUpdater must satisfy the Updater interface.
283 var _ Updater = CreaterUpdater(nil)
284
285 // Patcher is a storage object that supports both get and update.
286 type Patcher interface {
287 Getter
288 Updater
289 }
290
291 // Watcher should be implemented by all Storage objects that
292 // want to offer the ability to watch for changes through the watch api.
293 type Watcher interface {
294 // 'label' selects on labels; 'field' selects on the object's fields. Not all fields
295 // are supported; an error should be returned if 'field' tries to select on a field that
296 // isn't supported. 'resourceVersion' allows for continuing/starting a watch at a
297 // particular version.
298 Watch(ctx context.Context, options *metainternalversion.ListOptions) (watch.Interface, error)
299 }
300
301 // StandardStorage is an interface covering the common verbs. Provided for testing whether a
302 // resource satisfies the normal storage methods. Use Storage when passing opaque storage objects.
303 type StandardStorage interface {
304 Getter
305 Lister
306 CreaterUpdater
307 GracefulDeleter
308 CollectionDeleter
309 Watcher
310
311 // Destroy cleans up its resources on shutdown.
312 // Destroy has to be implemented in thread-safe way and be prepared
313 // for being called more than once.
314 Destroy()
315 }
316
317 // Redirector know how to return a remote resource's location.
318 type Redirector interface {
319 // ResourceLocation should return the remote location of the given resource, and an optional transport to use to request it, or an error.
320 ResourceLocation(ctx context.Context, id string) (remoteLocation *url.URL, transport http.RoundTripper, err error)
321 }
322
323 // Responder abstracts the normal response behavior for a REST method and is passed to callers that
324 // may wish to handle the response directly in some cases, but delegate to the normal error or object
325 // behavior in other cases.
326 type Responder interface {
327 // Object writes the provided object to the response. Invoking this method multiple times is undefined.
328 Object(statusCode int, obj runtime.Object)
329 // Error writes the provided error to the response. This method may only be invoked once.
330 Error(err error)
331 }
332
333 // Connecter is a storage object that responds to a connection request.
334 type Connecter interface {
335 // Connect returns an http.Handler that will handle the request/response for a given API invocation.
336 // The provided responder may be used for common API responses. The responder will write both status
337 // code and body, so the ServeHTTP method should exit after invoking the responder. The Handler will
338 // be used for a single API request and then discarded. The Responder is guaranteed to write to the
339 // same http.ResponseWriter passed to ServeHTTP.
340 Connect(ctx context.Context, id string, options runtime.Object, r Responder) (http.Handler, error)
341
342 // NewConnectOptions returns an empty options object that will be used to pass
343 // options to the Connect method. If nil, then a nil options object is passed to
344 // Connect. It may return a bool and a string. If true, the value of the request
345 // path below the object will be included as the named string in the serialization
346 // of the runtime object.
347 NewConnectOptions() (runtime.Object, bool, string)
348
349 // ConnectMethods returns the list of HTTP methods handled by Connect
350 ConnectMethods() []string
351 }
352
353 // ResourceStreamer is an interface implemented by objects that prefer to be streamed from the server
354 // instead of decoded directly.
355 type ResourceStreamer interface {
356 // InputStream should return an io.ReadCloser if the provided object supports streaming. The desired
357 // api version and an accept header (may be empty) are passed to the call. If no error occurs,
358 // the caller may return a flag indicating whether the result should be flushed as writes occur
359 // and a content type string that indicates the type of the stream.
360 // If a null stream is returned, a StatusNoContent response wil be generated.
361 InputStream(ctx context.Context, apiVersion, acceptHeader string) (stream io.ReadCloser, flush bool, mimeType string, err error)
362 }
363
364 // StorageMetadata is an optional interface that callers can implement to provide additional
365 // information about their Storage objects.
366 type StorageMetadata interface {
367 // ProducesMIMETypes returns a list of the MIME types the specified HTTP verb (GET, POST, DELETE,
368 // PATCH) can respond with.
369 ProducesMIMETypes(verb string) []string
370
371 // ProducesObject returns an object the specified HTTP verb respond with. It will overwrite storage object if
372 // it is not nil. Only the type of the return object matters, the value will be ignored.
373 ProducesObject(verb string) interface{}
374 }
375
376 // StorageVersionProvider is an optional interface that a storage object can
377 // implement if it wishes to disclose its storage version.
378 type StorageVersionProvider interface {
379 // StorageVersion returns a group versioner, which will outputs the gvk
380 // an object will be converted to before persisted in etcd, given a
381 // list of kinds the object might belong to.
382 StorageVersion() runtime.GroupVersioner
383 }
384
385 // ResetFieldsStrategy is an optional interface that a storage object can
386 // implement if it wishes to provide the fields reset by its strategies.
387 type ResetFieldsStrategy interface {
388 GetResetFields() map[fieldpath.APIVersion]*fieldpath.Set
389 }
390
391 // ResetFieldsFilterStrategy is an optional interface that a storage object can
392 // implement if it wishes to provide a fields filter reset by its strategies.
393 type ResetFieldsFilterStrategy interface {
394 GetResetFieldsFilter() map[fieldpath.APIVersion]fieldpath.Filter
395 }
396
397 // CreateUpdateResetFieldsStrategy is a union of RESTCreateUpdateStrategy
398 // and ResetFieldsStrategy.
399 type CreateUpdateResetFieldsStrategy interface {
400 RESTCreateUpdateStrategy
401 ResetFieldsStrategy
402 }
403
404 // UpdateResetFieldsStrategy is a union of RESTUpdateStrategy
405 // and ResetFieldsStrategy.
406 type UpdateResetFieldsStrategy interface {
407 RESTUpdateStrategy
408 ResetFieldsStrategy
409 }
410
411 // CorruptObjectDeleterProvider is an interface the storage implements
412 // to support unsafe deletion of corrupt object(s). It returns a
413 // GracefulDeleter that is used to perform unsafe deletion of corrupt object(s).
414 type CorruptObjectDeleterProvider interface {
415 GetCorruptObjDeleter() GracefulDeleter
416 }