scroll

package
v0.0.0-...-c360844 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 5, 2016 License: Apache-2.0, MIT Imports: 18 Imported by: 0

README

scroll

Build Status

Scroll is a lightweight library for building Go HTTP services at Mailgun. It is built on top of mux and adds:

  • Service Discovery
  • Graceful Shutdown
  • Configurable Logging
  • Request Metrics

Scroll is a work in progress. Use at your own risk.

Installation

go get github.com/mailgun/scroll

Getting Started

Building an application with Scroll is simple. Here's a server that listens for GET or POST requests to http://0.0.0.0:8080/resources/{resourceID} and echoes back the resource ID provided in the URL.

package main

import (
	"fmt"
	"net/http"

	"github.com/mailgun/scroll"
	"github.com/mailgun/scroll/registry"
)

func handler(w http.ResponseWriter, r *http.Request, params map[string]string) (interface{}, error) {
	return scroll.Response{
		"message": fmt.Sprintf("Resource ID: %v", params["resourceID"]),
	}, nil
}

func main() {
	// create an app
	appConfig := scroll.AppConfig{
		Name:       "scrollexample",
		ListenIP:   "0.0.0.0",
		ListenPort: 8080,
		Registry:   &registry.NopRegistry{},
	}
	app := scroll.NewAppWithConfig(appConfig)

	// register a handler
	handlerSpec := scroll.Spec{
		Methods:  []string{"GET", "POST"},
		Paths:    []string{"/resources/{resourceID}"},
		Handler:  handler,
	}

	app.AddHandler(handlerSpec)

	// start the app
	app.Run()
}

Documentation

Index

Constants

View Source
const (
	// Suggested result set limit for APIs that may return many entries (e.g. paging).
	DefaultLimit = 100

	// Suggested max allowed result set limit for APIs that may return many entries (e.g. paging).
	MaxLimit = 10000

	// Suggested max allowed amount of entries that batch APIs can accept (e.g. batch uploads).
	MaxBatchSize = 1000
)

Variables

This section is empty.

Functions

func GetDurationField

func GetDurationField(r *http.Request, fieldName string) (time.Duration, error)

GetDurationField retrieves a request field as a time.Duration, which is not allowed to be negative. Returns `MissingFieldError` if requested field is missing.

func GetFloatField

func GetFloatField(r *http.Request, fieldName string) (float64, error)

Retrieve a request field as a float. Returns `MissingFieldError` if requested field is missing.

func GetIntField

func GetIntField(r *http.Request, fieldName string) (int, error)

Retrieve a POST request field as an integer. Returns `MissingFieldError` if requested field is missing.

func GetMultipleFields

func GetMultipleFields(r *http.Request, fieldName string) ([]string, error)

Retrieve fields with the same name as an array of strings.

func GetStringField

func GetStringField(r *http.Request, fieldName string) (string, error)

Retrieve a POST request field as a string. Returns `MissingFieldError` if requested field is missing.

func GetStringFieldSafe

func GetStringFieldSafe(r *http.Request, fieldName string, allowSet AllowSet) (string, error)

Retrieves requested field as a string, allowSet provides input sanitization. If an error occurs, returns either a `MissingFieldError` or an `UnsafeFieldError`.

func GetStringFieldWithDefault

func GetStringFieldWithDefault(r *http.Request, fieldName, defaultValue string) string

Retrieve a POST request field as a string. If the requested field is missing, returns provided default value.

func GetTimestampField

func GetTimestampField(r *http.Request, fieldName string) (time.Time, error)

Helper method to retrieve an optional timestamp from POST request field. If no timestamp provided, returns current time. Returns `InvalidFormatError` if provided timestamp can't be parsed.

func GetVarSafe

func GetVarSafe(r *http.Request, variableName string, allowSet AllowSet) (string, error)

GetVarSafe is a helper function that returns the requested variable from URI with allowSet providing input sanitization. If an error occurs, returns either a `MissingFieldError` or an `UnsafeFieldError`.

func HasField

func HasField(r *http.Request, fieldName string) bool

func MakeHandler

func MakeHandler(app *App, fn HandlerFunc, spec Spec) http.HandlerFunc

Wraps the provided handler function encapsulating boilerplate code so handlers do not have to implement it themselves: parsing a request's form, formatting a proper JSON response, emitting the request stats, etc.

func MakeHandlerWithBody

func MakeHandlerWithBody(app *App, fn HandlerWithBodyFunc, spec Spec) http.HandlerFunc

Make a handler out of HandlerWithBodyFunc, just like regular MakeHandler function.

func Reply

func Reply(w http.ResponseWriter, response interface{}, status int)

Reply with the provided HTTP response and status code.

Response body must be JSON-marshallable, otherwise the response will be "Internal Server Error".

func ReplyError

func ReplyError(w http.ResponseWriter, err error)

ReplyError converts registered error into HTTP response code and writes it back.

func ReplyInternalError

func ReplyInternalError(w http.ResponseWriter, message string)

Helper that replies with the 500 code and happened error message.

Types

type AllowSet

type AllowSet interface {
	IsSafe(string) error
}

The AllowSet interface is implemented to detect if input is safe or not.

type AllowSetBytes

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

AllowSetBytes allows the definition of a set of safe allowed ASCII characters. AllowSetBytes does not support unicode code points. If you pass the string "ü" (which encodes as 0xc3 0xbc) they will be skipped over.

func NewAllowSetBytes

func NewAllowSetBytes(s string, maxlen int) AllowSetBytes

func (AllowSetBytes) IsSafe

func (a AllowSetBytes) IsSafe(s string) error

type AllowSetStrings

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

AllowSetStrings allows the definition of a set of safe allowed strings.

func NewAllowSetStrings

func NewAllowSetStrings(s []string) AllowSetStrings

func (AllowSetStrings) IsSafe

func (a AllowSetStrings) IsSafe(s string) error

type App

type App struct {
	Config AppConfig
	// contains filtered or unexported fields
}

Represents an app.

func NewApp

func NewApp() *App

Create a new app.

func NewAppWithConfig

func NewAppWithConfig(config AppConfig) *App

Create a new app with the provided configuration.

func (*App) AddHandler

func (app *App) AddHandler(spec Spec) error

Register a handler function.

If vulcan registration is enabled in the both app config and handler spec, the handler will be registered in the local etcd instance.

func (*App) GetHandler

func (app *App) GetHandler() http.Handler

GetHandler returns HTTP compatible Handler interface.

func (*App) IsPublicRequest

func (app *App) IsPublicRequest(request *http.Request) bool

IsPublicRequest determines whether the provided request came through the public HTTP endpoint.

func (*App) Run

func (app *App) Run() error

Start the app on the configured host/port.

Supports graceful shutdown on 'kill' and 'int' signals.

func (*App) SetNotFoundHandler

func (app *App) SetNotFoundHandler(fn http.HandlerFunc)

SetNotFoundHandler sets the handler for the case when URL can not be matched by the router.

type AppConfig

type AppConfig struct {
	// name of the app being created
	Name string

	// IP/port the app will bind to
	ListenIP   string
	ListenPort int

	// optional router to use
	Router *mux.Router

	// hostnames of the public and protected API entrypoints used for vulcan registration
	PublicAPIHost    string
	ProtectedAPIHost string
	ProtectedAPIURL  string

	// how to register the app's endpoint and handlers in vulcan
	Registry registry.Registry
	Interval time.Duration

	// metrics service used for emitting the app's real-time metrics
	Client metrics.Client
}

Represents a configuration object an app is created with.

type ConflictError

type ConflictError struct {
	Description string
}

func (ConflictError) Error

func (e ConflictError) Error() string

type GenericAPIError

type GenericAPIError struct {
	Reason string
}

func (GenericAPIError) Error

func (e GenericAPIError) Error() string

type HandlerFunc

type HandlerFunc func(http.ResponseWriter, *http.Request, map[string]string) (interface{}, error)

Defines the signature of a handler function that can be registered by an app.

The 3rd parameter is a map of variables extracted from the request path, e.g. if a request path was:

/resources/{resourceID}

and the request was made to:

/resources/1

then the map will contain the resource ID value:

{"resourceID": 1}

A handler function should return a JSON marshallable object, e.g. Response.

type HandlerWithBodyFunc

type HandlerWithBodyFunc func(http.ResponseWriter, *http.Request, map[string]string, []byte) (interface{}, error)

Defines a signature of a handler function, just like HandlerFunc.

In addition to the HandlerFunc a request's body is passed into this function as a 4th parameter.

type InvalidFormatError

type InvalidFormatError struct {
	Field string
	Value string
}

func (InvalidFormatError) Error

func (e InvalidFormatError) Error() string

type InvalidParameterError

type InvalidParameterError struct {
	Field string
	Value string
}

func (InvalidParameterError) Error

func (e InvalidParameterError) Error() string

type MissingFieldError

type MissingFieldError struct {
	Field string
}

func (MissingFieldError) Error

func (e MissingFieldError) Error() string

type NotFoundError

type NotFoundError struct {
	Description string
}

func (NotFoundError) Error

func (e NotFoundError) Error() string

type Response

type Response map[string]interface{}

Response objects that apps' handlers are advised to return.

Allows to easily return JSON-marshallable responses, e.g.:

Response{"message": "OK"}

type Scope

type Scope int
const (
	ScopePublic Scope = iota
	ScopeProtected
)

func (Scope) String

func (scope Scope) String() string

type Spec

type Spec struct {
	// List of HTTP methods the handler should match.
	Methods []string

	// List of paths the handler should match. A separate handler will be registered for each one of them.
	Paths []string

	// Key/value pairs of specific HTTP headers the handler should match (e.g. Content-Type).
	Headers []string

	// A handler function to use. Just one of these should be provided.
	RawHandler      http.HandlerFunc
	Handler         HandlerFunc
	HandlerWithBody HandlerWithBodyFunc

	// Unique identifier used when emitting performance metrics for the handler.
	MetricName string

	// Controls the handler's accessibility via vulcan (public or protected). If not specified, public is assumed.
	Scopes []Scope

	// Vulcan middlewares to register with the handler. When registering, middlewares are assigned priorities
	// according to their positions in the list: a middleware that appears in the list earlier is executed first.
	Middlewares []middleware.Middleware

	// When Handler or HandlerWithBody is used, this function will be called after every request with a log message.
	// If nil, defaults to github.com/mailgun/log.Infof.
	Logger func(format string, a ...interface{})
}

Represents handler's specification.

type UnsafeFieldError

type UnsafeFieldError struct {
	Field       string
	Description string
}

func (UnsafeFieldError) Error

func (e UnsafeFieldError) Error() string

Directories

Path Synopsis
examples

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL