core

Documentation

Overview

Package core holds the request context behind the public tifa package. The server package builds contexts through the functions here, which application code cannot import.

Index

• Variables
• func Finish(c *Ctx) error
• func SetNext(c *Ctx, next func() error)
• func Use[T any](c *Ctx, load func(*Ctx) (T, error)) (T, error)
• type Ctx
  • func New(w http.ResponseWriter, r *http.Request, pattern string, bodyLimit int64) *Ctx
  • func (c *Ctx) Bind(v any) error
  • func (c *Ctx) BindQuery(v any) error
  • func (c *Ctx) Context() context.Context
  • func (c *Ctx) Cookie(name string) (*http.Cookie, error)
  • func (c *Ctx) Header(name string) string
  • func (c *Ctx) IsData() bool
  • func (c *Ctx) JSON(code int, v any) error
  • func (c *Ctx) Next() error
  • func (c *Ctx) NoContent(code int) error
  • func (c *Ctx) Param(name string) string
  • func (c *Ctx) Pattern() string
  • func (c *Ctx) Query(name string) string
  • func (c *Ctx) QueryAll(name string) []string
  • func (c *Ctx) Redirect(url string, code int) error
  • func (c *Ctx) Request() *http.Request
  • func (c *Ctx) SetBodyLimit(n int64) error
  • func (c *Ctx) SetContext(ctx context.Context)
  • func (c *Ctx) SetCookie(cookie *http.Cookie)
  • func (c *Ctx) SetHeader(key, value string)
  • func (c *Ctx) Text(code int, s string) error
  • func (c *Ctx) Writer() http.ResponseWriter
• type Error
  • func (e Error) Error() string
• type Fields
  • func (f Fields) Error() string
• type RedirectError
  • func (e *RedirectError) Error() string

Variables

var ErrNotFound = errors.New("tifa: not found")

ErrNotFound is an expected result. The server answers 404 without calling OnError.

Functions

func Finish

func Finish(c *Ctx) error

Finish releases what the request copies hold. The server calls it once the request is done.

func SetNext

func SetNext(c *Ctx, next func() error)

SetNext turns c into the context of OnRequest. Ctx.Next runs next once.

func Use

func Use[T any](c *Ctx, load func(*Ctx) (T, error)) (T, error)

Use returns the result of load for this request, running it at most once. A caller that arrives while load is running waits for that run.

Types

type Ctx

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

Ctx wraps one request and its response.

func New

func New(w http.ResponseWriter, r *http.Request, pattern string, bodyLimit int64) *Ctx

New builds the context for one request. pattern is the matched route pattern, empty when no route matched. The request body is limited to bodyLimit bytes unless SetBodyLimit changes it before the first read.

func (*Ctx) Bind

func (c *Ctx) Bind(v any) error

Bind decodes the request body into v by Content-Type: JSON, URL-encoded form or multipart form. Client mistakes come back as Error with status 400, 413 or 415.

func (*Ctx) BindQuery

func (c *Ctx) BindQuery(v any) error

BindQuery decodes the query string into the struct v, with the names and value types of a form body. Query parameters that name no field are ignored. A query string that does not parse, or a value that does not, comes back as Error with status 400.

func (*Ctx) Context

func (c *Ctx) Context() context.Context

func (*Ctx) Cookie

func (c *Ctx) Cookie(name string) (*http.Cookie, error)

func (*Ctx) Header

func (c *Ctx) Header(name string) string

func (*Ctx) IsData

func (c *Ctx) IsData() bool

IsData reports whether this is a client navigation asking for route data.

func (*Ctx) JSON

func (c *Ctx) JSON(code int, v any) error

func (*Ctx) Next

func (c *Ctx) Next() error

Next runs the matched route from OnRequest and returns its error. It may be called once.

func (*Ctx) NoContent

func (c *Ctx) NoContent(code int) error

func (*Ctx) Param

func (c *Ctx) Param(name string) string

func (*Ctx) Pattern

func (c *Ctx) Pattern() string

Pattern is the matched route pattern, empty when the URL matched no route.

func (*Ctx) Query

func (c *Ctx) Query(name string) string

func (*Ctx) QueryAll

func (c *Ctx) QueryAll(name string) []string

QueryAll returns every value of the query parameter name, in order, and nil when there is none. Query returns only the first.

func (*Ctx) Redirect

func (c *Ctx) Redirect(url string, code int) error

Redirect returns an error value. Returning it from Load, a method handler or OnRequest makes the server redirect.

func (*Ctx) Request

func (c *Ctx) Request() *http.Request

func (*Ctx) SetBodyLimit

func (c *Ctx) SetBodyLimit(n int64) error

SetBodyLimit changes the request body limit. Call it before anything reads the body, on the goroutine that handles the request, usually in OnRequest. Once reading has started it returns an error and the limit stays as it was. The body stays an http.MaxBytesReader, so ParseForm honours the limit instead of its own 10 MiB cap.

func (*Ctx) SetContext

func (c *Ctx) SetContext(ctx context.Context)

SetContext replaces the request context, for middleware that stores request-scoped values.

func (*Ctx) SetCookie

func (c *Ctx) SetCookie(cookie *http.Cookie)

func (*Ctx) SetHeader

func (c *Ctx) SetHeader(key, value string)

func (*Ctx) Text

func (c *Ctx) Text(code int, s string) error

func (*Ctx) Writer

func (c *Ctx) Writer() http.ResponseWriter

type Error

type Error struct {
	Status  int
	Message string
}

Error is a failure that is safe to show to the client. The server answers it as is, without calling OnError.

func (Error) Error

func (e Error) Error() string

type Fields

type Fields map[string]string

Fields is a message per input field, by its json name, for a form to show next to each field. The server answers it with 422 without calling OnError, and an answer in JSON carries it as "fields". It is a separate type so that Error stays comparable.

func (Fields) Error

func (f Fields) Error() string

type RedirectError

type RedirectError struct {
	URL  string
	Code int
}

RedirectError is returned by Ctx.Redirect. The server performs the redirect without calling OnError.

func (*RedirectError) Error

func (e *RedirectError) Error() string