Documentation
¶
Overview ¶
Package builder provides a functional, immutable HTTP request builder with composable operations. It follows functional programming principles to construct HTTP requests in a type-safe, testable, and maintainable way.
The Builder type is immutable - all operations return a new builder instance rather than modifying the existing one. This ensures thread-safety and makes the code easier to reason about.
Key Features:
- Immutable builder pattern with method chaining
- Lens-based access to builder properties
- Support for headers, query parameters, request body, and HTTP methods
- JSON and form data encoding
- URL construction with query parameter merging
- Hash generation for caching
- Bearer token authentication helpers
Basic Usage:
import (
B "github.com/IBM/fp-go/v2/http/builder"
F "github.com/IBM/fp-go/v2/function"
)
// Build a simple GET request
builder := F.Pipe2(
B.Default,
B.WithURL("https://api.example.com/users"),
B.WithHeader("Accept")("application/json"),
)
// Build a POST request with JSON body
builder := F.Pipe3(
B.Default,
B.WithURL("https://api.example.com/users"),
B.WithMethod("POST"),
B.WithJSON(map[string]string{"name": "John"}),
)
// Build a request with query parameters
builder := F.Pipe3(
B.Default,
B.WithURL("https://api.example.com/search"),
B.WithQueryArg("q")("golang"),
B.WithQueryArg("limit")("10"),
)
The package provides several convenience functions for common HTTP methods:
- WithGet, WithPost, WithPut, WithDelete for setting HTTP methods
- WithBearer for adding Bearer token authentication
- WithJSON for JSON payloads
- WithFormData for form-encoded payloads
Lenses are provided for advanced use cases:
- URL, Method, Body, Headers, Query for accessing builder properties
- Header(name) for accessing individual headers
- QueryArg(name) for accessing individual query parameters
Index ¶
- Variables
- func MakeHash(b *Builder) string
- func WithHeader(name string) func(value string) Endomorphism
- func WithQueryArg(name string) func(value string) Endomorphism
- type Builder
- func (builder *Builder) DelHeader(name string) *Builder
- func (builder *Builder) GetBody() Option[Result[[]byte]]
- func (builder *Builder) GetHash() string
- func (builder *Builder) GetHeader(name string) Option[string]
- func (builder *Builder) GetHeaderValues(name string) []string
- func (builder *Builder) GetHeaders() http.Header
- func (builder *Builder) GetMethod() string
- func (builder *Builder) GetQuery() url.Values
- func (builder *Builder) GetTargetURL() Result[string]
- func (builder *Builder) GetTargetUrl() Result[string]deprecated
- func (builder *Builder) GetURL() string
- func (builder *Builder) GetUrl() stringdeprecated
- func (builder *Builder) SetBody(body Option[Result[[]byte]]) *Builder
- func (builder *Builder) SetHeader(name, value string) *Builder
- func (builder *Builder) SetHeaders(headers http.Header) *Builder
- func (builder *Builder) SetMethod(method string) *Builder
- func (builder *Builder) SetQuery(query url.Values) *Builder
- func (builder *Builder) SetURL(url string) *Builder
- func (builder *Builder) SetUrl(url string) *Builderdeprecated
- type Endomorphism
- type Lens
- type Option
- type Result
Constants ¶
This section is empty.
Variables ¶
var ( // Default is the default builder Default = &Builder{method: O.Some(defaultMethod()), headers: make(http.Header), body: noBody} // Monoid is the [M.Monoid] for the [Endomorphism] Monoid = ENDO.Monoid[*Builder]() // Url is a [Lens] for the URL // // Deprecated: use [URL] instead Url = L.MakeLensRef((*Builder).GetURL, (*Builder).SetURL) // URL is a [Lens] for the URL URL = L.MakeLensRef((*Builder).GetURL, (*Builder).SetURL) // Method is a [Lens] for the HTTP method Method = L.MakeLensRef((*Builder).GetMethod, (*Builder).SetMethod) // Body is a [Lens] for the request body Body = L.MakeLensRef((*Builder).GetBody, (*Builder).SetBody) // Headers is a [Lens] for the complete set of request headers Headers = L.MakeLensRef((*Builder).GetHeaders, (*Builder).SetHeaders) // Query is a [Lens] for the set of query parameters Query = L.MakeLensRef((*Builder).GetQuery, (*Builder).SetQuery) // WithQuery creates a [Endomorphism] for a complete set of query parameters WithQuery = Query.Set // WithMethod creates a [Endomorphism] for a certain method WithMethod = Method.Set // WithUrl creates a [Endomorphism] for the URL // // Deprecated: use [WithURL] instead WithUrl = URL.Set // WithURL creates a [Endomorphism] for the URL WithURL = URL.Set // WithHeaders creates a [Endomorphism] for a set of headers WithHeaders = Headers.Set // WithBody creates a [Endomorphism] for a request body WithBody = F.Flow2( O.Of[Result[[]byte]], Body.Set, ) // WithBytes creates a [Endomorphism] for a request body using bytes WithBytes = F.Flow2( result.Of[[]byte], WithBody, ) // WithContentType adds the [H.ContentType] header WithContentType = WithHeader(H.ContentType) // WithAuthorization adds the [H.Authorization] header WithAuthorization = WithHeader(H.Authorization) // WithGet adds the [http.MethodGet] method WithGet = WithMethod(http.MethodGet) // WithPost adds the [http.MethodPost] method WithPost = WithMethod(http.MethodPost) // WithPut adds the [http.MethodPut] method WithPut = WithMethod(http.MethodPut) // WithDelete adds the [http.MethodDelete] method WithDelete = WithMethod(http.MethodDelete) // WithBearer creates a [Endomorphism] to add a Bearer [H.Authorization] header WithBearer = F.Flow2( S.Format[string]("Bearer %s"), WithAuthorization, ) // WithoutBody creates a [Endomorphism] to remove the body WithoutBody = F.Pipe1( noBody, Body.Set, ) // WithFormData creates a [Endomorphism] to send form data payload WithFormData = F.Flow4( url.Values.Encode, S.ToBytes, WithBytes, ENDO.Chain(WithContentType(C.FormEncoded)), ) )
Functions ¶
func WithHeader ¶
func WithHeader(name string) func(value string) Endomorphism
WithHeader creates a Endomorphism for a certain header
func WithQueryArg ¶
func WithQueryArg(name string) func(value string) Endomorphism
WithQueryArg creates a Endomorphism for a certain query argument
Types ¶
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
func (*Builder) GetHash ¶
GetHash returns a hash value for the builder that can be used as a cache key
func (*Builder) GetHeaderValues ¶
func (*Builder) GetHeaders ¶
func (*Builder) GetTargetURL ¶
GetTargetURL constructs a full URL with query parameters on top of the provided URL string
func (*Builder) GetTargetUrl
deprecated
type Endomorphism ¶
type Endomorphism = ENDO.Endomorphism[*Builder]
Endomorphism returns an [ENDO.Endomorphism] that transforms a builder
func WithJSON ¶
func WithJSON[T any](data T) Endomorphism
WithJSON creates a Endomorphism to send JSON payload
func WithJson
deprecated
func WithJson[T any](data T) Endomorphism
WithJson creates a Endomorphism to send JSON payload
Deprecated: use WithJSON instead
func WithoutHeader ¶
func WithoutHeader(name string) Endomorphism
WithoutHeader creates a Endomorphism to remove a certain header
func WithoutQueryArg ¶
func WithoutQueryArg(name string) Endomorphism
WithoutQueryArg creates a Endomorphism that removes a query argument