Documentation ¶
Index ¶
- Constants
- Variables
- func CreateJWTOptionalMiddleware(s *Server) negroni.HandlerFunc
- func CreateJWTRequiredMiddleware(s *Server) negroni.HandlerFunc
- func GetUserIdentity(r *http.Request) (identity string, ok bool)
- func InitDbWithCfg(cfg *DatabaseConfig) (*gorm.DB, error)
- 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 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 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 WithStack(base error) error
- func WritePaginationHeaders(page PaginationResult, w http.ResponseWriter, r *http.Request) error
- type DatabaseConfig
- type Detail
- type ErrMsg
- type FormatHandler
- type FormatHandlers
- type Handler
- type HandlerWithResult
- type Header
- 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
- type ProtoResult
- type Route
- type RouterConfigurer
- type Routes
- type SecureMethods
- type Server
- 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
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 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 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 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)
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
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 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 GetUserIdentity ¶
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 IsSQLTxError ¶
IsSQLTxError checks if the given error is a sqlTx error. Note: we need to do that by testing its error message.
func Max ¶
Max is an implementation of "int" Max See https://mrekucci.blogspot.com.ar/2015/07/dont-abuse-mathmax-mathmin.html
func Min ¶
Min is an implementation of "int" Min See https://mrekucci.blogspot.com.ar/2015/07/dont-abuse-mathmax-mathmin.html
func NewContextWithLogger ¶
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 ParseHTMLTemplate ¶
ParseHTMLTemplate opens an HTML template and replaces placeholders with values.
func RandomString ¶
RandomString creates a random string of a given length. Ref: https://siongui.github.io/2015/04/13/go-generate-random-string/
func ReadEnvVar ¶
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 ¶
SameElements returns True if the two given string slices contain the same elements, even in different order.
func SendEmail ¶
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 ¶
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 Trace ¶
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 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 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.ir/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
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 ¶
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 ¶
NewErrorMessage is a convenience function that receives an error code and returns a pointer to an ErrMsg.
func NewErrorMessageWithArgs ¶
NewErrorMessageWithArgs receives an error code, a root error, and a slice of extra arguments, and returns a pointer to an ErrMsg.
func NewErrorMessageWithBase ¶
NewErrorMessageWithBase receives an error code and a root error and returns a pointer to an ErrMsg.
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 ¶
Handler represents an HTTP Handler that can also return a ErrMsg See https://blog.golang.org/error-handling-and-go
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 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 ¶
LoggerFromContext - gets an ign logger from the given context.
func LoggerFromRequest ¶
LoggerFromRequest - gets an ign logger from the given http request.
func NewLogger ¶
NewLogger - creates a new logger implementation associated to the given request ID.
func NewLoggerNoRollbar ¶
NewLoggerNoRollbar - creates a new logger implementation associated to the given request ID, which does not log to rollbar
func NewLoggerWithRollbarVerbosity ¶
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 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 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.ir/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) *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 SecureMethods ¶
type SecureMethods []Method
SecureMethods is a slice of Method that require authentication.
type Server ¶
type Server struct { /// Global database interface Db *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 ¶
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 ¶
Auth0RsaPublicKey return the Auth0 public key
func (*Server) ConfigureRouterWithRoutes ¶
ConfigureRouterWithRoutes takes a given mux.Router and configures it with a set of declared routes. The router is configured with default middlewares. 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 ¶
IsUsingSSL returns true if the server was configured to use SSL.
func (*Server) SetAuth0RsaPublicKey ¶
SetAuth0RsaPublicKey sets the server's Auth0 RSA public key
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)