httpservice

Documentation

Overview

The httpservice package provides a way to run a simple HTTP server service as a charm. It does not provide any way to interact with the running service - for more control, see the httprelation and service packages, which the httpservice package uses for its implementation.

Index

• Variables
• func RegisterRelationType(...)
• type Feedback
• type Handler
• type ServerState
• type Service
  • func (svc *Service) HTTPPort() int
  • func (svc *Service) HTTPSPort() int
  • func (svc *Service) PublicHTTPSURL() (string, error)
  • func (svc *Service) PublicHTTPURL() (string, error)
  • func (svc *Service) Register(r *hook.Registry, serviceName, httpRelationName string, handler interface{})
  • func (svc *Service) Restart() error
  • func (svc *Service) Start(arg interface{}) error
  • func (svc *Service) Stop() error

Variables

var (
	ErrRestartNeeded      = errgo.New("handler needs to be restarted")
	ErrRelationIncomplete = errgo.New("relation data is incomplete")
)

var ErrHTTPSNotConfigured = errgo.New("HTTPS not configured")

Functions

func RegisterRelationType

func RegisterRelationType(
	registerField func(r *hook.Registry, tag string) (getVal func() (interface{}, error)),
	setFieldValue interface{},
)

RegisterRelationType registers a relation type that can be passed to a handler. It may be called by a relation package to register a type that may be used in field of the R argument to handler function registered with Register.

This function is usually called implicitly as a result of importing a relation package.

The register function argument will be called when a charm registers a handler function that has an second argument with a struct type that has a field of type T. Its arguments are the current hook registry, the httpservice tag associated with the field (if any).

The registerField function should return a function that will be called after any hook functions registered and which should return any data associated with the relation in a JSON-marshalable value. This will be unmarshaled and passed as the second setFieldValue argument when the server is started.

If the data associated with the relation is incomplete, registerField may return an error with an ErrRelationIncomplete cause, in which case the handler will be stopped until the relation is complete. TODO provide a mechanism for making relations optional.

The setFieldValue argument should be a function of the form

func(fv *T, val D) error

where T is the struct-field type to be registered and D is the JSON-marshalable type returned from getVal (the data that will be sent to the server). The setFieldValue function will be called within the service whenever the value returned by getVal changes. The value of fv will point to the field to fill in from the relation data. Note that each time the relation changes while the service is still running, the fv value will be the same. If the change in the value requires the service to be restarted, setFieldValue should not set anything and should return an error with an ErrRestartNeeded cause. If any other error is returned, it will be logged as a warning and made available in the charm status.

When the server is finally stopped, setFieldValue will be called with a zero D value, signifying that the value should be finalized (for example by closing it if it is a network connection).

Types

type Feedback

type Feedback struct {
	Warnings []string
}

Feedback is an implementation detail, exposed only because net/rpc requires it.

type Handler

type Handler interface {
	http.Handler
	io.Closer
}

Handler represents a handler that can also be closed to free any of its associated resources.

type ServerState

type ServerState struct {
	HTTPPort  int
	HTTPSPort int
	CertPEM   string

	// Arg holds the value passed to Service.Start, marshaled as JSON.
	ArgData []byte

	// RelationValues holds an entry for each relation
	// defined in the second argument of the handler function
	// passed to Register.
	RelationValues map[string][]byte
}

ServerState holds the state of a server - all the parameters that might affect it.

It is an implementation detail and only exposed because net/rpc requires it.

type Service

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

Service represents an HTTP service. It provides an http relation runs a Go HTTP handler as a service.

func (*Service) HTTPPort

func (svc *Service) HTTPPort() int

HTTPPort returns the currently configured HTTP port for the service.

func (*Service) HTTPSPort

func (svc *Service) HTTPSPort() int

HTTPSPort returns the currently configured HTTPS port for the service.

func (*Service) PublicHTTPSURL

func (svc *Service) PublicHTTPSURL() (string, error)

PublicHTTPSURL returns an http URL that can be used to access the HTTPS service, not including the trailing slash. It returns ErrHTTPSNotConfigured if there is no current https service.

func (*Service) PublicHTTPURL

func (svc *Service) PublicHTTPURL() (string, error)

PublicHTTPURL returns a URL that can be used to access the HTTP service, not including the trailing slash. TODO https?

func (*Service) Register

func (svc *Service) Register(r *hook.Registry, serviceName, httpRelationName string, handler interface{})

Register registers the service with the given registry. If serviceName is non-empty, it specifies the name of the service, otherwise the service will be named after the charm's unit. The httpRelationName parameter specifies the name of the http relation.

The handler value must be a function in one of the following forms:

func(T) (Handler, error)
func(T, *R) (Handler, error)

for some type T that can be marshaled as JSON and some struct type R that contains exported fields with types registered with RegisterRelationType. Currently, anonymous fields are not supported.

When the service is started, this function will be called with the argument provided to the Start method, and any R argument filled in with the values for any current relations. Note that it is not the responsibility of the handler to finalize any relation values.

Note that the handler function will not be called with any hook context available, as it is run by the OS-provided service runner (e.g. upstart).

When a new handler is required, the old one will be closed before the new one is started, but outstanding HTTP requests will not be waited for (this may change).

func (*Service) Restart

func (svc *Service) Restart() error

Restart restarts the service.

func (*Service) Start

func (svc *Service) Start(arg interface{}) error

Start starts the service with the given argument. The type of arg must be the same as the type T in the handler function provided to Register.

If the value changes, a new handler will be started with the given argument value.

func (*Service) Stop

func (svc *Service) Stop() error

Stop stops the service.