risefront

README

risefront

risefront is a package for gracefully upgrading the server behing a tcp connection, 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

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)

Functions

func New

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

New calls Run with working 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.

Types

type Config

type Config struct {
	Addresses []string                   // Addresses to listen to.
	Run       func([]net.Listener) error // Handle the connections. All running connections should be 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(string, error) // print to stdout if empty
}

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)