gonia

README

Gonia

A helper library for building web servers with the LabStack Echo framework

Description

Provides a way to build a server with additional services, called Modules, to provide functionality

Pass a value of a type that implements the Module interface to AddMod() before calling Start() on the server to have gonia manage its lifecycle

Getting Started

Dependencies

• labstack echo v4
• go 1.14 or compatible

Installing

• add gitlab.com/cratermoon/gonia to your go.mod

Executing

• Basic Usage

myModule := MyCoolMod()
s := gonia.New()
s.AddMod(myModule)

s.Start()

...

s.Shutdown()

Structure

Routes

Modules

The Module interface has three methods

Name() string Init(s *Server) error Cleanup(s *Server) error

When the server's Start() method is called, it will call all the Init methods of configured modules, in no particular order. If any of the Init methods returns an error, it will be place on the channel provided to server Start.

The server uses the Name() method for logging and monitoring.

At server shutdown, each module will get a Cleanup call. TODO: context with timeout, so a hung module doesn't hang up the server)

Middleware

The Middleware interface has one method, Handler() func(next echo.HandlerFunc) echo.HandlerFunc

Help

Start() doesn't return. If you want to call Shutdown() you'll need a mechanism

go func() {
    done := make(chan error)
    s.Start(done)
    ("Start: %s\n", <-done)
}
}()

// Wait for interrupt signal to gracefully shutdown the server with
// a timeout of 5 seconds.
quit := make(chan os.Signal)
// kill (no param) default send syscall.SIGTERM
// kill -2 is syscall.SIGINT
// kill -9 is syscall.SIGKILL but can't be catch, so don't need add it
signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
<-quit
log.Println("Shutting down server...")

// The context is used to inform the server it has 5 seconds to finish
// the request it is currently handling
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

// if you don't have a Context, you can just call s.Shutdown()
if err := s.ShutdownCtx(ctx); err != nil {
	log.Fatal("Server forced to shutdown:", err)
}

log.Println("Server exiting")

Authors

Contributors names and contact info

• Steven E. Newton

Version History

• 0.0.1
  • Initial Release

License

This project is licensed under the GNU Affero License - see the LICENSE file for details

Acknowledgments

Documentation

Index

• type Middleware
• type Module
• type Route
  • func NewRoute(p string, h echo.HandlerFunc) Route
  • func NewRouteNamed(p, n string, h echo.HandlerFunc) Route
• type Server
  • func New(id string) *Server
  • func NewWithRouter(id string, router *echo.Echo) *Server
  • func (s *Server) AddGET(r Route) string
  • func (s *Server) AddMod(m Module)
  • func (s *Server) AddPOST(r Route) string
  • func (s *Server) Logger() echo.Logger
  • func (s *Server) Shutdown()
  • func (s *Server) ShutdownWithContext(parent context.Context)
  • func (s *Server) Start(done chan error)
  • func (s *Server) StartOn(port string, initError chan error)
  • func (s *Server) UseMiddleware(m Middleware)

Types

type Middleware

type Middleware interface {
	Handler() func(next echo.HandlerFunc) echo.HandlerFunc
}

Middleware defines a method for the server to find the handler function

type Module

type Module interface {
	Name() string
	Init(s *Server) error
	Cleanup(s *Server) error
}

The Module interface defines the methods that all gonia modules must implement. Init is called on server startup, before handling connections Cleanup is called on server shutdown, before closing the server

type Route

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

Route describes an http route and handler with path and a handler function.

func NewRoute

func NewRoute(p string, h echo.HandlerFunc) Route

NewRoute creates a new route. The name will be set to the path value

func NewRouteNamed

func NewRouteNamed(p, n string, h echo.HandlerFunc) Route

NewRouteNamed creates a new route with the given path, name, and handlerFunc.

type Server

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

Server is the top-level gonia object

func New

func New(id string) *Server

New creates a new server with the given id

func NewWithRouter

func NewWithRouter(id string, router *echo.Echo) *Server

NewWithRouter creates a new server given an existing router

func (*Server) AddGET

func (s *Server) AddGET(r Route) string

AddGET configures the given Route for the GET method

func (*Server) AddMod

func (s *Server) AddMod(m Module)

AddMod installs a Module on the list of modules to be initialized and cleaned up buy the server. This must be called before Start()

func (*Server) AddPOST

func (s *Server) AddPOST(r Route) string

AddPOST configures the given Route for the POST method

func (*Server) Logger

func (s *Server) Logger() echo.Logger

Logger returns the underlying echo.Logger

func (*Server) Shutdown

func (s *Server) Shutdown()

Shutdown is a convenience method that calls shuts down the server with a nil Context

func (*Server) ShutdownWithContext

func (s *Server) ShutdownWithContext(parent context.Context)

Shutdown stops the server. Before stopping, the server will call the Cleanup method on any installed Modules if parent is nil the function will use context.Background()

func (*Server) Start

func (s *Server) Start(done chan error)

Start begins serving on port 8080 The server will call the Init method on any installed Modules before serving The done channel will have the error if startup fails.

func (*Server) StartOn

func (s *Server) StartOn(port string, initError chan error)

StartOn begins serving on the given port. The server will call the Init method on any installed Modules before serving The done channel will have the error if startup fails.

func (*Server) UseMiddleware

func (s *Server) UseMiddleware(m Middleware)

UseMiddleware will install the Middleware for all paths