risefront

README

risefront

code.pfad.fr/risefront is a package for gracefully upgrading the server behing a tcp connection with zero-downtime (without disturbing running transfers or dropping incoming requests).

The name is meant to be the opposite of fallback (since it switches to a new executable when asked to do so).

Inspired by overseer, but re-engineered to also work on windows!

Usage

risefront.New(ctx, risefront.Config{
    Addresses: []string{":8080"}, // addresses to listen to
    Run: func(l []net.Listener) error { // listeners, for you to use
        s := http.Server{
            Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
                w.Write([]byte("hello world " + strconv.Itoa(os.Getpid()) + "\n"))
            }),
        }
        defer s.Shutdown(context.Background()) // needed to ensure proper cleanup of children

        fmt.Println("READY", l[0].Addr()) // some logging to show that it works
        defer fmt.Println("BYE", l[0].Addr())

        return s.Serve(l[0])
    },
})

Underlying logic

When you start multiple instances of the code above:

• the first one (the parent o) will actually listen to the addresses and call Run
• when a second instance (child A) is started, it detects that a parent is already running
  • it creates some random sockets to locally listen to
  • it informs the parent, that it wants to take over
  • it calls Run with those "proxy listeners"
  • from now on, the parent will forward all new connections to those "proxy listeners"
• if a third instance is started (child B), the same steps happen and the second instance will exit after handling its last request

Documentation

Overview

package risefront enables gracefully upgrading the server behing a tcp connection with zero-downtime (without disturbing running transfers or dropping incoming requests).

Example (Http)

package main

import (
	"context"
	"errors"
	"net"
	"net/http"
	"os"
	"strconv"
	"time"

	"code.pfad.fr/risefront"
)

func newServer() *http.Server {
	// This is an example server, which shows the PID of its process.
	// Start processes in parallel to show the forwarding of the
	// incoming connection to the latest process.
	return &http.Server{
		Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			w.Write([]byte("hello world " + strconv.Itoa(os.Getpid()) + "\n"))
			if r.URL.Path == "/hang" {
				time.Sleep(10 * time.Second)
			}
			w.Write([]byte("bye " + strconv.Itoa(os.Getpid())))
		}),
	}
}

func main() {
	// In production, use signal.NotifyContext to interrupt on Ctrl+C:
	// ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt)
	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
	defer cancel()

	err := risefront.New(ctx, risefront.Config{
		Addresses: []string{":8080"},
		Run: func(l []net.Listener) error {
			// Example http.Server
			s := newServer()

			// defer Shutdown to wait for ongoing requests to be served before returning
			defer s.Shutdown(context.Background())
			return s.Serve(l[0]) // serve on the given listener
		},
	})
	if !errors.Is(err, context.DeadlineExceeded) {
		panic(err)
	}
}

Index

• func New(ctx context.Context, cfg Config) error
• type Config
• type Dialer
• type PrefixDialer
  • func (pd PrefixDialer) Dial(name string) (net.Conn, error)
  • func (pd PrefixDialer) Listen(name string) (net.Listener, error)

Examples

• Package (Http)

Functions

func New

func New(ctx context.Context, cfg Config) error

New calls cfg.Run with opened listeners.

• if no other instance of risefront is found running, it will actually listen on the given addresses.
• if a parent instance of risefront is found running, it will ask this parent to forward all new connections.

The parent will live as long as the context lives. The child will live as long as the parent is alive and no other child has been started.

Types

type Config

type Config struct {
	Addresses []string                   // Addresses to listen to.
	Run       func([]net.Listener) error // Handle the connections. All open connections should be properly closed before returning (srv.Shutdown for http.Server for instance).

	Dialer       Dialer                       // Dialer for child-parent communication. Let empty for default dialer (PrefixDialer{}).
	Network      string                       // "tcp" (default if empty), "tcp4", "tcp6", "unix" or "unixpacket"
	ErrorHandler func(kind string, err error) // Where errors should be logged (print to stderr by default)
	// contains filtered or unexported fields
}

type Dialer

type Dialer interface {
	Listen(name string) (net.Listener, error)
	Dial(name string) (net.Conn, error)
}

Dialer is used for the child-parent communication.

type PrefixDialer

type PrefixDialer struct {
	Prefix string
}

PrefixDialer uses github.com/Microsoft/go-winio.{DialPipe,ListenPipe} on windows and net.{Dial,Listen} on other platforms.

func (PrefixDialer) Dial

func (pd PrefixDialer) Dial(name string) (net.Conn, error)

func (PrefixDialer) Listen

func (pd PrefixDialer) Listen(name string) (net.Listener, error)