statuspages

README

statuspages

Status pages library for go programs.

Back-end services usually export metrics and logs, but to be able to understand what is going on inside them, it makes sense to create status pages. These are simple web pages served directly by the binary and exposing internal state, potentially also allowing to act on the service for maintenance purposes: restart, change elected master, reload configuration, etc.

This library provides tools to easily:

• Generate status pages with simple HTML code, forms and tables.
• Make your status pages secure, by authenticating the user or using a proxy for authentication. Generate also audit logs for any user action.

Current status of the project

Draft

Usage

TODO

Login plugin

TODO

Audit log plugin

TODO

Documentation

Overview

Package statuspages provide tools to implement status pages on your services.

Index

• Constants
• Variables
• type Option
  • func WithBindRootPath() Option
  • func WithHttpServer(server *http.Server) Option
  • func WithListener(listener net.Listener) Option
• type Server
  • func NewServer(opts ...Option) *Server
  • func (s *Server) AddHandler(path string, handler http.Handler)
  • func (s *Server) AddService(name string, service Service) string
  • func (s *Server) RemoveService(service Service)
  • func (s *Server) Run(ctx context.Context) error
  • func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type Service

Constants

const End = `` /* 325-byte string literal not displayed */

Variables

var (
	// Begin is the start of status pages, End is the end.
	Begin *template.Template
)

Types

type Option

type Option func(s *Server)

func WithBindRootPath

func WithBindRootPath() Option

WithBindRootPath will bind the root path "/" to the status pages. This is useful when the web server is dedicated to status pages, and should be avoided if the web server is also used for another purpose. The /status path is always bound anyway.

func WithHttpServer

func WithHttpServer(server *http.Server) Option

WithHttpServer allows users to provide their own http server.

func WithListener

func WithListener(listener net.Listener) Option

WithListener allows users to provide their own listener.

type Server

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

Server (statuspages.Server) is a status pages HTTP server.

func NewServer

func NewServer(opts ...Option) *Server

NewServer creates a new server with provided options.

func (*Server) AddHandler

func (s *Server) AddHandler(path string, handler http.Handler)

AddHandler adds a http handler to the status pages web server.

func (*Server) AddService

func (s *Server) AddService(name string, service Service) string

Add a new service on the status page. If another service with this name alreay exists, a suffix will be appended to the service name. The possibly suffixed service name is returned, then passed back to each Service.MainPageEntry and Service.ServicePage calls. If the service is already registred, this has no effect and returns the current name.

func (*Server) RemoveService

func (s *Server) RemoveService(service Service)

RemoveService removes a service from the status page. This has no effect if the service is not registered.

func (*Server) Run

func (s *Server) Run(ctx context.Context) error

Run runs the server until context is cancelled.

func (*Server) ServeHTTP

func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements http.Handler interface.

type Service

type Service interface {
	// MainPageEntry returns a HTML snippet to include on the main page.
	MainPageEntry(name string) (string, error)

	// ServicePage handle requests to this service.
	ServicePage(name string, w http.ResponseWriter, r *http.Request) error
}

Service handles requests to /status pages.