restclient

package
v0.0.2 Latest Latest
Warning

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

 Go to latest Published: Sep 9, 2024 License: Apache-2.0 Imports: 27 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	DefaultQPS   float32 = 5.0
	DefaultBurst int     = 10
)

Variables

View Source 
var NameMayNotBe = []string{".", ".."}

NameMayNotBe specifies strings that cannot be used as names specified as path segments (like the REST API or etcd store)

View Source 
var NameMayNotContain = []string{"/", "%"}

NameMayNotContain specifies substrings that cannot be used in names specified as path segments (like the REST API or etcd store)

Functions

func DefaultServerURL 

func DefaultServerURL(host, apiPath string, defaultTLS bool) (*url.URL, error)

DefaultServerURL converts a host, host:port, or URL string to the default base server API path to use with a Client at a given API version following the standard conventions for a rest client

func HTTPWrappersForConfig 

func HTTPWrappersForConfig(config *Config, rt http.RoundTripper) (http.RoundTripper, error)

HTTPWrappersForConfig wraps a round tripper with any relevant layered behavior from the config. Exposed to allow more clients that need HTTP-like behavior but then must hijack the underlying connection (like WebSocket or HTTP2 clients). Pure HTTP clients should use the higher level TransportFor or RESTClientFor methods.

func IsConfigTransportTLS 

func IsConfigTransportTLS(config Config) bool

IsConfigTransportTLS returns true if and only if the provided config will result in a protected connection to the server when it is passed to restclient.RESTClientFor(). Use to determine when to send credentials over the wire.

Note: the Insecure flag is ignored when testing for this value, so MITM attacks are still possible.

func IsConnectionReset 

func IsConnectionReset(err error) bool

IsConnectionReset Returns if the given err is "connection reset by peer" error.

func IsValidPathSegmentName 

func IsValidPathSegmentName(name string) []string

IsValidPathSegmentName validates the name can be safely encoded as a path segment

func IsValidPathSegmentPrefix 

func IsValidPathSegmentPrefix(name string) []string

IsValidPathSegmentPrefix validates the name can be used as a prefix for a name which will be encoded as a path segment It does not check for exact matches with disallowed names, since an arbitrary suffix might make the name valid

func LoadTLSFiles 

func LoadTLSFiles(c *Config) error

LoadTLSFiles copies the data from the CertFile, KeyFile, and CAFile fields into the CertData, KeyData, and CAFile fields, or returns an error. If no error is returned, all three fields are either populated or were empty to start.

func RegisterAuthProviderPlugin 

func RegisterAuthProviderPlugin(name string, plugin Factory) error

func TLSConfigFor 

func TLSConfigFor(config *Config) (*tls.Config, error)

TLSConfigFor returns a tls.Config that will provide the transport level security defined by the provided Config. Will return nil if no transport level security is requested.

func TransportFor 

func TransportFor(config *Config) (http.RoundTripper, error)

TransportFor returns an http.RoundTripper that will provide the authentication or transport level security defined by the provided Config. Will return the default http.DefaultTransport if no special case behavior is needed.

func ValidatePathSegmentName 

func ValidatePathSegmentName(name string, prefix bool) []string

ValidatePathSegmentName validates the name can be safely encoded as a path segment

Types

type AuthProvider 

type AuthProvider interface {
	// WrapTransport allows the plugin to create a modified RoundTripper that
	// attaches authorization headers (or other info) to requests.
	WrapTransport(http.RoundTripper) http.RoundTripper
	// Login allows the plugin to initialize its configuration. It must not
	// require direct user interaction.
	Login() error
}

type AuthProviderConfigPersister 

type AuthProviderConfigPersister interface {
	Persist(map[string]string) error
}

AuthProviderConfigPersister allows a plugin to persist configuration info for just itself.

type BackoffManager 

type BackoffManager interface {
	UpdateBackoff(actualUrl *url.URL, err error, responseCode int)
	CalculateBackoff(actualUrl *url.URL) time.Duration
	Sleep(d time.Duration)
}

type Config 

type Config struct {
	// Host must be a host string, a host:port pair, or a URL to the base of the apiserver.
	// If a URL is given then the (optional) Path of that URL represents a prefix that must
	// be appended to all request URIs used to access the apiserver. This allows a frontend
	// proxy to easily relocate all of the apiserver endpoints.
	Host string
	// APIPath is a sub-path that points to an API root.
	APIPath string

	// ContentConfig contains settings that affect how objects are transformed when
	// sent to the server.
	ContentConfig

	// Server requires Basic authentication
	Username string
	Password string

	// Server requires Bearer authentication. This client will not attempt to use
	// refresh tokens for an OAuth2 flow.
	// TODO: demonstrate an OAuth2 compatible client.
	BearerToken string

	// Path to a file containing a BearerToken.
	// If set, the contents are periodically read.
	// The last successfully read value takes precedence over BearerToken.
	BearerTokenFile string

	// Impersonate is the configuration that RESTClient will use for impersonation.
	Impersonate ImpersonationConfig

	// TLSClientConfig contains settings to enable transport layer security
	TLSClientConfig

	// UserAgent is an optional field that specifies the caller of this request.
	UserAgent string

	// Transport may be used for custom HTTP behavior. This attribute may not
	// be specified with the TLS client certificate options. Use WrapTransport
	// to provide additional per-server middleware behavior.
	Transport http.RoundTripper
	// WrapTransport will be invoked for custom HTTP behavior after the underlying
	// transport is initialized (either the transport created from TLSClientConfig,
	// Transport, or http.DefaultTransport). The config may layer other RoundTrippers
	// on top of the returned RoundTripper.
	//
	// A future release will change this field to an array. Use config.Wrap()
	// instead of setting this value directly.
	WrapTransport transport.WrapperFunc

	// QPS indicates the maximum QPS to the server from this client.
	// If it's zero, the created RESTClient will use DefaultQPS: 5
	QPS float32

	// Maximum burst for throttle.
	// If it's zero, the created RESTClient will use DefaultBurst: 10.
	Burst int

	// Rate limiter for limiting connections to the master from this client. If present overwrites QPS/Burst
	RateLimiter flowcontrol.RateLimiter

	// The maximum length of time to wait before giving up on a server request. A value of zero means no timeout.
	Timeout time.Duration

	// Dial specifies the dial function for creating unencrypted TCP connections.
	Dial func(ctx context.Context, network, address string) (net.Conn, error)
}

Config holds the common attributes that can be passed to a Kubernetes client on initialization.

func AddUserAgent 

func AddUserAgent(config *Config, userAgent string) *Config

AddUserAgent add user agent

func AnonymousClientConfig 

func AnonymousClientConfig(config *Config) *Config

AnonymousClientConfig returns a copy of the given config with all user credentials (cert/key, bearer token, and username/password) removed

func CopyConfig 

func CopyConfig(config *Config) *Config

CopyConfig returns a copy of the given config

func (*Config) GoString 

func (c *Config) GoString() string

GoString implements fmt.GoStringer and sanitizes sensitive fields of Config to prevent accidental leaking via logs.

func (*Config) String 

func (c *Config) String() string

String implements fmt.Stringer and sanitizes sensitive fields of Config to prevent accidental leaking via logs.

func (*Config) TransportConfig 

func (c *Config) TransportConfig() (*transport.Config, error)

TransportConfig converts a client config to an appropriate transport config.

func (*Config) Wrap 

func (c *Config) Wrap(fn transport.WrapperFunc)

Wrap adds a transport middleware function that will give the caller an opportunity to wrap the underlying http.RoundTripper prior to the first API call being made. The provided function is invoked after any existing transport wrappers are invoked.

type ContentConfig 

type ContentConfig struct {
	// AcceptContentTypes specifies the types the client will accept and is optional.
	// If not set, ContentType will be used to define the Accept header
	AcceptContentTypes string
	// ContentType specifies the wire format used to communicate with the server.
	// This value will be set as the Accept header on requests made to the server, and
	// as the default content type on any object sent to the server. If not set,
	// "application/json" is used.
	ContentType string
}

ContentConfig content configu eg. application/json

type Factory 

type Factory func(clusterAddress string, config map[string]string, persister AuthProviderConfigPersister) (AuthProvider, error)

Factory generates an AuthProvider plugin. 

clusterAddress is the address of the current cluster.
config is the initial configuration for this plugin.
persister allows the plugin to save updated configuration.

type HTTPClient 

type HTTPClient interface {
	Do(req *http.Request) (*http.Response, error)
}

HTTPClient is an interface for testing a request object.

type ImpersonationConfig 

type ImpersonationConfig struct {
	// UserName is the username to impersonate on each request.
	UserName string
	// Groups are the groups to impersonate on each request.
	Groups []string
	// Extra is a free-form field which can be used to link some authentication information
	// to authorization information.  This field allows you to impersonate it.
	Extra map[string][]string
}

ImpersonationConfig has all the available impersonation options

type Interface 

type Interface interface {
	GetRateLimiter() flowcontrol.RateLimiter
	Verb(verb string) *Request
	Post() *Request
	Put() *Request
	Patch(pt PatchType) *Request
	Get() *Request
	Delete() *Request
}

Interface captures the set of operations for generically interacting with normal rest client

type NoBackoff 

type NoBackoff struct {
}

NoBackoff is a stub implementation, can be used for mocking or else as a default.

func (*NoBackoff) CalculateBackoff 

func (n *NoBackoff) CalculateBackoff(actualUrl *url.URL) time.Duration

func (*NoBackoff) Sleep 

func (n *NoBackoff) Sleep(d time.Duration)

func (*NoBackoff) UpdateBackoff 

func (n *NoBackoff) UpdateBackoff(actualUrl *url.URL, err error, responseCode int)

type Object 

type Object interface {
	//GetObjectKind return what kind with this object
	GetObjectKind() string
}

Object 用来抽象rest接口的不同类型的数据结构

type ObjectImpl 

type ObjectImpl struct {
}

ObjectImpl 嵌入此结构，实现Object接口

func (*ObjectImpl) GetObjectKind 

func (bo *ObjectImpl) GetObjectKind() string

GetObjectKind get object kind

type PatchType 

type PatchType string

PatchType these are constants to support HTTP PATCH utilized by both the client and server that didn't make sense for a whole package to be dedicated to. 

const (
	JSONPatchType           PatchType = "application/json-patch+json"
	MergePatchType          PatchType = "application/merge-patch+json"
	StrategicMergePatchType PatchType = "application/strategic-merge-patch+json"
)

type RESTClient 

type RESTClient struct {

	// TODO extract this into a wrapper interface via the RESTClient interface in kubectl.
	Throttle flowcontrol.RateLimiter

	// Set specific behavior of the client.  If not set http.DefaultClient will be used.
	Client *http.Client
	// contains filtered or unexported fields
}

RESTClient normal restful api client

func NewRESTClient 

func NewRESTClient(baseURL *url.URL, config ContentConfig, maxQPS float32, maxBurst int, rateLimiter flowcontrol.RateLimiter, client *http.Client) (*RESTClient, error)

NewRESTClient creates a new RESTClient. This client performs generic REST functions such as Get, Put, Post, and Delete on specified paths. Codec controls encoding and decoding of responses from the server.

func RESTClientFor 

func RESTClientFor(config *Config) (*RESTClient, error)

RESTClientFor returns a RESTClient that satisfies the requested attributes on a client Config object. Note that a RESTClient may require fields that are optional when initializing a Client. A RESTClient created by this method is generic - it expects to operate on an API that follows the Kubernetes conventions, but may not be the Kubernetes API.

func (*RESTClient) Delete 

func (c *RESTClient) Delete() *Request

Delete begins a DELETE request. Short for c.Verb("DELETE").

func (*RESTClient) Get 

func (c *RESTClient) Get() *Request

Get begins a GET request. Short for c.Verb("GET").

func (*RESTClient) GetRateLimiter 

func (c *RESTClient) GetRateLimiter() flowcontrol.RateLimiter

GetRateLimiter returns rate limier for a given client, or nil if it's called on a nil client

func (*RESTClient) Patch 

func (c *RESTClient) Patch(pt PatchType) *Request

Patch begins a PATCH request. Short for c.Verb("Patch").

func (*RESTClient) Post 

func (c *RESTClient) Post() *Request

Post begins a POST request. Short for c.Verb("POST").

func (*RESTClient) Put 

func (c *RESTClient) Put() *Request

Put begins a PUT request. Short for c.Verb("PUT").

func (*RESTClient) Verb 

func (c *RESTClient) Verb(verb string) *Request

Verb begins a request with a verb (GET, POST, PUT, DELETE).

Example usage of RESTClient's request building interface: c, err := NewRESTClient(...) if err != nil { ... } resp, err := c.Verb("GET"). 

Path("pods").
SelectorParam("labels", "area=staging").
Timeout(10*time.Second).
Do()

if err != nil { ... } list, ok := resp.(*api.PodList)

type Request 

type Request struct {
	// contains filtered or unexported fields
}

Request allows for building up a request to a server in a chained fashion. Any errors are stored until the end of your call, so you only have to check once.

func NewRequest 

func NewRequest(client HTTPClient, verb string, baseURL *url.URL, content ContentConfig, backoff BackoffManager, throttle flowcontrol.RateLimiter, timeout time.Duration) *Request

NewRequest creates a new request helper object for accessing runtime.Objects on a server.

func (*Request) AbsPath 

func (r *Request) AbsPath(segments ...string) *Request

AbsPath overwrites an existing path with the segments provided. Trailing slashes are preserved when a single segment is passed.

func (*Request) BackOff 

func (r *Request) BackOff(manager BackoffManager) *Request

BackOff sets the request's backoff manager to the one specified, or defaults to the stub implementation if nil is provided

func (*Request) Body 

func (r *Request) Body(obj interface{}) *Request

Body makes the request use obj as the body. Optional. If obj is a string, try to read a file of that name. If obj is a []byte, send it directly. If obj is an io.Reader, use it directly. default will marshal obj with json encode. Otherwise, set an error.

func (*Request) Context 

func (r *Request) Context(ctx context.Context) *Request

Context adds a context to the request. Contexts are only used for timeouts, deadlines, and cancellations.

func (*Request) Do 

func (r *Request) Do() Result

Do formats and executes the request. Returns a Result object for easy response processing.

Error type:

  • If the request can't be constructed, or an error happened earlier while building its arguments: *RequestConstructionError
  • If the server responds with a status: *errors.StatusError or *errors.UnexpectedObjectError
  • http.Client.Do errors are returned directly.

func (*Request) DoRaw 

func (r *Request) DoRaw() ([]byte, error)

DoRaw executes the request but does not process the response body.

func (*Request) Param 

func (r *Request) Param(paramName, s string) *Request

Param creates a query parameter with the given string value.

func (*Request) Prefix 

func (r *Request) Prefix(segments ...string) *Request

Prefix adds segments to the relative beginning to the request path. These items will be placed before the optional Namespace, Resource, or Name sections. Setting AbsPath will clear any previously set Prefix segments

func (*Request) RequestURI 

func (r *Request) RequestURI(uri string) *Request

RequestURI overwrites existing path and parameters with the value of the provided server relative URI.

func (*Request) SetHeader 

func (r *Request) SetHeader(key string, values ...string) *Request

SetHeader append http header with request

func (*Request) Stream 

func (r *Request) Stream() (io.ReadCloser, error)

Stream formats and executes the request, and offers streaming of the response. Returns io.ReadCloser which could be used for streaming of the response, or an error Any non-2xx http status code causes an error. If we get a non-2xx code, we try to convert the body into an APIStatus object. If we can, we return that as an error. Otherwise, we create an error that lists the http status and the content of the response.

func (*Request) Suffix 

func (r *Request) Suffix(segments ...string) *Request

Suffix appends segments to the end of the path. These items will be placed after the prefix and optional Namespace, Resource, or Name sections.

func (*Request) Throttle 

func (r *Request) Throttle(limiter flowcontrol.RateLimiter) *Request

Throttle receives a rate-limiter and sets or replaces an existing request limiter

func (*Request) Timeout 

func (r *Request) Timeout(d time.Duration) *Request

Timeout makes the request use the given duration as an overall timeout for the request. Additionally, if set passes the value as "timeout" parameter in URL.

func (*Request) URL 

func (r *Request) URL() *url.URL

URL returns the current working URL.

type RequestConstructionError 

type RequestConstructionError struct {
	Err error
}

RequestConstructionError is returned when there's an error assembling a request.

func (*RequestConstructionError) Error 

func (r *RequestConstructionError) Error() string

Error returns a textual description of 'r'.

type ResponseWrapper 

type ResponseWrapper interface {
	DoRaw() ([]byte, error)
	Stream() (io.ReadCloser, error)
}

ResponseWrapper is an interface for getting a response. The response may be either accessed as a raw data (the whole output is put into memory) or as a stream.

type Result 

type Result struct {
	// contains filtered or unexported fields
}

Result contains the result of calling Request.Do().

func (Result) Error 

func (r Result) Error() error

Error returns the error executing the request, nil if no error occurred. If the returned object is of type Status and has Status != StatusSuccess, the additional information in Status will be used to enrich the error. See the Request.Do() comment for what errors you might get.

func (Result) Into 

func (r Result) Into(obj Object) error

Into stores the result into obj, if possible. If obj is nil it is ignored. If the returned object is of type Status and has .Status != StatusSuccess, the additional information in Status will be used to enrich the error.

func (Result) Raw 

func (r Result) Raw() ([]byte, error)

Raw returns the raw result.

func (Result) StatusCode 

func (r Result) StatusCode(statusCode *int) Result

StatusCode returns the HTTP status code of the request. (Only valid if no error was returned.)

func (Result) WasCreated 

func (r Result) WasCreated(wasCreated *bool) Result

WasCreated updates the provided bool pointer to whether the server returned 201 created or a different response.

type TLSClientConfig 

type TLSClientConfig struct {
	// Server should be accessed without verifying the TLS certificate. For testing only.
	Insecure bool
	// ServerName is passed to the server for SNI and is used in the client to check server
	// ceritificates against. If ServerName is empty, the hostname used to contact the
	// server is used.
	ServerName string

	// Server requires TLS client certificate authentication
	CertFile string
	// Server requires TLS client certificate authentication
	KeyFile string
	// Trusted root certificates for server
	CAFile string

	// CertData holds PEM-encoded bytes (typically read from a client certificate file).
	// CertData takes precedence over CertFile
	CertData []byte
	// KeyData holds PEM-encoded bytes (typically read from a client certificate key file).
	// KeyData takes precedence over KeyFile
	KeyData []byte
	// CAData holds PEM-encoded bytes (typically read from a root certificates bundle).
	// CAData takes precedence over CAFile
	CAData []byte
}

TLSClientConfig contains settings to enable transport layer security

func (TLSClientConfig) GoString 

func (c TLSClientConfig) GoString() string

GoString implements fmt.GoStringer and sanitizes sensitive fields of TLSClientConfig to prevent accidental leaking via logs.

func (TLSClientConfig) String 

func (c TLSClientConfig) String() string

String implements fmt.Stringer and sanitizes sensitive fields of TLSClientConfig to prevent accidental leaking via logs.

type URLBackoff 

type URLBackoff struct {
	// Uses backoff as underlying implementation.
	Backoff *flowcontrol.Backoff
}

URLBackoff struct implements the semantics on top of Backoff which we need for URL specific exponential backoff.

func (*URLBackoff) CalculateBackoff 

func (b *URLBackoff) CalculateBackoff(actualUrl *url.URL) time.Duration

CalculateBackoff takes a url and back's off exponentially, based on its knowledge of existing failures.

func (*URLBackoff) Disable 

func (b *URLBackoff) Disable()

Disable makes the backoff trivial, i.e., sets it to zero. This might be used by tests which want to run 1000s of mock requests without slowing down.

func (*URLBackoff) Sleep 

func (b *URLBackoff) Sleep(d time.Duration)

func (*URLBackoff) UpdateBackoff 

func (b *URLBackoff) UpdateBackoff(actualUrl *url.URL, err error, responseCode int)

UpdateBackoff updates backoff metadata

Source Files

View all Source files

Directories

Path Synopsis
Package metrics provides abstractions for registering which metrics to record.
 Package metrics provides abstractions for registering which metrics to record.
spdy

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.