Documentation ¶
Index ¶
- Constants
- func SkipResponseHandling() (interface{}, error)
- type ActionFunc
- type AppBaseError
- type AppContainerError
- type AppError
- func GetAccessForbidden(errorMessage string, innerErrors ...error) AppError
- func GetBadRequest(errorMessage string, innerErrors ...error) AppError
- func GetCircuitBreak(errorMessage string, innerErrors ...error) AppError
- func GetDataCorruption(errorMessage string, innerErrors ...error) AppError
- func GetGeneralFailure(errorMessage string, innerErrors ...error) AppError
- func GetInvalidOperation(errorMessage string, innerErrors ...error) AppError
- func GetNotFound(errorMessage string, innerErrors ...error) AppError
- func GetNotImplemented(errorMessage string, innerErrors ...error) AppError
- func GetOperationLock(errorMessage string, innerErrors ...error) AppError
- func GetUnauthorized(errorMessage string, innerErrors ...error) AppError
- func WrapError(sourceError error, innerErrors ...error) AppError
- type AppHTTPError
- type Application
- type BootstrapCustomization
- type Customization
- type DefaultCustomization
- func (customization *DefaultCustomization) AppClosing() error
- func (customization *DefaultCustomization) CaCertPool() *x509.CertPool
- func (customization *DefaultCustomization) ClientCert() *tls.Certificate
- func (customization *DefaultCustomization) DefaultTimeout() time.Duration
- func (customization *DefaultCustomization) GraceShutdownWaitTime() time.Duration
- func (customization *DefaultCustomization) InstrumentRouter(router *mux.Router) *mux.Router
- func (customization *DefaultCustomization) InterpretError(err error) (int, string)
- func (customization *DefaultCustomization) InterpretSuccess(responseContent interface{}) (int, string)
- func (customization *DefaultCustomization) Listener() net.Listener
- func (customization *DefaultCustomization) Log(session Session, logType LogType, logLevel LogLevel, ...)
- func (customization *DefaultCustomization) MethodNotAllowedHandler() http.Handler
- func (customization *DefaultCustomization) Middlewares() []MiddlewareFunc
- func (customization *DefaultCustomization) NotFoundHandler() http.Handler
- func (customization *DefaultCustomization) PostAction(session Session) error
- func (customization *DefaultCustomization) PostBootstrap() error
- func (customization *DefaultCustomization) PreAction(session Session) error
- func (customization *DefaultCustomization) PreBootstrap() error
- func (customization *DefaultCustomization) RecoverPanic(session Session, recoverResult interface{}) (interface{}, error)
- func (customization *DefaultCustomization) RoundTripper(originalTransport http.RoundTripper) http.RoundTripper
- func (customization *DefaultCustomization) Routes() []Route
- func (customization *DefaultCustomization) ServerCert() *tls.Certificate
- func (customization *DefaultCustomization) SkipServerCertVerification() bool
- func (customization *DefaultCustomization) Statics() []Static
- func (customization *DefaultCustomization) WrapHandler(handler http.Handler) http.Handler
- func (customization *DefaultCustomization) WrapRequest(session Session, httpRequest *http.Request) *http.Request
- type HandlerCustomization
- type HostingCustomization
- type LogLevel
- type LogType
- type LoggingCustomization
- type MiddlewareFunc
- type ParameterType
- type Route
- type Session
- type SessionAttachment
- type SessionHTTP
- type SessionHTTPRequest
- type SessionHTTPResponse
- type SessionLogging
- type SessionMeta
- type SessionWebcall
- type Static
- type WebRequest
- type WebRequestCustomization
Constants ¶
const (
ContentTypeJSON = "application/json; charset=utf-8"
)
These are the constants used by the HTTP modules
Variables ¶
This section is empty.
Functions ¶
func SkipResponseHandling ¶ added in v1.1.5
func SkipResponseHandling() (interface{}, error)
SkipResponseHandling indicates to the library to skip operating on the HTTP response writer
Types ¶
type ActionFunc ¶
ActionFunc defines the action function to be called for route processing logic
type AppBaseError ¶
type AppBaseError interface { // Error refers to the Golang built-in error interface method Error() string // ErrorCode returns the string representation of the error code enum ErrorCode() string }
AppBaseError is the error extending interface that is compatible with Golang error type
type AppContainerError ¶
type AppContainerError interface { // Contains checks if the current error object or any of its inner errors contains the given error object Contains(err error) bool // Wrap wraps the given list of inner errors into the current app error object Wrap(innerErrors ...error) AppError }
AppContainerError is the error extending interface that can be used to wrap inner errors
type AppError ¶
type AppError interface { // AppBaseError is the error extending interface that is compatible with Golang error type AppBaseError // AppHTTPError is the error extending interface that can be translated into HTTP status code and response body AppHTTPError // AppContainerError is the error extending interface that can be used to wrap inner errors AppContainerError }
AppError is the error wrapper interface for all web service generated errors
func GetAccessForbidden ¶
GetAccessForbidden creates an error related to AccessForbidden
func GetBadRequest ¶
GetBadRequest creates an error related to BadRequest
func GetCircuitBreak ¶
GetCircuitBreak creates an error related to CircuitBreak
func GetDataCorruption ¶
GetDataCorruption creates an error related to DataCorruption
func GetGeneralFailure ¶
GetGeneralFailure creates a generic error based on GeneralFailure
func GetInvalidOperation ¶
GetInvalidOperation creates an error related to InvalidOperation
func GetNotFound ¶
GetNotFound creates an error related to NotFound
func GetNotImplemented ¶
GetNotImplemented creates an error related to NotImplemented
func GetOperationLock ¶
GetOperationLock creates an error related to OperationLock
func GetUnauthorized ¶
GetUnauthorized creates an error related to Unauthorized
type AppHTTPError ¶
type AppHTTPError interface { // HTTPStatusCode returns the corresponding HTTP status code mapped to the error code value HTTPStatusCode() int // HTTPResponseMessage returns the JSON representation of this error for HTTP response HTTPResponseMessage() string }
AppHTTPError is the error extending interface that can be translated into HTTP status code and response body
type Application ¶
type Application interface { // Start starts the web server hosting in the current running thread, causing the thread to be blocked until a Stop is called or an interrupt signal is received Start() // Session retrieves the application-level session instance for logging or any other necessary operations Session() Session // IsRunning returns true if the server has been successfully started and is currently running IsRunning() bool // Stop interrupts the web server hosting, causing the web server to gracefully shutdown; a synchronous Start would then return, or an asynchronous StartSync would mark its wait group done and then return Stop() }
Application is the interface for web server application
func NewApplication ¶
func NewApplication( name string, address string, version string, customization Customization, ) Application
NewApplication creates a new application for web server hosting
type BootstrapCustomization ¶
type BootstrapCustomization interface { // PreBootstrap is to customize the pre-processing logic before bootstrapping PreBootstrap() error // PostBootstrap is to customize the post-processing logic after bootstrapping PostBootstrap() error // AppClosing is to customize the application closing logic after server shutdown AppClosing() error }
BootstrapCustomization holds customization methods related to bootstrapping
type Customization ¶
type Customization interface { // BootstrapCustomization holds customization methods related to bootstrapping BootstrapCustomization // LoggingCustomization holds customization methods related to logging LoggingCustomization // HostingCustomization holds customization methods related to hosting HostingCustomization // HandlerCustomization holds customization methods related to handlers HandlerCustomization // WebRequestCustomization holds customization methods related to web requests WebRequestCustomization }
Customization holds all customization methods
type DefaultCustomization ¶
type DefaultCustomization struct{}
DefaultCustomization can be used for easier customization override
func (*DefaultCustomization) AppClosing ¶
func (customization *DefaultCustomization) AppClosing() error
AppClosing is to customize the application closing logic after server shutdown
func (*DefaultCustomization) CaCertPool ¶
func (customization *DefaultCustomization) CaCertPool() *x509.CertPool
CaCertPool is to customize the CA cert pool for incoming client certificate validation; if not set or nil, no validation is conducted for incoming client certificates
func (*DefaultCustomization) ClientCert ¶
func (customization *DefaultCustomization) ClientCert() *tls.Certificate
ClientCert is to customize the client certificate for external requests; if not set or nil, no client certificate is sent to external web services
func (*DefaultCustomization) DefaultTimeout ¶
func (customization *DefaultCustomization) DefaultTimeout() time.Duration
DefaultTimeout is to customize the default timeout for any webcall communications through HTTP/HTTPS by session
func (*DefaultCustomization) GraceShutdownWaitTime ¶
func (customization *DefaultCustomization) GraceShutdownWaitTime() time.Duration
GraceShutdownWaitTime is to customize the graceful shutdown wait time for the application
func (*DefaultCustomization) InstrumentRouter ¶
func (customization *DefaultCustomization) InstrumentRouter(router *mux.Router) *mux.Router
InstrumentRouter is to customize the instrumentation on top of a fully configured router; usually useful for 3rd party monitoring tools such as new relic, etc.
func (*DefaultCustomization) InterpretError ¶
func (customization *DefaultCustomization) InterpretError(err error) (int, string)
InterpretError is to customize how application interpret an error into HTTP status code and corresponding status message
func (*DefaultCustomization) InterpretSuccess ¶
func (customization *DefaultCustomization) InterpretSuccess(responseContent interface{}) (int, string)
InterpretSuccess is to customize how application interpret a response content into HTTP status code and corresponding response body
func (*DefaultCustomization) Listener ¶ added in v1.2.3
func (customization *DefaultCustomization) Listener() net.Listener
Listener is to customize the override of net.Listener to be used by http.Serve and http.ServeTLS; usually useful with UDS connections for local web server
func (*DefaultCustomization) Log ¶
func (customization *DefaultCustomization) Log(session Session, logType LogType, logLevel LogLevel, category, subcategory, description string)
Log is to customize the logging backend for the whole application
func (*DefaultCustomization) MethodNotAllowedHandler ¶
func (customization *DefaultCustomization) MethodNotAllowedHandler() http.Handler
MethodNotAllowedHandler is to customize the handler to be used when the request method does not match the route
func (*DefaultCustomization) Middlewares ¶
func (customization *DefaultCustomization) Middlewares() []MiddlewareFunc
Middlewares is to customize the middlewares registration
func (*DefaultCustomization) NotFoundHandler ¶
func (customization *DefaultCustomization) NotFoundHandler() http.Handler
NotFoundHandler is to customize the handler to be used when no route matches.
func (*DefaultCustomization) PostAction ¶
func (customization *DefaultCustomization) PostAction(session Session) error
PostAction is to customize the post-action used after each route action takes place, e.g. finalization, etc.
func (*DefaultCustomization) PostBootstrap ¶
func (customization *DefaultCustomization) PostBootstrap() error
PostBootstrap is to customize the post-processing logic after bootstrapping
func (*DefaultCustomization) PreAction ¶
func (customization *DefaultCustomization) PreAction(session Session) error
PreAction is to customize the pre-action used before each route action takes place, e.g. authorization, etc.
func (*DefaultCustomization) PreBootstrap ¶
func (customization *DefaultCustomization) PreBootstrap() error
PreBootstrap is to customize the pre-processing logic before bootstrapping
func (*DefaultCustomization) RecoverPanic ¶
func (customization *DefaultCustomization) RecoverPanic(session Session, recoverResult interface{}) (interface{}, error)
RecoverPanic is to customize the recovery of panic into a valid response and error in case it happens (for recoverable panic only)
func (*DefaultCustomization) RoundTripper ¶
func (customization *DefaultCustomization) RoundTripper(originalTransport http.RoundTripper) http.RoundTripper
RoundTripper is to customize the creation of the HTTP transport for any webcall communications through HTTP/HTTPS by session
func (*DefaultCustomization) Routes ¶
func (customization *DefaultCustomization) Routes() []Route
Routes is to customize the routes registration
func (*DefaultCustomization) ServerCert ¶
func (customization *DefaultCustomization) ServerCert() *tls.Certificate
ServerCert is to customize the server certificate for application; also determines the server hosting security option (HTTP v.s. HTTPS)
func (*DefaultCustomization) SkipServerCertVerification ¶
func (customization *DefaultCustomization) SkipServerCertVerification() bool
SkipServerCertVerification is to customize the skip of server certificate verification for any webcall communications through HTTP/HTTPS by session
func (*DefaultCustomization) Statics ¶
func (customization *DefaultCustomization) Statics() []Static
Statics is to customize the static contents registration
func (*DefaultCustomization) WrapHandler ¶ added in v1.1.3
func (customization *DefaultCustomization) WrapHandler(handler http.Handler) http.Handler
WrapHandler is to customize the overall wrapping of http.Handler before the server is configured
func (*DefaultCustomization) WrapRequest ¶
func (customization *DefaultCustomization) WrapRequest(session Session, httpRequest *http.Request) *http.Request
WrapRequest is to customize the creation of the HTTP request for any webcall communications through HTTP/HTTPS by session; utilize this method if needed for new relic wrapping, etc.
type HandlerCustomization ¶
type HandlerCustomization interface { // PreAction is to customize the pre-action used before each route action takes place, e.g. authorization, etc. PreAction(session Session) error // PostAction is to customize the post-action used after each route action takes place, e.g. finalization, etc. PostAction(session Session) error // InterpretSuccess is to customize how application interpret a response content into HTTP status code and corresponding response body InterpretSuccess(responseContent interface{}) (int, string) // InterpretError is to customize how application interpret an error into HTTP status code and corresponding response body InterpretError(err error) (int, string) // RecoverPanic is to customize the recovery of panic into a valid response and error in case it happens (for recoverable panic only) RecoverPanic(session Session, recoverResult interface{}) (interface{}, error) // NotFoundHandler is to customize the handler to be used when no route matches. NotFoundHandler() http.Handler // MethodNotAllowed is to customize the handler to be used when the request method does not match the route MethodNotAllowedHandler() http.Handler }
HandlerCustomization holds customization methods related to handlers
type HostingCustomization ¶
type HostingCustomization interface { // ServerCert is to customize the server certificate for application; also determines the server hosting security option (HTTP v.s. HTTPS) ServerCert() *tls.Certificate // CaCertPool is to customize the CA cert pool for incoming client certificate validation; if not set or nil, no validation is conducted for incoming client certificates CaCertPool() *x509.CertPool // GraceShutdownWaitTime is to customize the graceful shutdown wait time for the application GraceShutdownWaitTime() time.Duration // Routes is to customize the routes registration Routes() []Route // Statics is to customize the static contents registration Statics() []Static // Middlewares is to customize the middlewares registration Middlewares() []MiddlewareFunc // InstrumentRouter is to customize the instrumentation on top of a fully configured router; usually useful for 3rd party monitoring tools such as new relic, etc. InstrumentRouter(router *mux.Router) *mux.Router // WrapHandler is to customize the overall wrapping of http.Handler before the server is configured WrapHandler(handler http.Handler) http.Handler // Listener is to customize the override of net.Listener to be used by http.Serve and http.ServeTLS; usually useful with UDS connections for local web server Listener() net.Listener }
HostingCustomization holds customization methods related to hosting
type LogLevel ¶
type LogLevel int
LogLevel is the severity level of logging
These are the enum definitions of log types and presets
func NewLogLevel ¶
NewLogLevel converts a string representation of LogLevel flag to its strongly typed instance
type LogType ¶
type LogType int
LogType is the entry type of logging
const ( LogTypeEndpointEnter LogType = 1 << iota LogTypeEndpointRequest LogTypeMethodEnter LogTypeMethodParameter LogTypeMethodLogic LogTypeWebcallStart LogTypeWebcallRequest LogTypeWebcallResponse LogTypeWebcallFinish LogTypeMethodReturn LogTypeMethodExit LogTypeEndpointResponse LogTypeEndpointExit LogTypeBasicTracing LogType = LogTypeMethodLogic LogTypeGeneralTracing LogType = LogTypeBasicTracing | LogTypeEndpointEnter | LogTypeEndpointExit LogTypeVerboseTracing LogType = LogTypeGeneralTracing | LogTypeWebcallStart | LogTypeWebcallFinish LogTypeFullTracing LogType = LogTypeVerboseTracing | LogTypeMethodEnter | LogTypeMethodExit LogTypeBasicDebugging LogType = LogTypeMethodLogic LogTypeGeneralDebugging LogType = LogTypeBasicDebugging | LogTypeEndpointRequest | LogTypeEndpointResponse LogTypeVerboseDebugging LogType = LogTypeGeneralDebugging | LogTypeWebcallRequest | LogTypeWebcallResponse LogTypeFullDebugging LogType = LogTypeVerboseDebugging | LogTypeMethodParameter | LogTypeMethodReturn LogTypeBasicLogging LogType = LogTypeBasicTracing | LogTypeBasicDebugging LogTypeGeneralLogging LogType = LogTypeBasicLogging | LogTypeGeneralTracing | LogTypeGeneralDebugging LogTypeVerboseLogging LogType = LogTypeGeneralLogging | LogTypeVerboseTracing | LogTypeVerboseDebugging LogTypeFullLogging LogType = LogTypeVerboseLogging | LogTypeFullTracing | LogTypeFullDebugging LogTypeAppRoot LogType = 0 )
These are the enum definitions of log types and presets
func NewLogType ¶
NewLogType converts a string representation of LogType flag to its strongly typed instance
type LoggingCustomization ¶
type LoggingCustomization interface { // Log is to customize the logging backend for the whole application Log(session Session, logType LogType, logLevel LogLevel, category, subcategory, description string) }
LoggingCustomization holds customization methods related to logging
type MiddlewareFunc ¶
type MiddlewareFunc mux.MiddlewareFunc
MiddlewareFunc warps around mux.MiddlewareFunc, which receives an http.Handler and returns another http.Handler. Typically, the returned handler is a closure which does something with the http.ResponseWriter and http.Request passed to it, and then calls the handler passed as parameter to the MiddlewareFunc.
type ParameterType ¶
type ParameterType string
ParameterType defines the type specification of a route parameter
const ( ParameterTypeAnything ParameterType = `.*` ParameterTypeString ParameterType = `\w+` ParameterTypeInteger ParameterType = `\d+` ParameterTypeUUID ParameterType = `[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}` ParameterTypeDate ParameterType = `\d{4}-\d{2}-\d{2}` ParameterTypeTime ParameterType = `\d{2}:\d{2}:\d{2}(?:\.\d+)?` ParameterTypeDateTime ParameterType = ParameterTypeDate + `T` + ParameterTypeTime + `(?:Z|[+-]\d{2}:\d{2})` ParameterTypeBoolean ParameterType = `(?i)(?:true|false)` ParameterTypeFloat ParameterType = `\d+(?:\.\d+)?` )
These are constants for parameter types and their corresponding replacement RegExp statements
type Route ¶
type Route struct { Endpoint string Method string Path string Parameters map[string]ParameterType Queries map[string]ParameterType ActionFunc ActionFunc }
Route holds the registration information of a dynamic route hosting
type Session ¶
type Session interface { SessionMeta SessionHTTP SessionAttachment SessionLogging SessionWebcall }
Session is the storage for the current HTTP request session, containing information needed for logging, monitoring, etc.
type SessionAttachment ¶
type SessionAttachment interface { // Attach attaches any value object into the given session associated to the session ID Attach(name string, value interface{}) bool // Detach detaches any value object from the given session associated to the session ID Detach(name string) bool // GetRawAttachment retrieves any value object from the given session associated to the session ID and returns the raw interface (consumer needs to manually cast, but works for struct with private fields) GetRawAttachment(name string) (interface{}, bool) // GetAttachment retrieves any value object from the given session associated to the session ID and unmarshals the content to given data template (only works for structs with exported fields) GetAttachment(name string, dataTemplate interface{}) bool }
SessionAttachment is a subset of Session interface, containing only attachment related methods
type SessionHTTP ¶
type SessionHTTP interface { SessionHTTPRequest SessionHTTPResponse }
SessionHTTP is a subset of Session interface, containing only HTTP request & response related methods
type SessionHTTPRequest ¶
type SessionHTTPRequest interface { // GetRequest returns the HTTP request object from session object for given session ID GetRequest() *http.Request // GetRequestBody loads HTTP request body associated to session and unmarshals the content JSON to given data template GetRequestBody(dataTemplate interface{}) error // GetRequestParameter loads HTTP request parameter associated to session for given name and unmarshals the content to given data template GetRequestParameter(name string, dataTemplate interface{}) error // GetRequestQuery loads HTTP request single query string associated to session for given name and unmarshals the content to given data template GetRequestQuery(name string, index int, dataTemplate interface{}) error // GetRequestHeader loads HTTP request single header string associated to session for given name and unmarshals the content to given data template GetRequestHeader(name string, index int, dataTemplate interface{}) error }
SessionHTTPRequest is a subset of Session interface, containing only HTTP request related methods
type SessionHTTPResponse ¶
type SessionHTTPResponse interface { // GetResponseWriter returns the HTTP response writer object from session object for given session ID GetResponseWriter() http.ResponseWriter }
SessionHTTPResponse is a subset of SessionHTTP interface, containing only HTTP response related methods
type SessionLogging ¶
type SessionLogging interface { // LogMethodEnter sends a logging entry of MethodEnter log type for the given session associated to the session ID LogMethodEnter() // LogMethodParameter sends a logging entry of MethodParameter log type for the given session associated to the session ID LogMethodParameter(parameters ...interface{}) // LogMethodLogic sends a logging entry of MethodLogic log type for the given session associated to the session ID LogMethodLogic(logLevel LogLevel, category string, subcategory string, messageFormat string, parameters ...interface{}) // LogMethodReturn sends a logging entry of MethodReturn log type for the given session associated to the session ID LogMethodReturn(returns ...interface{}) // LogMethodExit sends a logging entry of MethodExit log type for the given session associated to the session ID LogMethodExit() }
SessionLogging is a subset of Session interface, containing only logging related methods
type SessionMeta ¶
type SessionMeta interface { // GetID returns the ID of this registered session object GetID() uuid.UUID // GetName returns the name registered to session object for given session ID GetName() string }
SessionMeta is a subset of Session interface, containing only meta data related methods
type SessionWebcall ¶
type SessionWebcall interface { // CreateWebcallRequest generates a webcall request object to the targeted external web service for the given session associated to the session ID CreateWebcallRequest(method string, url string, payload string, sendClientCert bool) WebRequest }
SessionWebcall is a subset of Session interface, containing only webcall related methods
type WebRequest ¶
type WebRequest interface { // AddQuery adds a query to the request URL for sending through HTTP AddQuery(name string, value string) WebRequest // AddHeader adds a header to the request Header for sending through HTTP AddHeader(name string, value string) WebRequest // SetupRetry sets up automatic retry upon error of specific HTTP status codes; each entry maps an HTTP status code to how many times retry should happen if code matches SetupRetry(connectivityRetryCount int, httpStatusRetryCount map[int]int, retryDelay time.Duration) WebRequest // Anticipate registers a data template to be deserialized to when the given range of HTTP status codes are returned during the processing of the web request; latter registration overrides former when overlapping Anticipate(beginStatusCode int, endStatusCode int, dataTemplate interface{}) WebRequest // Process sends the webcall request over the wire, retrieves and serialize the response to registered data templates, and returns status code, header and error accordingly Process() (statusCode int, responseHeader http.Header, responseError error) }
WebRequest is an interface for easy operating on webcall requests and responses
type WebRequestCustomization ¶
type WebRequestCustomization interface { // ClientCert is to customize the client certificate for external requests; if not set or nil, no client certificate is sent to external web services ClientCert() *tls.Certificate // DefaultTimeout is to customize the default timeout for any webcall communications through HTTP/HTTPS by session DefaultTimeout() time.Duration // SkipServerCertVerification is to customize the skip of server certificate verification for any webcall communications through HTTP/HTTPS by session SkipServerCertVerification() bool // RoundTripper is to customize the creation of the HTTP transport for any webcall communications through HTTP/HTTPS by session RoundTripper(originalTransport http.RoundTripper) http.RoundTripper // WrapRequest is to customize the creation of the HTTP request for any webcall communications through HTTP/HTTPS by session; utilize this method if needed for new relic wrapping, etc. WrapRequest(session Session, httpRequest *http.Request) *http.Request }
WebRequestCustomization holds customization methods related to web requests
Source Files ¶
- 0_functionPointers.go
- actionFunc.go
- appError.go
- application.go
- customization.go
- errorCode.go
- handler.go
- jsonutil.go
- logLevel.go
- logType.go
- logger.go
- middlewareFunc.go
- nilResponseWriter.go
- panic.go
- parameter.go
- pointerutil.go
- register.go
- request.go
- response.go
- route.go
- server.go
- session.go
- static.go
- timeutil.go
- webRequest.go