1/*
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 rest
18
19import (
20	"net/http"
21	"net/url"
22	"os"
23	"strconv"
24	"strings"
25	"time"
26
27	"k8s.io/apimachinery/pkg/runtime"
28	"k8s.io/apimachinery/pkg/runtime/schema"
29	"k8s.io/apimachinery/pkg/types"
30	"k8s.io/client-go/util/flowcontrol"
31)
32
33const (
34	// Environment variables: Note that the duration should be long enough that the backoff
35	// persists for some reasonable time (i.e. 120 seconds).  The typical base might be "1".
36	envBackoffBase     = "KUBE_CLIENT_BACKOFF_BASE"
37	envBackoffDuration = "KUBE_CLIENT_BACKOFF_DURATION"
38)
39
40// Interface captures the set of operations for generically interacting with Kubernetes REST apis.
41type Interface interface {
42	GetRateLimiter() flowcontrol.RateLimiter
43	Verb(verb string) *Request
44	Post() *Request
45	Put() *Request
46	Patch(pt types.PatchType) *Request
47	Get() *Request
48	Delete() *Request
49	APIVersion() schema.GroupVersion
50}
51
52// ClientContentConfig controls how RESTClient communicates with the server.
53//
54// TODO: ContentConfig will be updated to accept a Negotiator instead of a
55//   NegotiatedSerializer and NegotiatedSerializer will be removed.
56type ClientContentConfig struct {
57	// AcceptContentTypes specifies the types the client will accept and is optional.
58	// If not set, ContentType will be used to define the Accept header
59	AcceptContentTypes string
60	// ContentType specifies the wire format used to communicate with the server.
61	// This value will be set as the Accept header on requests made to the server if
62	// AcceptContentTypes is not set, and as the default content type on any object
63	// sent to the server. If not set, "application/json" is used.
64	ContentType string
65	// GroupVersion is the API version to talk to. Must be provided when initializing
66	// a RESTClient directly. When initializing a Client, will be set with the default
67	// code version. This is used as the default group version for VersionedParams.
68	GroupVersion schema.GroupVersion
69	// Negotiator is used for obtaining encoders and decoders for multiple
70	// supported media types.
71	Negotiator runtime.ClientNegotiator
72}
73
74// RESTClient imposes common Kubernetes API conventions on a set of resource paths.
75// The baseURL is expected to point to an HTTP or HTTPS path that is the parent
76// of one or more resources.  The server should return a decodable API resource
77// object, or an api.Status object which contains information about the reason for
78// any failure.
79//
80// Most consumers should use client.New() to get a Kubernetes API client.
81type RESTClient struct {
82	// base is the root URL for all invocations of the client
83	base *url.URL
84	// versionedAPIPath is a path segment connecting the base URL to the resource root
85	versionedAPIPath string
86
87	// content describes how a RESTClient encodes and decodes responses.
88	content ClientContentConfig
89
90	// creates BackoffManager that is passed to requests.
91	createBackoffMgr func() BackoffManager
92
93	// rateLimiter is shared among all requests created by this client unless specifically
94	// overridden.
95	rateLimiter flowcontrol.RateLimiter
96
97	// warningHandler is shared among all requests created by this client.
98	// If not set, defaultWarningHandler is used.
99	warningHandler WarningHandler
100
101	// Set specific behavior of the client.  If not set http.DefaultClient will be used.
102	Client *http.Client
103}
104
105// NewRESTClient creates a new RESTClient. This client performs generic REST functions
106// such as Get, Put, Post, and Delete on specified paths.
107func NewRESTClient(baseURL *url.URL, versionedAPIPath string, config ClientContentConfig, rateLimiter flowcontrol.RateLimiter, client *http.Client) (*RESTClient, error) {
108	if len(config.ContentType) == 0 {
109		config.ContentType = "application/json"
110	}
111
112	base := *baseURL
113	if !strings.HasSuffix(base.Path, "/") {
114		base.Path += "/"
115	}
116	base.RawQuery = ""
117	base.Fragment = ""
118
119	return &RESTClient{
120		base:             &base,
121		versionedAPIPath: versionedAPIPath,
122		content:          config,
123		createBackoffMgr: readExpBackoffConfig,
124		rateLimiter:      rateLimiter,
125
126		Client: client,
127	}, nil
128}
129
130// GetRateLimiter returns rate limiter for a given client, or nil if it's called on a nil client
131func (c *RESTClient) GetRateLimiter() flowcontrol.RateLimiter {
132	if c == nil {
133		return nil
134	}
135	return c.rateLimiter
136}
137
138// readExpBackoffConfig handles the internal logic of determining what the
139// backoff policy is.  By default if no information is available, NoBackoff.
140// TODO Generalize this see #17727 .
141func readExpBackoffConfig() BackoffManager {
142	backoffBase := os.Getenv(envBackoffBase)
143	backoffDuration := os.Getenv(envBackoffDuration)
144
145	backoffBaseInt, errBase := strconv.ParseInt(backoffBase, 10, 64)
146	backoffDurationInt, errDuration := strconv.ParseInt(backoffDuration, 10, 64)
147	if errBase != nil || errDuration != nil {
148		return &NoBackoff{}
149	}
150	return &URLBackoff{
151		Backoff: flowcontrol.NewBackOff(
152			time.Duration(backoffBaseInt)*time.Second,
153			time.Duration(backoffDurationInt)*time.Second)}
154}
155
156// Verb begins a request with a verb (GET, POST, PUT, DELETE).
157//
158// Example usage of RESTClient's request building interface:
159// c, err := NewRESTClient(...)
160// if err != nil { ... }
161// resp, err := c.Verb("GET").
162//  Path("pods").
163//  SelectorParam("labels", "area=staging").
164//  Timeout(10*time.Second).
165//  Do()
166// if err != nil { ... }
167// list, ok := resp.(*api.PodList)
168//
169func (c *RESTClient) Verb(verb string) *Request {
170	return NewRequest(c).Verb(verb)
171}
172
173// Post begins a POST request. Short for c.Verb("POST").
174func (c *RESTClient) Post() *Request {
175	return c.Verb("POST")
176}
177
178// Put begins a PUT request. Short for c.Verb("PUT").
179func (c *RESTClient) Put() *Request {
180	return c.Verb("PUT")
181}
182
183// Patch begins a PATCH request. Short for c.Verb("Patch").
184func (c *RESTClient) Patch(pt types.PatchType) *Request {
185	return c.Verb("PATCH").SetHeader("Content-Type", string(pt))
186}
187
188// Get begins a GET request. Short for c.Verb("GET").
189func (c *RESTClient) Get() *Request {
190	return c.Verb("GET")
191}
192
193// Delete begins a DELETE request. Short for c.Verb("DELETE").
194func (c *RESTClient) Delete() *Request {
195	return c.Verb("DELETE")
196}
197
198// APIVersion returns the APIVersion this RESTClient is expected to use.
199func (c *RESTClient) APIVersion() schema.GroupVersion {
200	return c.content.GroupVersion
201}
202