graceful

README

graceful

Gin wrapper to enable graceful termination when shutting down a process

Example

package main

import (
  "context"
  "net/http"
  "os/signal"
  "syscall"

  "github.com/optimalcompa/graceful"
  "github.com/gin-gonic/gin"
)

func main() {
  ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
  defer stop()

  router, err := graceful.Default()
  if err != nil {
    panic(err)
  }
  defer router.Close()

  router.GET("/", func(c *gin.Context) {
    c.String(http.StatusOK, "Welcome Gin Server")
  })

  if err := router.RunWithContext(ctx); err != nil && err != context.Canceled {
    panic(err)
  }
}

Documentation

Overview

graceful provides a wrapper around the gin.Engine to enable graceful shutdown of HTTP servers. It allows for starting, stopping, and shutting down servers with various configurations, such as listening on TCP addresses, Unix sockets, file descriptors, or custom net.Listeners.

Index

• Variables
• type Graceful
  • func Default(opts ...Option) (*Graceful, error)
  • func New(router *gin.Engine, opts ...Option) (*Graceful, error)
  • func (g *Graceful) Close()
  • func (g *Graceful) Run(addr ...string) error
  • func (g *Graceful) RunFd(fd uintptr) error
  • func (g *Graceful) RunListener(listener net.Listener) error
  • func (g *Graceful) RunTLS(addr, certFile, keyFile string) error
  • func (g *Graceful) RunUnix(file string) error
  • func (g *Graceful) RunWithContext(ctx context.Context) error
  • func (g *Graceful) Shutdown(ctx context.Context) error
  • func (g *Graceful) Start() error
  • func (g *Graceful) Stop() error
• type Option
  • func WithAddr(addr string) Option
  • func WithFd(fd uintptr) Option
  • func WithListener(l net.Listener) Option
  • func WithServer(srv *http.Server) Option
  • func WithTLS(addr string, certFile string, keyFile string) Option
  • func WithUnix(file string) Option

Variables

var ErrAlreadyStarted = errors.New("already started router")

ErrAlreadyStarted is returned when trying to start a router that has already been started.

var ErrNotStarted = errors.New("router not started")

ErrNotStarted is returned when trying to stop a router that has not been started.

Types

type Graceful

type Graceful struct {
	*gin.Engine
	// contains filtered or unexported fields
}

Graceful wraps a gin.Engine and provides methods to start, stop, and gracefully shut down HTTP servers.

func Default

func Default(opts ...Option) (*Graceful, error)

Default returns a Graceful gin instance with the Logger and Recovery middleware already attached.

func New

func New(router *gin.Engine, opts ...Option) (*Graceful, error)

New returns a Graceful gin instance from the given gin.Engine.

func (*Graceful) Close

func (g *Graceful) Close()

Close gracefully shuts down the server. It first shuts down the server using the Shutdown method, then it performs any cleanup operations registered with the server. Finally, it resets the server's internal state.

func (*Graceful) Run

func (g *Graceful) Run(addr ...string) error

Run attaches the router to an http.Server and starts listening and serving HTTP requests.

func (*Graceful) RunFd

func (g *Graceful) RunFd(fd uintptr) error

RunFd attaches the router to an http.Server and starts listening and serving HTTP requests through the specified file descriptor.

func (*Graceful) RunListener

func (g *Graceful) RunListener(listener net.Listener) error

RunListener attaches the router to an http.Server and starts listening and serving HTTP requests through the specified net.Listener.

func (*Graceful) RunTLS

func (g *Graceful) RunTLS(addr, certFile, keyFile string) error

RunTLS attaches the router to an http.Server and starts listening and serving HTTPS (secure) requests.

func (*Graceful) RunUnix

func (g *Graceful) RunUnix(file string) error

RunUnix attaches the router to an http.Server and starts listening and serving HTTP requests through the specified Unix socket (i.e., a file).

func (*Graceful) RunWithContext

func (g *Graceful) RunWithContext(ctx context.Context) error

RunWithContext attaches the router to the configured http.Server (fallback to configuring one on :8080 if none are configured) and starts listening and serving HTTP requests. If the passed context is canceled, the server is gracefully shut down.

func (*Graceful) Shutdown

func (g *Graceful) Shutdown(ctx context.Context) error

Shutdown gracefully shuts down the server without interrupting any active connections.

func (*Graceful) Start

func (g *Graceful) Start() error

Start will start the Graceful instance and all underlying http.Servers in a separate goroutine and return right away. You must call Stop and not Shutdown if you use Start.

func (*Graceful) Stop

func (g *Graceful) Stop() error

Stop will stop the Graceful instance previously started with Start. It will return once the instance has been stopped.

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option specifies instrumentation configuration options.

func WithAddr

func WithAddr(addr string) Option

WithAddr configure a http.Server to listen on the given address.

func WithFd

func WithFd(fd uintptr) Option

WithFd configure a http.Server to listen on the given file descriptor.

func WithListener

func WithListener(l net.Listener) Option

WithListener configure a http.Server to listen on the given net.Listener.

func WithServer

func WithServer(srv *http.Server) Option

WithServer configure an existing http.Server to serve HTTP or HTTPS requests. This allows for a more complete customization of the http.Server, and srv Handler will be set to the current gin.Engine. If srv contains TLSConfig, ListenAndServeTLS will be used; otherwise, ListenAndServe will be used.

func WithTLS

func WithTLS(addr string, certFile string, keyFile string) Option

WithTLS configure a http.Server to listen on the given address and serve HTTPS requests.

func WithUnix

func WithUnix(file string) Option

WithUnix configure a http.Server to listen on the given unix socket file.