uapi

Documentation

Overview

Defines a standard way to define routes

Index

• func CompileValidationErrors(payload any) map[string]string
• func SetupState(s UAPIState)
• type APIRouter
• type AuthData
• type AuthType
• type HttpResponse
  • func DefaultResponse(statusCode int) HttpResponse
  • func MarshalReq(r *http.Request, dst any) (resp HttpResponse, ok bool)
  • func MarshalReqWithHeaders(r *http.Request, dst any, headers map[string]string) (resp HttpResponse, ok bool)
  • func ValidatorErrorResponse(compiled map[string]string, v validator.ValidationErrors) HttpResponse
• type Method
  • func (m Method) String() string
• type Route
  • func (r Route) Route(ro Router)
  • func (r Route) String() string
• type RouteData
• type Router
• type UAPIConstants
• type UAPIDefaultResponder
• type UAPIInitData
• type UAPIState
  • func (s *UAPIState) SetCurrentTag(tag string)

Functions

func CompileValidationErrors

func CompileValidationErrors(payload any) map[string]string

func SetupState

func SetupState(s UAPIState)

Types

type APIRouter

type APIRouter interface {
	Routes(r *chi.Mux)
	Tag() (string, string)
}

A API Router, not to be confused with Router which routes the actual routes

type AuthData

type AuthData struct {
	TargetType string         `json:"target_type"`
	ID         string         `json:"id"`
	Authorized bool           `json:"authorized"`
	Banned     bool           `json:"banned"` // Only applicable with AllowedScope
	Data       map[string]any `json:"data"`   // Additional data
}

type AuthType

type AuthType struct {
	URLVar       string
	Type         string
	AllowedScope string // If this is set, then ban checks are not fatal
}

type HttpResponse

type HttpResponse struct {
	// Data is the data to be sent to the client
	Data string
	// Optional, can be used in place of Data
	Bytes []byte
	// Json body to be sent to the client
	Json any
	// Headers to set
	Headers map[string]string
	// Status is the HTTP status code to send
	Status int
	// Redirect to a URL
	Redirect string
}

func DefaultResponse

func DefaultResponse(statusCode int) HttpResponse

Creates a default HTTP response based on the status code 200 is treated as 204 No Content

func MarshalReq

func MarshalReq(r *http.Request, dst any) (resp HttpResponse, ok bool)

func MarshalReqWithHeaders

func MarshalReqWithHeaders(r *http.Request, dst any, headers map[string]string) (resp HttpResponse, ok bool)

func ValidatorErrorResponse

func ValidatorErrorResponse(compiled map[string]string, v validator.ValidationErrors) HttpResponse

type Method

type Method int

const (
	GET Method = iota
	POST
	PATCH
	PUT
	DELETE
	HEAD
)

func (Method) String

func (m Method) String() string

Returns the method as a string

type Route

type Route struct {
	Method       Method
	Pattern      string
	Aliases      map[string]string // Aliases for the route, this is useful for e.g. URL rewrites, format is pattern: reason
	OpId         string
	Handler      func(d RouteData, r *http.Request) HttpResponse
	Setup        func()
	Docs         func() *docs.Doc
	Auth         []AuthType
	ExtData      map[string]any
	AuthOptional bool
	SanityCheck  func() error

	// Disables sanity check that ensures all variables are followed by a /
	//
	// e.g. /{foo}s/
	DisablePathSlashCheck bool
}

Represents a route on the API

func (Route) Route

func (r Route) Route(ro Router)

func (Route) String

func (r Route) String() string

type RouteData

type RouteData struct {
	Context context.Context
	Auth    AuthData
	Props   map[string]string // Stores additional properties
}

type Router

type Router interface {
	Get(pattern string, h http.HandlerFunc)
	Post(pattern string, h http.HandlerFunc)
	Patch(pattern string, h http.HandlerFunc)
	Put(pattern string, h http.HandlerFunc)
	Delete(pattern string, h http.HandlerFunc)
	Head(pattern string, h http.HandlerFunc)
}

type UAPIConstants

type UAPIConstants struct {
	// String returned when the resource could not be found
	ResourceNotFound string

	// String returned when the request is invalid
	BadRequest string

	// String returned when the user is not authorized (403)
	Forbidden string

	// String returned when the user is not authorized (401)
	Unauthorized string

	// String returned when the server encounters an internal error
	InternalServerError string

	// String returned when the method is not allowed
	MethodNotAllowed string

	// String returned when the body is required
	BodyRequired string
}

type UAPIDefaultResponder

type UAPIDefaultResponder interface {
	// Returns the msg with the response type
	New(msg string, ctx map[string]string) any
}

type UAPIInitData

type UAPIInitData struct {
	// The current tag being loaded
	Tag string
}

This struct contains initialization data while loading UAPI (such as the current tag etc.)

type UAPIState

type UAPIState struct {
	Logger              *zap.Logger
	Authorize           func(r Route, req *http.Request) (AuthData, HttpResponse, bool)
	AuthTypeMap         map[string]string // E.g. bot => Bot, user => User etc.
	RouteDataMiddleware func(rd *RouteData, req *http.Request) (*RouteData, error)
	BaseSanityCheck     func(r Route) error
	PatchDocs           func(d *docs.Doc) *docs.Doc

	// Used in cache algo
	Context context.Context

	// Api constants
	Constants *UAPIConstants

	// UAPI default response type to use for default responses
	//
	// This is used for 404 errors, validation errors, default statuses etc.
	DefaultResponder UAPIDefaultResponder

	// Used to store init data
	InitData UAPIInitData
}

Setup struct

var (
	// Stores the UAPI state for UAPI plugins
	State *UAPIState
)

func (*UAPIState) SetCurrentTag

func (s *UAPIState) SetCurrentTag(tag string)