server

README

server

Additional Subdomains

Use any http.Handler implementation of your choice. Register the handler for a given path using the server.RegisterHandler function.

Check out these premade handlers to get you going!

• web-app
• git server
• grpc server
• graphql endpoint

Running and Stopping

To stop the server send the program an SIGINT or SIGKILL - either natively through another process or with a Ctrl-C.

Stopping the server is not "graceful" - it does not await any open connections and will likely attempt to close down IO/handles without consideration of consumers waiting their results.

HTTP/2 and Certs

Deploy production-grade cert files (backed by a trusted CA) to the same machine as the server binary.

Load them in and pass them to the server.Run function.

NOTE Still in process of testing.

Consuming

This is a very high-level server library. Using it requires the import and use of a single Run function:

import (
  "context"
  "crypto/tls"

  "git.sonicoriginal.software/server.git/v2"
  "git.sonicoriginal.software/server.git/v2/handler"
)

func main() {
  const portEnvKey = "APP_PORT"
  os.Setenv(portEnvKey, "4430") // Default

  // TODO Import your desired handlers and register them here
  // e.g. if importing the 'app' handler, use
  // _ = app.New()

  var certs []tls.Certificate

  // TODO Load your cert and key or skip and just use
  // cert, err := tls.X509KeyPair(cert, key)
  // if err != nil {
  //   // Handle a certificate server failure for your app here
  // }
  // certs = []tls.Certificate{cert}

  ctx, cancelContext := context.WithCancel(context.Background())

	address, serverErrorChannel := server.Run(ctx, &certs, portEnvKey)

	serverError := <-serverErrorChannel
	if serverError.Close != nil {
    // Handle closing server error
	}

	contextError := serverError.Context.Error()

	if serverError.Context.Error() != nil {
    // Handle server failing unexpectedly
	}

  cancelCtx()
}

Documentation

Index

• Constants
• Variables
• func RegisterHandler(path string, handler http.Handler, mux *http.ServeMux) (route string)
• func Run(ctx context.Context, certs *[]tls.Certificate, mux *http.ServeMux, ...) (address string, reportedError chan Error)
• type Error

Constants

const (

	// ServerContextCancelled denotes when a server run returns because its context is cancelled
	ServerContextCancelled = "Server context cancelled"
	// ServerReceivedInterrupt denotes when a server run returns because its context is cancelled
	ServerReceivedInterrupt = "Server received interrupt signal"
)

Variables

var (
	// ErrContextCancelled denotes when a server run returns because its context is cancelled
	ErrContextCancelled error = fmt.Errorf(ServerContextCancelled)
	// ErrReceivedInterrupt denotes when a server run returns because it received an interrupt signal
	ErrReceivedInterrupt error = fmt.Errorf(ServerReceivedInterrupt)
)

Functions

func RegisterHandler

func RegisterHandler(path string, handler http.Handler, mux *http.ServeMux) (route string)

RegisterHandler registers a handler for a path with the default serve mux

func Run

func Run(ctx context.Context, certs *[]tls.Certificate, mux *http.ServeMux, portEnvKey string) (address string, reportedError chan Error)

Run executes the main server loop in a goroutine

It allows consumer cancellation through the context and server-side cancellation notification via the returned `reportedError` channel

Fatal errors will be sent to the returned channel and the server will shutdown

Types

type Error

type Error struct {
	Context error
	Close   error
}

Error contains the errors applicable from running and stopping a server