http

package
v2.9.0 Latest Latest
Warning

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

 Go to latest Published: Apr 20, 2024 License: MIT Imports: 19 Imported by: 7

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

View Source 
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)
	StatusUnauthorized                 = StatusCode(http.StatusUnauthorized)
	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)
	StatusUnavailableForLegalReasons   = StatusCode(http.StatusUnavailableForLegalReasons)

	//
	StatusInternalServerError           = StatusCode(http.StatusInternalServerError)
	StatusNotImplemented                = StatusCode(http.StatusNotImplemented)
	StatusBadGateway                    = StatusCode(http.StatusBadGateway)
	StatusServiceUnavailable            = StatusCode(http.StatusServiceUnavailable)
	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

This section is empty.

Functions

func Client 

func Client() *http.Client

Creates default HTTP client

func HintedContentCodec added in v2.8.1 

func HintedContentCodec[T any](content string, stream io.ReadCloser, data *T) error

func IO 

func IO[T any](ctx *Context, arrows ...Arrow) (*T, error)

Executes protocol operation

func NewRequest 

func NewRequest(method, url string) (*http.Request, error)

Creates instance of HTTP Request

func WriteOnce added in v2.2.0 

func WriteOnce(w io.Writer, stack Stack, tests ...func() Arrow) error

Types

type Arrow 

type Arrow func(*Context) error

Arrow is a morphism applied to HTTP protocol stack

func Bind added in v2.6.0 

func Bind(arrows ...interface{ Arrow() Arrow }) Arrow

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 

func DELETE(arrows ...Arrow) Arrow

DELETE composes HTTP arrows to high-order function for HTTP DELETE request (a ⟼ b, b ⟼ c, c ⟼ d) ⤇ a ⟼ d

func GET 

func GET(arrows ...Arrow) Arrow

GET composes HTTP arrows to high-order function for HTTP GET request (a ⟼ b, b ⟼ c, c ⟼ d) ⤇ a ⟼ d 

func HEAD(arrows ...Arrow) Arrow

HEAD composes HTTP arrows to high-order function for HTTP HEAD request (a ⟼ b, b ⟼ c, c ⟼ d) ⤇ a ⟼ d

func Join 

func Join(arrows ...Arrow) Arrow

Join composes HTTP arrows to high-order function (a ⟼ b, b ⟼ c, c ⟼ d) ⤇ a ⟼ d

func PATCH 

func PATCH(arrows ...Arrow) Arrow

PATCH composes HTTP arrows to high-order function for HTTP PATCH request (a ⟼ b, b ⟼ c, c ⟼ d) ⤇ a ⟼ d

func POST 

func POST(arrows ...Arrow) Arrow

POST composes HTTP arrows to high-order function for HTTP POST request (a ⟼ b, b ⟼ c, c ⟼ d) ⤇ a ⟼ d

func PUT 

func PUT(arrows ...Arrow) Arrow

PUT composes HTTP arrows to high-order function for HTTP PUT request (a ⟼ b, b ⟼ c, c ⟼ d) ⤇ a ⟼ d

type Config 

type Config func(*Protocol)

Config option for HTTP client

func WithClient 

func WithClient(client Socket) Config

WithClient replaces default client with custom instance

func WithCookieJar added in v2.3.0 

func WithCookieJar() Config

WithCookieJar enables cookie handlings

func WithDebugPayload added in v2.3.0 

func WithDebugPayload() Config

Enables debug logging for requests, responses and payload

func WithDebugRequest added in v2.3.0 

func WithDebugRequest() Config

Enables debug logging for requests

func WithDebugResponse added in v2.3.0 

func WithDebugResponse() Config

Enables debug logging for requests & response

func WithDefaultHost added in v2.3.0 

func WithDefaultHost(host string) Config

func WithDefaultRedirectPolicy added in v2.8.2 

func WithDefaultRedirectPolicy() Config

WithDefaultRedirectPolicy resets default gurl no-redirect policy to Golang's one. It enables the HTTP stack follows redirects

func WithInsecureTLS added in v2.3.0 

func WithInsecureTLS() Config

WithInsecureTLS disables certificates validation

func WithMemento added in v2.3.0 

func WithMemento() Config

WithMemorize the response payload

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

func (*Context) IO 

func (ctx *Context) IO(arrows ...Arrow) error

IO executes protocol operations

func (*Context) Unsafe 

func (ctx *Context) Unsafe() error

Unsafe evaluates current context of HTTP I/O

type MatchableHeaderValues 

type MatchableHeaderValues interface {
	ReadableHeaderValues | WriteableHeaderValues
}

type Protocol 

type Protocol struct {
	Socket
	Host     string
	LogLevel int
	Memento  bool
}

Protocol is an instance of Stack

func (*Protocol) IO 

func (stack *Protocol) IO(ctx context.Context, arrows ...Arrow) error

func (*Protocol) WithContext 

func (stack *Protocol) WithContext(ctx context.Context) *Context

WithContext create instance of I/O Context

type ReadableHeaderValues 

type ReadableHeaderValues interface {
	int | string | time.Time
}

type Socket added in v2.8.3 

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

type Stack 

type Stack interface {
	WithContext(context.Context) *Context
	IO(context.Context, ...Arrow) error
}

Stack is HTTP protocol stack

func New 

func New(opts ...Config) Stack

Allocate instance of HTTP Stack

type Status added in v2.2.0 

type Status struct {
	ID       string        `json:"id"`
	Status   string        `json:"status"`
	Duration time.Duration `json:"duration"`
	Reason   string        `json:"reason,omitempty"`
	Payload  string        `json:"payload"`
}

func Once added in v2.2.0 

func Once(stack Stack, tests ...func() Arrow) []Status

Evaluates sequence of tests, returns status object for each

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) Error 

func (e StatusCode) Error() string

Error makes StatusCode to be error

func (StatusCode) Is 

func (e StatusCode) Is(err error) bool

Is compares wrapped errors

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

type WriteableHeaderValues 

type WriteableHeaderValues interface {
	*int | *string | *time.Time
}

Source Files

View all 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

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.