ign

README

Ignition Robotics

Ignition Go is a general purpose golang library that encapsulates a set of common functionalities for a webserver.

Getting started

Ignition Go provides a set of features to help with web server development. It is a set of tools that were chosen to solve different problems in fuelserver and cloudsim packages.

Features

• A custom router based on the gorilla/mux package.
• A thread-safe concurrent queue based on the enriquebris/goconcurrentqueue package.
• A scheduler to set jobs to be executed at certain dates, based on the ignitionrobotics/web/scheduler package.
• A custom logger based on the default log package but including a rollbar implementation.
• An error handler with a list of default and custom error messages.

Usage

Routes

ign.Routes{
    ign.Route{
        Name:        "Route example",
        Description: "Route description example",
        URI:         "/example",
        Headers:     ign.AuthHeadersRequired,
        Methods:     ign.Methods{
            ign.Method{
                Type:        "GET",
                Description: "Get all the examples",
                Handlers:    ign.FormatHandlers{
                    ign.FormatHandler{
                        Extension: "",
                        Handler:   ign.JSONResult(/* Your method handler in here */),
                    },
                },
            },
        },
        SecureMethods: ign.SecureMethods{
            ign.Method{
                Type:        "POST",
                Description: "Creates a new example",
                Handlers:    ign.FormatHandlers{
                    ign.FormatHandler{
                        Extension: "",
                        Handler:   ign.JSONResult(/* Your secure method handler in here */),
                    },
                },
            },
        },
    },
}

Queue

func main() {
	queue := ign.NewQueue()
	queue.Enqueue("Value")
	if v, err := queue.DequeueOrWaitForNextElement(); err == nil {
		fmt.Println(v)
	}
}

Scheduler

func main() {
	s := scheduler.GetInstance()
	s.DoAt(example, time.Now().Add(5*time.Second))
}

func example() {
	fmt.Println("Scheduled task")
}

Installing

Using Go CLI

go get gitlab.com/ignitionrobotics/web/ign-go.git

Contribute

There are many ways to contribute to Ignition Go.

• Reviewing the source code changes.
• Report new bugs.
• Suggest new packages that we should consider including.

Environment variables

• IGN_SSL_CERT: Path to an SSL certificate file. This is used for local SSL testing and development.
• IGN_SSL_KEY: Path to an SSL key. THis is used for local SSL testing and development
• IGN_DB_USERNAME: Username for the database connection.
• IGN_DB_PASSWORD: Password for the database connection.
• IGN_DB_ADDRESS: URL address for the database server.
• IGN_DB_NAME: Name of the database to use on the database sever.
• IGN_DB_LOG: Controls whether or not database transactions generate log output. Set to true to enable database logging. This environment variable is optional, and database logging will default to off expect for tests.
• IGN_DB_MAX_OPEN_CONNS: Max number of open connections in connections pool. A value <= 0 means unlimited connections. Tip: You can learn max_connections of your mysql by running this query: SHOW VARIABLES LIKE "max_connections";
• IGN_GA_TRACKING_ID: Google Analytics Tracking ID to use. If not set, then GA will not be enabled. The format is UA-XXXX-Y.
• IGN_GA_APP_NAME: Google Analytics Application Name. If not set, then GA will not be enabled.
• IGN_GA_CAT_PREFIX: (optional) A string to use as a prefix to Google Analytics Event Category.
• IGN_ROLLBAR_TOKEN: (optional) Rollbar authentication token. If valid, then log messages will be sent to rollbar.com. It is recommended NOT to use rollbar during local development.
• IGN_ROLLBAR_ENV: (optional) Rollbar environment string, such as "staging" or "production".
• IGN_ROLLBAR_ROOT: (optional) Path to the application code root, not including the final slash. Such as bitbucket.org/ignitionrobotics/ign-fuelserver
• IGN_LOGGER_LOG_STDOUT: (optional) Controls whether or not logs will be also sent to stdout/err. If missing, a false value will be used.

Documentation

Index

• Constants
• Variables
• func Bool(v bool) *bool
• func CreateJWTOptionalMiddleware(s *Server) negroni.HandlerFunc
• func CreateJWTRequiredMiddleware(s *Server) negroni.HandlerFunc
• func Float64(v float64) *float64
• func GetUserIdentity(r *http.Request) (identity string, ok bool)
• func InitDbWithCfg(cfg *DatabaseConfig) (*gorm.DB, error)
• func Int(v int) *int
• func Int64(v int64) *int64
• func IsBotHandler(botHandler http.Handler, userHandler http.Handler) http.Handler
• func IsError(err error, target error) bool
• func IsSQLTxError(err error) bool
• func Max(x, y int64) int64
• func Min(x, y int64) int64
• func NewContextWithLogger(ctx context.Context, logger Logger) context.Context
• func NewPaginationRequest(r *http.Request) (*PaginationRequest, *ErrMsg)
• func NewRouter() *mux.Router
• func ParseHTMLTemplate(templateFilename string, data interface{}) (string, error)
• func ParseTemplate(templateFilename string, data interface{}) (string, error)
• func RandomString(strlen int) string
• func ReadEnvVar(name string) (string, error)
• func ReadLogVerbosityEnvVar() int
• func ReadRollbarLogVerbosityEnvVar() int
• func ReadStdLogEnvVar() bool
• func SameElements(a0, b0 []string) bool
• func SendEmail(sender, recipient, subject, body string) error
• func StrToSlice(tagsStr string) []string
• func String(v string) *string
• func StringSlice(src []string) []*string
• func Trace(skip int64) string
• func Unzip(buff bytes.Buffer, size int64, dest string, verbose bool) error
• func UnzipFile(zipfile string, dest string, verbose bool) error
• func UnzipImpl(reader *zip.Reader, dest string, verbose bool) error
• func ValidateAccessToken(token string, tx *gorm.DB) (*AccessToken, *ErrMsg)
• func WithStack(base error) error
• func WritePaginationHeaders(page PaginationResult, w http.ResponseWriter, r *http.Request) error
• type AccessToken
• type AccessTokenCreateRequest
  • func (createReq *AccessTokenCreateRequest) Create(tx *gorm.DB) (*AccessTokenCreateResponse, *AccessToken, *ErrMsg)
• type AccessTokenCreateResponse
• type AccessTokens
• type DatabaseConfig
  • func NewDatabaseConfigFromEnvVars() (DatabaseConfig, error)
• type Detail
• type ErrMsg
  • func ErrorMessage(err int64) ErrMsg
  • func ErrorMessageOK() ErrMsg
  • func NewErrorMessage(err int64) *ErrMsg
  • func NewErrorMessageWithArgs(err int64, base error, extra []string) *ErrMsg
  • func NewErrorMessageWithBase(err int64, base error) *ErrMsg
  • func (e *ErrMsg) LogString() string
• type FormatHandler
• type FormatHandlers
• type Handler
  • func (fn Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type HandlerWithResult
• type Header
• type JWTMiddlewareIgn
  • func (m *JWTMiddlewareIgn) AccessTokenHandler(w http.ResponseWriter, r *http.Request, next http.HandlerFunc)
• type Logger
  • func LoggerFromContext(ctx context.Context) Logger
  • func LoggerFromRequest(r *http.Request) Logger
  • func NewLogger(reqID string, std bool, verbosity int) Logger
  • func NewLoggerNoRollbar(reqID string, verbosity int) Logger
  • func NewLoggerWithRollbarVerbosity(reqID string, std bool, verbosity, rollbarVerbosity int) Logger
• type Method
• type Methods
• type PaginationRequest
• type PaginationResult
  • func PaginateQuery(q *gorm.DB, result interface{}, p PaginationRequest) (*PaginationResult, error)
• type ProtoResult
  • func (fn ProtoResult) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type Queue
  • func NewQueue() (queue *Queue)
  • func (st *Queue) Dequeue() (interface{}, *ErrMsg)
  • func (st *Queue) DequeueOrWaitForNextElement() (interface{}, *ErrMsg)
  • func (st *Queue) Enqueue(value interface{})
  • func (st *Queue) Find(criteria func(element interface{}) bool) []int
  • func (st *Queue) FindByIDs(ids []int) []interface{}
  • func (st *Queue) FindOne(target interface{}) int
  • func (st *Queue) GetCap() int
  • func (st *Queue) GetElement(index int) (interface{}, *ErrMsg)
  • func (st *Queue) GetElements() ([]interface{}, *ErrMsg)
  • func (st *Queue) GetFilteredElements(offset, limit int) ([]interface{}, *ErrMsg)
  • func (st *Queue) GetLen() int
  • func (st *Queue) MoveToBack(target interface{}) *ErrMsg
  • func (st *Queue) MoveToFront(target interface{}) *ErrMsg
  • func (st *Queue) Remove(target interface{}) *ErrMsg
  • func (st *Queue) Swap(a interface{}, b interface{}) *ErrMsg
• type Repository
• type Route
• type RouterConfigurer
  • func NewRouterConfigurer(r *mux.Router, monitoring monitoring.Provider) *RouterConfigurer
  • func (rc *RouterConfigurer) ConfigureRouter(pathPrefix string, routes Routes) *RouterConfigurer
  • func (rc *RouterConfigurer) SetAuthHandlers(optionalJWT, requiredJWT negroni.HandlerFunc) *RouterConfigurer
  • func (rc *RouterConfigurer) SetCustomHandlers(handlers ...negroni.Handler) *RouterConfigurer
• type Routes
• type SecureMethods
• type Server
  • func Init(auth0RSAPublicKey string, dbNameSuffix string, monitoring monitoring.Provider) (server *Server, err error)
  • func (s *Server) Auth0RsaPublicKey() string
  • func (s *Server) ConfigureRouterWithRoutes(pathPrefix string, router *mux.Router, routes Routes)
  • func (s *Server) IsUsingSSL() bool
  • func (s *Server) Run()
  • func (s *Server) SetAuth0RsaPublicKey(key string)
  • func (s *Server) SetRouter(router *mux.Router) *Server
• type TypeJSONResult
  • func JSONListResult(wrapper string, handler HandlerWithResult) TypeJSONResult
  • func JSONResult(handler HandlerWithResult) TypeJSONResult
  • func JSONResultNoTx(handler HandlerWithResult) TypeJSONResult
  • func (t TypeJSONResult) ServeHTTP(w http.ResponseWriter, r *http.Request)

Constants

const ErrorAuthJWTInvalid = 4001

ErrorAuthJWTInvalid is triggered when is not possible to get a user ID from the JWT in the request

const ErrorAuthNoUser = 4000

ErrorAuthNoUser is triggered when there's no user in the database with the claimed user ID.

const ErrorCastingID = 100011

ErrorCastingID is triggered when casting an id fails.

const ErrorCollectionNotInRequest = 3020

ErrorCollectionNotInRequest is triggered when a collection name is not found in the request

const ErrorCreatingDir = 100002

ErrorCreatingDir is triggered when the server was unable to create a new directory for a resource (no space on device or a temporary server problem).

const ErrorCreatingFile = 100004

ErrorCreatingFile is triggered when the server was unable to create a new file for a resource (no space on device or a temporary server problem).

const ErrorCreatingRepo = 100003

ErrorCreatingRepo is triggered when the server was unable to create a new repository for a resource (no space on device or a temporary server problem).

const ErrorDbDelete = 1001

ErrorDbDelete is triggered when the database was unable to delete a resource

const ErrorDbSave = 1002

ErrorDbSave is triggered when the database was unable to save a resource

const ErrorFileNotFound = 1005

ErrorFileNotFound is triggered when a model's file with the specified name is not found

const ErrorFileTree = 100009

ErrorFileTree is triggered when there was a problem accessing the model's files.

const ErrorForm = 3004

ErrorForm is triggered when an expected field is missing in a multipart form request.

const ErrorFormDuplicateFile = 3014

ErrorFormDuplicateFile is triggered when the POSTed model carries duplicate file entries.

const ErrorFormDuplicateModelName = 3015

ErrorFormDuplicateModelName is triggered when the POSTed model carries duplicate model name.

const ErrorFormDuplicateWorldName = 3018

ErrorFormDuplicateWorldName is triggered when the POSTed world carries duplicate name.

const ErrorFormInvalidValue = 3013

ErrorFormInvalidValue is triggered when a given form field has an invalid value.

const ErrorFormMissingFiles = 3012

ErrorFormMissingFiles is triggered when the expected "file" field is missing in the multipart form request.

const ErrorIDNotFound = 1003

ErrorIDNotFound is triggered when a resource with the specified id is not found in the database

const ErrorIDNotInRequest = 3000

ErrorIDNotInRequest is triggered when a id is not found in the request

const ErrorIDWrongFormat = 3001

ErrorIDWrongFormat is triggered when an id is not in a valid format

const ErrorInvalidPaginationRequest = 3016

ErrorInvalidPaginationRequest is triggered when the requested pagination is invalid. eg. invalid page or per_page argument values.

const ErrorInvalidSimulationStatus = 5007

ErrorInvalidSimulationStatus is triggered when the simulation is not in a status suitable for the requested operation. This error usually has a status extra argument.

const ErrorK8Create = 5003

ErrorK8Create is triggered when there is an error creating a kubernetes resource

const ErrorK8Delete = 5004

ErrorK8Delete is triggered when there is an error deleting a kubernetes resource

const ErrorLaunchGazebo = 5000

ErrorLaunchGazebo is triggered when we cannot launch gazebo in the context of a simulation

const ErrorLaunchingCloudInstance = 5005

ErrorLaunchingCloudInstance is triggered when there is an error launching a cloud instance (eg. aws ec2)

const ErrorLaunchingCloudInstanceNotEnoughResources = 5008

ErrorLaunchingCloudInstanceNotEnoughResources is triggered when there are not enough cloud instances to launch a simulation

const ErrorMarshalJSON = 2000

ErrorMarshalJSON is triggered if there is an error marshalling data into JSON

const ErrorMarshalProto = 2500

ErrorMarshalProto is triggered if there is an error marshalling data into protobuf

const ErrorMissingField = 3009

ErrorMissingField is triggered when the JSON contained in a request does not contain one or more required fields

const ErrorModelNotInRequest = 3011

ErrorModelNotInRequest is triggered when a model is not found in the request

const ErrorNameNotFound = 1004

ErrorNameNotFound is triggered when a resource with the specified name is not found in the database

const ErrorNameWrongFormat = 3002

ErrorNameWrongFormat is triggered when a name is not in a valid format

const ErrorNoDatabase = 1000

ErrorNoDatabase is triggered when the database connection is unavailable

const ErrorNonExistentResource = 100006

ErrorNonExistentResource is triggered when the server was unable to find a resource.

const ErrorOwnerNotInRequest = 3010

ErrorOwnerNotInRequest is triggered when an owner is not found in the request

const ErrorPaginationPageNotFound = 3017

ErrorPaginationPageNotFound is triggered when the requested page is empty / not found.

const ErrorPayloadEmpty = 3003

ErrorPayloadEmpty is triggered when payload is expected but is not found in the request

const ErrorQueueEmpty = 6000

ErrorQueueEmpty is triggered when a queue is empty

const ErrorQueueIndexOutOfBounds = 6001

ErrorQueueIndexOutOfBounds is triggered when there is an attempt to access an index that does not exist.

const ErrorQueueInternalChannelClosed = 6002

ErrorQueueInternalChannelClosed is triggered when the queue's internal channel is closed.

const ErrorQueueMoveIndexBackPosition = 6005

ErrorQueueMoveIndexBackPosition is triggered when there is an attempt to move the back element to the back position

const ErrorQueueMoveIndexFrontPosition = 6004

ErrorQueueMoveIndexFrontPosition is triggered when there is an attempt to move the front element to the front position

const ErrorQueueSwapIndexesMatch = 6003

ErrorQueueSwapIndexesMatch is triggered when there is an attempt to swap the same element.

const ErrorQueueTooManyListeners = 6006

ErrorQueueTooManyListeners is triggered when there are too many listeners waiting for the next element from the queue.

const ErrorRemovingDir = 100008

ErrorRemovingDir is triggered when the server was unable to remove a directory.

const ErrorRepo = 100007

ErrorRepo is triggered when the server was unable to handle repo command.

const ErrorResourceExists = 100001

ErrorResourceExists is triggered when the server cannot create a new resource because the requested id already exists. E.g.: When the creation of a new model is requested but the server already has a model with the same id.

const ErrorScheduler = 100012

ErrorScheduler is triggered initializing a scheduler fails.

const ErrorShutdownGazebo = 5001

ErrorShutdownGazebo is triggered when there is an error during the process of shutting down gazebo.

const ErrorSimGroupNotFound = 5002

ErrorSimGroupNotFound is triggered when a simulation Group ID is not found.

const ErrorStoppingCloudInstance = 5006

ErrorStoppingCloudInstance is triggered when there is an error stopping or terminating a cloud instance (eg. aws ec2)

const ErrorUnauthorized = 4002

ErrorUnauthorized is triggered when a user is not authorized to perform a given action.

const ErrorUnexpected = 150000

ErrorUnexpected is used to represent unexpected or still uncategorized errors.

const ErrorUnexpectedID = 3005

ErrorUnexpectedID is triggered when the id of a file attached in a request is not expected. E.g.: When the attached world file does not end in ".world" during a world creation request.

const ErrorUnknownSuffix = 3006

ErrorUnknownSuffix is triggered when a suffix for content negotiation is not recognized.

const ErrorUnmarshalJSON = 2001

ErrorUnmarshalJSON is triggered if there is an error unmarshalling JSON

const ErrorUnzipping = 100005

ErrorUnzipping is triggered when the server was unable to unzip a zipped file

const ErrorUserNotInRequest = 3007

ErrorUserNotInRequest is triggered when the user/team is not found in the request.

const ErrorUserUnknown = 3008

ErrorUserUnknown is triggered when the user/team does not exist on the server

const ErrorVersionNotFound = 100010

ErrorVersionNotFound is triggered when the requested version of a resource is not available

const ErrorWorldNotInRequest = 3019

ErrorWorldNotInRequest is triggered when a world is not found in the request

const ErrorZipNotAvailable = 100000

ErrorZipNotAvailable is triggered when the server does not have a zip file for the requested resource

const VerbosityCritical = 0

VerbosityCritical - Critical verbosity level Output will include Critical

const VerbosityDebug = 4

VerbosityDebug - Debug verbosity level Output will include Critical + Error + Warning + Info + Debug

const VerbosityError = 1

VerbosityError - Error verbosity level Output will include Critical + Error

const VerbosityInfo = 3

VerbosityInfo - Info verbosity level Output will include Critical + Error + Warning + Info

const VerbosityWarning = 2

VerbosityWarning - Warning verbosity level Output will include Critical + Error + Warning

const (
	// WaitForNextElementChanCapacity is being used to set the maximum capacity of listeners
	WaitForNextElementChanCapacity = 1000
)

Variables

var AuthHeadersOptional = []Header{
	{
		Name: "authorization: Bearer <YOUR_JWT_TOKEN>",
		HeaderDetails: Detail{
			Required: false,
		},
	},
}

AuthHeadersOptional is an array of Headers needed when authentication is optional.

var AuthHeadersRequired = []Header{
	{
		Name: "authorization: Bearer <YOUR_JWT_TOKEN>",
		HeaderDetails: Detail{
			Required: true,
		},
	},
}

AuthHeadersRequired is an array of Headers needed when authentication is required.

Functions

func Bool

func Bool(v bool) *bool

Bool returns a pointer to the bool value passed in.

func CreateJWTOptionalMiddleware

func CreateJWTOptionalMiddleware(s *Server) negroni.HandlerFunc

CreateJWTOptionalMiddleware creates and returns a middleware that allows requests with optional JWT tokens.

func CreateJWTRequiredMiddleware

func CreateJWTRequiredMiddleware(s *Server) negroni.HandlerFunc

CreateJWTRequiredMiddleware creates and returns a middleware that rejects requests that do not have a JWT token.

func Float64

func Float64(v float64) *float64

Float64 returns a pointer to the float64 value passed in.

func GetUserIdentity

func GetUserIdentity(r *http.Request) (identity string, ok bool)

GetUserIdentity returns the user identity found in the http request's JWT token.

func InitDbWithCfg

func InitDbWithCfg(cfg *DatabaseConfig) (*gorm.DB, error)

InitDbWithCfg initialize the database connection based on the given cfg.

func Int

func Int(v int) *int

Int returns a pointer to the int value passed in.

func Int64

func Int64(v int64) *int64

Int64 returns a pointer to the int64 value passed in.

func IsBotHandler

func IsBotHandler(botHandler http.Handler, userHandler http.Handler) http.Handler

IsBotHandler decides which handler to use whether the request was made by a bot or a user.

func IsError

func IsError(err error, target error) bool

IsError returns true when err is the target error.

func IsSQLTxError

func IsSQLTxError(err error) bool

IsSQLTxError checks if the given error is a sqlTx error. Note: we need to do that by testing its error message.

func Max

func Max(x, y int64) int64

Max is an implementation of "int" Max See https://mrekucci.blogspot.com.ar/2015/07/dont-abuse-mathmax-mathmin.html

func Min

func Min(x, y int64) int64

Min is an implementation of "int" Min See https://mrekucci.blogspot.com.ar/2015/07/dont-abuse-mathmax-mathmin.html

func NewContextWithLogger

func NewContextWithLogger(ctx context.Context, logger Logger) context.Context

NewContextWithLogger - configures the context with a new ign Logger,

func NewPaginationRequest

func NewPaginationRequest(r *http.Request) (*PaginationRequest, *ErrMsg)

NewPaginationRequest creates a new PaginationRequest from the given http request.

func NewRouter

func NewRouter() *mux.Router

NewRouter just creates a new Gorilla/mux router

func ParseHTMLTemplate

func ParseHTMLTemplate(templateFilename string, data interface{}) (string, error)

ParseHTMLTemplate opens an HTML template and replaces placeholders with values.

func ParseTemplate

func ParseTemplate(templateFilename string, data interface{}) (string, error)

ParseTemplate opens a template and replaces placeholders with values.

func RandomString

func RandomString(strlen int) string

RandomString creates a random string of a given length. Ref: https://siongui.github.io/2015/04/13/go-generate-random-string/

func ReadEnvVar

func ReadEnvVar(name string) (string, error)

ReadEnvVar reads an environment variable and return an error if not present

func ReadLogVerbosityEnvVar

func ReadLogVerbosityEnvVar() int

ReadLogVerbosityEnvVar reads the IGN_LOGGER_VERBOSITY env var and returns its bool value.

func ReadRollbarLogVerbosityEnvVar

func ReadRollbarLogVerbosityEnvVar() int

ReadRollbarLogVerbosityEnvVar reads the IGN_LOGGER_ROLLBAR_VERBOSITY env var and returns its bool value.

func ReadStdLogEnvVar

func ReadStdLogEnvVar() bool

ReadStdLogEnvVar reads the IGN_LOGGER_LOG_STDOUT env var and returns its bool value.

func SameElements

func SameElements(a0, b0 []string) bool

SameElements returns True if the two given string slices contain the same elements, even in different order.

func SendEmail

func SendEmail(sender, recipient, subject, body string) error

SendEmail using AWS Simple Email Service (SES) The following environment variables must be set:

AWS_REGION AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY

func StrToSlice

func StrToSlice(tagsStr string) []string

StrToSlice returns the slice of strings with all tags parsed from the input string. It will trim leading and trailing whitespace, and reduce middle whitespaces to 1 space. It will also remove 'empty' tags (ie. whitespaces enclosed with commas, ', ,') The input string contains tags separated with commas. E.g. input string: " tag1, tag2, tag3 , , " E.g. output: ["tag1", "tag2", "tag3"]

func String

func String(v string) *string

String returns a pointer to the string value passed in.

func StringSlice

func StringSlice(src []string) []*string

StringSlice converts a slice of string values into a slice of string pointers

func Trace

func Trace(skip int64) string

Trace returns the filename, line and function name of its caller. The skip parameter is the number of stack frames to skip, with 1 identifying the Trace frame itself. Skip will be set to 1 if the passed in value is <= 0. Ref: http://stackoverflow.com/questions/25927660/golang-get-current-scope-of-function-name

func Unzip

func Unzip(buff bytes.Buffer, size int64, dest string, verbose bool) error

Unzip a memory buffer TODO: remove. Unused code.

func UnzipFile

func UnzipFile(zipfile string, dest string, verbose bool) error

UnzipFile extracts a compressed .zip file TODO: remove. Unused code.

func UnzipImpl

func UnzipImpl(reader *zip.Reader, dest string, verbose bool) error

UnzipImpl is a helper unzip implementation TODO: remove. Unused code.

func ValidateAccessToken

func ValidateAccessToken(token string, tx *gorm.DB) (*AccessToken, *ErrMsg)

ValidateAccessToken checks a token string against tokens that exist in the provided database. If the access token is validated, then it is returned as the first return value.

func WithStack

func WithStack(base error) error

WithStack wraps a given error with a stack trace if needed.

func WritePaginationHeaders

func WritePaginationHeaders(page PaginationResult, w http.ResponseWriter, r *http.Request) error

WritePaginationHeaders writes the 'next', 'last', 'first', and 'prev' Link headers to the given ResponseWriter.

Types

type AccessToken

type AccessToken struct {
	// ID is the primary key for access tokens.
	ID uint `gorm:"primary_key" json:"-"`

	// CreatedAt is the time when the access token was created
	CreatedAt time.Time `json:"created_at"`

	// UserID is the user that owns this token.
	UserID uint `json:"-"`

	// Name is a string given to a token by the user. The name does not have to be unique.
	Name string `json:"name"`

	// Prefix is the first set of characters in the token. The prefix is used to identify the user
	// and help a user keep track of their tokens. We use 'latin1_general_cs` collation to enforce
	// case-senstive queries.
	Prefix string `sql:"type:VARCHAR(64) CHARACTER SET latin1 COLLATE latin1_general_cs" json:"prefix"`

	// Key is the second set of characters in the token, following the Prefix. The key is used to
	// authenticate the user. We use 'latin1_general_cs` collation to enforce case-senstive queries. The key is omitted from json to prevent it from being transmitted over the wire.
	Key string `sql:"type:VARCHAR(512) CHARACTER SET latin1 COLLATE latin1_general_cs" json:"-"`

	// Last used time.
	LastUsed *time.Time `json:"last_used"`

	// For future use, when we add in the ability to expire tokens.
	Expires *time.Time `json:"expires"`
}

AccessToken is a single personal access token for a user.

type AccessTokenCreateRequest

type AccessTokenCreateRequest struct {
	Name string `json:"name" validate:"required,min=3,alphanum"`
}

AccessTokenCreateRequest contains information required to create a new access token.

func (*AccessTokenCreateRequest) Create

func (createReq *AccessTokenCreateRequest) Create(tx *gorm.DB) (*AccessTokenCreateResponse, *AccessToken, *ErrMsg)

Create instantiates a new unique random access token. The first return value is the full access token, which can be passed along to a user. Be careful with the full access token since it is a full-access key. The second return value is a salted token, which is suitable for storage in a database. The third return value is an error, or nil.

type AccessTokenCreateResponse

type AccessTokenCreateResponse struct {
	// Name is a string given to a token by the user.
	Name string `json:"name"`

	// Prefix is the first set of characters in the token. The prefix is used to identify the user
	// and help a user keep track of their tokens.
	Prefix string `json:"prefix"`

	// Key is the second set of characters in the token, following the Prefix. The key is used to
	// authenticate the user.
	Key string `json:"key"`
}

AccessTokenCreateResponse contains information about a newly created access token.

type AccessTokens

type AccessTokens []AccessToken

AccessTokens is an array of AccessToken

type DatabaseConfig

type DatabaseConfig struct {
	// Username to login to a database.
	UserName string
	// Password to login to a database.
	Password string
	// Address of the database.
	Address string
	// Name of the database.
	Name string
	// Allowed Max Open Connections.
	// A value <= 0 means unlimited connections.
	// See 'https://golang.org/src/database/sql/sql.go'
	MaxOpenConns int
	// True to enable database logging. This will cause all database transactions
	// to output messages to standard out, which could create large log files in
	// docker. It is recommended to use this only during development and testing.
	// Logging can be controlled via the IGN_DB_LOG environment variable.
	//
	// By default logging is enabled only in tests with verbose flag.
	EnableLog bool
}

DatabaseConfig contains information about a database connection

func NewDatabaseConfigFromEnvVars

func NewDatabaseConfigFromEnvVars() (DatabaseConfig, error)

NewDatabaseConfigFromEnvVars returns a DatabaseConfig object from the following env vars: - IGN_DB_USERNAME - IGN_DB_PASSWORD - IGN_DB_ADDRESS - IGN_DB_NAME - IGN_DB_MAX_OPEN_CONNS - (Optional) You run the risk of getting a 'too many connections' error if this is not set.

type Detail

type Detail struct {
	Type        string `json:"type"`
	Description string `json:"description"`
	Required    bool   `json:"required"`
}

Detail stores information about a paramter.

type ErrMsg

type ErrMsg struct {
	// Internal error code.
	ErrCode int `json:"errcode"`
	// HTTP status code.
	StatusCode int `json:"-"`
	// Error message.
	Msg string `json:"msg"`
	// Extra information/arguments associated to Error message.
	Extra []string `json:"extra"`
	// The root cause error
	BaseError error `json:"-"`
	// Generated ID for easy tracking in server logs
	ErrID string `json:"errid"`
	// Associated request Route, if applicable
	Route string `json:"route"`
	// Associated request User-Agent, if applicable
	UserAgent string `json:"user-agent"`
	// Associated request remote address, if applicable
	RemoteAddress string `json:"remote-address"`
}

ErrMsg is serialized as JSON, and returned if the request does not succeed TODO: consider making ErrMsg an 'error'

func ErrorMessage

func ErrorMessage(err int64) ErrMsg

ErrorMessage receives an error code and generate an error message response

func ErrorMessageOK

func ErrorMessageOK() ErrMsg

ErrorMessageOK creates an ErrMsg initialized with OK (default) values.

func NewErrorMessage

func NewErrorMessage(err int64) *ErrMsg

NewErrorMessage is a convenience function that receives an error code and returns a pointer to an ErrMsg.

func NewErrorMessageWithArgs

func NewErrorMessageWithArgs(err int64, base error, extra []string) *ErrMsg

NewErrorMessageWithArgs receives an error code, a root error, and a slice of extra arguments, and returns a pointer to an ErrMsg.

func NewErrorMessageWithBase

func NewErrorMessageWithBase(err int64, base error) *ErrMsg

NewErrorMessageWithBase receives an error code and a root error and returns a pointer to an ErrMsg.

func (*ErrMsg) LogString

func (e *ErrMsg) LogString() string

LogString creates a verbose error string

type FormatHandler

type FormatHandler struct {
	// Format (eg: .json, .proto, .html)
	Extension string `json:"extension"`

	// Processor for the url pattern
	Handler http.Handler `json:"-"`
}

FormatHandler represents a format type string, and handler function pair. Handlers are called in response to a route request.

type FormatHandlers

type FormatHandlers []FormatHandler

FormatHandlers is a slice of FormatHandler values.

type Handler

type Handler func(*gorm.DB, http.ResponseWriter, *http.Request) *ErrMsg

Handler represents an HTTP Handler that can also return a ErrMsg See https://blog.golang.org/error-handling-and-go

func (Handler) ServeHTTP

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

type HandlerWithResult

type HandlerWithResult func(tx *gorm.DB, w http.ResponseWriter,
	r *http.Request) (interface{}, *ErrMsg)

HandlerWithResult represents an HTTP Handler that that has a result

type Header

type Header struct {
	Name          string `json:"name"`
	HeaderDetails Detail `json:"details"`
}

Header stores the information about headers included in a request.

type JWTMiddlewareIgn

type JWTMiddlewareIgn struct {
	*jwtmiddleware.JWTMiddleware
}

JWTMiddlewareIgn wraps jwtmiddleware.JWTMiddleware so that we can create a custom AccessTokenHandler that first checks for a Private-Token and then checks for a JWT if the Private-Token doesn't exist.

func (*JWTMiddlewareIgn) AccessTokenHandler

func (m *JWTMiddlewareIgn) AccessTokenHandler(w http.ResponseWriter, r *http.Request, next http.HandlerFunc)

AccessTokenHandler first checks for a Private-Token and then checks for a JWT if the Private-Token doesn't exist.

type Logger

type Logger interface {
	// Output when verbosity => 4
	Debug(interfaces ...interface{})
	// Output when verbosity => 3
	Info(interfaces ...interface{})
	// Output when verbosity => 2
	Warning(interfaces ...interface{})
	// Output when verbosity => 1
	Error(interfaces ...interface{})
	// Output when verbosity => 0
	Critical(interfaces ...interface{})
	// Clone this logger and returns a copy.
	Clone(reqID string) Logger
}

Logger - interface for any ign logger.

func LoggerFromContext

func LoggerFromContext(ctx context.Context) Logger

LoggerFromContext - gets an ign logger from the given context.

func LoggerFromRequest

func LoggerFromRequest(r *http.Request) Logger

LoggerFromRequest - gets an ign logger from the given http request.

func NewLogger

func NewLogger(reqID string, std bool, verbosity int) Logger

NewLogger - creates a new logger implementation associated to the given request ID.

func NewLoggerNoRollbar

func NewLoggerNoRollbar(reqID string, verbosity int) Logger

NewLoggerNoRollbar - creates a new logger implementation associated to the given request ID, which does not log to rollbar

func NewLoggerWithRollbarVerbosity

func NewLoggerWithRollbarVerbosity(reqID string, std bool, verbosity, rollbarVerbosity int) Logger

NewLoggerWithRollbarVerbosity - creates a new logger implementation associated to the given request ID and also configures a minimum verbosity to send logs to Rollbar.

type Method

type Method struct {
	// GET, POST, PUT, DELETE
	// \todo: Make this an enum
	Type string `json:"type"`

	// Description of the method
	Description string `json:"description"`

	// A slice of hanlders used to process this method.
	Handlers FormatHandlers `json:"handler"`
}

Method associates an HTTP method (GET, POST, PUT, DELETE) with a list of handlers.

type Methods

type Methods []Method

Methods is a slice of Method.

type PaginationRequest

type PaginationRequest struct {
	// Flag that indicates if the request included a "page" argument.
	PageRequested bool
	// The requested page number (value >= 1)
	Page int64
	// The requested number of items per page.
	PerPage int64
	// The original request URL
	URL string
}

PaginationRequest represents the pagination values requested in the URL query (eg. ?page=2&per_page=10)

type PaginationResult

type PaginationResult struct {
	// Page number
	Page int64
	// Page size
	PerPage int64
	// Original request' url
	URL string
	// Query "total" count (ie. this is NOT the "page" count)
	QueryCount int64
	// A page is considered "found" if it is within the range of valid pages,
	// OR if it is the first page and the DB query is empty. In this empty scenario,
	// we want to return status OK with zero elements, rather than a 404 status.
	PageFound bool
}

PaginationResult represents the actual pagination output.

func PaginateQuery

func PaginateQuery(q *gorm.DB, result interface{}, p PaginationRequest) (*PaginationResult, error)

PaginateQuery applies a pagination request to a GORM query and executes it. Param[in] q gorm.DB The query to be paginated Param[out] result [interface{}] The paginated list of items Param[in] p The pagination request Returns a PaginationResult describing the returned page.

type ProtoResult

type ProtoResult HandlerWithResult

ProtoResult provides protobuf serialization for handler results

func (ProtoResult) ServeHTTP

func (fn ProtoResult) ServeHTTP(w http.ResponseWriter, r *http.Request)

type Queue

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

Queue is a thread-safe data type that uses an underlying slice as a queue. It provides a set of methods to modify the elements of the queue. It was created to replace a go channel since channels don't let you modify their elements order. You can push elements inside the queue using Enqueue method. They will be pushed to the back of the queue. You can pop elements from the queue using both Dequeue() and DequeueOrWaitForNextElement(). DequeueOrWaitForNextElement() waits until the queue has any element inside to pop it out.

func NewQueue

func NewQueue() (queue *Queue)

NewQueue returns a new Queue instance.

func (*Queue) Dequeue

func (st *Queue) Dequeue() (interface{}, *ErrMsg)

Dequeue dequeues an element. Returns error if queue is locked or empty.

func (*Queue) DequeueOrWaitForNextElement

func (st *Queue) DequeueOrWaitForNextElement() (interface{}, *ErrMsg)

DequeueOrWaitForNextElement dequeues an element (if exist) or waits until the next element gets enqueued and returns it. Multiple calls to DequeueOrWaitForNextElement() would enqueue multiple "listeners" for future enqueued elements.

func (*Queue) Enqueue

func (st *Queue) Enqueue(value interface{})

Enqueue enqueues an element.

func (*Queue) Find

func (st *Queue) Find(criteria func(element interface{}) bool) []int

Find returns a list of ids of the elements that match the given criteria. Returns an empty slice if there are not elements that match.

func (*Queue) FindByIDs

func (st *Queue) FindByIDs(ids []int) []interface{}

FindByIDs returns a list of elements of the given ids. Returns an empty slice if there are no elements in the queue.

func (*Queue) FindOne

func (st *Queue) FindOne(target interface{}) int

FindOne returns the id from a given element. Returns -1 if the element does not exist in the queue.

func (*Queue) GetCap

func (st *Queue) GetCap() int

GetCap returns the queue's capacity

func (*Queue) GetElement

func (st *Queue) GetElement(index int) (interface{}, *ErrMsg)

GetElement returns an element's value and keeps the element at the queue

func (*Queue) GetElements

func (st *Queue) GetElements() ([]interface{}, *ErrMsg)

GetElements returns the entire list of elements from the queue

func (*Queue) GetFilteredElements

func (st *Queue) GetFilteredElements(offset, limit int) ([]interface{}, *ErrMsg)

GetFilteredElements returns a subset list from the queue

func (*Queue) GetLen

func (st *Queue) GetLen() int

GetLen returns the number of enqueued elements

func (*Queue) MoveToBack

func (st *Queue) MoveToBack(target interface{}) *ErrMsg

MoveToBack moves an element to the back of the queue

func (*Queue) MoveToFront

func (st *Queue) MoveToFront(target interface{}) *ErrMsg

MoveToFront moves an element to the front of the queue

func (*Queue) Remove

func (st *Queue) Remove(target interface{}) *ErrMsg

Remove removes an element from the queue

func (*Queue) Swap

func (st *Queue) Swap(a interface{}, b interface{}) *ErrMsg

Swap swaps values A and B.

type Repository

type Repository interface {
	Add(entity interface{}) (interface{}, *ErrMsg)
	Get(id interface{}) (interface{}, *ErrMsg)
	GetAll(offset, limit *int) ([]interface{}, *ErrMsg)
	Update(id interface{}, entity interface{}) (interface{}, *ErrMsg)
	Remove(id interface{}) (interface{}, *ErrMsg)
	Find(criteria func(element interface{}) bool) ([]interface{}, *ErrMsg)
	FindByIDs(ids []interface{}) ([]interface{}, *ErrMsg)
	FindOne(criteria func(element interface{}) bool) (interface{}, *ErrMsg)
	Clear() *ErrMsg
	Count(criteria func(element interface{}) bool) int
}

Repository represents a set of methods of a generic repository. It is based in the Repository pattern, and allows to a system to change the underlying data structure without changing anything else. It could be used to provide an abstraction layer between a service and an ORM.

type Route

type Route struct {

	// Name of the route
	Name string `json:"name"`

	// Description of the route
	Description string `json:"description"`

	// URI pattern
	URI string `json:"uri"`

	// Headers required by the route
	Headers []Header `json:"headers"`

	// HTTP methods supported by the route
	Methods Methods `json:"methods"`

	// Secure HTTP methods supported by the route
	SecureMethods SecureMethods `json:"secure_methods"`
}

Route is a definition of a route

type RouterConfigurer

type RouterConfigurer struct {
	// Embedded type mux.Router
	// See https://golang.org/doc/effective_go.html#embedding
	*mux.Router
	// contains filtered or unexported fields
}

RouterConfigurer is used to configure a mux.Router with declared routes and middlewares. It also adds support for default global OPTIONS handler based on the route declarations.

func NewRouterConfigurer

func NewRouterConfigurer(r *mux.Router, monitoring monitoring.Provider) *RouterConfigurer

NewRouterConfigurer creates a new RouterConfigurer, used to configure a mux.Router with routes declarations.

func (*RouterConfigurer) ConfigureRouter

func (rc *RouterConfigurer) ConfigureRouter(pathPrefix string, routes Routes) *RouterConfigurer

ConfigureRouter - given an array of Route declarations, this method confifures the router to handle them. This is the main method to invoke with a RouterConfigurer.

It supports an optional pathPrefix used to differentiate API versions (eg. "/2.0/").

func (*RouterConfigurer) SetAuthHandlers

func (rc *RouterConfigurer) SetAuthHandlers(optionalJWT, requiredJWT negroni.HandlerFunc) *RouterConfigurer

SetAuthHandlers - set the JWT handlers to be used by the router for secure and unsecure routes.

func (*RouterConfigurer) SetCustomHandlers

func (rc *RouterConfigurer) SetCustomHandlers(handlers ...negroni.Handler) *RouterConfigurer

SetCustomHandlers - allows to set a list of optional middlewares that will be injected between the common middlewares and the final route handler.

type Routes

type Routes []Route

Routes is an array of Route

type SecureMethods

type SecureMethods []Method

SecureMethods is a slice of Method that require authentication.

type Server

type Server struct {
	/// Global database interface
	Db *gorm.DB

	/// Global database to the user database interface
	UsersDb *gorm.DB

	Router *mux.Router

	// Port used for non-secure requests
	HTTPPort string

	// SSLport used for secure requests
	SSLport string

	// SSLCert is the path to the SSL certificate.
	SSLCert string

	// SSLKey is the path to the SSL private key.
	SSLKey string

	// DbConfig contains information about the database
	DbConfig DatabaseConfig

	// IsTest is true when tests are running.
	IsTest bool

	// Google Analytics tracking ID. The format is UA-XXXX-Y
	GaTrackingID string

	// Google Analytics Application Name
	GaAppName string

	// (optional) A string to use as a prefix to GA Event Category.
	GaCategoryPrefix string

	// Should the Server log to stdout/err? Can be configured using IGN_LOGGER_LOG_STDOUT env var.
	LogToStd bool
	// Verbosity level of the Ign Logger - 4 debug, 3 info, 2 warning, 1 error, 0 critical
	LogVerbosity int
	// Verbosity level of the Ign Logger, to send to Rollbar - 4 debug, 3 info, 2 warning, 1 error, 0 critical
	RollbarLogVerbosity int
	// contains filtered or unexported fields
}

Server encapsulates information needed by a downstream application

func Init

func Init(auth0RSAPublicKey string, dbNameSuffix string, monitoring monitoring.Provider) (server *Server, err error)

Init initialize this package. Note: This method does not configure the Server's Router. You will later need to configure the router and set it to the server.

func (*Server) Auth0RsaPublicKey

func (s *Server) Auth0RsaPublicKey() string

Auth0RsaPublicKey return the Auth0 public key

func (*Server) ConfigureRouterWithRoutes

func (s *Server) ConfigureRouterWithRoutes(pathPrefix string, router *mux.Router, routes Routes)

ConfigureRouterWithRoutes takes a given mux.Router and configures it with a set of declared routes. The router is configured with default middlewares. If a monitoring provider was set on the server, the router will include an additional middleware to track server metrics and add a monitoring route defined by the provider. If the router is a mux subrouter gotten by PathPrefix().Subrouter() then you need to pass the pathPrefix as argument here too (eg. "/2.0/")

func (*Server) IsUsingSSL

func (s *Server) IsUsingSSL() bool

IsUsingSSL returns true if the server was configured to use SSL.

func (*Server) Run

func (s *Server) Run()

Run the router and server

func (*Server) SetAuth0RsaPublicKey

func (s *Server) SetAuth0RsaPublicKey(key string)

SetAuth0RsaPublicKey sets the server's Auth0 RSA public key

func (*Server) SetRouter

func (s *Server) SetRouter(router *mux.Router) *Server

SetRouter sets the main mux.Router to the server. If a monitoring provider has been defined, this will also configure the router to include routes for the monitoring service.

type TypeJSONResult

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

TypeJSONResult represents a function result that can be exported to JSON

func JSONListResult

func JSONListResult(wrapper string, handler HandlerWithResult) TypeJSONResult

JSONListResult provides JSON serialization for handler results that are slices of objects.

func JSONResult

func JSONResult(handler HandlerWithResult) TypeJSONResult

JSONResult provides JSON serialization for handler results

func JSONResultNoTx

func JSONResultNoTx(handler HandlerWithResult) TypeJSONResult

JSONResultNoTx provides JSON serialization for handler results

func (TypeJSONResult) ServeHTTP

func (t TypeJSONResult) ServeHTTP(w http.ResponseWriter, r *http.Request)