http

Documentation

Index

• func Escape(p Path) string
• type Body
• type Encoding
  • func (e Encoding) Identity() bool
• type Environment
• type OnBodyCallback
• type Params
• type Path
• type Request
  • func NewRequest(cfg config.Config, hdrs headers.Headers, query *query.Query, ...) *Request
  • func (r *Request) Clear() (err error)
  • func (r *Request) Cookies() (cookie.Jar, error)
  • func (r *Request) Hijack() (tcp.Client, error)
  • func (r *Request) JSON(model any) error
  • func (r *Request) Respond() *Response
  • func (r *Request) WasHijacked() bool
• type Response
  • func Bytes(request *Request, b []byte) *Response
  • func Code(request *Request, code status.Code) *Response
  • func Error(request *Request, err error, code ...status.Code) *Response
  • func File(request *Request, path string) *Response
  • func JSON(request *Request, model any) *Response
  • func NewResponse() *Response
  • func Respond(request *Request) *Response
  • func String(request *Request, str string) *Response
  • func (r *Response) Attachment(reader io.Reader, size int) *Response
  • func (r *Response) Bytes(body []byte) *Response
  • func (r *Response) Clear() *Response
  • func (r *Response) Code(code status.Code) *Response
  • func (r *Response) ContentType(value string) *Response
  • func (r *Response) Cookie(cookies ...cookie.Cookie) *Response
  • func (r *Response) Error(err error, code ...status.Code) *Response
  • func (r *Response) File(path string) *Response
  • func (r *Response) Header(key string, values ...string) *Response
  • func (r *Response) Headers(headers map[string][]string) *Response
  • func (r *Response) JSON(model any) *Response
  • func (r *Response) Reveal() *response.Fields
  • func (r *Response) Status(status status.Status) *Response
  • func (r *Response) String(body string) *Response
  • func (r *Response) TransferEncoding(value string) *Response
  • func (r *Response) TryFile(path string) (*Response, error)
  • func (r *Response) TryJSON(model any) (*Response, error)
  • func (r *Response) Write(b []byte) (n int, err error)
• type ResponseWriter

Functions

func Escape

func Escape(p Path) string

Types

type Body

type Body interface {
	io.Reader

	// String returns the whole request's body at once as a string
	String() (string, error)
	// Bytes returns the whole request's body at once as a byte slice
	Bytes() ([]byte, error)
	// Callback takes a function that'll be called each time as at least 1 byte of request's
	// body is received. The call will be blocked until the whole body won't be processed.
	// When the body is completely processed, the method will silently exit without notifying
	// the passed function anyhow
	Callback(cb OnBodyCallback) error
	// Retrieve reads request's body from a socket. If there's no data yet, the call will
	// be blocked. It's safe to call the method after whole body was read, as only io.EOF
	// will be returned
	Retrieve() ([]byte, error)
	// Discard discards the rest of the body
	Discard() error
	// Init MUST NOT be used, as it leads to deadlock. FOR INTERNAL PURPOSES ONLY.
	Init(*Request)
}

type Encoding

type Encoding struct {
	// Transfer represents Transfer-Encoding header value, split by comma
	Transfer []string
	// Content represents Content-Encoding header value, split by comma
	Content []string
	// Chunked doesn't belong to any of encodings, as it is still must be processed individually
	Chunked, HasTrailer bool
}

func (Encoding) Identity

func (e Encoding) Identity() bool

Identity returns, whether the message was encoded

type Environment

type Environment struct {
	// Error contains an error, if occurred
	Error error
	// AllowedMethods is used to pass a string containing all the allowed methods for a
	// specific endpoint. Has non-zero-value only when 405 Method Not Allowed raises
	AllowedMethods string
	// Encryption is a token that corresponds to the used encryption method. May be
	// extended by custom values
	Encryption encryption.Token
	// AliasFrom contains the original request path, in case it was replaced via alias
	// aka implicit redirect
	AliasFrom string
}

type OnBodyCallback

type OnBodyCallback func([]byte) error

type Params

type Params = *keyvalue.Storage

type Path

type Path = string

type Request

type Request struct {
	// Method represents the request's method
	Method method.Method
	// Path represents decoded request URI
	Path Path
	// Query are request's URI parameters
	Query *query.Query
	// Params are dynamic path's wildcards
	Params Params
	// Proto is the protocol, which was used to make the request
	Proto proto.Proto
	// Headers are request headers. They are stored non-normalized, however lookup is
	// case-insensitive
	Headers headers.Headers
	// Encoding holds an information about encoding, that was used to make the request
	Encoding Encoding
	// ContentLength obtains the value from Content-Length header. It holds the value of 0
	// if isn't presented.
	//
	// NOTE: if any of transfer-encodings were applied, you MUST NOT look at this value
	ContentLength int
	// ContentType obtains Content-Type header value
	ContentType string
	// Connection holds the Connection header value. It isn't normalized, so can be anything
	// and in any case. So in order to compare it, highly recommended to do it case-insensibly
	Connection 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.
	// WARNING: in order to use the value to represent a user, MAKE SURE there are no proxies
	// in the middle
	Remote net.Addr
	// Ctx is a request context. It may be filled with arbitrary data across middlewares
	// and handler by itself
	Ctx context.Context
	// Env is a set of fixed variables passed by core. They are passed separately from Request.Ctx
	// in order to not only distinguish user-defined values in ctx from those from core, but also
	// to gain performance, as accessing the struct is much faster than looking up in context.Context
	Env Environment
	// Body accesses the request's body
	Body Body
	// contains filtered or unexported fields
}

Request represents HTTP request

func NewRequest

func NewRequest(
	cfg config.Config, hdrs headers.Headers, query *query.Query, response *Response,
	client tcp.Client, body Body, params Params,
) *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) 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) Cookies

func (r *Request) Cookies() (cookie.Jar, error)

Cookies returns a cookie jar with parsed cookies key-value pairs, and an error if the syntax is malformed. The returned jar should be re-used, as this method doesn't cache the parsed result across calls and may be pretty expensive

func (*Request) Hijack

func (r *Request) Hijack() (tcp.Client, 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 {
	// contains filtered or unexported fields
}

func Bytes

func Bytes(request *Request, b []byte) *Response

Bytes is a predicate to request.Respond().Bytes(...)

func Code

func Code(request *Request, code status.Code) *Response

Code is a predicate to request.Respond().Code(...)

func Error

func Error(request *Request, err error, code ...status.Code) *Response

Error is a predicate to request.Respond().Error(...)

Error returns a response builder with an error set. If passed err is nil, nothing will happen. If an instance of status.HTTPError is passed, error code will be automatically set. Custom codes can be passed, however only first will be used. By default, the error is status.ErrInternalServerError

func File

func File(request *Request, path string) *Response

File is a predicate to request.Respond().File(...)

func JSON

func JSON(request *Request, model any) *Response

JSON is a predicate to request.Respond().JSON(...)

func NewResponse

func NewResponse() *Response

NewResponse returns a new instance of the Response object with status code set to 200 OK, pre-allocated space for response headers and text/html content-type. NOTE: it's recommended to use Request.Respond() method inside of handlers, if there's no clear reason otherwise

func Respond

func Respond(request *Request) *Response

Respond is a predicate to request.Respond(). May be used as a dummy handler

func String

func String(request *Request, str string) *Response

String is a predicate to request.Respond().String(...)

func (*Response) Attachment

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

Attachment 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) Bytes

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

Bytes sets the response's body to passed slice WITHOUT COPYING. Changing the passed slice later will affect the response by itself

func (*Response) Clear

func (r *Response) Clear() *Response

Clear discards everything was done with Response object before

func (*Response) Code

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

Code 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) ContentType

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

ContentType sets a custom Content-Type header value.

func (*Response) Cookie

func (r *Response) Cookie(cookies ...cookie.Cookie) *Response

Cookie adds cookies. They'll be later rendered as a set of Set-Cookie headers

func (*Response) Error

func (r *Response) Error(err error, code ...status.Code) *Response

Error returns a response builder with an error set. If passed err is nil, nothing will happen. If an instance of status.HTTPError is passed, error code will be automatically set. Custom codes can be passed, however only first will be used. By default, the error is status.ErrInternalServerError

func (*Response) File

func (r *Response) File(path string) *Response

File opens a file for reading and returns a new Response with attachment, set to the file descriptor.fields. If error occurred, it'll be silently returned

func (*Response) Header

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

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

func (*Response) Headers

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

Headers 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) JSON

func (r *Response) JSON(model any) *Response

JSON does the same as TryJSON does, except returned error is being implicitly wrapped by Error

func (*Response) Reveal

func (r *Response) Reveal() *response.Fields

Reveal returns a struct with values, filled by builder. Used mostly in internal purposes

func (*Response) Status

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

Status 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) String

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

String sets the response's body to the passed string

func (*Response) TransferEncoding

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

TransferEncoding sets a custom Transfer-Encoding header value.

func (*Response) TryFile

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

TryFile tries to open a file for reading and returns a new Response with attachment.

func (*Response) TryJSON

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

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

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