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

Source Files

View all Source files

Directories

Path Synopsis
examples
leader
loadbalancer
middleware

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.