l4proxy

README

go-l4proxy

Layer4, TCP and UDP, proxy servers and library for Go.

Features

• TCP server
• TCP proxy
• UDP server
• UDP proxy
• High performance

Usages

TCP Server and proxy

svr := &tcp.Server{
    Addr:    ":8000",
    Handler: tcp.NewProxy("localhost:9000"),
}

if err := svr.ListenAndServe(); err != nil && err != tcp.ErrServerClosed {
    panic(err)
}

UDP Server and proxy

svr := &udp.Server{
    Addr:    ":8000",
    Handler: udp.NewProxy("localhost:9000"),
}

if err := svr.ListenAndServe(); err != nil && err != udp.ErrServerClosed {
    panic(err)
}

Docs & Examples

• GoDoc: https://pkg.go.dev/github.com/aileron-projects/go-l4proxy
• Examples:
  • TCP proxy: examples/tcp-proxy
  • TCP proxy with upstream TLS: examples/tcp-proxy-tls
  • TCP server: examples/tcp-server-simple
  • TCP server graceful shutdown: examples/tcp-server-runner
  • TCP TLS server: examples/tcp-server-tls
  • TCP server with ip whitelist: examples/tcp-server-whitelist
  • TCP server with max connections: examples/tcp-limit-concurrency
  • TCP server listens on a unix abstract socket: examples/tcp-socket-abstract
  • TCP server listens on a unix path socket: examples/tcp-socket-path
  • UDP proxy: examples/udp-proxy
  • UDP server: examples/udp-server-simple
  • UDP server graceful shutdown: examples/udp-server-runner
  • UDP server with ip whitelist: examples/udp-server-whitelist
  • UDP server listens on a unix abstract socket: examples/udp-socket-abstract
  • UDP server listens on a unix path socket: examples/udp-socket-path

References

Documentation

Index

• Variables
• type ServerRunner
  • func (r *ServerRunner) Run(sigCtx context.Context) error

Variables

var ErrShutdownTimeout = errors.New("go-l4proxy/l4proxy: shutdown timeout")

ErrShutdownTimeout tells that shutdown has timeout.

Types

type ServerRunner

type ServerRunner struct {
	// Serve starts a server.
	// Serve must blocks until the server closed.
	// Serve must not be nil.
	Serve func() error
	// Shutdown gracefully shutdowns the server.
	// Shutdown must not be nil.
	// It will be called only when the context given to
	// the ServerRunner.Run is done.
	// Otherwise, Shutdown is not called even the Server exited.
	// Typically [http.Server.Shutdown] should be set.
	Shutdown func(context.Context) error
	// Close immediately closes a server.
	// Unlike Shutdown, it should not block.
	// Close, if non-nil, will be called only when shutdown timeout occurred.
	// Typically [net/http.Server.Close] should be set.
	// Note that the [net/http.Server.Shutdown] does not close remaining
	// connection after shutdown timeout occurred but this Runner try to.
	Close func() error
	// ShutdownTimeout is the shutdown timeout duration.
	// ShutdownTimeout = 0 means no timeout.
	// ShutdownTimeout < 0 means shutdown immediately.
	ShutdownTimeout time.Duration
}

ServerRunner runs a server with an ability of graceful shutdown.

Example:

svr := &http.Server{Addr: ":8080"}
r := &ServerRunner{
	Serve:           svr.ListenAndServe,
	Shutdown:        svr.Shutdown,
	Close:           svr.Close,
	ShutdownTimeout: 30 * time.Second,
}

sigCtx, cancel := signal.NotifyContext(context.Background(), os.Interrupt)
defer cancel()

if err := r.Run(sigCtx); err != nil {
	panic(err)
}

func (*ServerRunner) Run

func (r *ServerRunner) Run(sigCtx context.Context) error

Run runs a server. A server will be shutdown when the sigCtx is done. It returns non-nil error if r.Serve returns non-nil error. When a timeout occurred while shutting down, a ErrShutdownTimeout can be returned.