docs/client/request.md
The Request struct in Fiber's HTTP client represents an HTTP request. It encapsulates the data required to send a request, including:
This structure is designed to be both flexible and efficient, allowing you to easily build and modify HTTP requests as needed.
type Request struct {
url string
method string
userAgent string
boundary string
referer string
ctx context.Context
header *Header
params *QueryParam
cookies *Cookie
path *PathParam
timeout time.Duration
maxRedirects int
client *Client
body any
formData *FormData
files []*File
bodyType bodyType
RawRequest *fasthttp.Request
}
Get sends a GET request to the specified URL. It sets the URL and HTTP method, then dispatches the request to the server.
func (r *Request) Get(url string) (*Response, error)
Post sends a POST request. It sets the URL and method to POST, then sends the request.
func (r *Request) Post(url string) (*Response, error)
Put sends a PUT request. It sets the URL and method to PUT, then sends the request.
func (r *Request) Put(url string) (*Response, error)
Patch sends a PATCH request. It sets the URL and method to PATCH, then sends the request.
func (r *Request) Patch(url string) (*Response, error)
Delete sends a DELETE request. It sets the URL and method to DELETE, then sends the request.
func (r *Request) Delete(url string) (*Response, error)
Head sends a HEAD request. It sets the URL and method to HEAD, then sends the request.
func (r *Request) Head(url string) (*Response, error)
Options sends an OPTIONS request. It sets the URL and method to OPTIONS, then sends the request.
func (r *Request) Options(url string) (*Response, error)
Custom sends a request using a custom HTTP method. For example, you can use this to send a TRACE or CONNECT request.
func (r *Request) Custom(url, method string) (*Response, error)
AcquireRequest returns a new pooled Request. Call ReleaseRequest when you're finished to return it to the pool and limit allocations.
func AcquireRequest() *Request
ReleaseRequest returns the Request to the pool. Do not use it after releasing; doing so may cause data races.
func ReleaseRequest(req *Request)
Method returns the current HTTP method set for the request.
func (r *Request) Method() string
SetMethod sets the HTTP method for the Request object. Typically, you should use the specialized request methods (Get, Post, etc.) instead of calling SetMethod directly.
func (r *Request) SetMethod(method string) *Request
URL returns the current URL set in the Request.
func (r *Request) URL() string
SetURL sets the URL for the Request object.
func (r *Request) SetURL(url string) *Request
Client retrieves the Client instance associated with the Request.
func (r *Request) Client() *Client
SetClient assigns a Client to the Request. If the provided client is nil, it will panic.
func (r *Request) SetClient(c *Client) *Request
Context returns the context.Context of the request, or context.Background() if none is set.
func (r *Request) Context() context.Context
SetContext sets the context.Context for the request, allowing you to cancel or time out the request. See the Go blog and context docs for more details.
func (r *Request) SetContext(ctx context.Context) *Request
Header returns all values for the specified header key. It searches all header fields stored in the request.
func (r *Request) Header(key string) []string
Headers returns an iterator over all headers in the request. Use maps.Collect() to transform them into a map if needed. The returned values are valid only until the request is released. Make copies as required.
func (r *Request) Headers() iter.Seq2[string, []string]
req := client.AcquireRequest()
req.AddHeader("Golang", "Fiber")
req.AddHeader("Test", "123456")
req.AddHeader("Test", "654321")
for k, v := range req.Headers() {
fmt.Printf("Header Key: %s, Header Value: %v\n", k, v)
}
Header Key: Golang, Header Value: [Fiber]
Header Key: Test, Header Value: [123456 654321]
req := client.AcquireRequest()
req.AddHeader("Golang", "Fiber")
req.AddHeader("Test", "123456")
req.AddHeader("Test", "654321")
headers := maps.Collect(req.Headers()) // Collect all headers into a map
for k, v := range headers {
fmt.Printf("Header Key: %s, Header Value: %v\n", k, v)
}
Header Key: Golang, Header Value: [Fiber]
Header Key: Test, Header Value: [123456 654321]
AddHeader adds a single header field and its value to the request.
func (r *Request) AddHeader(key, val string) *Request
req := client.AcquireRequest()
defer client.ReleaseRequest(req)
req.AddHeader("Golang", "Fiber")
req.AddHeader("Test", "123456")
req.AddHeader("Test", "654321")
resp, err := req.Get("https://httpbin.org/headers")
if err != nil {
panic(err)
}
fmt.Println(resp.String())
{
"headers": {
"Golang": "Fiber",
"Host": "httpbin.org",
"Referer": "",
"Test": "123456,654321",
"User-Agent": "fiber",
"X-Amzn-Trace-Id": "Root=1-664105d2-033cf7173457adb56d9e7193"
}
}
SetHeader sets a single header field and its value, overriding any previously set header with the same key.
func (r *Request) SetHeader(key, val string) *Request
req := client.AcquireRequest()
defer client.ReleaseRequest(req)
req.SetHeader("Test", "123456")
req.SetHeader("Test", "654321")
resp, err := req.Get("https://httpbin.org/headers")
if err != nil {
panic(err)
}
fmt.Println(resp.String())
{
"headers": {
"Golang": "Fiber",
"Host": "httpbin.org",
"Referer": "",
"Test": "654321",
"User-Agent": "fiber",
"X-Amzn-Trace-Id": "Root=1-664105e5-5d676ba348450cdb62847f04"
}
}
AddHeaders adds multiple headers at once from a map of string slices.
func (r *Request) AddHeaders(h map[string][]string) *Request
SetHeaders sets multiple headers at once from a map of strings, overriding any previously set headers.
func (r *Request) SetHeaders(h map[string]string) *Request
Param returns all values associated with a given query parameter key.
func (r *Request) Param(key string) []string
Params returns an iterator over all query parameters. Use maps.Collect() if you need them in a map. The returned values are valid only until the request is released.
func (r *Request) Params() iter.Seq2[string, []string]
AddParam adds a single query parameter key-value pair.
func (r *Request) AddParam(key, val string) *Request
req := client.AcquireRequest()
defer client.ReleaseRequest(req)
req.AddParam("name", "john")
req.AddParam("hobbies", "football")
req.AddParam("hobbies", "basketball")
resp, err := req.Get("https://httpbin.org/response-headers")
if err != nil {
panic(err)
}
fmt.Println(string(resp.Body()))
{
"Content-Length": "145",
"Content-Type": "application/json",
"hobbies": [
"football",
"basketball"
],
"name": "joe"
}
SetParam sets a single query parameter key-value pair, overriding any previously set values for that key.
func (r *Request) SetParam(key, val string) *Request
AddParams adds multiple query parameters from a map of string slices.
func (r *Request) AddParams(m map[string][]string) *Request
SetParams sets multiple query parameters from a map of strings, overriding previously set values.
func (r *Request) SetParams(m map[string]string) *Request
SetParamsWithStruct sets multiple query parameters from a struct. Nested structs are not supported.
func (r *Request) SetParamsWithStruct(v any) *Request
req := client.AcquireRequest()
defer client.ReleaseRequest(req)
req.SetParamsWithStruct(struct {
Name string `json:"name"`
Hobbies []string `json:"hobbies"`
}{
Name: "John Doe",
Hobbies: []string{
"Football",
"Basketball",
},
})
resp, err := req.Get("https://httpbin.org/response-headers")
if err != nil {
panic(err)
}
fmt.Println(string(resp.Body()))
{
"Content-Length": "147",
"Content-Type": "application/json",
"Hobbies": [
"Football",
"Basketball"
],
"Name": "John Doe"
}
DelParams removes one or more query parameters by their keys.
func (r *Request) DelParams(key ...string) *Request
UserAgent returns the user agent currently set in the request.
func (r *Request) UserAgent() string
SetUserAgent sets the user agent header for the request, overriding the one set at the client level if any.
func (r *Request) SetUserAgent(ua string) *Request
Boundary returns the multipart boundary used by the request.
func (r *Request) Boundary() string
SetBoundary sets the multipart boundary for file uploads.
func (r *Request) SetBoundary(b string) *Request
Referer returns the Referer header value currently set in the request.
func (r *Request) Referer() string
SetReferer sets the Referer header for the request, overriding the one set at the client level if any.
func (r *Request) SetReferer(referer string) *Request
Cookie returns the value of the specified cookie. If the cookie does not exist, it returns an empty string.
func (r *Request) Cookie(key string) string
Cookies returns an iterator over all cookies set in the request. Use maps.Collect() to gather them into a map.
func (r *Request) Cookies() iter.Seq2[string, string]
SetCookie sets a single cookie key-value pair, overriding any previously set cookie with the same key.
func (r *Request) SetCookie(key, val string) *Request
SetCookies sets multiple cookies from a map, overriding previously set values.
func (r *Request) SetCookies(m map[string]string) *Request
req := client.AcquireRequest()
defer client.ReleaseRequest(req)
req.SetCookies(map[string]string{
"cookie1": "value1",
"cookie2": "value2",
})
resp, err := req.Get("https://httpbin.org/cookies")
if err != nil {
panic(err)
}
fmt.Println(string(resp.Body()))
{
"cookies": {
"test": "123"
}
}
SetCookiesWithStruct sets multiple cookies from a struct.
func (r *Request) SetCookiesWithStruct(v any) *Request
DelCookies removes one or more cookies by their keys.
func (r *Request) DelCookies(key ...string) *Request
PathParam returns the value of a named path parameter. If not found, returns an empty string.
func (r *Request) PathParam(key string) string
PathParams returns an iterator over all path parameters in the request. Use maps.Collect() to convert them into a map.
func (r *Request) PathParams() iter.Seq2[string, string]
SetPathParam sets a single path parameter key-value pair, overriding previously set values.
func (r *Request) SetPathParam(key, val string) *Request
req := client.AcquireRequest()
defer client.ReleaseRequest(req)
req.SetPathParam("base64", "R29maWJlcg==")
resp, err := req.Get("https://httpbin.org/base64/:base64")
if err != nil {
panic(err)
}
fmt.Println(string(resp.Body()))
Gofiber
SetPathParams sets multiple path parameters at once, overriding previously set values.
func (r *Request) SetPathParams(m map[string]string) *Request
SetPathParamsWithStruct sets multiple path parameters from a struct.
func (r *Request) SetPathParamsWithStruct(v any) *Request
DelPathParams deletes one or more path parameters by their keys.
func (r *Request) DelPathParams(key ...string) *Request
ResetPathParams deletes all path parameters.
func (r *Request) ResetPathParams() *Request
SetJSON sets the request body to a JSON-encoded payload.
func (r *Request) SetJSON(v any) *Request
SetXML sets the request body to an XML-encoded payload.
func (r *Request) SetXML(v any) *Request
SetCBOR sets the request body to a CBOR-encoded payload. It automatically sets the Content-Type to application/cbor.
func (r *Request) SetCBOR(v any) *Request
SetRawBody sets the request body to raw bytes.
func (r *Request) SetRawBody(v []byte) *Request
FormData returns all values associated with the given form data field.
func (r *Request) FormData(key string) []string
AllFormData returns an iterator over all form data fields. Use maps.Collect() if needed.
func (r *Request) AllFormData() iter.Seq2[string, []string]
AddFormData adds a single form data key-value pair.
func (r *Request) AddFormData(key, val string) *Request
req := client.AcquireRequest()
defer client.ReleaseRequest(req)
req.AddFormData("points", "80")
req.AddFormData("points", "90")
req.AddFormData("points", "100")
resp, err := req.Post("https://httpbin.org/post")
if err != nil {
panic(err)
}
fmt.Println(string(resp.Body()))
{
"args": {},
"data": "",
"files": {},
"form": {
"points": [
"80",
"90",
"100"
]
},
// ...
}
SetFormData sets a single form data field, overriding any previously set values.
func (r *Request) SetFormData(key, val string) *Request
req := client.AcquireRequest()
defer client.ReleaseRequest(req)
req.SetFormData("name", "john")
req.SetFormData("email", "[email protected]")
resp, err := req.Post("https://httpbin.org/post")
if err != nil {
panic(err)
}
fmt.Println(string(resp.Body()))
{
"args": {},
"data": "",
"files": {},
"form": {
"email": "[email protected]",
"name": "john"
},
// ...
}
AddFormDataWithMap adds multiple form data fields and values from a map of string slices.
func (r *Request) AddFormDataWithMap(m map[string][]string) *Request
SetFormDataWithMap sets multiple form data fields from a map of strings.
func (r *Request) SetFormDataWithMap(m map[string]string) *Request
SetFormDataWithStruct sets multiple form data fields from a struct.
func (r *Request) SetFormDataWithStruct(v any) *Request
DelFormData deletes one or more form data fields by their keys.
func (r *Request) DelFormData(key ...string) *Request
File returns a file from the request by its name. If no name was provided, it attempts to match by path.
func (r *Request) File(name string) *File
Files returns all files in the request as a slice. The returned slice is valid only until the request is released.
func (r *Request) Files() []*File
FileByPath returns a file from the request by its file path.
func (r *Request) FileByPath(path string) *File
AddFile adds a single file to the request from a file path.
func (r *Request) AddFile(path string) *Request
req := client.AcquireRequest()
defer client.ReleaseRequest(req)
req.AddFile("test.txt")
resp, err := req.Post("https://httpbin.org/post")
if err != nil {
panic(err)
}
fmt.Println(string(resp.Body()))
{
"args": {},
"data": "",
"files": {
"file1": "This is an empty file!\n"
},
"form": {},
// ...
}
AddFileWithReader adds a single file to the request from an io.ReadCloser.
func (r *Request) AddFileWithReader(name string, reader io.ReadCloser) *Request
req := client.AcquireRequest()
defer client.ReleaseRequest(req)
buf := bytes.NewBuffer([]byte("Hello, World!"))
req.AddFileWithReader("test.txt", io.NopCloser(buf))
resp, err := req.Post("https://httpbin.org/post")
if err != nil {
panic(err)
}
fmt.Println(string(resp.Body()))
{
"args": {},
"data": "",
"files": {
"file1": "Hello, World!"
},
"form": {},
// ...
}
AddFiles adds multiple files to the request at once.
func (r *Request) AddFiles(files ...*File) *Request
Timeout returns the timeout duration set in the request.
func (r *Request) Timeout() time.Duration
SetTimeout sets a timeout for the request, overriding any timeout set at the client level.
func (r *Request) SetTimeout(t time.Duration) *Request
req := client.AcquireRequest()
defer client.ReleaseRequest(req)
req.SetTimeout(5 * time.Second)
resp, err := req.Get("https://httpbin.org/delay/4")
if err != nil {
panic(err)
}
fmt.Println(string(resp.Body()))
{
"args": {},
"data": "",
"files": {},
"form": {},
// ...
}
req := client.AcquireRequest()
defer client.ReleaseRequest(req)
req.SetTimeout(5 * time.Second)
resp, err := req.Get("https://httpbin.org/delay/6")
if err != nil {
panic(err)
}
fmt.Println(string(resp.Body()))
panic: timeout or cancel
goroutine 1 [running]:
main.main()
main.go:18 +0xeb
exit status 2
MaxRedirects returns the maximum number of redirects allowed for the request.
func (r *Request) MaxRedirects() int
SetMaxRedirects sets the maximum number of redirects for the request, overriding the client's setting.
func (r *Request) SetMaxRedirects(count int) *Request
Send executes the HTTP request and returns a Response.
func (r *Request) Send() (*Response, error)
Reset clears the Request object, making it ready for reuse. This is used by ReleaseRequest.
func (r *Request) Reset()
Header is a wrapper around fasthttp.RequestHeader, storing headers for both the client and request.
type Header struct {
*fasthttp.RequestHeader
}
PeekMultiple returns multiple values associated with the same header key.
func (h *Header) PeekMultiple(key string) []string
AddHeaders adds multiple headers from a map of string slices.
func (h *Header) AddHeaders(r map[string][]string)
SetHeaders sets multiple headers from a map of strings, overriding previously set headers.
func (h *Header) SetHeaders(r map[string]string)
QueryParam is a wrapper around fasthttp.Args, storing query parameters.
type QueryParam struct {
*fasthttp.Args
}
Keys returns all keys in the query parameters.
func (p *QueryParam) Keys() []string
AddParams adds multiple query parameters from a map of string slices.
func (p *QueryParam) AddParams(r map[string][]string)
SetParams sets multiple query parameters from a map of strings, overriding previously set values.
func (p *QueryParam) SetParams(r map[string]string)
SetParamsWithStruct sets multiple query parameters from a struct. Nested structs are not supported.
func (p *QueryParam) SetParamsWithStruct(v any)
Cookie is a map that stores cookies.
type Cookie map[string]string
Add adds a cookie key-value pair.
func (c Cookie) Add(key, val string)
Del removes a cookie by its key.
func (c Cookie) Del(key string)
SetCookie sets a single cookie key-value pair, overriding previously set values.
func (c Cookie) SetCookie(key, val string)
SetCookies sets multiple cookies from a map of strings.
func (c Cookie) SetCookies(m map[string]string)
SetCookiesWithStruct sets multiple cookies from a struct.
func (c Cookie) SetCookiesWithStruct(v any)
DelCookies deletes one or more cookies by their keys.
func (c Cookie) DelCookies(key ...string)
All returns an iterator over all cookies. The key and value returned should not be retained after the loop ends.
func (c Cookie) All() iter.Seq2[string, string]
Reset clears all cookies.
func (c Cookie) Reset()
PathParam is a map that stores path parameters.
type PathParam map[string]string
Add adds a path parameter key-value pair.
func (p PathParam) Add(key, val string)
Del removes a path parameter by its key.
func (p PathParam) Del(key string)
SetParam sets a single path parameter key-value pair, overriding previously set values.
func (p PathParam) SetParam(key, val string)
SetParams sets multiple path parameters from a map of strings.
func (p PathParam) SetParams(m map[string]string)
SetParamsWithStruct sets multiple path parameters from a struct.
func (p PathParam) SetParamsWithStruct(v any)
DelParams deletes one or more path parameters by their keys.
func (p PathParam) DelParams(key ...string)
All returns an iterator over all path parameters. The key and value returned should not be retained after the loop ends.
func (p PathParam) All() iter.Seq2[string, string]
Reset clears all path parameters.
func (p PathParam) Reset()
FormData is a wrapper around fasthttp.Args, used to handle URL-encoded and form-data (multipart) request bodies.
type FormData struct {
*fasthttp.Args
}
Keys returns all form data keys.
func (f *FormData) Keys() []string
Add adds a single form field key-value pair.
func (f *FormData) Add(key, val string)
Set sets a single form field key-value pair, overriding any previously set values.
func (f *FormData) Set(key, val string)
AddWithMap adds multiple form fields from a map of string slices.
func (f *FormData) AddWithMap(m map[string][]string)
SetWithMap sets multiple form fields from a map of strings.
func (f *FormData) SetWithMap(m map[string]string)
SetWithStruct sets multiple form fields from a struct.
func (f *FormData) SetWithStruct(v any)
DelData deletes one or more form fields by their keys.
func (f *FormData) DelData(key ...string)
Reset clears all form data fields.
func (f *FormData) Reset()
File represents a file to be uploaded. It can be specified by name, path, or an io.ReadCloser.
type File struct {
name string
fieldName string
path string
reader io.ReadCloser
}
AcquireFile returns a File from the pool and applies any provided SetFileFunc functions to it. Release it with ReleaseFile when done.
func AcquireFile(setter ...SetFileFunc) *File
ReleaseFile returns the File to the pool. Do not use the file afterward.
func ReleaseFile(f *File)
SetName sets the file's name.
func (f *File) SetName(n string)
SetFieldName sets the field name of the file in the multipart form.
func (f *File) SetFieldName(n string)
SetPath sets the file's path.
func (f *File) SetPath(p string)
SetReader sets the file's io.ReadCloser. The reader is closed automatically when the request body is parsed.
func (f *File) SetReader(r io.ReadCloser)
Reset clears the file's fields.
func (f *File) Reset()