httpd

Documentation

Overview

Provides an HTTP API exposing many components of Kapacitor.

Index

• Constants
• Variables
• func HttpError(w http.ResponseWriter, err string, pretty bool, code int)
• func MarshalJSON(v interface{}, pretty bool) []byte
• func ServeOptions(w http.ResponseWriter, r *http.Request)
• type AuthenticationMethod
• type AuthorizationHandler
• type Config
  • func NewConfig() Config
  • func (c Config) Port() (int, error)
  • func (c Config) Validate() error
• type Diagnostic
• type Handler
  • func NewHandler(...) *Handler
  • func (h *Handler) AddPreviewRoute(r Route) error
  • func (h *Handler) AddPreviewRoutes(routes []Route) error
  • func (h *Handler) AddRoute(r Route) error
  • func (h *Handler) AddRoutes(routes []Route) error
  • func (h *Handler) DelRoute(r Route)
  • func (h *Handler) DelRoutes(routes []Route)
  • func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type Route
• type ServeMux
  • func NewServeMux() *ServeMux
  • func (mux *ServeMux) Deregister(pattern string)
  • func (mux *ServeMux) Handle(pattern string, handler http.Handler) error
  • func (mux *ServeMux) HandleFunc(pattern string, handler func(http.ResponseWriter, *http.Request)) error
  • func (mux *ServeMux) Handler(r *http.Request) (h http.Handler, pattern string)
  • func (mux *ServeMux) Patterns() []string
  • func (mux *ServeMux) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type Service
  • func NewService(c Config, hostname string, t *tls.Config, d Diagnostic) *Service
  • func (s *Service) AddPreviewRoutes(routes []Route) error
  • func (s *Service) AddRoutes(routes []Route) error
  • func (s *Service) Addr() net.Addr
  • func (s *Service) Close() error
  • func (s *Service) DelRoutes(routes []Route)
  • func (s *Service) Err() <-chan error
  • func (s *Service) ExternalURL() string
  • func (s *Service) Open() error
  • func (s *Service) URL() string

Constants

const (
	// Root path for the API
	BasePath = "/kapacitor/v1"
	// Root path for the preview API
	BasePreviewPath = "/kapacitor/v1preview"
	// Name of the special user for subscriptions
	SubscriptionUser = "~subscriber"
)

const (
	DefaultShutdownTimeout = toml.Duration(time.Second * 10)
)

Variables

var DefaultServeMux = NewServeMux()

DefaultServeMux is the default ServeMux used by Serve.

Functions

func HttpError

func HttpError(w http.ResponseWriter, err string, pretty bool, code int)

HttpError writes an error to the client in a standard format.

func MarshalJSON

func MarshalJSON(v interface{}, pretty bool) []byte

MarshalJSON will marshal v to JSON. Pretty prints if pretty is true.

func ServeOptions

func ServeOptions(w http.ResponseWriter, r *http.Request)

ServeOptions returns an empty response to comply with OPTIONS pre-flight requests

Types

type AuthenticationMethod

type AuthenticationMethod int

AuthenticationMethod defines the type of authentication used.

const (
	UserAuthentication AuthenticationMethod = iota
	BearerAuthentication
	SubscriptionAuthentication
)

Supported authentication methods.

type AuthorizationHandler

type AuthorizationHandler func(http.ResponseWriter, *http.Request, auth.User)

type Config

type Config struct {
	BindAddress      string        `toml:"bind-address"`
	AuthEnabled      bool          `toml:"auth-enabled"`
	LogEnabled       bool          `toml:"log-enabled"`
	WriteTracing     bool          `toml:"write-tracing"`
	PprofEnabled     bool          `toml:"pprof-enabled"`
	HttpsEnabled     bool          `toml:"https-enabled"`
	HttpsCertificate string        `toml:"https-certificate"`
	HTTPSPrivateKey  string        `toml:"https-private-key"`
	ShutdownTimeout  toml.Duration `toml:"shutdown-timeout"`
	SharedSecret     string        `toml:"shared-secret"`

	// Enable gzipped encoding
	// NOTE: this is ignored in toml since it is only consumed by the tests
	GZIP bool `toml:"-"`
}

func NewConfig

func NewConfig() Config

func (Config) Port

func (c Config) Port() (int, error)

Determine HTTP port from BindAddress.

func (Config) Validate

func (c Config) Validate() error

type Diagnostic

type Diagnostic interface {
	NewHTTPServerErrorLogger() *log.Logger

	StartingService()
	StoppedService()
	ShutdownTimeout()
	AuthenticationEnabled(enabled bool)

	ListeningOn(addr string, proto string)

	WriteBodyReceived(body string)

	HTTP(
		host string,
		username string,
		start time.Time,
		method string,
		uri string,
		proto string,
		status int,
		referer string,
		userAgent string,
		reqID string,
		duration time.Duration,
	)

	Error(msg string, err error)
	RecoveryError(
		msg string,
		err string,
		host string,
		username string,
		start time.Time,
		method string,
		uri string,
		proto string,
		status int,
		referer string,
		userAgent string,
		reqID string,
		duration time.Duration,
	)
}

type Handler

type Handler struct {
	Version string

	AuthService auth.Interface

	PointsWriter interface {
		WritePoints(database, retentionPolicy string, consistencyLevel models.ConsistencyLevel, points []models.Point) error
	}

	DiagService interface {
		SetLogLevelFromName(lvl string) error
	}
	// contains filtered or unexported fields
}

Handler represents an HTTP handler for the Kapacitor API server.

func NewHandler

func NewHandler(
	requireAuthentication,
	pprofEnabled,
	loggingEnabled,
	writeTrace,
	allowGzip bool,
	statMap *expvar.Map,
	d Diagnostic,
	sharedSecret string,
) *Handler

NewHandler returns a new instance of handler with routes.

func (*Handler) AddPreviewRoute

func (h *Handler) AddPreviewRoute(r Route) error

func (*Handler) AddPreviewRoutes

func (h *Handler) AddPreviewRoutes(routes []Route) error

func (*Handler) AddRoute

func (h *Handler) AddRoute(r Route) error

func (*Handler) AddRoutes

func (h *Handler) AddRoutes(routes []Route) error

func (*Handler) DelRoute

func (h *Handler) DelRoute(r Route)

Delete a route from the handler. No-op if route does not exist.

func (*Handler) DelRoutes

func (h *Handler) DelRoutes(routes []Route)

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP responds to HTTP request to the handler.

type Route

type Route struct {
	Method      string
	Pattern     string
	HandlerFunc interface{}
	NoGzip      bool
	NoJSON      bool
	BypassAuth  bool
}

type ServeMux

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

What follows is an copy of golang's built in ServeMux with a few modifications:

1. An error is returned instead of a panics on registering handlers.
2. A delete method has been added to remove handlers.
3. Removed 'Helpful Behavior' of adding redirects automatically

ServeMux is an HTTP request multiplexer. It matches the URL of each incoming request against a list of registered patterns and calls the handler for the pattern that most closely matches the URL.

Patterns name fixed, rooted paths, like "/favicon.ico", or rooted subtrees, like "/images/" (note the trailing slash). Longer patterns take precedence over shorter ones, so that if there are handlers registered for both "/images/" and "/images/thumbnails/", the latter handler will be called for paths beginning "/images/thumbnails/" and the former will receive requests for any other paths in the "/images/" subtree.

Note that since a pattern ending in a slash names a rooted subtree, the pattern "/" matches all paths not matched by other registered patterns, not just the URL with Path == "/".

Patterns may optionally begin with a host name, restricting matches to URLs on that host only. Host-specific patterns take precedence over general patterns, so that a handler might register for the two patterns "/codesearch" and "codesearch.google.com/" without also taking over requests for "http://www.google.com/".

ServeMux also takes care of sanitizing the URL request path, redirecting any request containing . or .. elements to an equivalent .- and ..-free URL.

func NewServeMux

func NewServeMux() *ServeMux

NewServeMux allocates and returns a new ServeMux.

func (*ServeMux) Deregister

func (mux *ServeMux) Deregister(pattern string)

func (*ServeMux) Handle

func (mux *ServeMux) Handle(pattern string, handler http.Handler) error

Handle registers the handler for the given pattern. If a handler already exists for pattern an error is returned.

func (*ServeMux) HandleFunc

func (mux *ServeMux) HandleFunc(pattern string, handler func(http.ResponseWriter, *http.Request)) error

HandleFunc registers the handler function for the given pattern.

func (*ServeMux) Handler

func (mux *ServeMux) Handler(r *http.Request) (h http.Handler, pattern string)

Handler returns the handler to use for the given request, consulting r.Method, r.Host, and r.URL.Path. It always returns a non-nil handler. If the path is not in its canonical form, the handler will be an internally-generated handler that redirects to the canonical path.

Handler also returns the registered pattern that matches the request or, in the case of internally-generated redirects, the pattern that will match after following the redirect.

If there is no registered handler that applies to the request, Handler returns a “page not found” handler and an empty pattern.

func (*ServeMux) Patterns

func (mux *ServeMux) Patterns() []string

func (*ServeMux) ServeHTTP

func (mux *ServeMux) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP dispatches the request to the handler whose pattern most closely matches the request URL.

type Service

type Service struct {
	Handler *Handler
	// LocalHandler handler is used internally only for the local transport clients.
	// It does not have authentication enabled.
	LocalHandler *Handler
	// contains filtered or unexported fields
}

func NewService

func NewService(c Config, hostname string, t *tls.Config, d Diagnostic) *Service

func (*Service) AddPreviewRoutes

func (s *Service) AddPreviewRoutes(routes []Route) error

func (*Service) AddRoutes

func (s *Service) AddRoutes(routes []Route) error

func (*Service) Addr

func (s *Service) Addr() net.Addr

func (*Service) Close

func (s *Service) Close() error

Close closes the underlying listener.

func (*Service) DelRoutes

func (s *Service) DelRoutes(routes []Route)

func (*Service) Err

func (s *Service) Err() <-chan error

func (*Service) ExternalURL

func (s *Service) ExternalURL() string

URL that should resolve externally to the server HTTP endpoint. It is possible that the URL does not resolve correctly if the hostname config setting is incorrect.

func (*Service) Open

func (s *Service) Open() error

Open starts the service

func (*Service) URL

func (s *Service) URL() string