github.com/timstclair/heapster@v0.20.0-alpha1/Godeps/_workspace/src/k8s.io/kubernetes/pkg/api/rest/rest.go (about) 1 /* 2 Copyright 2014 The Kubernetes Authors All rights reserved. 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 "io" 21 "net/http" 22 "net/url" 23 24 "k8s.io/kubernetes/pkg/api" 25 "k8s.io/kubernetes/pkg/api/unversioned" 26 "k8s.io/kubernetes/pkg/runtime" 27 "k8s.io/kubernetes/pkg/watch" 28 ) 29 30 //TODO: 31 // Storage interfaces need to be separated into two groups; those that operate 32 // on collections and those that operate on individually named items. 33 // Collection interfaces: 34 // (Method: Current -> Proposed) 35 // GET: Lister -> CollectionGetter 36 // WATCH: Watcher -> CollectionWatcher 37 // CREATE: Creater -> CollectionCreater 38 // DELETE: (n/a) -> CollectionDeleter 39 // UPDATE: (n/a) -> CollectionUpdater 40 // 41 // Single item interfaces: 42 // (Method: Current -> Proposed) 43 // GET: Getter -> NamedGetter 44 // WATCH: (n/a) -> NamedWatcher 45 // CREATE: (n/a) -> NamedCreater 46 // DELETE: Deleter -> NamedDeleter 47 // UPDATE: Update -> NamedUpdater 48 49 // Storage is a generic interface for RESTful storage services. 50 // Resources which are exported to the RESTful API of apiserver need to implement this interface. It is expected 51 // that objects may implement any of the below interfaces. 52 type Storage interface { 53 // New returns an empty object that can be used with Create and Update after request data has been put into it. 54 // This object must be a pointer type for use with Codec.DecodeInto([]byte, runtime.Object) 55 New() runtime.Object 56 } 57 58 // Lister is an object that can retrieve resources that match the provided field and label criteria. 59 type Lister interface { 60 // NewList returns an empty object that can be used with the List call. 61 // This object must be a pointer type for use with Codec.DecodeInto([]byte, runtime.Object) 62 NewList() runtime.Object 63 // List selects resources in the storage which match to the selector. 'options' can be nil. 64 List(ctx api.Context, options *unversioned.ListOptions) (runtime.Object, error) 65 } 66 67 // Getter is an object that can retrieve a named RESTful resource. 68 type Getter interface { 69 // Get finds a resource in the storage by name and returns it. 70 // Although it can return an arbitrary error value, IsNotFound(err) is true for the 71 // returned error value err when the specified resource is not found. 72 Get(ctx api.Context, name string) (runtime.Object, error) 73 } 74 75 // GetterWithOptions is an object that retrieve a named RESTful resource and takes 76 // additional options on the get request. It allows a caller to also receive the 77 // subpath of the GET request. 78 type GetterWithOptions interface { 79 // Get finds a resource in the storage by name and returns it. 80 // Although it can return an arbitrary error value, IsNotFound(err) is true for the 81 // returned error value err when the specified resource is not found. 82 // The options object passed to it is of the same type returned by the NewGetOptions 83 // method. 84 Get(ctx api.Context, name string, options runtime.Object) (runtime.Object, error) 85 86 // NewGetOptions returns an empty options object that will be used to pass 87 // options to the Get method. It may return a bool and a string, if true, the 88 // value of the request path below the object will be included as the named 89 // string in the serialization of the runtime object. E.g., returning "path" 90 // will convert the trailing request scheme value to "path" in the map[string][]string 91 // passed to the convertor. 92 NewGetOptions() (runtime.Object, bool, string) 93 } 94 95 // Deleter is an object that can delete a named RESTful resource. 96 type Deleter interface { 97 // Delete finds a resource in the storage and deletes it. 98 // Although it can return an arbitrary error value, IsNotFound(err) is true for the 99 // returned error value err when the specified resource is not found. 100 // Delete *may* return the object that was deleted, or a status object indicating additional 101 // information about deletion. 102 Delete(ctx api.Context, name string) (runtime.Object, error) 103 } 104 105 // GracefulDeleter knows how to pass deletion options to allow delayed deletion of a 106 // RESTful object. 107 type GracefulDeleter interface { 108 // Delete finds a resource in the storage and deletes it. 109 // If options are provided, the resource will attempt to honor them or return an invalid 110 // request error. 111 // Although it can return an arbitrary error value, IsNotFound(err) is true for the 112 // returned error value err when the specified resource is not found. 113 // Delete *may* return the object that was deleted, or a status object indicating additional 114 // information about deletion. 115 Delete(ctx api.Context, name string, options *api.DeleteOptions) (runtime.Object, error) 116 } 117 118 // GracefulDeleteAdapter adapts the Deleter interface to GracefulDeleter 119 type GracefulDeleteAdapter struct { 120 Deleter 121 } 122 123 // Delete implements RESTGracefulDeleter in terms of Deleter 124 func (w GracefulDeleteAdapter) Delete(ctx api.Context, name string, options *api.DeleteOptions) (runtime.Object, error) { 125 return w.Deleter.Delete(ctx, name) 126 } 127 128 // Creater is an object that can create an instance of a RESTful object. 129 type Creater interface { 130 // New returns an empty object that can be used with Create after request data has been put into it. 131 // This object must be a pointer type for use with Codec.DecodeInto([]byte, runtime.Object) 132 New() runtime.Object 133 134 // Create creates a new version of a resource. 135 Create(ctx api.Context, obj runtime.Object) (runtime.Object, error) 136 } 137 138 // NamedCreater is an object that can create an instance of a RESTful object using a name parameter. 139 type NamedCreater interface { 140 // New returns an empty object that can be used with Create after request data has been put into it. 141 // This object must be a pointer type for use with Codec.DecodeInto([]byte, runtime.Object) 142 New() runtime.Object 143 144 // Create creates a new version of a resource. It expects a name parameter from the path. 145 // This is needed for create operations on subresources which include the name of the parent 146 // resource in the path. 147 Create(ctx api.Context, name string, obj runtime.Object) (runtime.Object, error) 148 } 149 150 // Updater is an object that can update an instance of a RESTful object. 151 type Updater interface { 152 // New returns an empty object that can be used with Update after request data has been put into it. 153 // This object must be a pointer type for use with Codec.DecodeInto([]byte, runtime.Object) 154 New() runtime.Object 155 156 // Update finds a resource in the storage and updates it. Some implementations 157 // may allow updates creates the object - they should set the created boolean 158 // to true. 159 Update(ctx api.Context, obj runtime.Object) (runtime.Object, bool, error) 160 } 161 162 // CreaterUpdater is a storage object that must support both create and update. 163 // Go prevents embedded interfaces that implement the same method. 164 type CreaterUpdater interface { 165 Creater 166 Update(ctx api.Context, obj runtime.Object) (runtime.Object, bool, error) 167 } 168 169 // CreaterUpdater must satisfy the Updater interface. 170 var _ Updater = CreaterUpdater(nil) 171 172 // Patcher is a storage object that supports both get and update. 173 type Patcher interface { 174 Getter 175 Updater 176 } 177 178 // Watcher should be implemented by all Storage objects that 179 // want to offer the ability to watch for changes through the watch api. 180 type Watcher interface { 181 // 'label' selects on labels; 'field' selects on the object's fields. Not all fields 182 // are supported; an error should be returned if 'field' tries to select on a field that 183 // isn't supported. 'resourceVersion' allows for continuing/starting a watch at a 184 // particular version. 185 Watch(ctx api.Context, options *unversioned.ListOptions) (watch.Interface, error) 186 } 187 188 // StandardStorage is an interface covering the common verbs. Provided for testing whether a 189 // resource satisfies the normal storage methods. Use Storage when passing opaque storage objects. 190 type StandardStorage interface { 191 Getter 192 Lister 193 CreaterUpdater 194 GracefulDeleter 195 Watcher 196 } 197 198 // Redirector know how to return a remote resource's location. 199 type Redirector interface { 200 // ResourceLocation should return the remote location of the given resource, and an optional transport to use to request it, or an error. 201 ResourceLocation(ctx api.Context, id string) (remoteLocation *url.URL, transport http.RoundTripper, err error) 202 } 203 204 // Responder abstracts the normal response behavior for a REST method and is passed to callers that 205 // may wish to handle the response directly in some cases, but delegate to the normal error or object 206 // behavior in other cases. 207 type Responder interface { 208 // Object writes the provided object to the response. Invoking this method multiple times is undefined. 209 Object(statusCode int, obj runtime.Object) 210 // Error writes the provided error to the response. This method may only be invoked once. 211 Error(err error) 212 } 213 214 // Connecter is a storage object that responds to a connection request. 215 type Connecter interface { 216 // Connect returns an http.Handler that will handle the request/response for a given API invocation. 217 // The provided responder may be used for common API responses. The responder will write both status 218 // code and body, so the ServeHTTP method should exit after invoking the responder. The Handler will 219 // be used for a single API request and then discarded. The Responder is guaranteed to write to the 220 // same http.ResponseWriter passed to ServeHTTP. 221 Connect(ctx api.Context, id string, options runtime.Object, r Responder) (http.Handler, error) 222 223 // NewConnectOptions returns an empty options object that will be used to pass 224 // options to the Connect method. If nil, then a nil options object is passed to 225 // Connect. It may return a bool and a string. If true, the value of the request 226 // path below the object will be included as the named string in the serialization 227 // of the runtime object. 228 NewConnectOptions() (runtime.Object, bool, string) 229 230 // ConnectMethods returns the list of HTTP methods handled by Connect 231 ConnectMethods() []string 232 } 233 234 // ResourceStreamer is an interface implemented by objects that prefer to be streamed from the server 235 // instead of decoded directly. 236 type ResourceStreamer interface { 237 // InputStream should return an io.ReadCloser if the provided object supports streaming. The desired 238 // api version and a accept header (may be empty) are passed to the call. If no error occurs, 239 // the caller may return a flag indicating whether the result should be flushed as writes occur 240 // and a content type string that indicates the type of the stream. 241 // If a null stream is returned, a StatusNoContent response wil be generated. 242 InputStream(apiVersion, acceptHeader string) (stream io.ReadCloser, flush bool, mimeType string, err error) 243 } 244 245 // StorageMetadata is an optional interface that callers can implement to provide additional 246 // information about their Storage objects. 247 type StorageMetadata interface { 248 // ProducesMIMETypes returns a list of the MIME types the specified HTTP verb (GET, POST, DELETE, 249 // PATCH) can respond with. 250 ProducesMIMETypes(verb string) []string 251 } 252 253 // ConnectRequest is an object passed to admission control for Connect operations 254 type ConnectRequest struct { 255 // Name is the name of the object on which the connect request was made 256 Name string 257 258 // Options is the options object passed to the connect request. See the NewConnectOptions method on Connecter 259 Options runtime.Object 260 261 // ResourcePath is the path for the resource in the REST server (ie. "pods/proxy") 262 ResourcePath string 263 } 264 265 // IsAnAPIObject makes ConnectRequest a runtime.Object 266 func (*ConnectRequest) IsAnAPIObject() {}