http

README

http

build restful services with absolute minimum amount of code using annotations.

usage example

Declaring a REST-Service

package sms

import (
	"context"
	"fmt"
	"github.com/worldiety/mercurius/ee4g/uuid"
)

// @ee.http.Controller
// @ee.http.Route("/api/v1/sms")
type RestController struct {
	sms Repository
}

func NewRestController(sms Repository) *RestController {
	return &RestController{sms}
}

// @ee.http.QueryParam("limit")
// @ee.http.Method("GET")
func (s *RestController) List(ctx context.Context, limit int) ([]SMS, error) {
	return s.sms.FindAll(ctx, limit)
}

// @ee.http.HeaderParam("value":"userAgent","alias":"User-Agent")
// @ee.http.Route("/:id")
// @ee.http.Method("GET")
func (s *RestController) Get(ctx context.Context, id uuid.UUID, userAgent string) (SMS, error) {
	fmt.Println(userAgent)
	return s.sms.FindById(ctx, id)
}

Regenerate reflectplus and start the server

    srv := http.NewServer()
    
    ctr, err := http2.NewController(srv, sms.NewRestController(...))
    if err != nil {
        panic(err)
    }
    
    err = srv.Start(8080)

Documentation

Index

• Constants
• func MakeDoc(doc *v3.Document, controllers []reflectplus.Struct) error
• type Controller
  • func MustNewController(srv *Server, ctr interface{}) *Controller
  • func NewController(srv *Server, ctr interface{}) (*Controller, error)
• type Error
  • func AsError(err error) *Error
  • func FindError(err error, id string) *Error
  • func ParseError(reader io.Reader) *Error
  • func WrapError(id string, causedBy error) *Error
  • func (c *Error) Class() string
  • func (c *Error) Error() string
  • func (c *Error) ID() string
  • func (c *Error) LocalizedError() string
  • func (c *Error) Payload() interface{}
  • func (c *Error) String() string
  • func (c *Error) Unwrap() error
• type Handler
• type KeyValues
• type Param
• type Params
  • func (p Params) ByName(name string) string
• type Scanner
• type Server
  • func NewServer() *Server
  • func (s *Server) Handle(method, path string, handle Handler)
  • func (s *Server) Handler() http.Handler
  • func (s *Server) SetNotFound(handler http.Handler)
  • func (s *Server) Start(port int) error
  • func (s *Server) Use(middleware func(Handler) Handler)

Constants

const AnnotationHeaderParam = "ee.http.HeaderParam"

AnnotationHeaderParam only applies to method parameters and uses the names from the http request. 'value' denotes the method variable name and 'alias' an optional name (e.g. accept-language)

const AnnotationMethod = "ee.http.Method"

AnnotationMethod only applies to methods and describes which http verb is applied for routing.

const AnnotationQueryParam = "ee.http.QueryParam"

AnnotationQueryParam only applies to method parameters and uses the names as the url query parameter. value' denotes the method variable name and 'alias' an optional name (e.g. accept-language)

const AnnotationRoute = "ee.http.Route"

AnnotationRoute can be used for a struct and/or struct methods. The value is the route with path variables preceded by a : like the following example:

/api/v1/sms/:id
/resource/:kind1/:kind2

const AnnotationStereotypeController = "ee.stereotype.Controller"

AnnotationStereotypeController is a non http annotation used to group OpenAPI endpoints together, using the given name.

Functions

func MakeDoc

func MakeDoc(doc *v3.Document, controllers []reflectplus.Struct) error

MakeDoc tries to generate the OpenAPI documentation from all given controller structs

Types

type Controller

type Controller struct {
}

func MustNewController

func MustNewController(srv *Server, ctr interface{}) *Controller

MustNewController asserts that ctr is useful controller and otherwise bails out.

func NewController

func NewController(srv *Server, ctr interface{}) (*Controller, error)

NewController tries to create a http/rest presentation service/controller/layer from the given instance.

type Error

type Error struct {
	Id               string      `json:"id"`                         // Id is unique for a specific error, e.g. mydomain.not.assigned
	Message          string      `json:"message"`                    // Message is a string for the developer
	LocalizedMessage string      `json:"localizedMessage,omitempty"` // LocalizedMessage is something to display the user
	CausedBy         *Error      `json:"causedBy,omitempty"`         // CausedBy returns an optional root error
	Type             string      `json:"type,omitempty"`             // Type is a developer notice for the internal inspection
	Details          interface{} `json:"details,omitempty"`          // Details contains arbitrary payload
}

Error describes a (nested) server error

func AsError

func AsError(err error) *Error

AsError either casts the given error (if possible) or creates a new Error from the given error. Returns only nil if err is nil.

func FindError

func FindError(err error, id string) *Error

FindError returns the first occurrence of the error identified by id or nil.

func ParseError

func ParseError(reader io.Reader) *Error

ParseError tries to parse the response as json. In any case it returns an error.

func WrapError

func WrapError(id string, causedBy error) *Error

WrapError takes the cause and converts it into an Error for later serialization.

func (*Error) Class

func (c *Error) Class() string

Class returns the technical type

func (*Error) Error

func (c *Error) Error() string

Error returns the message

func (*Error) ID

func (c *Error) ID() string

ID returns the unique error class id

func (*Error) LocalizedError

func (c *Error) LocalizedError() string

LocalizedError is like Error but translated or empty

func (*Error) Payload

func (c *Error) Payload() interface{}

Payload returns the details

func (*Error) String

func (c *Error) String() string

func (*Error) Unwrap

func (c *Error) Unwrap() error

Unwrap returns the cause or nil

type Handler

type Handler = func(writer http.ResponseWriter, request *http.Request, params KeyValues) error

type KeyValues

type KeyValues = interface {
	ByName(name string) string
}

type Param

type Param struct {
	Key   string
	Value string
}

type Params

type Params []Param

func (Params) ByName

func (p Params) ByName(name string) string

type Scanner

type Scanner interface {
	Scan(src interface{}) error
}

A Scanner is SQL scanner compatible, but only needs tp scan from a string

type Server

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

func NewServer

func NewServer() *Server

func (*Server) Handle

func (s *Server) Handle(method, path string, handle Handler)

Handle provides a custom handler

func (*Server) Handler

func (s *Server) Handler() http.Handler

Handler returns the internal handler

func (*Server) SetNotFound

func (s *Server) SetNotFound(handler http.Handler)

func (*Server) Start

func (s *Server) Start(port int) error

func (*Server) Use

func (s *Server) Use(middleware func(Handler) Handler)