api

Documentation

Overview

Package api has code that offers a REST API for the applications that want to push messages.

Index

• Constants
• Variables
• func MakeHandlersMux(storage StoreAccess, broker broker.BrokerSending, logger logger.Logger) *http.ServeMux
• func PanicTo500Handler(h http.Handler, logger logger.Logger) http.Handler
• func RespondError(writer http.ResponseWriter, apiErr *APIError)
• type APIError
  • func ReadBody(request *http.Request, maxBodySize int64) ([]byte, *APIError)
  • func (apiErr *APIError) Error() string
• type Broadcast
• type JSONPostHandler
  • func (h *JSONPostHandler) ServeHTTP(writer http.ResponseWriter, request *http.Request)
• type Registration
• type StoreAccess
• type Unicast

Constants

const JSONMediaType = "application/json"

const MaxRequestBodyBytes = 4 * 1024

const MaxUnicastPayload = 2 * 1024

Variables

var (
	ErrNoContentLengthProvided = &APIError{
		http.StatusLengthRequired,
		invalidRequest,
		"A Content-Length must be provided",
		nil,
	}
	ErrRequestBodyEmpty = &APIError{
		http.StatusBadRequest,
		invalidRequest,
		"Request body empty",
		nil,
	}
	ErrRequestBodyTooLarge = &APIError{
		http.StatusRequestEntityTooLarge,
		invalidRequest,
		"Request body too large",
		nil,
	}
	ErrWrongContentType = &APIError{
		http.StatusUnsupportedMediaType,
		invalidRequest,
		"Wrong content type, should be application/json",
		nil,
	}
	ErrWrongRequestMethod = &APIError{
		http.StatusMethodNotAllowed,
		invalidRequest,
		"Wrong request method, should be POST",
		nil,
	}
	ErrWrongRequestMethodGET = &APIError{
		http.StatusMethodNotAllowed,
		invalidRequest,
		"Wrong request method, should be GET",
		nil,
	}
	ErrMalformedJSONObject = &APIError{
		http.StatusBadRequest,
		invalidRequest,
		"Malformed JSON Object",
		nil,
	}
	ErrCouldNotReadBody = &APIError{
		http.StatusBadRequest,
		ioError,
		"Could not read request body",
		nil,
	}
	ErrMissingIdField = &APIError{
		http.StatusBadRequest,
		invalidRequest,
		"Missing id field",
		nil,
	}
	ErrMissingData = &APIError{
		http.StatusBadRequest,
		invalidRequest,
		"Missing data field",
		nil,
	}
	ErrDataTooLarge = &APIError{
		http.StatusBadRequest,
		invalidRequest,
		"Data too large",
		nil,
	}
	ErrInvalidExpiration = &APIError{
		http.StatusBadRequest,
		invalidRequest,
		"Invalid expiration date",
		nil,
	}
	ErrPastExpiration = &APIError{
		http.StatusBadRequest,
		invalidRequest,
		"Past expiration date",
		nil,
	}
	ErrUnknownChannel = &APIError{
		http.StatusBadRequest,
		unknownChannel,
		"Unknown channel",
		nil,
	}
	ErrUnknownToken = &APIError{
		http.StatusBadRequest,
		unknownToken,
		"Unknown token",
		nil,
	}
	ErrUnknown = &APIError{
		http.StatusInternalServerError,
		internalError,
		"Unknown error",
		nil,
	}
	ErrStoreUnavailable = &APIError{
		http.StatusServiceUnavailable,
		unavailable,
		"Message store unavailable",
		nil,
	}
	ErrCouldNotStoreNotification = &APIError{
		http.StatusServiceUnavailable,
		unavailable,
		"Could not store notification",
		nil,
	}
	ErrCouldNotMakeToken = &APIError{
		http.StatusServiceUnavailable,
		unavailable,
		"Could not make token",
		nil,
	}
	ErrCouldNotRemoveToken = &APIError{
		http.StatusServiceUnavailable,
		unavailable,
		"Could not remove token",
		nil,
	}
	ErrCouldNotResolveToken = &APIError{
		http.StatusServiceUnavailable,
		unavailable,
		"Could not resolve token",
		nil,
	}
	ErrUnauthorized = &APIError{
		http.StatusUnauthorized,
		unauthorized,
		"Unauthorized",
		nil,
	}
	ErrTooManyPendingNotifications = &APIError{
		http.StatusRequestEntityTooLarge,
		tooManyPending,
		"Too many pending notifications for this application",
		nil,
	}
)

Well-known prebuilt API errors

Functions

func MakeHandlersMux

func MakeHandlersMux(storage StoreAccess, broker broker.BrokerSending, logger logger.Logger) *http.ServeMux

MakeHandlersMux makes a handler that dispatches for the various API endpoints.

func PanicTo500Handler

func PanicTo500Handler(h http.Handler, logger logger.Logger) http.Handler

PanicTo500Handler wraps another handler such that panics are recovered and 500 reported.

func RespondError

func RespondError(writer http.ResponseWriter, apiErr *APIError)

RespondError writes back a JSON error response for a APIError.

Types

type APIError

type APIError struct {
	// http status code
	StatusCode int `json:"-"`
	// machine readable label
	ErrorLabel string `json:"error"`
	// human message
	Message string `json:"message"`
	// extra information
	Extra json.RawMessage `json:"extra,omitempty"`
}

APIError represents a API error (both internally and as JSON in a response).

func ReadBody

func ReadBody(request *http.Request, maxBodySize int64) ([]byte, *APIError)

ReadBody checks that a POST request is well-formed and reads its body.

func (*APIError) Error

func (apiErr *APIError) Error() string

type Broadcast

type Broadcast struct {
	Channel  string          `json:"channel"`
	ExpireOn string          `json:"expire_on"`
	Data     json.RawMessage `json:"data"`
}

Broadcast request JSON object.

type JSONPostHandler

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

JSONPostHandler is able to handle POST requests with a JSON body delegating for the actual details.

func (*JSONPostHandler) ServeHTTP

func (h *JSONPostHandler) ServeHTTP(writer http.ResponseWriter, request *http.Request)

type Registration

type Registration struct {
	DeviceId string `json:"deviceid"`
	AppId    string `json:"appid"`
}

type StoreAccess

type StoreAccess interface {
	// StoreForRequest gets a pending store for the request.
	StoreForRequest(w http.ResponseWriter, request *http.Request) (store.PendingStore, error)
	// GetMaxNotificationsPerApplication gets the maximum number
	// of pending notifications allowed for a signle application.
	GetMaxNotificationsPerApplication() int
}

StoreAccess lets get a notification pending store and parameters for storage.

type Unicast

type Unicast struct {
	Token    string          `json:"token"`
	UserId   string          `json:"userid"`   // not part of the official API
	DeviceId string          `json:"deviceid"` // not part of the official API
	AppId    string          `json:"appid"`
	ExpireOn string          `json:"expire_on"`
	Data     json.RawMessage `json:"data"`
	// clear all pending messages for appid
	ClearPending bool `json:"clear_pending,omitempty"`
	// replace pending messages with the same replace_tag
	ReplaceTag string `json:"replace_tag,omitempty"`
}