graceful

Graceful

Graceful is a minimal package for building a graceful service. It implements an opinionated workflow for:

• Gracefully opening long-lived connections
• Gracefully retrying dropped connections
• Gracefully starting servers to listen
• Gracefully terminating all connections and listeners

A client is any kind of long-lived connection that needs to be preserved during a service's operation (gRPC connection, database connection, message queue connection, etc.). A server is any kind of listener that needs to listen to a port and serve requests (HTTP server, gRPC server, etc.).

Quick Start

package main

import (
  "os"

  "github.com/moorara/graceful"
)

func main() {
  logger := &Logger{}
  dbClient := NewClient("db-client")
  queueClient := NewClient("queue-client")
  apiServer := NewServer("api-server", 8080)
  infoServer := NewServer("info-server", 8081)

  graceful.SetLogger(logger)
  graceful.RegisterClient(dbClient, queueClient)
  graceful.RegisterServer(apiServer, infoServer)
  code := graceful.StartAndWait()

  os.Exit(code)
}

You can find the complete example here.

Behaviour

Here is how the StartAndWait behaves:

1. It tries to connect all clients each in a new goroutine.
   • If a client fails to connect, it will be automatically retried for a limited number of times with exponential backoff.
   • If at least one client fails to connect (after retries), a graceful termination will be initiated.
2. Once all clients are connected successfully, all servers start listening each in a new goroutine.
   • If any server errors, a graceful termination will be initiated.
3. Then, this method blocks the current goroutine until one of the following conditions happen:
   • If any of SIGHUP, SIGINT, SIGQUIT, SIGTERM signals is sent, a graceful termination will be initiated.
   • If any of the above signals is sent for the second time before the graceful termination is completed, the process will exit immediately with an error code.