Documentation
¶
Overview ¶
Package http defines category of HTTP I/O, "do"-notation becomes
http.Join( ø..., ø..., ƒ..., ƒ..., )
Symbol `ø` (option + o) is an convenient alias to module gurl/http/send, which defines writer morphism that focuses inside and reshapes HTTP protocol request. The writer morphism is used to declare HTTP method, destination URL, request headers and payload.
Symbol `ƒ` (option + f) is an convenient alias to module gurl/http/recv, which defines reader morphism that focuses into side-effect, HTTP protocol response. The reader morphism is a pattern matcher, is used to match HTTP response code, headers and response payload. It helps us to declare our expectations on the response. The evaluation of "program" fails if expectations do not match actual response.
Let's look on step-by-step usage of the category.
**Method and URL** are mandatory. It has to be a first element in the construction.
http.GET(
ø.URI("http://example.com"),
...
)
Definition of **request headers** is an optional. You can list as many headers as needed. Either using string literals or variables. Some frequently used headers implements aliases (e.g. ø.ContentJSON(), ...)
http.GET(
...
ø.Header("Accept", "application/json"),
ø.Header("Authorization", &token),
...
)
The **request payload** is also an optional. You can also use native Golang data types as egress payload. The library implicitly encodes input structures to binary using Content-Type as a hint.
http.GET(
...
ø.Send(MyType{Hello: "World"}),
...
)
The declaration of expected response is always starts with mandatory HTTP **status code**. The execution fails if peer responds with other than specified value.
http.GET( ... ƒ.Code(http.StatusCodeOK), ... )
It is possible to match presence of header in the response, match its entire content or lift the header value to a variable. The execution fails if HTTP response do not match the expectation.
http.GET(
...
ƒ.Header("Content-Type", "application/json"),
...
)
The library is able to **decode payload** into Golang native data structure using Content-Type header as a hint.
var data MyType http.GET( ... ƒ.Recv(&data) ... )
Please note, the library implements lenses to inline assert of decoded content. See the documentation of gurl/http/recv module.
Index ¶
- Constants
- Variables
- func Client() *http.Client
- func HintedContentCodec[T any](content string, stream io.ReadCloser, data *T) error
- func IO[T any](ctx *Context, arrows ...Arrow) (*T, error)
- func NewRequest(method, url string) (*http.Request, error)
- func WriteOnce(w io.Writer, stack Stack, tests ...func() Arrow) error
- type Arrow
- type Context
- type MatchableHeaderValues
- type Option
- type Protocol
- type ReadableHeaderValues
- type Socket
- type Stack
- type Status
- type StatusCode
- type WriteableHeaderValues
Constants ¶
const ( // StatusContinue = StatusCode(http.StatusContinue) StatusSwitchingProtocols = StatusCode(http.StatusSwitchingProtocols) StatusProcessing = StatusCode(http.StatusProcessing) StatusEarlyHints = StatusCode(http.StatusEarlyHints) // StatusOK = StatusCode(http.StatusOK) StatusCreated = StatusCode(http.StatusCreated) StatusAccepted = StatusCode(http.StatusAccepted) StatusNonAuthoritativeInfo = StatusCode(http.StatusNonAuthoritativeInfo) StatusNoContent = StatusCode(http.StatusNoContent) StatusResetContent = StatusCode(http.StatusResetContent) StatusPartialContent = StatusCode(http.StatusPartialContent) StatusMultiStatus = StatusCode(http.StatusMultiStatus) StatusAlreadyReported = StatusCode(http.StatusAlreadyReported) StatusIMUsed = StatusCode(http.StatusIMUsed) // StatusMultipleChoices = StatusCode(http.StatusMultipleChoices) StatusMovedPermanently = StatusCode(http.StatusMovedPermanently) StatusFound = StatusCode(http.StatusFound) StatusSeeOther = StatusCode(http.StatusSeeOther) StatusNotModified = StatusCode(http.StatusNotModified) StatusUseProxy = StatusCode(http.StatusUseProxy) StatusTemporaryRedirect = StatusCode(http.StatusTemporaryRedirect) StatusPermanentRedirect = StatusCode(http.StatusPermanentRedirect) // StatusBadRequest = StatusCode(http.StatusBadRequest) StatusPaymentRequired = StatusCode(http.StatusPaymentRequired) StatusForbidden = StatusCode(http.StatusForbidden) StatusNotFound = StatusCode(http.StatusNotFound) StatusMethodNotAllowed = StatusCode(http.StatusMethodNotAllowed) StatusNotAcceptable = StatusCode(http.StatusNotAcceptable) StatusProxyAuthRequired = StatusCode(http.StatusProxyAuthRequired) StatusRequestTimeout = StatusCode(http.StatusRequestTimeout) StatusConflict = StatusCode(http.StatusConflict) StatusGone = StatusCode(http.StatusGone) StatusLengthRequired = StatusCode(http.StatusLengthRequired) StatusPreconditionFailed = StatusCode(http.StatusPreconditionFailed) StatusRequestEntityTooLarge = StatusCode(http.StatusRequestEntityTooLarge) StatusRequestURITooLong = StatusCode(http.StatusRequestURITooLong) StatusUnsupportedMediaType = StatusCode(http.StatusUnsupportedMediaType) StatusRequestedRangeNotSatisfiable = StatusCode(http.StatusRequestedRangeNotSatisfiable) StatusExpectationFailed = StatusCode(http.StatusExpectationFailed) StatusTeapot = StatusCode(http.StatusTeapot) StatusMisdirectedRequest = StatusCode(http.StatusMisdirectedRequest) StatusUnprocessableEntity = StatusCode(http.StatusUnprocessableEntity) StatusLocked = StatusCode(http.StatusLocked) StatusFailedDependency = StatusCode(http.StatusFailedDependency) StatusTooEarly = StatusCode(http.StatusTooEarly) StatusUpgradeRequired = StatusCode(http.StatusUpgradeRequired) StatusPreconditionRequired = StatusCode(http.StatusPreconditionRequired) StatusTooManyRequests = StatusCode(http.StatusTooManyRequests) StatusRequestHeaderFieldsTooLarge = StatusCode(http.StatusRequestHeaderFieldsTooLarge) // StatusInternalServerError = StatusCode(http.StatusInternalServerError) StatusNotImplemented = StatusCode(http.StatusNotImplemented) StatusBadGateway = StatusCode(http.StatusBadGateway) StatusGatewayTimeout = StatusCode(http.StatusGatewayTimeout) StatusHTTPVersionNotSupported = StatusCode(http.StatusHTTPVersionNotSupported) StatusVariantAlsoNegotiates = StatusCode(http.StatusVariantAlsoNegotiates) StatusInsufficientStorage = StatusCode(http.StatusInsufficientStorage) StatusLoopDetected = StatusCode(http.StatusLoopDetected) StatusNotExtended = StatusCode(http.StatusNotExtended) StatusNetworkAuthenticationRequired = StatusCode(http.StatusNetworkAuthenticationRequired) )
Variables ¶
var ( // Set custom implementation of HTTP client. // It requires anything that implements Socket interface (aka http.Client) // // type Socket interface { // Do(req *http.Request) (*http.Response, error) // } WithClient = opts.ForType[Protocol, Socket]() // Set the default host for http stack. // The host is used when request URI does not contain any host. WithHost = opts.ForName[Protocol, string]("Host") // Enables HTTP Response buffering WithMemento = opts.ForName[Protocol, bool]("Memento") // Buffers HTTP Response Payload into context. WithMementoPayload = WithMemento(true) // Disables TLS certificate validation for HTTP(S) sessions. WithInsecureTLS = opts.From(withInsecureTLS) // Enables automated cookie handling across requests originated from the session. WithCookieJar = opts.From(withCookieJar) // Disables default [gurl] redirect policy to Golang's one. // It enables the HTTP stack automatically follows redirects WithRedirects = opts.From(withRedirects) // Enable log level WithLogLevel = opts.ForName[Protocol, int]("LogLevel") // Enables debug logging. // The logger outputs HTTP requests only. WithDebugRequest = WithLogLevel(1) // Enables debug logging. // The logger outputs HTTP requests and responses. WithDebugResponse = WithLogLevel(2) // Enable debug logging. WithDebugPayload = WithLogLevel(3) )
Functions ¶
func HintedContentCodec ¶ added in v2.8.1
func HintedContentCodec[T any](content string, stream io.ReadCloser, data *T) error
func NewRequest ¶
Creates instance of HTTP Request
Types ¶
type Arrow ¶
Arrow is a morphism applied to HTTP protocol stack
func Bind ¶ added in v2.6.0
Bind composes HTTP arrows to high-order function In contrast with Join, input is arrow builders (a ⟼ b, b ⟼ c, c ⟼ d) ⤇ a ⟼ d
func DELETE ¶
DELETE composes HTTP arrows to high-order function for HTTP DELETE request (a ⟼ b, b ⟼ c, c ⟼ d) ⤇ a ⟼ d
func GET ¶
GET composes HTTP arrows to high-order function for HTTP GET request (a ⟼ b, b ⟼ c, c ⟼ d) ⤇ a ⟼ d
func HEAD ¶
HEAD composes HTTP arrows to high-order function for HTTP HEAD request (a ⟼ b, b ⟼ c, c ⟼ d) ⤇ a ⟼ d
func PATCH ¶
PATCH composes HTTP arrows to high-order function for HTTP PATCH request (a ⟼ b, b ⟼ c, c ⟼ d) ⤇ a ⟼ d
type Context ¶
type Context struct {
context.Context
Host string
Method string
Request *http.Request
Response *http.Response
Payload []byte
// contains filtered or unexported fields
}
Context of HTTP I/O
type MatchableHeaderValues ¶
type MatchableHeaderValues interface {
ReadableHeaderValues | WriteableHeaderValues
}
type Status ¶ added in v2.2.0
type StatusCode ¶
type StatusCode int
StatusCode is a base type for typesafe HTTP status codes. The library advertises a usage of "pattern-matching" on HTTP status handling, which helps developers to catch mismatch of HTTP statuses along with other side-effect failures.
The final values of HTTP statuses embeds StatusCode type. It makes them to look like a "sum-types" and be compatible with any other error (side effect failures) within IO category. Use final type instances in the error handling routines.
Use type switch for error handling "branches"
switch err := cat.Fail.(type) {
case nil:
// Nothing
case StatusCode:
switch err {
case http.StatusOK:
// HTTP 200 OK
case http.StatusNotFound:
// HTTP 404 NotFound
default:
// any other HTTP errors
}
default:
// any other errors
}
Conditional error handling on expected HTTP Status
if errors.Is(cat.Fail, http.StatusNotFound) {
}
Conditional error handling on any HTTP Status
if _, ok := cat.Fail.(gurl.StatusCode); ok {
}
func NewStatusCode ¶
func NewStatusCode(code int, required ...StatusCode) StatusCode
NewStatusCode transforms integer codes to types
func (StatusCode) Required ¶
func (e StatusCode) Required() int
Required returns (expected, required) HTTP status
func (StatusCode) StatusCode ¶
func (e StatusCode) StatusCode() int
Value transforms StatusCode type to integer value: StatusCode ⟼ int
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package recv defines a pure computations to compose HTTP response receivers
|
Package recv defines a pure computations to compose HTTP response receivers |
|
Package send defines a pure computations to compose HTTP request senders
|
Package send defines a pure computations to compose HTTP request senders |