gemax

Documentation

Overview

Package gemax provides gemini protocol implementations. Gemini specification: gemini://gemini.circumlunar.space/docs/specification.gmi

Index

• Constants
• Variables
• func NotFound(rw ResponseWriter, req IncomingRequest)
• func ParseResponseHeader(re io.ByteReader) (status.Code, string, error)
• func Query(query urlpkg.Values) []string
• func Redirect(rw ResponseWriter, req IncomingRequest, target string, code status.Code)
• type Client
  • func (client *Client) Fetch(ctx context.Context, url string) (*Response, error)
• type FileSystem
  • func (fileSystem *FileSystem) Serve(ctx context.Context, rw ResponseWriter, req IncomingRequest)
• type Handler
  • func ServeContent(contentType string, content []byte) Handler
• type IncomingRequest
  • func ParseIncomingRequest(re io.Reader, remoteAddr string) (IncomingRequest, error)
• type Response
• type ResponseWriter
• type Server
  • func (server *Server) ListenAndServe(ctx context.Context, tlsCfg *tls.Config) error
  • func (server *Server) Serve(ctx context.Context, listener net.Listener) error
  • func (server *Server) Stop()

Constants

const MIMEGemtext = "text/gemini"

MIMEGemtext describes a MIME type for gemini text. As a subtype of the top-level media type "text", "text/gemini" inherits the "charset" parameter defined in RFC 2046. However, as noted in 3.3, the default value of "charset" is "UTF-8" for "text" content transferred via Gemini.

A single additional parameter specific to the "text/gemini" subtype is defined: the "lang" parameter. The value of "lang" denotes the natural language or language(s) in which the textual content of a "text/gemini" document is written. The presence of the "lang" parameter is optional. When the "lang" parameter is present, its interpretation is defined entirely by the client. For example, clients which use text-to-speech technology to make Gemini content accessible to visually impaired users may use the value of "lang" to improve pronunciation of content. Clients which render text to a screen may use the value of "lang" to determine whether text should be displayed left-to-right or right-to-left. Simple clients for users who only read languages written left-to-right may simply ignore the value of "lang". When the "lang" parameter is not present, no default value should be assumed and clients which require some notion of a language in order to process the content (such as text-to-speech screen readers) should rely on user-input to determine how to proceed in the absence of a "lang" parameter.

Valid values for the "lang" parameter are comma-separated lists of one or more language tags as defined in RFC4646. For example:

• "text/gemini; lang=en" Denotes a text/gemini document written in English
• "text/gemini; lang=fr" Denotes a text/gemini document written in French
• "text/gemini; lang=en,fr" Denotes a text/gemini document written in a mixture of English and French
• "text/gemini; lang=de-CH" Denotes a text/gemini document written in Swiss German
• "text/gemini; lang=sr-Cyrl" Denotes a text/gemini document written in Serbian using the Cyrllic script
• "text/gemini; lang=zh-Hans-CN" Denotes a text/gemini document written in Chinese using the Simplified script as used in mainland China

const MaxHeaderSize = 1024

MaxHeaderSize is used while parsing server responses.

const MaxRequestSize = 1026

MaxRequestSize is the maximum incoming request size in bytes.

Variables

var ErrHeaderTooLarge = errors.New("header is too large: max header size is " + strconv.Itoa(MaxHeaderSize))

ErrHeaderTooLarge means that server response exceeds the MaxHeaderSize limit.

var ErrInvalidResponse = errors.New("malformed server response header")

ErrInvalidResponse means that server response is badly formed.

var ErrInvalidServerName = errors.New("server domain and server TLS domain name don't match")

ErrInvalidServerName means that the server certificate doesn't match the server domain.

Functions

func NotFound

func NotFound(rw ResponseWriter, req IncomingRequest)

NotFound serves a not found error.

func ParseResponseHeader

func ParseResponseHeader(re io.ByteReader) (status.Code, string, error)

ParseResponseHeader reads gemini header in form of "<code><SP><meta><CRLF>". If provided header is longer than MaxHeaderSize, than returns ErrHeaderTooLarge. Returns ErrInvalidResponse for badly formed server responses.

func Query

func Query(query urlpkg.Values) []string

Query extracts canonical gemini query values from url query part. Values are sorted in ascending order. Expected values:

?query&key=value => [query]
?a&b=&key=value => [a, b]

func Redirect

func Redirect(rw ResponseWriter, req IncomingRequest, target string, code status.Code)

Redirect client to another page. This handler can work with relative If code is status.Success, then generates a small gemini document with a single redirect link. This mechanism can be used as redirect on other protocol pages.

Examples:

Redirect(rw, req, "gemini://other.server.com/page", status.Redirect)
Redirect(rw, req, "../root/page", status.PermanentRedirect)
Redirect(rw, req, "https://wikipedia.org", status.Success)

Types

type Client

type Client struct {
	MaxResponseSize int64
	Dial            func(ctx context.Context, host string, cfg *tls.Config) (net.Conn, error)
	// contains filtered or unexported fields
}

Client is used to fetch gemini resources. Empty client value cane be considered as initialized.

func (*Client) Fetch

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

Fetch gemini resource.

type FileSystem

type FileSystem struct {
	// The backend file system.
	FS fs.FS

	// Will be prepended to the request pats.
	Prefix string
	// Optional text logger.
	Logf func(format string, args ...interface{})
}

FileSystem serves file systems as gemini catalogs. It will search index.gmi and index.gemini in each catalog to use it content as header of corresponding directory page.

This handler is not intended to be used as file server, it's more like a static site server.

func (*FileSystem) Serve

func (fileSystem *FileSystem) Serve(ctx context.Context, rw ResponseWriter, req IncomingRequest)

Serve provided file system as gemini catalogs.

type Handler

type Handler func(ctx context.Context, rw ResponseWriter, req IncomingRequest)

Handler describes a gemini protocol handler.

func ServeContent

func ServeContent(contentType string, content []byte) Handler

ServeContent creates a handler, which serves provided bytes as static page.

type IncomingRequest

type IncomingRequest interface {
	URL() *url.URL
	RemoteAddr() string
}

IncomingRequest describes a server side request object.

func ParseIncomingRequest

func ParseIncomingRequest(re io.Reader, remoteAddr string) (IncomingRequest, error)

ParseIncomingRequest constructs an IncomingRequest from bytestream and additional parameters (remote address for now).

type Response

type Response struct {
	Status status.Code
	Meta   string
	// contains filtered or unexported fields
}

Response contains parsed server response.

type ResponseWriter

type ResponseWriter interface {
	WriteStatus(code status.Code, meta string)
	io.WriteCloser
}

ResponseWriter describes a server side response writer.

type Server

type Server struct {
	Addr string
	// Hosts expected by server.
	// If empty, then every host will be valid.
	Hosts       []string
	Handler     Handler
	ConnContext func(ctx context.Context, conn net.Conn) context.Context
	Logf        func(format string, args ...interface{})
	// contains filtered or unexported fields
}

Server is gemini protocol server.

func (*Server) ListenAndServe

func (server *Server) ListenAndServe(ctx context.Context, tlsCfg *tls.Config) error

ListenAndServe starts a TLS gemini server at specified server.

func (*Server) Serve

func (server *Server) Serve(ctx context.Context, listener net.Listener) error

Serve starts server on provided listener. Provided context will be passed to handlers.

func (*Server) Stop

func (server *Server) Stop()

Stop gracefully shuts down the server: closes all connections.