dioscuri

package module
v0.0.0-...-6a1e3ad Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 7, 2021 License: MIT Imports: 18 Imported by: 0

README

= dioscuri

Gemini [1] protocol packages and tools.

= Install

	go get github.com/littleroot/dioscuri

= Documentation, Examples

 	https://pkg.go.dev/github.com/littleroot/dioscuri

[1]: https://gemini.circumlunar.space/

Documentation

Overview

Package dioscuri implements a Gemini client, a Gemini server, and a parser for the "text/gemini" mime type.

Gemini: https://gemini.circumlunar.space/

Example (Get)
rsp, err := Get(context.Background(), "gemini://gus.guru")
if err != nil {
	log.Fatal(err)
}

defer rsp.Body.Close()

if StatusClass(rsp.Status) != Success {
	log.Fatalf("bad status %d", rsp.Status)
}

// do something with rsp.Body
_ = rsp.Body
Output:

Example (Parser)
var r io.Reader // response body with mime type "text/gemini; charset=utf-8"
p := NewParser(r)

for {
	line, err := p.Next()
	if err == io.EOF {
		break // done
	}
	if err != nil {
		log.Fatal(err)
	}
	// do something with line
	_ = line
}
Output:

Example (Serve)
HandleFunc("/", func(w ResponseWriter, _ *Request) {
	w.Write([]byte("hello, gemini!"))
})

err := ListenAndServe(":1965", "cert.pem", "key.rsa", nil)
if err != nil {
	log.Fatal(err)
}
Output:

Index

Examples

Constants

View Source
const (
	StatusInput          = 10
	StatusSensitiveInput = 11

	StatusSuccess = 20

	StatusTemporaryRedirect = 30
	StatusPermanentRedirect = 31

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

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

	StatusClientCertificateRequired = 60
	StatusCertificateNotAuthorised  = 61
	StatusCertificateNotValid       = 62
)

Specific status codes.

View Source
const (
	DefaultMimeType = "text/gemini; charset=utf-8"
)

Variables

View Source
var DefaultServeMux = &ServeMux{}

Functions

func Error

func Error(w ResponseWriter, message string, status int)

Error replies to the request with the specified message in the meta portion of the response and the given status code.

func Handle

func Handle(pattern string, h Handler)

func HandleFunc

func HandleFunc(pattern string, h func(ResponseWriter, *Request))

func IsGemtext

func IsGemtext(meta string) bool

IsGemtext returns whether the supplied mine media type (typically the value of Meta for success statuses) has content-type "text/gemini" with a UTF-8 charset parameter. If a charset parameter isn't specified, it is considered to be UTF-8.

func ListenAndServe

func ListenAndServe(addr string, certFile, keyFile string, h Handler) error

func Serve

func Serve(lis net.Listener, h Handler) error

Types

type Class

type Class int
const (
	Input Class
	Success
	Redirect
	TemporaryFailure
	PermanentFailure
	ClientCertificateRequired
)

func StatusClass

func StatusClass(status int) Class

type Handler

type Handler interface {
	ServeGemini(ResponseWriter, *Request)
}

func FileServer

func FileServer(root fs.FS) Handler

func NotFoundHandler

func NotFoundHandler() Handler

func RedirectHandler

func RedirectHandler(status int, u string) Handler

type HandlerFunc

type HandlerFunc func(ResponseWriter, *Request)

func (HandlerFunc) ServeGemini

func (h HandlerFunc) ServeGemini(w ResponseWriter, r *Request)

type HeadingLine

type HeadingLine struct {
	Level   int // 1 | 2 | 3
	Content []byte
}

func (HeadingLine) String

func (l HeadingLine) String() string

type Line

type Line interface {
	String() string
	// contains filtered or unexported methods
}

A Line represents a line of gemtext (i.e., "text/gemini" mime type) content.

func ParseGemtextLine

func ParseGemtextLine(b []byte, pre bool) (Line, bool, error)

ParseGemtextLine parses the "text/gemini" content line specified by the given bytes. The pre parameter indicates whether preformatted mode is currently on or off. The function returns the parsed line, the updated value for the preformatted mode (which should be passed in as the argument when parsing the next line), and any error.

ParseGemtextLine assumes the input is UTF-8 encoded.

type LinkLine

type LinkLine struct {
	URL  []byte
	Name []byte
}

func (LinkLine) String

func (l LinkLine) String() string

type Parser

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

Parser parses "text/gemini" input, otherwise referred to as gemtext. It assumes the input is UTF-8 encoded. Use NewParser to constrct a Parser. See package-level example for usage.

func NewParser

func NewParser(r io.Reader) *Parser

NewParser constructs a "text/gemini" parser with the given input.

func (*Parser) Next

func (p *Parser) Next() (Line, error)

Next parses and returns the next line. The bytes in the returned Line are only valid until the subsequent call to Next. The error is io.EOF if there are no more lines.

func (*Parser) Pre

func (p *Parser) Pre() bool

Pre returns whether preformatted mode has been toggled on or off.

type PreTextLine

type PreTextLine []byte

func (PreTextLine) String

func (l PreTextLine) String() string

type PreToggleLine

type PreToggleLine struct {
	On      bool   // whether the line toggles preformatting mode on or off
	AltText []byte // valid if On == true
}

func (PreToggleLine) String

func (l PreToggleLine) String() string

type QuoteLine

type QuoteLine []byte

func (QuoteLine) String

func (l QuoteLine) String() string

type Request

type Request struct {
	URL          *url.URL
	Certificates []tls.Certificate
}

A Request represents a Gemini protocol request.

func NewRequest

func NewRequest(rawUrl string) (*Request, error)

NewRequest constructs a Gemini request for the given URL.

type Response

type Response struct {
	Status  int
	RawMeta []byte
	Body    io.ReadCloser
}

Response represents a Gemini protocol response.

func Do

func Do(ctx context.Context, r *Request) (*Response, error)

Do performs a Gemini protocol request.

func Get

func Get(ctx context.Context, rawUrl string) (*Response, error)

Get performs a request for content served over the Gemini protocol at the given URL.

func (*Response) Meta

func (r *Response) Meta() string

Meta returns the normalized value of RawMeta. That is, if RawMeta is empty Meta returns "text/gemini; charset=utf-8". Otherwise, RawMeta is returned as is.

type ResponseWriter

type ResponseWriter interface {
	// WriteHeader writes the status code and meta portion of the response header.
	WriteHeader(status int, meta string)

	// Write writes the data to the connection as part of the response body.
	// If WriteHeader has not yet been called, Write calls WriteHeader with
	// status code 20 and and meta "text/gemini; charset=utf-8".
	Write(p []byte) (n int, err error)
}

type ServeMux

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

func (*ServeMux) Handle

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

func (*ServeMux) HandleFunc

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

func (*ServeMux) ServeGemini

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

type Server

type Server struct {
	// Address specifies the TCP address to listen on.
	// If empty, ":1965" is used.
	Addr string

	// Handler to invoke.
	// If nil, DefaultServeMux is used.
	Handler Handler

	ReadTimeout  time.Duration
	WriteTimeout time.Duration
}

func (*Server) ListenAndServe

func (s *Server) ListenAndServe(certFile, keyFile string) error

func (*Server) Serve

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

type TextLine

type TextLine []byte

func (TextLine) String

func (l TextLine) String() string

type UnorderedListItemLine

type UnorderedListItemLine []byte

func (UnorderedListItemLine) String

func (l UnorderedListItemLine) String() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL