README
¶
Buv Web Server
Table of Contents
- What Is Buv?
- Features
- How To
- License
What Is Buv? (Baby Don't Hurt Me!)
Buv is a configurable web server designed to abstract away the mechanics of serving HTTP and AJAX requests while allowing client code to still be able to have full support for standard web features. These features are manifested in Buv by the gorilla web toolkit.
Features
Buv is configurable to allow clients to:
- Specify port and domain to service
- Use gorilla-mux-style pattern matching to designate request handlers based on:
- Schemes
- URI
- HTTP method
- Queries
- A parent's patterns
- Register handlers guarded by redirecting functions
- Create, rotate, and configure secure cookies
- Specify secure cookie lifetimes & whether to only modify cookies over HTTP
- Save Buv's configuration to file for easier instantiation
- Specify a default handler for nonexistant resources
- Register template files for handler use
- Notifies client if not all correct template dependencies are added (no manual testing of every template needed)
- Drop favicon.ico at the root
- Designate special folders to serve assets from
- Gracefully terminate open connections upon shutdown
The handler-specific benefits include:
- Web logging services
- Session value setting, retrieving, and erasing
- Session flash setting and retrieving
- HTTP method of the request
- Manual redirection to another URI with an HTTP status code
- Access to the URL of the request
- Any query and post values of the request
- Render templates that are registered with the server
- Fetch another valid URL for another URI
How To
Todo!
License
This work is released under the GNU's Lesser General Public License version 3 (LGPLv3).
Please see the Copying and Copying.Lesser files for the license body.
Documentation
¶
Overview ¶
Buv is a web server dedicated to being a slave to Web 2.0, serving up web pages, parsing templates and providing a logger to client handling code. It allows a client to specify gorilla-style mux's to specific handlers, and exposes the gorilla session interface to handlers using secure cookies. Furthermore, redirection code can be specified separately from handler code, keeping content-delivery interests orthogonal to authentication-authorization-access interests.
Buv is a web server dedicated to being a slave to Web 2.0, serving up web pages, parsing templates and providing a logger to client handling code. It allows a client to specify gorilla-style mux's to specific handlers, and exposes the gorilla session interface to handlers using secure cookies. Furthermore, redirection code can be specified separately from handler code, keeping content-delivery interests orthogonal to authentication-authorization-access interests.
Index ¶
- Constants
- type HandlerData
- func (h *HandlerData) GetBoolSessionValue(sessionName, key string) bool
- func (h *HandlerData) GetFirstStringFlashMessage(sessionName, flashKey string) string
- func (h *HandlerData) GetSessionValue(sessionName, key string) interface{}
- func (h *HandlerData) GetStringFlashMessages(sessionName, flashKey string) []string
- func (h *HandlerData) GetStringSessionValue(sessionName, key string) string
- func (h *HandlerData) GetUrl(URLName string, pathVars map[string]string) *url.URL
- func (h *HandlerData) HasBoolSessionValue(sessionName, key string) bool
- func (h *HandlerData) HasSessionValue(sessionName, key string) bool
- func (h *HandlerData) HasStringSessionValue(sessionName, key string) bool
- func (h *HandlerData) IsConnectMethod() bool
- func (h *HandlerData) IsDeleteMethod() bool
- func (h *HandlerData) IsGetMethod() bool
- func (h *HandlerData) IsHeadMethod() bool
- func (h *HandlerData) IsOptionsMethod() bool
- func (h *HandlerData) IsPostMethod() bool
- func (h *HandlerData) IsPutMethod() bool
- func (h *HandlerData) IsTraceMethod() bool
- func (h *HandlerData) Method() string
- func (h *HandlerData) PostForm() url.Values
- func (h *HandlerData) PostFormValue(key string) string
- func (h *HandlerData) Println(logString string)
- func (h *HandlerData) Query() url.Values
- func (h *HandlerData) Redirect(newURI string, code int)
- func (h *HandlerData) Referrer() string
- func (h *HandlerData) RemoveSessionValue(sessionName, key string)
- func (h *HandlerData) RenderTemplate(templateName string, templateData interface{})
- func (h *HandlerData) SetFlashMessage(sessionName, message, flashKey string)
- func (h *HandlerData) SetSessionValue(sessionName, key string, value interface{})
- func (h *HandlerData) String() string
- func (h *HandlerData) URL() *url.URL
- func (h *HandlerData) WriteResponse(response string)
- type HandlerFunction
- type Redirector
- type Server
- func (b *Server) AddHandleFunc(schemes []string, path, URLName string, handleFunc HandlerFunction, ...)
- func (b *Server) Domain(domain, URLName string)
- func (b *Server) GetBoolSessionValue(request *http.Request, sessionName string, key string) bool
- func (b *Server) GetFirstStringFlashMessage(writer http.ResponseWriter, request *http.Request, ...) string
- func (b *Server) GetSessionValue(request *http.Request, sessionName string, key string) interface{}
- func (b *Server) GetStringFlashMessages(writer http.ResponseWriter, request *http.Request, ...) []string
- func (b *Server) GetStringSessionValue(request *http.Request, sessionName string, key string) string
- func (b *Server) GetUrl(URLName string, pathVars map[string]string) *url.URL
- func (b *Server) HasBoolSessionValue(request *http.Request, sessionName string, key string) bool
- func (b *Server) HasSessionValue(request *http.Request, sessionName string, key string) bool
- func (b *Server) HasStringSessionValue(request *http.Request, sessionName string, key string) bool
- func (b *Server) Localhost(URLName string)
- func (b *Server) NotFoundHandler(noHandler HandlerFunction)
- func (b *Server) Println(logString string)
- func (b *Server) RemoveSessionValue(writer http.ResponseWriter, request *http.Request, sessionName, key string)
- func (b *Server) RenderTemplate(w http.ResponseWriter, tmpl string, p interface{})
- func (b *Server) SaveConfigFile(options *ServerOptions) error
- func (b *Server) SetFlashMessage(writer http.ResponseWriter, request *http.Request, ...)
- func (b *Server) SetSessionValue(writer http.ResponseWriter, request *http.Request, sessionName, key string, ...)
- func (b *Server) Shutdown()
- func (b *Server) Start(address string, assetFolderToExtension map[string]string) error
- type ServerOptions
Constants ¶
const ( HTTP_METHOD_GET = "GET" HTTP_METHOD_POST = "POST" HTTP_METHOD_PUT = "PUT" HTTP_METHOD_CONNECT = "CONNECT" HTTP_METHOD_TRACE = "TRACE" HTTP_METHOD_DELETE = "DELETE" HTTP_METHOD_HEAD = "HEAD" HTTP_METHOD_OPTIONS = "OPTIONS" HTTP_SCHEME = "http" HTTPS_SCHEME = "https" LOCALHOST_SCHEME = "" )
const ( LOG_PRINTLN = 0 LOG_FATAL = 1 )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type HandlerData ¶
type HandlerData struct {
// contains filtered or unexported fields
}
func (*HandlerData) GetBoolSessionValue ¶
func (h *HandlerData) GetBoolSessionValue(sessionName, key string) bool
func (*HandlerData) GetFirstStringFlashMessage ¶
func (h *HandlerData) GetFirstStringFlashMessage(sessionName, flashKey string) string
func (*HandlerData) GetSessionValue ¶
func (h *HandlerData) GetSessionValue(sessionName, key string) interface{}
func (*HandlerData) GetStringFlashMessages ¶
func (h *HandlerData) GetStringFlashMessages(sessionName, flashKey string) []string
func (*HandlerData) GetStringSessionValue ¶
func (h *HandlerData) GetStringSessionValue(sessionName, key string) string
func (*HandlerData) HasBoolSessionValue ¶
func (h *HandlerData) HasBoolSessionValue(sessionName, key string) bool
func (*HandlerData) HasSessionValue ¶
func (h *HandlerData) HasSessionValue(sessionName, key string) bool
func (*HandlerData) HasStringSessionValue ¶
func (h *HandlerData) HasStringSessionValue(sessionName, key string) bool
func (*HandlerData) IsConnectMethod ¶
func (h *HandlerData) IsConnectMethod() bool
func (*HandlerData) IsDeleteMethod ¶
func (h *HandlerData) IsDeleteMethod() bool
func (*HandlerData) IsGetMethod ¶
func (h *HandlerData) IsGetMethod() bool
func (*HandlerData) IsHeadMethod ¶
func (h *HandlerData) IsHeadMethod() bool
func (*HandlerData) IsOptionsMethod ¶
func (h *HandlerData) IsOptionsMethod() bool
func (*HandlerData) IsPostMethod ¶
func (h *HandlerData) IsPostMethod() bool
func (*HandlerData) IsPutMethod ¶
func (h *HandlerData) IsPutMethod() bool
func (*HandlerData) IsTraceMethod ¶
func (h *HandlerData) IsTraceMethod() bool
func (*HandlerData) Method ¶
func (h *HandlerData) Method() string
func (*HandlerData) PostForm ¶
func (h *HandlerData) PostForm() url.Values
func (*HandlerData) PostFormValue ¶
func (h *HandlerData) PostFormValue(key string) string
func (*HandlerData) Println ¶
func (h *HandlerData) Println(logString string)
func (*HandlerData) Query ¶
func (h *HandlerData) Query() url.Values
func (*HandlerData) Redirect ¶
func (h *HandlerData) Redirect(newURI string, code int)
func (*HandlerData) Referrer ¶
func (h *HandlerData) Referrer() string
func (*HandlerData) RemoveSessionValue ¶
func (h *HandlerData) RemoveSessionValue(sessionName, key string)
func (*HandlerData) RenderTemplate ¶
func (h *HandlerData) RenderTemplate(templateName string, templateData interface{})
func (*HandlerData) SetFlashMessage ¶
func (h *HandlerData) SetFlashMessage(sessionName, message, flashKey string)
func (*HandlerData) SetSessionValue ¶
func (h *HandlerData) SetSessionValue(sessionName, key string, value interface{})
func (*HandlerData) String ¶
func (h *HandlerData) String() string
func (*HandlerData) URL ¶
func (h *HandlerData) URL() *url.URL
func (*HandlerData) WriteResponse ¶
func (h *HandlerData) WriteResponse(response string)
type HandlerFunction ¶
type HandlerFunction func(data *HandlerData)
HandlerFunction is the function clients must use when handling requests. It provides access to the specific request's HandlerData, through which handler functions can operate.
type Redirector ¶
type Redirector func(data *HandlerData) bool
Redirector is a function clients can use to cause a request to be redirected. Upon successful redirection, true must be returned to prevent the default handler from being called.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is a http server that is able to gracefully start and terminate TCP-over-IP connections as it starts up and shuts down. In brief it handles:
- Template execution & template dependencies
- One-Log-File-A-Day Logging
- Rich mux mapping to client handlers, guarded by redirectors
- Mapping a path to a filetype to serve up specific assets
- Constructing data-driven URLs
- Handling session values and flash messages
- New, re-used, or rotated secure cookie keys
A Server does not directly interact with the handlers, instead it exposes a limited subset of its interface through a HandlerData that contains additional request information beyond what the sole Server provides.
func NewServer ¶
func NewServer(options *ServerOptions) (w *Server, e error)
NewServer creates a new web Server from the specified options. It returns a non-nil error if a failure in creation occurs.
func NewServerFromConfig ¶
NewServerFromConfig creates a new Server from a JSON file representing a ServerOptions struct. It returns a non-nil error if a failure occurs.
func (*Server) AddHandleFunc ¶
func (b *Server) AddHandleFunc(schemes []string, path, URLName string, handleFunc HandlerFunction, redirectors []Redirector, methods []string, queries map[string]string, URLParent string)
AddHandleFunc adds a handler function to the web server. -schemes The request schemes to support by the handler (eg "http", "https", or in the case of localhost, ""). -path The URI/URA to handle. -URLName A unique name to call the URL so it can be reconstructed later if desired. -handleFunc The handler function for the specified URI/URA by the path. -redirectors A list of functions that act before the handling function & act as a gateway before calling the handler. The
handler is not called if one of the redirectors redirects.
-methods The HTTP methods to handle (eg "GET", "POST", etc). -queries Optional: Any queries that must be present in order to handle. The map keys are the query keys and the map
values are specific values (A value of "" matches any value).
-URLParent Optional: If specified, the subrouter based on the parent URI/URA is used and therefore this match will only
be attempted if the parent also matches.
func (*Server) GetBoolSessionValue ¶
func (*Server) GetFirstStringFlashMessage ¶
func (*Server) GetSessionValue ¶
func (*Server) GetStringFlashMessages ¶
func (*Server) GetStringSessionValue ¶
func (*Server) HasBoolSessionValue ¶
func (*Server) HasSessionValue ¶
func (*Server) HasStringSessionValue ¶
func (*Server) NotFoundHandler ¶
func (b *Server) NotFoundHandler(noHandler HandlerFunction)
func (*Server) RemoveSessionValue ¶
func (*Server) RenderTemplate ¶
func (b *Server) RenderTemplate(w http.ResponseWriter, tmpl string, p interface{})
func (*Server) SaveConfigFile ¶
func (b *Server) SaveConfigFile(options *ServerOptions) error
func (*Server) SetFlashMessage ¶
func (*Server) SetSessionValue ¶
type ServerOptions ¶
type ServerOptions struct {
// FileLog is the root name of the file to log to. A timestamp and file suffix
// will be applied to the name.
FileLog string
// DirectoryLog is the path where logging files will be placed and must be terminated
// by the directory separator character ('/' for unix-based systems, '\' for others)
DirectoryLog string
// FilePermissions specifies the logging file permissions when new files are created.
// It is suggested to set up proper permissions and ownerships and use a different
// value than the very permissible 0666, such as 0644, to prevent abuse.
FilePermissions os.FileMode
// DirectoryPermissions specifies the logging directory permissions if the path is
// created and does not already exist. It is suggested to set up proper permissions
// and ownerships if necessary to prevent abuse.
DirectoryPermissions os.FileMode
// AuthenticationKeySize determines the strength of the authentication key used in the session
// cookie store. It must be 32 or 64. Only used if the GenerateKeys field is true.
AuthenticationKeySize int
// EncryptionKeySize determines the strength of the encryption key used in the session cookie
// store. It must be 16, 24, or 32 bytes for AES-128, AES-192, or AES-256 modes. Only used if
// the GenerateKeys field is true.
EncryptionKeySize int
// The path of the cookie -- determines which paths in the domain to send the cookies
// along with. "/" would specify for all paths in the host domain.
CookiePath string
// The maximum age of the cookie before expiration, in seconds.
MaxAge int
// Whether the cookie is modifiable only through HTTP requests (recommended value: true).
HttpOnly bool
// Whether to use the AuthenticationKeySize & EncryptionKeySize fields in the ServerOptions
// to automatically generate new keys. If false, uses the KeyPairs field for the cookie store.
GenerateKeys bool
// Alternating Authentication and Encryption keys to use if they are not being generated for
// the cookie store. Only used if the GenerateKeys field is false.
KeyPairs [][]byte
// The name of the config file to save these options to, if specified, so a server can be
// constructed using NewServerFromConfig. A value of "" will not save a copy of these options.
ConfigFile string
// The path to the directory containing the template files
TemplatePath string
// The extension used by the template files
TemplateExtension string
}
BuvServerOptions is a structure for defining the parameters used when creating a new BuvServer.
Source Files