README
¶
bjorno
Bjorno is a recursive HTTP web server. It can be used with hugo and themes like docsy to add dynamic data to your website at runtime.
Bjorno serves static content, and also offers the following features.
- Easy way to build custom routes/endpoints on top of static content.
- Easy way to interpolate static content at runtime.
Using bjorno
You can build a custom application in Go and vendor bjorno directly into your program.
sample/index.html
<html>
<head>
<title>{{ .Name }}</title>
</head>
<body>
<div align="center">
<h2>Welcome to {{ .Name }}</h2>
<p>My nickname is {{ .Nickname }}</p>
</div>
</body>
</html>
main.go
Build a file and define the webserver components as well as the runtime program components.
package main
import (
"sync"
bjorno "github.com/kris-nova/bjorno"
)
func main() {
cfg := &bjorno.ServerConfig{
InterpolateExtensions: []string{
".html",
},
BindAddress: ":1313",
ServeDirectory: "sample/",
DefaultIndexFiles: []string{
"index.html",
},
}
bjorno.Runtime(cfg, &BjornoProgram{
Name: "Björn",
Nickname: "Pupperscotch",
})
}
type BjornoProgram struct {
Name string
Nickname string
mutex sync.Mutex
}
func (v *BjornoProgram) Values() interface{} {
return v
}
func (v *BjornoProgram) Refresh() {
v.Nickname = "butterscotch"
v.Name = "björn"
}
func (v *BjornoProgram) Lock() {
v.mutex.Lock()
}
func (v *BjornoProgram) Unlock() {
v.mutex.Unlock()
}
Run your web application
go run main.go
Now open your browser to localhost:1313 and you will see your values interpolated on the webpage.
Simply change your program to do what you need it to do.
Whatever .Values() returns in your program will be interpolated according to text/template.
Documentation
¶
Index ¶
- Constants
- func FileDirectoryPath(defaultFiles []string, requestPath string, httpDir http.Dir) (http.File, os.FileInfo, error)
- func RequestPath(r *http.Request) string
- func Runtime(cfg *ServerConfig, V RuntimeProgram) error
- type EmptyProgram
- type Endpoint
- type RootHandler
- type RuntimeProgram
- type ServerConfig
Constants ¶
const ( StatusDefault404 string = `404 not found (bjorno)` StatusDefault500 string = `500 server error (bjorno)` StatusDefault5XX string = `5xx server error (bjorno)` EndpointRoot string = "/" // DefaultCacheMaxAgeSeconds // // Default: 1 year // // https://web.dev/uses-long-cache-ttl/?utm_source=lighthouse&utm_medium=devtools DefaultCacheMaxAgeSeconds int = 31536000 )
Variables ¶
This section is empty.
Functions ¶
func FileDirectoryPath ¶
func FileDirectoryPath(defaultFiles []string, requestPath string, httpDir http.Dir) (http.File, os.FileInfo, error)
FileDirectoryPath will take a set of default file strings, a request path, and a valid http.Dir and handles the logic for checking the filesystem for default files in directories such as index.html
This will only return a file and stat if the file calculated actually exists.
func RequestPath ¶
RequestPath is a deterministic function that given an *http.Request will always return a request path to "search" for.
Note: this will *NOT* check an inode for a directory (isDir()) but will trust the request to identify a directory by POSIX convention.
If the path ends with "/" it's a directory...
func Runtime ¶
func Runtime(cfg *ServerConfig, V RuntimeProgram) error
Runtime is exactly what you think it is. This is the runtime component of Bjorno and is most likely the place everything will go wrong.
Here we have a stateless "Runtime" paradigm which means we NEVER want a .DoThing() workflow on Bjorno.
You are either running Bjorno as a web server, or you are using Bjorno incorrectly.
Here be dragons. Ye be warned.
cfg *ServerConfig web server configuration for runtime serving. V RuntimeProgram the top level runtime program to interpolate with.
Note that V will have an extremely specific paradigm behind it. and by design we expect V to change at runtime. Bjorno *should be resilient enough to support a chaotic V.
In other words, V should never break Bjorno. So have fun.
Types ¶
type EmptyProgram ¶
type EmptyProgram struct {
// contains filtered or unexported fields
}
func (*EmptyProgram) Lock ¶
func (v *EmptyProgram) Lock()
func (*EmptyProgram) Refresh ¶
func (v *EmptyProgram) Refresh()
func (*EmptyProgram) Unlock ¶
func (v *EmptyProgram) Unlock()
func (*EmptyProgram) Values ¶
func (v *EmptyProgram) Values(req *http.Request) interface{}
type Endpoint ¶
Endpoint is just a plain old endpoint - feel free to add these for other services you might want to use.
type RootHandler ¶
type RootHandler struct {
Config *ServerConfig
HTTPDir http.Dir
V RuntimeProgram
}
RootHandler is a custom server that proxies whatever HTTPDir is set to to the / (root) of the HTTP(s) server.
func NewRootHandler ¶
func NewRootHandler(cfg *ServerConfig, V RuntimeProgram) *RootHandler
func (*RootHandler) ServeHTTP ¶
func (rh *RootHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP is the main root serve method
type RuntimeProgram ¶
type RuntimeProgram interface {
// Values is where you should put the things you want to be interpolated.
//
// This is the program itself that will be passed to template.Execute()
//
// Values is called for every HTTP request, so we pass that in.
// Even though Refresh() is called concurrently for caching
// reasons we still couple a Values() read with an HTTP request.
// This is a design decision, and is subject to be a poor one.
Values(request *http.Request) interface{}
// Refresh is called slightly before your program is referenced.
//
// We will lock this for you - all you need to do is write the code that
// will refresh whatever Values() returns. Probably just hitting a cache
// or a web service or database and saving the results in your programs
// cache.
Refresh()
// Lock should lock a mutex.
Lock()
// Unlock should unlock a mutext.
Unlock()
}
RuntimeProgram is the program that Bjorno will run to interpolate your web pages. Have fun with your programs and be safe kiddos!
type ServerConfig ¶
type ServerConfig struct {
// LogVerbosity is the verbosity for the krisnova.Logger
LogVerbosity int
// ServeDirectory is a local directory you are hoping to serve.
// Relative directories are supported.
ServeDirectory string //
// BindAddress configures where you would like your server to
// listen to.
BindAddress string // localhost:80
// InterpolateExtensions are the names
// of the interpolation file extensions
// to parse.
//
// Usually this is something like ".html"
InterpolateExtensions []string
// DefaultIndexFiles are the names of file
// to look for if a directory is passed.
//
// Usually this is something like "index.html".
DefaultIndexFiles []string
// UseDefaultRootHandler gives us an easy way
// to run the server in a more "concrete" and
// reliable way while we are in alpha dev stages.
UseDefaultRootHandler bool
// The Server can have custom global response content
// for specific HTTP Error codes
// These can be defined at runtime.
Content404 []byte
Content500 []byte
Content5XX []byte
// Endpoints is our endpoints we hope to use.
Endpoints []*Endpoint
}
ServerConfig is the WebServer configuration component of bjorno This struct holds all of the WebServer bits (pun intended).
We should only expose fields we would like a consumer of Bjorno to use.
Source Files
Directories