serving

Documentation

Overview

Package serving provides an extremely opinionated serving infrastructure, with support net/http.Server and google.golang.org/grpc.Server.

It supports listening on specific ports or randomly-available ports, and reports the corresponding bind addresses. This is useful for creating multiple servers in tests where ports may conflict. The server also gracefully stops requests when the provided context is closed.

Example (GRPC)

package main

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

	"google.golang.org/grpc"

	"github.com/abcxyz/pkg/serving"
)

func main() {
	// Any cancellable context will work.
	ctx, done := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
	defer done()

	grpcServer := grpc.NewServer()

	server, err := serving.New(os.Getenv("PORT"))
	if err != nil {
		panic(err) // TODO: handle error
	}

	// This will block until the provided context is cancelled.
	if err := server.StartGRPC(ctx, grpcServer); err != nil {
		panic(err) // TODO: handle error
	}
}

Example (HTTP)

package main

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

	"github.com/abcxyz/pkg/serving"
)

func main() {
	// Any cancellable context will work.
	ctx, done := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
	defer done()

	mux := http.NewServeMux()
	mux.Handle("/", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.WriteHeader(200)
	}))

	httpServer := &http.Server{
		ReadHeaderTimeout: 1 * time.Second,

		Handler: mux,
	}

	server, err := serving.New(os.Getenv("PORT"))
	if err != nil {
		panic(err) // TODO: handle error
	}

	// This will block until the provided context is cancelled.
	if err := server.StartHTTP(ctx, httpServer); err != nil {
		panic(err) // TODO: handle error
	}
}

Example (HTTPHandler)

package main

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

	"github.com/abcxyz/pkg/serving"
)

func main() {
	// Any cancellable context will work.
	ctx, done := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
	defer done()

	mux := http.NewServeMux()
	mux.Handle("/", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.WriteHeader(200)
	}))

	server, err := serving.New(os.Getenv("PORT"))
	if err != nil {
		panic(err) // TODO: handle error
	}

	// This will block until the provided context is cancelled.
	if err := server.StartHTTPHandler(ctx, mux); err != nil {
		panic(err) // TODO: handle error
	}
}

Index

• type Server
  • func New(port string) (*Server, error)
  • func NewFromListener(listener net.Listener) (*Server, error)
  • func (s *Server) Addr() string
  • func (s *Server) IP() string
  • func (s *Server) Port() string
  • func (s *Server) StartGRPC(ctx context.Context, srv *grpc.Server) error
  • func (s *Server) StartHTTP(ctx context.Context, srv *http.Server) error
  • func (s *Server) StartHTTPHandler(ctx context.Context, handler http.Handler) error

Examples

• Package (GRPC)
• Package (HTTP)
• Package (HTTPHandler)

Types

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server provides a gracefully-stoppable http server implementation.

func New

func New(port string) (*Server, error)

New creates a new HTTP server listening on the provided address that responds to the http.Handler. It starts the listener, but does not start the server. If an empty port is given (or port "0"), the server randomly chooses one.

It binds to all interfaces (0.0.0.0, [::]). To bind to specific interfaces, use NewFromListener instead.

func NewFromListener

func NewFromListener(listener net.Listener) (*Server, error)

NewFromListener creates a new server on the given listener. This is useful if you want to customize the listener type or bind custom networks more than New allows.

func (*Server) Addr

func (s *Server) Addr() string

Addr returns the server's listening address (ip + port).

func (*Server) IP

func (s *Server) IP() string

IP returns the server's listening IP.

func (*Server) Port

func (s *Server) Port() string

Port returns the server's listening port.

func (*Server) StartGRPC

func (s *Server) StartGRPC(ctx context.Context, srv *grpc.Server) error

StartGRPC starts the given GRPC service and blocks until the provided context is closed. When the provided context is closed, the server is gracefully stopped.

Once a server has been stopped, it is NOT safe for reuse.

func (*Server) StartHTTP

func (s *Server) StartHTTP(ctx context.Context, srv *http.Server) error

StartHTTP starts the given net/http.Server and blocks until the provided context is closed. When the provided context is closed, the HTTP server is gracefully stopped with a timeout of 10 seconds; once a server has been stopped, it is NOT safe for reuse.

Note that the incoming net/http.Server's address is ignored over the listener's configuration.

func (*Server) StartHTTPHandler

func (s *Server) StartHTTPHandler(ctx context.Context, handler http.Handler) error

StartHTTPHandler creates and starts a net/http.Server with the given handler. See [StartHTTP] for more details.