gomini

README

gomini

go client and server implementation of the gemini protocol https://gemini.circumlunar.space/

docs

TODO - doc link

quick start examples

client

import (
    "git.sr.ht/~benvh/gomini"
)

func main() {
    knownHosts := &gomini.KnownHosts{TrustNewHosts: true}
    response, err := gomini.Fetch("gemini://benvh.tech/", knownHosts)

	if err != nil {
        panic(err)
    }

    fmt.Println("%d - %s", response.Status, response.Meta)

    // ...
}

server

import (
    "crypto/tls"
    "net/url"

    "git.sr.ht/~benvh/gomini"
)

func main() {
    cert, err := tls.LoadX509KeyPair("cert.pem", "key.pem")
    if err != nil {
        panic(err)
    }

    tlsConfig := &tls.Config{Certificates: []tls.Certificate{cert}}
    s := gomini.NewServer(tlsConfig)

    handler := new(gomini.ServeMux)
    handler.Handle(`^/`, gomini.FileHandler("./public"))

    handler.Handle(`^/foo/bar`, gomini.HandlerFunc(func(resp gomini.ResponseWriter, req *url.URL) {
        resp.WriteHeader(gomini.StatusSuccess, "text/plain")
        resp.Write([]byte("foobar"))
    }))

    s.ListenAndServe("0.0.0.0:1965", handler)
}

Documentation

Index

• Variables
• func NotFound(resp ResponseWriter, req *url.URL)
• func ProxyTo(resp ResponseWriter, req *url.URL, ...)
• func RunExternal(resp ResponseWriter, req *url.URL, command, contentType string)
• func TemporaryFailure(resp ResponseWriter, req *url.URL, message string)
• func TemporaryRedirect(resp ResponseWriter, req *url.URL, destination string)
• type Client
  • func NewClient(pemCertPath string, pemRsaKeyPath string, followRedirects bool) (*Client, error)
  • func (c *Client) Fetch(url url.URL)
• type Handler
  • func FileHandler(root string) Handler
  • func NotFoundHandler() Handler
  • func ProxyToHandler(upstream, upstreamIdentity, stripPattern string) Handler
  • func RunExternalHandler(command, contentType string) Handler
  • func TemporaryFailureHandler(message string) Handler
  • func TemporaryRedirectHandler(destination string) Handler
• type HandlerFunc
  • func (hf HandlerFunc) ServeGemini(resp ResponseWriter, req *url.URL)
• type KnownHosts
  • func NewKnownHosts() *KnownHosts
  • func (k *KnownHosts) IsKnownAs(hostname string, certificate *x509.Certificate) bool
  • func (k *KnownHosts) IsKown(hostname string) bool
  • func (k *KnownHosts) Load(filePath string) error
  • func (k *KnownHosts) ReadFrom(reader io.Reader) (int64, error)
  • func (k *KnownHosts) Remember(hostname string, certificate *x509.Certificate)
  • func (k *KnownHosts) Save(filePath string) error
  • func (k *KnownHosts) WriteTo(writer io.Writer) (int64, error)
• type Response
  • func Fetch(requestUrl string, knownHosts *KnownHosts) (*Response, error)
  • func (resp *Response) String() string
• type ResponseWriter
• type ServeMux
  • func NewServeMux() *ServeMux
  • func (mux *ServeMux) Handle(pattern string, handler Handler)
  • func (mux *ServeMux) Handler(req *url.URL) (h Handler, pattern string)
  • func (mux *ServeMux) ServeGemini(resp ResponseWriter, req *url.URL)
• type Server
  • func NewServer(tlsConfig *tls.Config) *Server
  • func (srv *Server) Close()
  • func (srv *Server) ListenAndServe(laddr string, handler Handler) error
• type VhostMux
  • func NewVhostMux() *VhostMux
  • func (mux *VhostMux) Handle(hostname string, handler Handler)
  • func (mux *VhostMux) ServeGemini(resp ResponseWriter, req *url.URL)

Variables

var (
	ErrUntrustedHost             = errors.New("The host is not trusted (yet). Add it to the known hosts if it is to be trusted")
	ErrInvalidHostCertificate    = errors.New("The received host certificate does not match the known one")
	ErrInvalidResponseStatusCode = errors.New("Could not parse the response status code")
	ErrResponseStatusTooBig      = errors.New("Response status/meta line exceeded its maximum size")
	ErrResponseStatusTooSmall    = errors.New("Response status/meta line is too small")
	ErrUnsupportedScheme         = errors.New("only the gemini:// scheme is supported")

	SchemeGemini = "gemini"
)

var (
	StatusInput = 10

	StatusSuccess                 = 20
	StatusSuccessEndClientSession = 21

	StatusRedirectTemporary = 30
	StatusRedirectPermanent = 31

	StatusTemporaryFailure  = 40
	StatusServerUnavailable = 41
	StatusCgiError          = 42
	StatusProxyError        = 43
	StatusSlowDow           = 44

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

	StatusClientCertificateRequired     = 60
	StatusTransientCertificateRequired  = 61
	StatusAuthorisedCertificateRequired = 62
	StatusCertificateNotAccepted        = 63
	StatusFutureCertificateRejected     = 64
	StatusExpiredCertificateRejected    = 65
)

var (
	ErrServerClosed = errors.New("Server closed")
)

Functions

func NotFound

func NotFound(resp ResponseWriter, req *url.URL)

NotFound replies to the request with a “NOT FOUND“ reply

func ProxyTo

func ProxyTo(resp ResponseWriter, req *url.URL, upstream, upstreamIdentity, stripPattern string)

func RunExternal

func RunExternal(resp ResponseWriter, req *url.URL, command, contentType string)

func TemporaryFailure

func TemporaryFailure(resp ResponseWriter, req *url.URL, message string)

TemporaryFailure replies to the request with a “TEMPORARY FAILURE“ reply message will be used as the response meta value

func TemporaryRedirect

func TemporaryRedirect(resp ResponseWriter, req *url.URL, destination string)

TemporaryRedirect replies to the request with a “TEMPORARY REDIRECT“ reply destination will be used as the reponse meta value

Types

type Client

type Client struct {
	Certificate     *tls.Certificate
	Key             crypto.PrivateKey
	FollowRedirects bool
}

func NewClient

func NewClient(pemCertPath string, pemRsaKeyPath string, followRedirects bool) (*Client, error)

func (*Client) Fetch

func (c *Client) Fetch(url url.URL)

type Handler

type Handler interface {
	ServeGemini(resp ResponseWriter, req *url.URL)
}

func FileHandler

func FileHandler(root string) Handler

func NotFoundHandler

func NotFoundHandler() Handler

NotFoundHandler creates a simple handler that replies to each request with a “NOT FOUND“ reply.

func ProxyToHandler

func ProxyToHandler(upstream, upstreamIdentity, stripPattern string) Handler

func RunExternalHandler

func RunExternalHandler(command, contentType string) Handler

func TemporaryFailureHandler

func TemporaryFailureHandler(message string) Handler

TemporaryFailureHandler creates a simple handler that replies to earch request with a “TEMPORARY FAILURE“ reply. message will be used as the response meta value

func TemporaryRedirectHandler

func TemporaryRedirectHandler(destination string) Handler

type HandlerFunc

type HandlerFunc func(resp ResponseWriter, req *url.URL)

func (HandlerFunc) ServeGemini

func (hf HandlerFunc) ServeGemini(resp ResponseWriter, req *url.URL)

type KnownHosts

type KnownHosts struct {
	TrustNewHosts bool
	Hosts         map[string]string
}

func NewKnownHosts

func NewKnownHosts() *KnownHosts

func (*KnownHosts) IsKnownAs

func (k *KnownHosts) IsKnownAs(hostname string, certificate *x509.Certificate) bool

func (*KnownHosts) IsKown

func (k *KnownHosts) IsKown(hostname string) bool

func (*KnownHosts) Load

func (k *KnownHosts) Load(filePath string) error

func (*KnownHosts) ReadFrom

func (k *KnownHosts) ReadFrom(reader io.Reader) (int64, error)

func (*KnownHosts) Remember

func (k *KnownHosts) Remember(hostname string, certificate *x509.Certificate)

func (*KnownHosts) Save

func (k *KnownHosts) Save(filePath string) error

func (*KnownHosts) WriteTo

func (k *KnownHosts) WriteTo(writer io.Writer) (int64, error)

type Response

type Response struct {
	Status int
	Meta   string
	Body   []byte
}

func Fetch

func Fetch(requestUrl string, knownHosts *KnownHosts) (*Response, error)

Fetch tries to do a simple gemini fetch call using the provided url string

func (*Response) String

func (resp *Response) String() string

type ResponseWriter

type ResponseWriter interface {
	WriteHeader(status int, meta string)
	Write(data []byte) (int, error)
	ReadFrom(r io.Reader) (int64, error)
}

type ServeMux

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

func NewServeMux

func NewServeMux() *ServeMux

func (*ServeMux) Handle

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

Handle registers the handler for the given pattern.

func (*ServeMux) Handler

func (mux *ServeMux) Handler(req *url.URL) (h Handler, pattern string)

func (*ServeMux) ServeGemini

func (mux *ServeMux) ServeGemini(resp ResponseWriter, req *url.URL)

type Server

type Server struct {
	TlsConfig *tls.Config
	// contains filtered or unexported fields
}

func NewServer

func NewServer(tlsConfig *tls.Config) *Server

func (*Server) Close

func (srv *Server) Close()

func (*Server) ListenAndServe

func (srv *Server) ListenAndServe(laddr string, handler Handler) error

type VhostMux

type VhostMux struct {
	HostHandlers map[string]Handler
}

func NewVhostMux

func NewVhostMux() *VhostMux

func (*VhostMux) Handle

func (mux *VhostMux) Handle(hostname string, handler Handler)

Handle registers the handle for the provided hostname

func (*VhostMux) ServeGemini

func (mux *VhostMux) ServeGemini(resp ResponseWriter, req *url.URL)