httpserver

package
v0.19.2 Latest Latest
Warning

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

Go to latest
Published: Jun 6, 2024 License: MIT Imports: 42 Imported by: 0

Documentation

Index

Constants

View Source
const (
	ApiViewKey          = "X-Api-View"
	ContentTypeHtml     = "text/html; charset=utf-8"
	ContentTypeJson     = "application/json; charset=utf-8"
	ContentTypeProtobuf = "application/x-protobuf"
)
View Source
const (
	MetricHttpRequestCount        = "HttpRequestCount"
	MetricHttpRequestResponseTime = "HttpRequestResponseTime"
	MetricHttpStatus              = "HttpStatus"
)
View Source
const (
	BaseProfiling = "/debug/profiling"
	CmdLine       = "/cmdline"
	Profile       = "/profile"
	Symbol        = "/symbol"
	Trace         = "/trace"
	Allocs        = "/allocs"
	Block         = "/block"
	GoRoutine     = "/goroutine"
	Heap          = "/heap"
	Mutex         = "/mutex"
	ThreadCreate  = "/threadcreate"
)

Variables

View Source
var ErrAccessForbidden = errors.New("cant access resource")

Functions

func AddCustomTypeFuncs

func AddCustomTypeFuncs(customTypeFuncs []CustomTypeFunc) error

func AddCustomValidators

func AddCustomValidators(customValidators []CustomValidator) error

func AddProfilingEndpoints

func AddProfilingEndpoints(r *gin.Engine)

func AddStructValidators

func AddStructValidators(structValidators []StructValidator) error

func AddValidateAlias

func AddValidateAlias(aliases []ValidateAlias) error

func Cors

func Cors(config cfg.Config) gin.HandlerFunc

func CreateDownloadHandler

func CreateDownloadHandler(handler HandlerWithStream) gin.HandlerFunc

CreateDownloadHandler creates a gin.HandlerFunc that handles the stream request and uses the query parameters as input binding Example input struct from handler.GetInput():

type example struct{
  A string `query:"a" binding:"required"`
}

func CreateHandler

func CreateHandler(handler HandlerWithoutInput) gin.HandlerFunc

CreateHandler creates a gin.HandlerFunc that handles the request without data binding and without passing the body to the handler

func CreateJsonHandler

func CreateJsonHandler(handler HandlerWithInput) gin.HandlerFunc

CreateJsonHandler creates a gin.HandlerFunc that handles the request with json binding Example input struct from handler.GetInput():

type example struct{
  A string `json:"a" binding:"required"`
}

func CreateMultiPartFormHandler

func CreateMultiPartFormHandler(handler HandlerWithInput) gin.HandlerFunc

CreateMultiPartFormHandler creates a gin.HandlerFunc that handles the request with Form multipart data binding Example input struct from handler.GetInput():

type example struct{
  File *multipart.FileHeader `form:"file" binding:"required"`
}

func CreateMultipleBindingsHandler

func CreateMultipleBindingsHandler(handler HandlerWithMultipleBindings) gin.HandlerFunc

CreateMultipleBindingsHandler creates a gin.HandlerFunc that handles the request with the bindings the input struct specifies Example input struct from handler.GetInput():

type example struct{
  A string `json:"a" binding:"required"`
  B string `form:"b" binding:"required"`
}

func CreateProtobufHandler added in v0.16.0

func CreateProtobufHandler(handler HandlerWithInput) gin.HandlerFunc

CreateProtobufHandler creates a gin.HandlerFunc that handles the request with protobuf binding Example input struct from handler.GetInput():

type example struct{ // <- this struct must implement ProtobufDecodable
  A string `json:"a" binding:"required"`
}

func CreateQueryHandler

func CreateQueryHandler(handler HandlerWithInput) gin.HandlerFunc

CreateQueryHandler creates a gin.HandlerFunc that handles the request and uses the query parameters as input binding Example input struct from handler.GetInput():

type example struct{
  A string `query:"a" binding:"required"`
}

func CreateRawHandler

func CreateRawHandler(handler HandlerWithoutInput) gin.HandlerFunc

CreateRawHandler creates a gin.HandlerFunc that handles the request without input binding and passes the body to the handler as []byte

func CreateReaderHandler

func CreateReaderHandler(handler HandlerWithoutInput) gin.HandlerFunc

CreateReaderHandler creates a gin.HandlerFunc that handles the request without input binding and passes the body to the handler as io.ReadCloser

func CreateSseHandler

func CreateSseHandler(handler HandlerWithStream) gin.HandlerFunc

CreateSseHandler creates a gin.HandlerFunc that handles the stream request and uses the query parameters as input binding Example input struct from handler.GetInput():

type example struct{
  A string `query:"a" binding:"required"`
}

func CreateStreamHandler

func CreateStreamHandler(handler HandlerWithStream) gin.HandlerFunc

CreateStreamHandler creates a gin.HandlerFunc that handles the stream request and uses the json body as input binding Example input struct from handler.GetInput():

type example struct{
  A string `json:"a" binding:"required"`
}

func CreateUriHandler added in v0.18.4

func CreateUriHandler(handler HandlerWithInput) gin.HandlerFunc

CreateUriHandler creates a gin.HandlerFunc that handles the request and uses the uri parameters as input binding Example input struct from handler.GetInput():

type example struct{
  A string `uri:"a" binding:"required"`
}

func GetStringFromRequest

func GetStringFromRequest(request *Request, name string) (*string, bool)

func GetUintFromRequest

func GetUintFromRequest(request *Request, name string) (*uint, bool)

func HttpTest

func HttpTest[Body HttpBody](method string, path string, requestPath string, body Body, handler gin.HandlerFunc, requestOptions ...func(r *http.Request)) *httptest.ResponseRecorder

func LoggingMiddleware

func LoggingMiddleware(logger log.Logger, settings LoggingSettings) gin.HandlerFunc

func New

func New(name string, definer Definer) kernel.ModuleFactory

func NewCountingBodyReader

func NewCountingBodyReader(reader io.ReadCloser) (io.ReadCloser, *int)

func NewCountingBodyWriter

func NewCountingBodyWriter(writer gin.ResponseWriter) (gin.ResponseWriter, *int)

func NewGZipBodyReader

func NewGZipBodyReader(body io.ReadCloser) (io.ReadCloser, *int, error)

func NewHealthCheck

func NewHealthCheck() kernel.ModuleFactory

func NewMetricMiddleware

func NewMetricMiddleware(name string) (middleware gin.HandlerFunc, setupHandler func(definitions []Definition))

func NewWithSettings

func NewWithSettings(name string, definer Definer, settings *Settings) kernel.ModuleFactory

func ProfilingModuleFactory added in v0.19.0

func ProfilingModuleFactory(_ context.Context, config cfg.Config, _ log.Logger) (map[string]kernel.ModuleFactory, error)

func RecoveryWithSentry

func RecoveryWithSentry(logger log.Logger) gin.HandlerFunc

func WithCustomModifier

func WithCustomModifier(modifier Modifier)

func WithErrorHandler

func WithErrorHandler(handler ErrorHandler)

Types

type ApiHealthCheck

type ApiHealthCheck struct {
	kernel.BackgroundModule
	kernel.ServiceStage
	// contains filtered or unexported fields
}

func NewHealthCheckWithInterfaces

func NewHealthCheckWithInterfaces(logger log.Logger, router *gin.Engine, healthChecker kernel.HealthChecker, settings *HealthCheckSettings) *ApiHealthCheck

func (*ApiHealthCheck) Run

func (a *ApiHealthCheck) Run(ctx context.Context) error

type CompressionExcludeSettings

type CompressionExcludeSettings struct {
	Extension []string `cfg:"extension"`
	Path      []string `cfg:"path"`
	PathRegex []string `cfg:"path_regex"`
}

CompressionExcludeSettings allow enabling of gzip support.

type CompressionSettings

type CompressionSettings struct {
	Level         string `cfg:"level" default:"default" validate:"oneof=none default best fast 0 1 2 3 4 5 6 7 8 9"`
	Decompression bool   `cfg:"decompression" default:"true"`
	// Exclude files by path, extension, or regular expression from being considered for compression. Useful if you are serving a format unknown to Gosoline.
	Exclude CompressionExcludeSettings `cfg:"exclude"`
}

CompressionSettings control gzip support for requests and responses. By default, compressed requests are accepted and compressed responses are returned (if accepted by the client).

type CustomTypeFunc

type CustomTypeFunc struct {
	Func  validator.CustomTypeFunc
	Types []interface{}
}

A CustomTypeFunc allows you to convert one type to another type before validation. This allows you to validate custom types with the built-in functions for, e.g., integers or strings.

type CustomValidator

type CustomValidator struct {
	Name      string
	Validator validator.Func
}

A CustomValidator allows you to validate single fields with custom rules. If you need to validate a whole struct, you need to use a StructValidator. See https://github.com/go-playground/validator/issues/470 for more details.

type Definer

type Definer func(ctx context.Context, config cfg.Config, logger log.Logger) (*Definitions, error)

type Definition

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

type Definitions

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

func (*Definitions) DELETE

func (d *Definitions) DELETE(relativePath string, handlers ...gin.HandlerFunc)

func (*Definitions) GET

func (d *Definitions) GET(relativePath string, handlers ...gin.HandlerFunc)

func (*Definitions) Group

func (d *Definitions) Group(relativePath string) *Definitions

func (*Definitions) Handle

func (d *Definitions) Handle(httpMethod, relativePath string, handlers ...gin.HandlerFunc)

func (*Definitions) OPTIONS

func (d *Definitions) OPTIONS(relativePath string, handlers ...gin.HandlerFunc)

func (*Definitions) POST

func (d *Definitions) POST(relativePath string, handlers ...gin.HandlerFunc)

func (*Definitions) PUT

func (d *Definitions) PUT(relativePath string, handlers ...gin.HandlerFunc)

func (*Definitions) Use

func (d *Definitions) Use(middleware ...gin.HandlerFunc)

type ErrorHandler

type ErrorHandler func(statusCode int, err error) *Response

func GetErrorHandler

func GetErrorHandler() ErrorHandler

type HandlerMetadata

type HandlerMetadata struct {
	// Method is the route method of this Handler.
	Method string `json:"method"`
	// Path is the route path ot this handler.
	Path string `json:"path"`
}

HandlerMetadata stores the Path and Method of this Handler.

type HandlerWithInput

type HandlerWithInput interface {
	HandlerWithoutInput
	GetInput() interface{}
}

type HandlerWithMultipleBindings

type HandlerWithMultipleBindings interface {
	HandlerWithInput
	GetBindings() []binding.Binding
}

type HandlerWithStream

type HandlerWithStream interface {
	GetInput() interface{}
	Handle(ginContext *gin.Context, requestContext context.Context, request *Request) (err error)
}

type HandlerWithoutInput

type HandlerWithoutInput interface {
	Handle(requestContext context.Context, request *Request) (response *Response, err error)
}

type HealthCheckSettings

type HealthCheckSettings struct {
	Port int    `cfg:"port" default:"8090"`
	Path string `cfg:"path" default:"/health"`
}

type HttpBody added in v0.16.0

type HttpBody interface {
	string | []byte
}

type HttpServer

type HttpServer struct {
	kernel.EssentialModule
	kernel.ServiceStage
	// contains filtered or unexported fields
}

func NewWithInterfaces

func NewWithInterfaces(logger log.Logger, router *gin.Engine, tracer tracing.Tracer, s *Settings) (*HttpServer, error)

func (*HttpServer) GetPort

func (a *HttpServer) GetPort() (*int, error)

func (*HttpServer) Run

func (a *HttpServer) Run(ctx context.Context) error

type LoggingSettings

type LoggingSettings struct {
	RequestBody       bool `cfg:"request_body"`
	RequestBodyBase64 bool `cfg:"request_body_base64"`
}

type Modifier

type Modifier interface {
	Struct(ctx context.Context, v interface{}) error
}

type Profiling

type Profiling struct {
	kernel.BackgroundModule
	kernel.ServiceStage
	// contains filtered or unexported fields
}

func NewProfilingWithInterfaces

func NewProfilingWithInterfaces(logger log.Logger, router *gin.Engine, settings *ProfilingSettings) *Profiling

func (*Profiling) Run

func (p *Profiling) Run(ctx context.Context) error

type ProfilingApiSettings added in v0.19.0

type ProfilingApiSettings struct {
	Port int `cfg:"port" default:"8091"`
}

type ProfilingSettings

type ProfilingSettings struct {
	Enabled bool                 `cfg:"enabled" default:"false"`
	Api     ProfilingApiSettings `cfg:"api"`
}

type ProtobufDecodable added in v0.16.0

type ProtobufDecodable interface {
	// EmptyMessage should provide an empty instance of the message format to decode from.
	EmptyMessage() proto.Message
	// FromMessage should extract the data from the message and write it to the receiver.
	FromMessage(message proto.Message) error
}

ProtobufDecodable allows CreateProtobufHandler to decode the request body via protobuf.

type ProtobufEncodable added in v0.16.0

type ProtobufEncodable interface {
	// ToMessage turns the response value into a protobuf message representation
	ToMessage() (proto.Message, error)
}

ProtobufEncodable is required for NewProtobufResponse to create the protobuf response.

type Request

type Request struct {
	Body     interface{}
	ClientIp string
	Cookies  map[string]string
	Header   http.Header
	Method   string
	Params   gin.Params
	Url      *url.URL
}

type Response

type Response struct {
	Body        interface{}
	ContentType *string // might be nil
	Header      http.Header
	StatusCode  int
}

Don't create a response directly, use New*Response instead

func NewHtmlResponse

func NewHtmlResponse(body interface{}) *Response

func NewJsonResponse

func NewJsonResponse(body interface{}) *Response

func NewProtobufResponse added in v0.16.0

func NewProtobufResponse(body ProtobufEncodable) (*Response, error)

func NewRedirectResponse

func NewRedirectResponse(url string) *Response

func NewResponse

func NewResponse(body interface{}, contentType string, statusCode int, header http.Header) *Response

func NewStatusResponse

func NewStatusResponse(statusCode int) *Response

func (*Response) AddHeader

func (r *Response) AddHeader(key string, value string)

func (*Response) WithBody

func (r *Response) WithBody(body interface{}) *Response

func (*Response) WithContentType

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

type ResponseBodyWriterError

type ResponseBodyWriterError struct {
	Err error
}

func (ResponseBodyWriterError) Error

func (e ResponseBodyWriterError) Error() string

func (ResponseBodyWriterError) Is

func (ResponseBodyWriterError) Unwrap

func (e ResponseBodyWriterError) Unwrap() error

type ServerMetadata

type ServerMetadata struct {
	Name     string            `json:"name"`
	Handlers []HandlerMetadata `json:"handlers"`
}

type Settings

type Settings struct {
	// Port the API listens to.
	Port string `cfg:"port" default:"8080"`
	// Mode is either debug, release, test.
	Mode string `cfg:"mode" default:"release" validate:"oneof=release debug test"`
	// Compression settings.
	Compression CompressionSettings `cfg:"compression"`
	// Timeout settings.
	Timeout TimeoutSettings `cfg:"timeout"`
	// Logging settings
	Logging LoggingSettings `cfg:"logging"`
}

Settings structure for an API server.

type StructValidator

type StructValidator struct {
	Struct    interface{}
	Validator validator.StructLevelFunc
}

A StructValidator validates every instance of a struct type with the given validation. It is a little bit unfortunate because you now can't have different validation rules for a struct at different places.

type TimeoutSettings

type TimeoutSettings struct {
	// You need to give at least 1s as timeout.
	// Read timeout is the maximum duration for reading the entire request, including the body.
	Read time.Duration `cfg:"read" default:"60s" validate:"min=1000000000"`
	// Write timeout is the maximum duration before timing out writes of the response.
	Write time.Duration `cfg:"write" default:"60s" validate:"min=1000000000"`
	// Idle timeout is the maximum amount of time to wait for the next request when keep-alives are enabled
	Idle time.Duration `cfg:"idle" default:"60s" validate:"min=1000000000"`
}

TimeoutSettings configures IO timeouts.

type ValidateAlias

type ValidateAlias struct {
	Alias string
	Tags  string
}

A ValidateAlias allows you to map one or more tags to a different name, making your validation rules easier to read.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL