Documentation
¶
Index ¶
- type Request
- func (r *Request) BuildHTTPContext(parentCtx context.Context, mediaType, basePath string, ...) (*http.Request, context.CancelFunc, error)
- func (r *Request) GetBody() []byte
- func (r *Request) GetBodyParam() any
- func (r *Request) GetFileParam() map[string][]runtime.NamedReadCloser
- func (r *Request) GetHeaderParams() http.Header
- func (r *Request) GetMethod() string
- func (r *Request) GetPath() string
- func (r *Request) GetQueryParams() url.Values
- func (r *Request) GetTimeout() time.Duration
- func (r *Request) SetBodyParam(payload any) error
- func (r *Request) SetConsumes(consumers []string)
- func (r *Request) SetFileParam(name string, files ...runtime.NamedReadCloser) error
- func (r *Request) SetFormParam(name string, values ...string) error
- func (r *Request) SetHeaderParam(name string, values ...string) error
- func (r *Request) SetPathParam(name string, value string) error
- func (r *Request) SetQueryParam(name string, values ...string) error
- func (r *Request) SetTimeout(timeout time.Duration) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Request ¶
type Request struct {
// contains filtered or unexported fields
}
Request represents a swagger client request. It binds parameters to a HTTP request.
The main purpose of this struct is to hide the machinery of adding OpenAPI v2 parameters to a transport request.
A generated client only implements what is necessary to turn a parameter into a valid value for these methods.
There is no parameter validation here, it is assumed to be used after a spec has been validated.
Request binding ¶
The binding of parameters is carried out by method Request.BuildHTTPContext.
It analyzes parameters, which may come in different flavors:
- a file or multipart form containing a file
- a body which is a io.Reader
- a buffered body (regular schema body, including urlencoded form)
In all cases, we may also have query or path parameters encoded in the URL, or header parameters.
The result is a http.Request, with the following properties:
- file, multipart form or io.Reader body: a streaming request with an attached go routine that consumes the io.Reader.
- buffered body: a simple request
The caller passes the parent context.Context to Request.BuildHTTPContext and receives back a cancel function to release the resources held by the derived request context once the response is consumed.
Authentication ¶
Authentication is built in the request by using a runtime.ClientAuthInfoWriter. This helper may need to inspect the body of the request before sending authentication info. To cover that case, streaming bodies use a copy of the body io.Reader for the runtime.ClientAuthInfoWriter to consume if it wants to.
Content negotiation ¶
The Request detects `multipart/form-data` to switch to streamed request.
`application/x-www-form-urlencoded` is also honored, even for file parameters, which are not streamed in this case. File parameters default behavior is `multipart/form-data`.
The natural way to define the `Content-Type` header is to use the `contentType` parameter to switch to the map of available body producers.
For buffered requests, this setting override any `Content-Type` header possibly set by calling Request.SetHeaderParam.
For streamed requests, users may want more flexibility, as we enter custom territory, with use-cases not supported by OpenAPI v2.
The `Content-Type` header of a streamed request is defined using the following sequence:
- if the caller sets an explicit value already in header — the user set it via Request.SetHeaderParam during WriteToRequest, and we treat that as an intentional escape hatch
- use payload's runtime.ContentTyper declaration (in this case, the produced payload knows its content type)
- use `application/octet-stream` if it is available in the registered producers
- otherwise ser the picker's mediaType
For multi-part requests, the content type of each part is auto-detected using the following sequence:
- use runtime.ContentTyper declaration (in this case, the file payload knows its content type)
- use http.DetectContentType on the first 512 bytes of the file
Concurrency ¶
A Request is a disposable object that is NOT intended to be reused or called concurrently.
Future evolutions ¶
There might be other similar structs that convert to other transports.
func New ¶
func New(method, pathPattern string, writer runtime.ClientRequestWriter) *Request
New creates a new http client Request to handle OpenAPI v2 parameters.
func (*Request) BuildHTTPContext ¶
func (r *Request) BuildHTTPContext(parentCtx context.Context, mediaType, basePath string, producers map[string]runtime.Producer, registry strfmt.Registry, auth runtime.ClientAuthInfoWriter) (*http.Request, context.CancelFunc, error)
BuildHTTPContext binds the request parameters and returns a ready-to-send http.Request.
Dispatch picks one of two end-to-end builders based on whether:
- the body source is a stream (multipart pipe or stream payload)
- or a buffer (urlencoded form, producer output, or no body)
It starts by writing the request, then proceed with adding authentication, then finally assembling URL or header parameters.
The split mirrors the auth question: streaming bodies require a lazy body-copy closure during AuthenticateRequest, whereas buffered bodies do not.
The returned http.Request carries a context derived from parentCtx that:
- inherits any deadline or cancellation already set on parentCtx;
- additionally honors the per-request timeout set via Request.SetTimeout (the runtime.ClientRequestWriter may override the runtime default during WriteToRequest, which is why the derivation happens here rather than at the call site).
The returned cancel must be invoked by the caller (typically deferred) once the response has been fully read; otherwise resources held by the derived context — including any timeout timer — are leaked.
On error the cancel is invoked internally and a no-op cancel is returned, so callers can defer cancel unconditionally.
func (*Request) GetBody ¶
GetBody returns the request body, if any.
For streaming requests, this is a copy of the original io.Reader.
func (*Request) GetBodyParam ¶
GetBodyParam returns the body payload.
func (*Request) GetFileParam ¶
func (r *Request) GetFileParam() map[string][]runtime.NamedReadCloser
GetFileParam yields all file parameters.
func (*Request) GetHeaderParams ¶
GetHeaderParams returns all headers currently set for the request.
func (*Request) GetQueryParams ¶
GetQueryParams returns a copy of all query params currently set for the request.
func (*Request) GetTimeout ¶
GetTimeout sets the timeout for a request.
func (*Request) SetBodyParam ¶
SetBodyParam sets a body parameter on the request.
This does not yet serialize the object: actual serialization happens as late as possible.
func (*Request) SetConsumes ¶
SetConsumes sets the list of registered consumed content for a request.
func (*Request) SetFileParam ¶
func (r *Request) SetFileParam(name string, files ...runtime.NamedReadCloser) error
SetFileParam adds a file parameter to the request.
Files must implement runtime.NamedReadCloser.
runtime.File is proposed as the default concrete implementation.
func (*Request) SetFormParam ¶
SetFormParam adds a forn param to the request.
- when there is only 1 value provided, it will set it.
- when there are several values provided, it will add all of those (no overriding).
func (*Request) SetHeaderParam ¶
SetHeaderParam adds a header parameter to the request.
The header key is always canonicalized.
- when there is only 1 value provided, it will set it.
- when there are several values provided, it will add all of those (no overriding).
func (*Request) SetPathParam ¶
SetPathParam adds a path param to the request.
func (*Request) SetQueryParam ¶
SetQueryParam adds a query parameter to the request.
- when there is only 1 value provided, it will set it.
- when there are several values provided, it will add all of those (no overriding).
Source Files