ada

README

Simple, flexible go web framework.

go get github.com/rakunlabs/ada

Usage

Check out the guide for more details.

package main

import (
	"net/http"

	"github.com/rakunlabs/ada"
)

func main() {
	server := ada.New()
	server.GET("/hello/{user}", SayHello)

	server.Start(":8080")
}

// /////////////////////

func SayHello(w http.ResponseWriter, r *http.Request) {
	w.Write([]byte("Hello, " + r.PathValue("user")))
}

Documentation

Index

• Constants
• Variables
• func Chain(middlewares ...func(next http.Handler) http.Handler) func(next http.Handler) http.Handler
• type Context
  • func NewContext(w http.ResponseWriter, r *http.Request) *Context
  • func (c *Context) Bind(obj any) error
  • func (c *Context) Err(err error) error
  • func (c *Context) SendBlob(reader io.Reader) error
  • func (c *Context) SendFile(name string, reader io.Reader) error
  • func (c *Context) SendJSON(data any) error
  • func (c *Context) SendJSONP(data any, indent string) error
  • func (c *Context) SendJSONRaw(data io.Reader) error
  • func (c *Context) SendNoContent() error
  • func (c *Context) SendString(s string) error
  • func (c *Context) SendZip(name string, files map[string]io.Reader) error
  • func (c *Context) SetHeader(kv ...string) *Context
  • func (c *Context) SetStatus(code int) *Context
• type HandlerError
  • func (e HandlerError) Error() string
  • func (e HandlerError) MarshalJSON() ([]byte, error)
  • func (e HandlerError) Unwrap() error
• type HandlerFunc
• type Logger
• type Mux
  • func NewMux() *Mux
  • func (m *Mux) CONNECT(path string, handler http.HandlerFunc, ...)
  • func (m *Mux) DELETE(path string, handler http.HandlerFunc, ...)
  • func (m *Mux) ErrorHandler(handler func(c *Context, err error))
  • func (m *Mux) GET(path string, handler http.HandlerFunc, ...)
  • func (m Mux) Group(pathGroup string, middlewares ...func(next http.Handler) http.Handler) *Mux
  • func (m *Mux) HEAD(path string, handler http.HandlerFunc, ...)
  • func (m *Mux) Handle(path string, handler http.Handler, ...)
  • func (m *Mux) HandleFunc(path string, handler http.HandlerFunc, ...)
  • func (m *Mux) HandleFuncWildcard(path string, handler http.HandlerFunc, ...)
  • func (m *Mux) HandleWildcard(path string, handler http.Handler, ...)
  • func (m *Mux) HandleWithMethod(method, path string, handler http.HandlerFunc, ...)
  • func (m *Mux) NotFound(handler http.HandlerFunc)
  • func (m *Mux) OPTIONS(path string, handler http.HandlerFunc, ...)
  • func (m *Mux) PATCH(path string, handler http.HandlerFunc, ...)
  • func (m *Mux) POST(path string, handler http.HandlerFunc, ...)
  • func (m *Mux) PUT(path string, handler http.HandlerFunc, ...)
  • func (m *Mux) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (m *Mux) TRACE(path string, handler http.HandlerFunc, ...)
  • func (m *Mux) Use(middlewares ...func(next http.Handler) http.Handler)
  • func (m *Mux) Wrap(handler HandlerFunc) func(http.ResponseWriter, *http.Request)
• type Option
  • func WithLogger(logger Logger) Option
  • func WithShutdownTimeout(timeout time.Duration) Option
• type OptionStart
  • func WithBaseContext(ctx context.Context) OptionStart
  • func WithContext(ctx context.Context) OptionStart
  • func WithHTTPServerFunc(fn func(server *http.Server) *http.Server) OptionStart
  • func WithNetwork(network string) OptionStart
  • func WithReadHeaderTimeout(d time.Duration) OptionStart
• type Server
  • func New(opts ...Option) *Server
  • func NewWithFunc(ctx context.Context, fn func(ctx context.Context, mux *Mux) error, ...) (*Server, error)
  • func (s *Server) Start(addr string, opts ...OptionStart) error
  • func (s *Server) StartWithContext(ctx context.Context, addr string, opts ...OptionStart) error
  • func (s *Server) Stop() error

Constants

const (
	MIMEApplicationJSON                  = "application/json"
	MIMEApplicationJSONCharsetUTF8       = MIMEApplicationJSON + "; " + charsetUTF8
	MIMEApplicationJavaScript            = "application/javascript"
	MIMEApplicationJavaScriptCharsetUTF8 = MIMEApplicationJavaScript + "; " + charsetUTF8
	MIMEApplicationXML                   = "application/xml"
	MIMEApplicationXMLCharsetUTF8        = MIMEApplicationXML + "; " + charsetUTF8
	MIMETextXML                          = "text/xml"
	MIMETextXMLCharsetUTF8               = MIMETextXML + "; " + charsetUTF8
	MIMEApplicationForm                  = "application/x-www-form-urlencoded"
	MIMEApplicationProtobuf              = "application/protobuf"
	MIMEApplicationMsgpack               = "application/msgpack"
	MIMETextHTML                         = "text/html"
	MIMETextHTMLCharsetUTF8              = MIMETextHTML + "; " + charsetUTF8
	MIMETextPlain                        = "text/plain"
	MIMETextPlainCharsetUTF8             = MIMETextPlain + "; " + charsetUTF8
	MIMEMultipartForm                    = "multipart/form-data"
	MIMEMultipartMixed                   = "multipart/mixed"
	MIMEOctetStream                      = "application/octet-stream"
)

const (
	HeaderContentType        = "Content-Type"
	HeaderContentDisposition = "Content-Disposition"
	HeaderXRequestID         = "X-Request-Id"
	HeaderVary               = "Vary"
	HeaderOrigin             = "Origin"
	HeaderLocation           = "Location"

	HeaderAccessControlAllowOrigin      = "Access-Control-Allow-Origin"
	HeaderAccessControlAllowCredentials = "Access-Control-Allow-Credentials"
	HeaderAccessControlExposeHeaders    = "Access-Control-Expose-Headers"
	HeaderAccessControlRequestMethod    = "Access-Control-Request-Method"
	HeaderAccessControlRequestHeaders   = "Access-Control-Request-Headers"
	HeaderAccessControlAllowMethods     = "Access-Control-Allow-Methods"
	HeaderAccessControlAllowHeaders     = "Access-Control-Allow-Headers"
	HeaderAccessControlMaxAge           = "Access-Control-Max-Age"
)

Variables

var (
	DefaultShutdownTimeout   = 10 * time.Second
	DefaultReadHeaderTimeout = 10 * time.Second
	ErrAlreadyStarted        = errors.New("server started already")
	ErrListen                = errors.New("listen")

	ListenerAddrContextKey = "listener_addr"
)

var DefaultErrHandler = func(c *Context, err error) {
	var errResp *HandlerError
	if errors.As(err, &errResp) {
		c.SetStatus(errResp.Code).SendJSON(errResp)
		return
	}

	c.SetStatus(http.StatusInternalServerError).SendJSON(map[string]string{"message": err.Error()})
}

Functions

func Chain

func Chain(middlewares ...func(next http.Handler) http.Handler) func(next http.Handler) http.Handler

Chain is a utility function to chain multiple middleware functions together.

Types

type Context

type Context struct {
	Request  *http.Request
	Response http.ResponseWriter
	// contains filtered or unexported fields
}

func NewContext

func NewContext(w http.ResponseWriter, r *http.Request) *Context

func (*Context) Bind

func (c *Context) Bind(obj any) error

Bind binds the request data to the provided struct based on content type and struct tags.

• The obj parameter must be a pointer.

func (*Context) Err

func (c *Context) Err(err error) error

func (*Context) SendBlob

func (c *Context) SendBlob(reader io.Reader) error

SendBlob streams data from an io.Reader to the response.

• The caller is responsible for setting appropriate headers (e.g., Content-Type).

func (*Context) SendFile

func (c *Context) SendFile(name string, reader io.Reader) error

SendFile sends a single file to the client.

func (*Context) SendJSON

func (c *Context) SendJSON(data any) error

SendJSON sends a json response.

func (*Context) SendJSONP

func (c *Context) SendJSONP(data any, indent string) error

SendJSONP sends a json pretty-printed response.

func (*Context) SendJSONRaw

func (c *Context) SendJSONRaw(data io.Reader) error

func (*Context) SendNoContent

func (c *Context) SendNoContent() error

SendNoContent always sends a 204 No Content response without body.

func (*Context) SendString

func (c *Context) SendString(s string) error

func (*Context) SendZip

func (c *Context) SendZip(name string, files map[string]io.Reader) error

SendZip sends files to the client as a zip file.

• If name is empty, defaults to "files.zip".

func (*Context) SetHeader

func (c *Context) SetHeader(kv ...string) *Context

SetHeader sets a response header.

SetHeader("Content-Type", "application/json", "X-Custom-Header", "value")

func (*Context) SetStatus

func (c *Context) SetStatus(code int) *Context

SetStatus sets the response status code.

• Use http package constants for standard status codes like http.StatusOK

type HandlerError

type HandlerError struct {
	Code int   `json:"-"`
	Err  error `json:"-"`
}

func (HandlerError) Error

func (e HandlerError) Error() string

func (HandlerError) MarshalJSON

func (e HandlerError) MarshalJSON() ([]byte, error)

func (HandlerError) Unwrap

func (e HandlerError) Unwrap() error

type HandlerFunc

type HandlerFunc func(c *Context) error

type Logger

type Logger interface {
	Error(msg string, keysAndValues ...any)
	Info(msg string, keysAndValues ...any)
	Debug(msg string, keysAndValues ...any)
	Warn(msg string, keysAndValues ...any)
}

type Mux

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

func NewMux

func NewMux() *Mux

func (*Mux) CONNECT

func (m *Mux) CONNECT(path string, handler http.HandlerFunc, middlewares ...func(next http.Handler) http.Handler)

func (*Mux) DELETE

func (m *Mux) DELETE(path string, handler http.HandlerFunc, middlewares ...func(next http.Handler) http.Handler)

func (*Mux) ErrorHandler

func (m *Mux) ErrorHandler(handler func(c *Context, err error))

ErrorHandler sets the handler for 500 Internal Server Error responses.

• If not set, it defaults to a generic error handler.
• Only usable for ada.HandlerFunc handlers.

func (*Mux) GET

func (m *Mux) GET(path string, handler http.HandlerFunc, middlewares ...func(next http.Handler) http.Handler)

func (Mux) Group

func (m Mux) Group(pathGroup string, middlewares ...func(next http.Handler) http.Handler) *Mux

func (*Mux) HEAD

func (m *Mux) HEAD(path string, handler http.HandlerFunc, middlewares ...func(next http.Handler) http.Handler)

func (*Mux) Handle

func (m *Mux) Handle(path string, handler http.Handler, middlewares ...func(next http.Handler) http.Handler)

func (*Mux) HandleFunc

func (m *Mux) HandleFunc(path string, handler http.HandlerFunc, middlewares ...func(next http.Handler) http.Handler)

func (*Mux) HandleFuncWildcard

func (m *Mux) HandleFuncWildcard(path string, handler http.HandlerFunc, middlewares ...func(next http.Handler) http.Handler)

HandleFuncWildcard is registering all paths under the given path.

func (*Mux) HandleWildcard

func (m *Mux) HandleWildcard(path string, handler http.Handler, middlewares ...func(next http.Handler) http.Handler)

HandleWildcard is registering all paths under the given path.

func (*Mux) HandleWithMethod

func (m *Mux) HandleWithMethod(method, path string, handler http.HandlerFunc, middlewares ...func(next http.Handler) http.Handler)

func (*Mux) NotFound

func (m *Mux) NotFound(handler http.HandlerFunc)

NotFound sets the handler for 404 Not Found responses.

• If not set, it defaults to http.NotFound.

func (*Mux) OPTIONS

func (m *Mux) OPTIONS(path string, handler http.HandlerFunc, middlewares ...func(next http.Handler) http.Handler)

func (*Mux) PATCH

func (m *Mux) PATCH(path string, handler http.HandlerFunc, middlewares ...func(next http.Handler) http.Handler)

func (*Mux) POST

func (m *Mux) POST(path string, handler http.HandlerFunc, middlewares ...func(next http.Handler) http.Handler)

func (*Mux) PUT

func (m *Mux) PUT(path string, handler http.HandlerFunc, middlewares ...func(next http.Handler) http.Handler)

func (*Mux) ServeHTTP

func (m *Mux) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements the http.Handler interface for Mux.

func (*Mux) TRACE

func (m *Mux) TRACE(path string, handler http.HandlerFunc, middlewares ...func(next http.Handler) http.Handler)

func (*Mux) Use

func (m *Mux) Use(middlewares ...func(next http.Handler) http.Handler)

func (*Mux) Wrap

func (m *Mux) Wrap(handler HandlerFunc) func(http.ResponseWriter, *http.Request)

Wrap converts ada.HandlerFunc to http.HandlerFunc.

type Option

type Option func(*option)

func WithLogger

func WithLogger(logger Logger) Option

func WithShutdownTimeout

func WithShutdownTimeout(timeout time.Duration) Option

WithShutdownTimeout sets the shutdown timeout, default is 10 seconds.

type OptionStart

type OptionStart func(*optionStart)

func WithBaseContext

func WithBaseContext(ctx context.Context) OptionStart

WithBaseContext sets the base context, default is context.Background().

• Default is context.Background().

func WithContext

func WithContext(ctx context.Context) OptionStart

WithContext sets the context, usable for stopping the server.

• Same as StartWithContext's ctx

func WithHTTPServerFunc

func WithHTTPServerFunc(fn func(server *http.Server) *http.Server) OptionStart

func WithNetwork

func WithNetwork(network string) OptionStart

WithNetwork sets the network, default is "tcp".

func WithReadHeaderTimeout

func WithReadHeaderTimeout(d time.Duration) OptionStart

WithReadHeaderTimeout sets the ReadHeaderTimeout for the http.Server.

• Default is 5 seconds.

type Server

type Server struct {
	*Mux
	// contains filtered or unexported fields
}

func New

func New(opts ...Option) *Server

func NewWithFunc

func NewWithFunc(ctx context.Context, fn func(ctx context.Context, mux *Mux) error, opts ...Option) (*Server, error)

func (*Server) Start

func (s *Server) Start(addr string, opts ...OptionStart) error

Start starts the server with the given address.

• If the server fails to start, an error will be returned.

func (*Server) StartWithContext

func (s *Server) StartWithContext(ctx context.Context, addr string, opts ...OptionStart) error

StartWithContext starts the server with the given context and address.

• If the context is canceled, the server will be stopped.
• If the server fails to start, an error will be returned.

func (*Server) Stop

func (s *Server) Stop() error