bjorno

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
  • func (v *EmptyProgram) Lock()
  • func (v *EmptyProgram) Refresh()
  • func (v *EmptyProgram) Unlock()
  • func (v *EmptyProgram) Values(req *http.Request) interface{}
• type Endpoint
• type RootHandler
  • func NewRootHandler(cfg *ServerConfig, V RuntimeProgram) *RootHandler
  • func (rh *RootHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• 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
)

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

func RequestPath(r *http.Request) string

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

type Endpoint struct {
	Pattern string
	Handler http.Handler
}

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.