http

Documentation

Index

• type Body
  • func NewBody(reader BodyReader) *Body
  • func (b *Body) Callback(onBody onBodyCallback) error
  • func (b *Body) Full() ([]byte, error)
  • func (b *Body) Init(req *Request)
  • func (b *Body) Read(into []byte) (n int, err error)
  • func (b *Body) Reset() error
• type BodyReader
• type Params
• type Request
  • func NewRequest(ctx context.Context, hdrs *headers.Headers, query query.Query, ...) *Request
  • func (r *Request) Body() *Body
  • func (r *Request) Clear() (err error)
  • func (r *Request) Hijack() (net.Conn, error)
  • func (r *Request) JSON(model any) error
  • func (r *Request) Respond() *Response
  • func (r *Request) WasHijacked() bool
• type Response
  • func Error(request *Request, err error) *Response
  • func NewResponse() *Response
  • func Respond(request *Request) *Response
  • func (r *Response) Attachment() types.Attachment
  • func (r *Response) Clear() *Response
  • func (r *Response) Headers() []string
  • func (r *Response) WithAttachment(reader io.Reader, size int) *Response
  • func (r *Response) WithBody(body string) *Response
  • func (r *Response) WithBodyByte(body []byte) *Response
  • func (r *Response) WithCode(code status.Code) *Response
  • func (r *Response) WithContentType(value string) *Response
  • func (r *Response) WithError(err error) *Response
  • func (r *Response) WithFile(path string) (*Response, error)
  • func (r *Response) WithHeader(key string, values ...string) *Response
  • func (r *Response) WithHeaders(headers map[string][]string) *Response
  • func (r *Response) WithJSON(model any) (*Response, error)
  • func (r *Response) WithStatus(status status.Status) *Response
  • func (r *Response) WithTransferEncoding(value string) *Response
  • func (r *Response) Write(b []byte) (n int, err error)
• type ResponseWriter

Types

type Body

type Body struct {
	// contains filtered or unexported fields
}

func NewBody

func NewBody(reader BodyReader) *Body

func (*Body) Callback

func (b *Body) Callback(onBody onBodyCallback) error

Callback takes a function, that'll be called with body piece every time it's received. In case error is returned from the callback, it'll also be returned from this method

func (*Body) Full

func (b *Body) Full() ([]byte, error)

Full returns the whole body at once

WARNING: returned slice is an underlying buffer, that will be re-written during the next call of this method.

func (*Body) Init

func (b *Body) Init(req *Request)

Init is a system method, that MUST not be called, otherwise connection may get stuck, leading to hanging connection (until read-timeout won't be exceeded)

func (*Body) Read

func (b *Body) Read(into []byte) (n int, err error)

Read implements the io.Reader interface, so behaves respectively

func (*Body) Reset

func (b *Body) Reset() error

Reset resets the body.

NOTE: this is a system method, that SHOULD NOT be called by user manually. However, this won't affect anything anyhow, except impossibility to restore the body data

type BodyReader

type BodyReader interface {
	Init(*Request)
	Read() ([]byte, error)
}

type Params

type Params = map[string]string

type Request

type Request struct {
	Method method.Method
	Path   string
	// Query is a key-value part of the Path
	Query query.Query
	// Params are dynamic segments, in case dynamic routing is enabled
	Params        Params
	Proto         proto.Proto
	Headers       *headers.Headers
	Encoding      headers.Encoding
	ContentLength int
	ContentType   string
	// Upgrade is the protocol token, which is set by default to proto.Unknown. In
	// case it is anything else, then Upgrade header was received
	Upgrade proto.Proto
	// Remote represents remote net.Addr
	Remote net.Addr
	// Ctx is a request context. It may be filled with arbitrary data across middlewares
	// and handler by itself.
	Ctx context.Context
	// IsTLS describes, whether request was made via https
	IsTLS bool
	// contains filtered or unexported fields
}

Request represents HTTP request

func NewRequest

func NewRequest(
	ctx context.Context, hdrs *headers.Headers, query query.Query, response *Response,
	conn net.Conn, body *Body, paramsMap Params, disableParamsMapClearing bool,
) *Request

NewRequest returns a new instance of request object and body gateway Must not be used externally, this function is for internal purposes only HTTP/1.1 as a protocol by default is set because if first request from user is invalid, we need to render a response using request method, but appears that default method is a null-value (proto.Unknown)

func (*Request) Body

func (r *Request) Body() *Body

Body returns an entity representing a request's body

func (*Request) Clear

func (r *Request) Clear() (err error)

Clear resets request headers and reads body into nowhere until completed. It is implemented to clear the request object between requests

func (*Request) Hijack

func (r *Request) Hijack() (net.Conn, error)

Hijack the connection. Request body will be implicitly read (so if you need it you should read it before) all the body left. After handler exits, the connection will be closed, so the connection can be hijacked only once

func (*Request) JSON

func (r *Request) JSON(model any) error

JSON takes a model and returns an error if occurred. Model must be a pointer to a structure. If Content-Type header is given, but is not "application/json", then status.ErrUnsupportedMediaType will be returned. If JSON is malformed, or it doesn't match the model, then custom jsoniter error will be returned

func (*Request) Respond

func (r *Request) Respond() *Response

Respond returns Response object.

WARNING: this method clears the response builder under the hood. As it is passed by reference, it'll be cleared EVERYWHERE along a handler

func (*Request) WasHijacked

func (r *Request) WasHijacked() bool

WasHijacked returns true or false, depending on whether was a connection hijacked

type Response

type Response struct {
	Status      status.Status
	ContentType string
	// TODO: add corresponding Content-Encoding field
	// TODO: automatically apply the encoding on a body when specified
	TransferEncoding string

	Body []byte
	Code status.Code
	// contains filtered or unexported fields
}

func Error

func Error(request *Request, err error) *Response

func NewResponse

func NewResponse() *Response

func Respond

func Respond(request *Request) *Response

Respond returns a response object of request

func (*Response) Attachment

func (r *Response) Attachment() types.Attachment

Attachment returns Response's attachment.

Note: it serves mostly internal purposes

func (*Response) Clear

func (r *Response) Clear() *Response

Clear discards everything was done with Response object before

func (*Response) Headers

func (r *Response) Headers() []string

Headers returns an underlying Response headers

func (*Response) WithAttachment

func (r *Response) WithAttachment(reader io.Reader, size int) *Response

WithAttachment sets a Response's attachment. In this case Response body will be ignored. If size <= 0, then Transfer-Encoding: chunked will be used

func (*Response) WithBody

func (r *Response) WithBody(body string) *Response

WithBody sets a string as a Response body. This will override already-existing body if it was set

func (*Response) WithBodyByte

func (r *Response) WithBodyByte(body []byte) *Response

WithBodyByte does all the same as Body does, but for byte slices

func (*Response) WithCode

func (r *Response) WithCode(code status.Code) *Response

WithCode sets a Response code and a corresponding status. In case of unknown code, "Unknown Status Code" will be set as a status code. In this case you should call Status explicitly

func (*Response) WithContentType

func (r *Response) WithContentType(value string) *Response

WithContentType sets a custom Content-Type header value.

func (*Response) WithError

func (r *Response) WithError(err error) *Response

WithError returns Response with corresponding HTTP error code, if passed error is status.HTTPError. Otherwise, code is considered to be 500 Internal Server Error. Note: revealing error text may be dangerous

func (*Response) WithFile

func (r *Response) WithFile(path string) (*Response, error)

WithFile opens a file for reading, and returns a new Response with attachment corresponding to the file FD. In case not found or any other error, it'll be directly returned. In case error occurred while opening the file, Response builder won't be affected and stay clean

func (*Response) WithHeader

func (r *Response) WithHeader(key string, values ...string) *Response

WithHeader sets header values to a key. In case it already exists the value will be appended.

func (*Response) WithHeaders

func (r *Response) WithHeaders(headers map[string][]string) *Response

WithHeaders simply merges passed headers into Response. Also, it is the only way to specify a quality marker of value. In case headers were not initialized before, Response headers will be set to a passed map, so editing this map will affect Response

func (*Response) WithJSON

func (r *Response) WithJSON(model any) (*Response, error)

WithJSON receives a model (must be a pointer to the structure) and returns a new Response object and an error

func (*Response) WithStatus

func (r *Response) WithStatus(status status.Status) *Response

WithStatus sets a custom status text. This text does not matter at all, and usually totally ignored by client, so there is actually no reasons to use this except some rare cases when you need to represent a Response status text somewhere

func (*Response) WithTransferEncoding

func (r *Response) WithTransferEncoding(value string) *Response

WithTransferEncoding sets a custom Transfer-Encoding header value.

func (*Response) Write

func (r *Response) Write(b []byte) (n int, err error)

Write implements io.Reader interface. It always returns n=len(b) and err=nil

type ResponseWriter

type ResponseWriter func(b []byte) error