sliderule

README

sliderule: The small web toolkit for Go

sliderule is the toolkit for working with the small web in Go.

 _____________________________________________________________
|  |"!"|"!"|"!"|"!"|"!"|"!"|"!"|"!"|"!"|"!"|"!"|"!"|"!"|"!"|  |
|  0   1   2   3   4   5   6   7   8   9  10  11  12  13   4  |
|---------------------------=====+=====-----------------------|
|___:981,:,!,,2::!:3n:4:5:6|7891:|:!:!2|:!.3:!:4!5:67891!:!___|mmm
    |   |891"!"|""2""|"3n|4|5"6|7891"!"|"|2""!"3"|"4|5"67891"!|   |
    |                      |     I     |                          |
 ___|___9:1:1c2:3:4:5:67892|::!::|3n:C:|4::!:5:::6::7::8:9:1:1c___|
|   9!1"1"2"3"4"5"67892"|"||""3n"|""4""|"5"!"6""7""8"9"1"1    |===
|__________________________|_____|__apx|______________________|
                            =====+=====

You still have to write your server, but you can focus on the logic you want to implement knowing the protocol is already dealt with. It's been said of gemini that you can write your server in a day. Now you can write it in well under an hour.

The slide rule

sliderule is named after the iconic instrument used to perform approximate mathematical calculations before the advent of handheld electronic calculators. It was the predominant tool that identified an engineer during project Gemini, a sort of developer's tool of it's time.

The "sliderule" package

sliderule is carefully structured as composable building blocks. The top-level package defines the framework in which servers and clients can be built.

• a request type
• a response type
• a "Server" interface type
• a "Handler" abstraction
• a "Middleware" abstraction
• a "Client" implementation which wraps multiple protocol-specific clients and can handle URLs with a variety of schemes
• some useful Handler wrappers: a router, request filtering, falling through a list of handlers

Protocols

The packages sliderule/gemini, sliderule/gopher, sliderule/finger, and sliderule/spartan provide concrete implementations specific to those protocols.

• I/O (parsing, formatting) request and responses
• constructors for the various kinds of protocol responses
• helpers for building a protocol-suitable TLS config
• Client implementations
• Servers which can run your Handlers.

The primary text formats for those protocols have higher-level support provided in sub-packages:

• sliderule/gemini/gemtext supports parsing gemtext and getting direct programmatic access to its AST.
• sliderule/gopher/gophermap similarly parses the gophermap format and provides access to its AST.

Sub-packages in the text formats provide conversion functions to HTML, markdown, and Atom XML, using overridable templates.

Logging

sliderule borrows the logging interface from go-kit.

=> The logger interface from go-kit/log.

The sliderule/logging package provides everything you need to get a good basic start to producing helpful logs.

• A request-logging middleware with common diagnostics (time, duration, url, status codes, response body lengths)
• A simple constructor of useful default loggers at various levels. They output colorful logfmt lines to stdout.

Routing

The router in the sliderule package supports slash-delimited path pattern strings. In the segments of these patterns:

• A "/:wildcard/" segment matches anything in that position, and captures the value as a route parameter. Or if the paramter name is omitted like "/:/", it matches anything in a single segment without capturing a paramter.
• A "/remainder" segment is only allowed at the end and matches the rest of the path, capturing it into the paramter name. Or again, omitting a parameter name like "/" simple matches any path suffix.
• Any other segment in the pattern must match the corresponding segment of a request exactly.

Router also supports maintaining a list of middlewares at the router level, mounting sub-routers under a pattern, looking up the matching handler for any request, and of course acting as a Handler itself.

sliderule/contrib/*

This is where useful building blocks themselves start to come in. Sub-packages of contrib include Handler and Middleware implementations which accomplish the things your servers actually need to do.

The sub-packages include:

• fs has handlers that make file servers possible: serve files, build directory listings, etc
• cgi includes handlers which can execute CGI programs
• sharedhost which provides means of handling /~username URLs
• tlsauth contains middlewares and bool functions for authenticating against TLS client certificates
• ...with more to come

Tools

The tools directory contains main packages that implement useful cli tools for working with the small web. You can install them all at once with:

go install tildegit.org/tjp/sliderule/tools/...

They all have useful output when given the -h/--help flag.

Get it

Using sliderule in your project

To add it to your own go project:

$ go get tildegit.org/tjp/sliderule

Straight to the code please

=> The code is hosted here on tildegit.

=> The generated documentation is on the go package index.

Verify releases

Releases are signed with minisign. The signature file is included in the release downloads page, and the public key is RWSzQywJwHgjSMD0y0RXwXAGpapcMJplwbCVYQqabhAJ+NAnKAeh98Vb - this is also referenced on tjp's gemini home page.

=> tjp's home page, which also mentions the public key used for signing sliderule releases.

Previously

This project used to be called "gus", and the original project's old issues can be found at:

=> https://tildegit.org/tjp/gus

Contribute

There's lots still to do, and contributions are very welcome!

=> submit an issue or pull request on the tildegit repository,

=> send me an email directly,

or poke me on IRC: I'm @tjp on irc.tilde.chat where you'll find me in #gemini

Documentation

Index

• Constants
• Variables
• func RouteParams(ctx context.Context) map[string]string
• type Client
  • func NewClient(tlsConf *tls.Config) Client
  • func (c Client) Fetch(ctx context.Context, url string) (*Response, error)
  • func (c Client) RoundTrip(ctx context.Context, request *Request) (*Response, error)
  • func (c Client) Upload(ctx context.Context, url string, contents io.Reader) (*Response, error)
• type Handler
  • func FallthroughHandler(handlers ...Handler) Handler
  • func HandlerFunc(f func(context.Context, *Request) *Response) Handler
  • func VirtualHosts(hosts map[string]Handler, catchall Handler) Handler
• type Middleware
  • func Filter(condition func(context.Context, *Request) bool, failure Handler) Middleware
• type Request
• type Response
• type ResponseReader
• type Router
  • func (r Router) Handle(ctx context.Context, request *Request) *Response
  • func (r Router) Handler() Handler
  • func (r Router) Match(request *Request) (Handler, map[string]string)
  • func (r *Router) Mount(prefix string, subrouter *Router)
  • func (r *Router) Route(pattern string, handler Handler)
  • func (r *Router) Use(mw Middleware)
• type Server
• type ServerProtocol
• type Status

Constants

const DefaultMaxRedirects int = 5

Variables

var ExceededMaxRedirects = errors.New("Client: exceeded MaxRedirects")

var RouteParamsKey = routeParamsKeyType{}

Functions

func RouteParams

func RouteParams(ctx context.Context) map[string]string

RouteParams gathers captured path parameters from the request context.

If the context doesn't contain a parameter map, it returns nil. If Router was used but no parameters were captured in the pattern, it returns a non-nil empty map.

Types

type Client

type Client struct {
	MaxRedirects int
	// contains filtered or unexported fields
}

Client is a multi-protocol client which handles all protocols known to sliderule.

func NewClient

func NewClient(tlsConf *tls.Config) Client

NewClient builds a Client object.

tlsConf may be nil, in which case gemini requests connections will not be made with any client certificate.

func (Client) Fetch

func (c Client) Fetch(ctx context.Context, url string) (*Response, error)

Fetch collects a resource from a URL including following any redirects.

func (Client) RoundTrip

func (c Client) RoundTrip(ctx context.Context, request *Request) (*Response, error)

RoundTrip sends a single request and returns the repsonse.

If the response is a redirect it will be returned, rather than fetched.

func (Client) Upload

func (c Client) Upload(ctx context.Context, url string, contents io.Reader) (*Response, error)

Upload sends a request with a body and returns any redirect response.

type Handler

type Handler = types.Handler

func FallthroughHandler

func FallthroughHandler(handlers ...Handler) Handler

FallthroughHandler builds a handler which tries multiple child handlers.

The returned handler will invoke each of the passed-in handlers in order, stopping when it receives a non-nil response.

func HandlerFunc

func HandlerFunc(f func(context.Context, *Request) *Response) Handler

HandlerFunc is a wrapper to allow using a function as a Handler.

func VirtualHosts

func VirtualHosts(hosts map[string]Handler, catchall Handler) Handler

VirtualHosts builds a handler which dispatches to site handlers by hostname.

The 'catchall' argument may be used to specify a handler for use when no hostname match is found. If the catchall is nil and no match is found, the VirtualHosts handler returns a nil response.

type Middleware

type Middleware = types.Middleware

func Filter

func Filter(
	condition func(context.Context, *Request) bool,
	failure Handler,
) Middleware

Filter builds a middleware which only calls the wrapped Handler under a condition.

When the condition function returns false it instead invokes the test-failure handler. The failure handler may also be nil, in which case the final handler will return a nil response whenever the condition fails.

type Request

type Request = types.Request

type Response

type Response = types.Response

type ResponseReader

type ResponseReader = types.ResponseReader

type Router

type Router struct {
	// contains filtered or unexported fields
}

Router stores a mapping of request path patterns to handlers.

Pattern may begin with "/" and then contain slash-delimited segments.

• Segments containing a colon (:) are wildcards and will match any path segment at that location. It may optionally have a word after the colon, which will be the parameter name the path segment is captured into. It may also optionally have text before the colon, in which case the pattern will not match unless the request path segment contains that prefix.
• Segments beginning with asterisk (*) are remainder wildcards. This must come last and will capture any remainder of the path. It may have a name after the asterisk which will be the parameter name.
• Any other segment in the pattern must match a path segment exactly.

These patterns do not match any path which shares a prefix, rather then full path must match a pattern. If you want to only match a prefix of the path you can end the pattern with a *remainder segment.

The zero value is a usable Router which will fail to match any request path.

func (Router) Handle

func (r Router) Handle(ctx context.Context, request *Request) *Response

Handle implements Handler

If no route matches, Handle returns a nil response. Captured path parameters will be stored in the context passed into the handler and can be retrieved with RouteParams().

func (Router) Handler

func (r Router) Handler() Handler

Handler builds a Handler

It is only here for compatibility because Router implements Handler directly.

func (Router) Match

func (r Router) Match(request *Request) (Handler, map[string]string)

Match returns the matched handler and captured path parameters, or (nil, nil).

The returned handlers will be wrapped with any middleware attached to the router.

func (*Router) Mount

func (r *Router) Mount(prefix string, subrouter *Router)

Mount attaches a sub-router to handle path suffixes after an initial prefix pattern.

The prefix pattern may include segment :wildcards, but no *remainder segment. The mounted sub-router should have patterns which only include the portion of the path after whatever was matched by the prefix pattern.

The root pattern ("/") in the sub-router will become a route which may or may not end with a forward slash.

func (*Router) Route

func (r *Router) Route(pattern string, handler Handler)

Route adds a handler to the router under a path pattern.

func (*Router) Use

func (r *Router) Use(mw Middleware)

Use attaches a middleware to the router.

Any routes set on the router will have their handlers decorated by the attached middlewares in reverse order (the first middleware attached will be the outer-most: first to see requests and the last to see responses).

Use will panic if Route or Mount have already been called on the router - middlewares must be set before any routes.

type Server

type Server = types.Server

type ServerProtocol

type ServerProtocol = types.ServerProtocol

type Status

type Status = types.Status