gemini

Documentation

Overview

Package gemini is a simple gemini server framework in the style of net/http.

This server conforms to the gemini protocol version v0.14.3 as described here: gemini://gemini.circumlunar.space/docs/specification.gmi

TODO(Xe): add examples here

Index

• Constants
• Variables
• type Handler
  • func NotFound() Handler
• type HandlerFunc
  • func (hf HandlerFunc) HandleGemini(w ResponseWriter, r *Request)
• type Request
• type ResponseWriter
• type ServeMux
  • func NewServeMux() *ServeMux
  • func (mux *ServeMux) Handle(pattern string, handler Handler)
  • func (mux *ServeMux) HandleFunc(pattern string, handler func(ResponseWriter, *Request))
  • func (mux *ServeMux) HandleGemini(w ResponseWriter, r *Request)
  • func (mux *ServeMux) Handler(r *Request) (h Handler, pattern string)
• type Server
  • func NewServer(hdl Handler) *Server
  • func (s *Server) ListenAndServe(addr string, certPath string, keyPath string) error
  • func (s *Server) ListenUnix(path string) error
  • func (s *Server) Serve(lis net.Listener) error

Constants

const (
	StatusInput          = 10
	StatusSensitiveInput = 11

	StatusSuccess = 20

	StatusRedirect          = 30
	StatusRedirectTemporary = 30
	StatusRedirectPermanent = 31

	StatusTemporaryFailure = 40
	StatusUnavailable      = 41
	StatusCGIError         = 42
	StatusProxyError       = 43
	StatusSlowDown         = 44

	StatusPermanentFailure    = 50
	StatusNotFound            = 51
	StatusGone                = 52
	StatusProxyRequestRefused = 53
	StatusBadRequest          = 59

	StatusClientCertificateRequired = 60
	StatusCertificateNotAuthorised  = 61
	StatusCertificateNotValid       = 62
)

Gemini status codes as defined in the Gemini spec Appendix 1.

Variables

var DefaultServeMux = &defaultServeMux

DefaultServeMux is the default ServeMux used by Serve.

Types

type Handler

type Handler interface {
	HandleGemini(rw ResponseWriter, req *Request)
}

A Handler responds to a gemini request.

HandleGemini should write the status line and any relevant body data then return.

The provided request is safe to modify provided you really understand what you are doing.

func NotFound

func NotFound() Handler

NotFound is a generic handler for when you can't find a resource.

type HandlerFunc

type HandlerFunc func(ResponseWriter, *Request)

HandlerFunc is a convenience wrapper that lets you easily construct Handlers from ad-hoc functions.

func (HandlerFunc) HandleGemini

func (hf HandlerFunc) HandleGemini(w ResponseWriter, r *Request)

type Request

type Request struct {
	URL        *url.URL
	Cert       *x509.Certificate
	RemoteAddr netaddr.IPPort
}

Request contains all relevant metadata for a gemini request.

type ResponseWriter

type ResponseWriter interface {
	// Status sends the status line to the client with the provided status
	// code and metadata.
	//
	// Only one status line may be sent to the client. Making more than one
	// call to this method should result in a panic.
	//
	// The provided code SHOULD be one of the status codes defined in this
	// package.
	Status(status int, meta string)
	io.Writer
}

ResponseWriter is used by a gemini handler to construct a gemini response.

This may not be used after the HandleGemini method has returned.

type ServeMux

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

ServeMux is a Gemini request multiplexer. It matches the URL of each incoming request against a list of registered patterns and calls the handler for the pattern that most closely matches the URL.

Patterns name fixed, rooted paths, like "/favicon.ico", or rooted subtrees, like "/images/" (note the trailing slash). Longer patterns take precedence over shorter ones, so that if there are handlers registered for both "/images/" and "/images/thumbnails/", the latter handler will be called for paths beginning "/images/thumbnails/" and the former will receive requests for any other paths in the "/images/" subtree.

Note that since a pattern ending in a slash names a rooted subtree, the pattern "/" matches all paths not matched by other registered patterns, not just the URL with Path == "/".

If a subtree has been registered and a request is received naming the subtree root without its trailing slash, ServeMux redirects that request to the subtree root (adding the trailing slash). This behavior can be overridden with a separate registration for the path without the trailing slash. For example, registering "/images/" causes ServeMux to redirect a request for "/images" to "/images/", unless "/images" has been registered separately.

ServeMux also takes care of sanitizing the URL request path, redirecting any request containing . or .. elements or repeated slashes to an equivalent, cleaner URL.

func NewServeMux

func NewServeMux() *ServeMux

NewServeMux allocates and returns a new ServeMux.

func (*ServeMux) Handle

func (mux *ServeMux) Handle(pattern string, handler Handler)

Handle registers the handler for the given pattern. If a handler already exists for pattern, Handle panics.

func (*ServeMux) HandleFunc

func (mux *ServeMux) HandleFunc(pattern string, handler func(ResponseWriter, *Request))

HandleFunc registers the handler function for the given pattern.

func (*ServeMux) HandleGemini

func (mux *ServeMux) HandleGemini(w ResponseWriter, r *Request)

HandleGemini dispatches the request to the handler whose pattern most closely matches the request URL.

func (*ServeMux) Handler

func (mux *ServeMux) Handler(r *Request) (h Handler, pattern string)

Handler returns the handler to use for the given request, consulting r.URL. It always returns a non-nil handler.

Handler also returns the registered pattern that matches the request.

If there is no registered handler that applies to the request, Handler returns a “resource not found” handler and an empty pattern.

type Server

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

Server is a gemini server struct in the vein of net/http#Server.

func NewServer

func NewServer(hdl Handler) *Server

NewServer creates a new Gemini server based on a particular handler.

func (*Server) ListenAndServe

func (s *Server) ListenAndServe(addr string, certPath string, keyPath string) error

ListenAndServe creates a new TLS listener on a given port with a given TLS certificate and key. This is most useful for serving a single site. If you need more control or want to host multiple sites, create your own tls.Listener and use the Serve method.

func (*Server) ListenUnix

func (s *Server) ListenUnix(path string) error

ListenUnix listens on a unix domain socket at the given path. It will automatically clear out the path at the given location.

This can be useful when hosting multiple gemini apps on the same host without having them each care about their TLS configuration.

func (*Server) Serve

func (s *Server) Serve(lis net.Listener) error

Serve serves gemini responses to clients connecting to this Listener.