gemini

Documentation

Overview

The gemini package contains everything needed for building clients and servers on the gemini protocol.

There are server and client implementations, parsers, formatters, and constructors for gemini requests and responses, and a utility for building a gemini-ready TLS configuration.

The gemtext subpackage is a library usefor for parsing and otherwise using gemtext documents, including transforming them into a few other languages with overridable templates.

Index

• Constants
• Variables
• func BadRequest(msg string) *types.Response
• func CGIError(err string) *types.Response
• func CertAuthFailure(msg string) *types.Response
• func CertInvalid(msg string) *types.Response
• func Failure(err error) *types.Response
• func FileTLS(certfile string, keyfile string) (*tls.Config, error)
• func GeminiOnly(allowTitan bool) types.Middleware
• func GetTitanRequestBody(request *types.Request) io.Reader
• func Gone(msg string) *types.Response
• func Input(prompt string) *types.Response
• func MultiTLS(configs map[string]*tls.Config, fallback *tls.Config) *tls.Config
• func NewResponseReader(response *types.Response) types.ResponseReader
• func NewServer(ctx context.Context, hostname string, network string, address string, ...) (types.Server, error)
• func NotFound(msg string) *types.Response
• func ParseRequest(rdr io.Reader) (*types.Request, error)
• func ParseResponse(rdr io.Reader) (*types.Response, error)
• func PermanentFailure(err error) *types.Response
• func PermanentRedirect(url string) *types.Response
• func ProxyError(msg string) *types.Response
• func Redirect(url string) *types.Response
• func RefuseProxy(msg string) *types.Response
• func RequireCert(msg string) *types.Response
• func SensitiveInput(prompt string) *types.Response
• func SlowDown(seconds int) *types.Response
• func StatusName(status types.Status) string
• func Success(mediatype string, body io.Reader) *types.Response
• func Unavailable(msg string) *types.Response
• type Client
  • func NewClient(tlsConf *tls.Config) Client
  • func (c Client) Fetch(ctx context.Context, url string) (*types.Response, error)
  • func (c Client) IsRedirect(response *types.Response) bool
  • func (client Client) RoundTrip(ctx context.Context, request *types.Request) (*types.Response, error)
• type ResponseCategory
  • func ResponseCategoryForStatus(status types.Status) ResponseCategory

Constants

const (
	// StatusInput indicates a required query parameter at the requested URL.
	StatusInput types.Status = types.Status(ResponseCategoryInput) + iota
	// StatusSensitiveInput indicates a sensitive query parameter is required.
	StatusSensitiveInput
)

const (
	// StatusTemporaryRedirect indicates a temporary redirect to another URL.
	StatusTemporaryRedirect = types.Status(ResponseCategoryRedirect) + iota
	// StatusPermanentRedirect indicates that the resource should always be requested at the new URL.
	StatusPermanentRedirect
)

const (
	// StatusTemporaryFailure indicates that the request failed and there is no response body.
	StatusTemporaryFailure = types.Status(ResponseCategoryTemporaryFailure) + iota
	// StatusServerUnavailable occurs when the server is unavailable due to overload or maintenance.
	StatusServerUnavailable
	// StatusCGIError is the result of a failure of a CGI script.
	StatusCGIError
	// StatusProxyError indicates that the server is acting as a proxy and the outbound request failed.
	StatusProxyError
	// StatusSlowDown tells the client that rate limiting is in effect.
	//
	// Unlike other statuses in this category, the META line is an integer indicating how
	// many more seconds the client must wait before sending another request.
	StatusSlowDown
)

const (
	// StatusPermanentFailure is a server failure which should be expected to continue indefinitely.
	StatusPermanentFailure = types.Status(ResponseCategoryPermanentFailure) + iota
	// StatusNotFound means the resource doesn't exist but it may in the future.
	StatusNotFound
	// StatusGone occurs when a resource will not be available any longer.
	StatusGone
	// StatusProxyRequestRefused means the server is unwilling to act as a proxy for the resource.
	StatusProxyRequestRefused
	// StatusBadRequest indicates that the request was malformed somehow.
	StatusBadRequest = types.Status(ResponseCategoryPermanentFailure) + 9
)

const (
	// StatusClientCertificateRequired is returned when a certificate was required but not provided.
	StatusClientCertificateRequired = types.Status(ResponseCategoryCertificateRequired) + iota
	// StatusCertificateNotAuthorized means the certificate doesn't grant access to the requested resource.
	StatusCertificateNotAuthorized
	// StatusCertificateNotValid means the provided client certificate is invalid.
	StatusCertificateNotValid
)

const DefaultMaxRedirects int = 2

DefaultMaxRedirects is the number of chained redirects a Client will perform for a single request by default. This can be changed by altering the MaxRedirects field.

const (
	// StatusSuccess is a successful response.
	StatusSuccess = types.Status(ResponseCategorySuccess) + iota
)

Variables

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

var InvalidRequestLineEnding = errors.New("invalid request line ending")

InvalidRequestLineEnding indicates that a gemini request didn't end with "\r\n".

var InvalidResponseHeaderLine = errors.New("Invalid response header line.")

InvalidResponseHeaderLine indicates a malformed gemini response header line.

var InvalidResponseLineEnding = errors.New("Invalid response line ending.")

InvalidResponseLineEnding indicates that a gemini response header didn't end with "\r\n".

var ServerProtocol types.ServerProtocol = proto{}

Functions

func BadRequest

func BadRequest(msg string) *types.Response

BadRequest builds a "bad request" response.

func CGIError

func CGIError(err string) *types.Response

CGIError builds a "cgi error" response.

func CertAuthFailure

func CertAuthFailure(msg string) *types.Response

CertAuthFailure builds a "certificate not authorized" response.

func CertInvalid

func CertInvalid(msg string) *types.Response

CertInvalid builds a "client certificate not valid" response.

func Failure

func Failure(err error) *types.Response

Failure builds a temporary failure response from an error.

func FileTLS

func FileTLS(certfile string, keyfile string) (*tls.Config, error)

FileTLS builds a TLS configuration from paths to a certificate and key file.

It sets parameters on the configuration to make it suitable for use with gemini.

func GeminiOnly

func GeminiOnly(allowTitan bool) types.Middleware

GeminiOnly filters requests down to just those on the gemini:// protocol.

Optionally, it will also allow through titan:// requests.

Filtered requests will be turned away with a 53 response "proxy request refused".

func GetTitanRequestBody

func GetTitanRequestBody(request *types.Request) io.Reader

GetTitanRequestBody fetches the request body from a titan request.

It returns nil if the argument is not a titan request or it otherwise does not have a request body set.

func Gone

func Gone(msg string) *types.Response

Gone builds a "resource gone" response.

func Input

func Input(prompt string) *types.Response

Input builds an input-prompting response.

func MultiTLS

func MultiTLS(configs map[string]*tls.Config, fallback *tls.Config) *tls.Config

MultiTLS returns a *tls.Config usable for virtual hosting multiple domains.

The provided configs map should be keyed on domain names, and the fallback will be used if the client does not support SNI, or if the requested domain isn't found.

func NewResponseReader

func NewResponseReader(response *types.Response) types.ResponseReader

func NewServer

func NewServer(
	ctx context.Context,
	hostname string,
	network string,
	address string,
	handler types.Handler,
	baseLog logging.Logger,
	tlsConfig *tls.Config,
) (types.Server, error)

NewServer builds a gemini server.

func NotFound

func NotFound(msg string) *types.Response

NotFound builds a "resource not found" response.

func ParseRequest

func ParseRequest(rdr io.Reader) (*types.Request, error)

ParseRequest parses a single gemini/titan request from a reader.

If the reader argument is a *bufio.Reader, it will only read a single line from it.

func ParseResponse

func ParseResponse(rdr io.Reader) (*types.Response, error)

ParseResponse parses a complete gemini response from a reader.

The reader must contain only one gemini response.

func PermanentFailure

func PermanentFailure(err error) *types.Response

PermanentFailure builds a "permanent failure" from an error.

func PermanentRedirect

func PermanentRedirect(url string) *types.Response

PermanentRedirect builds a response with a permanent redirect.

func ProxyError

func ProxyError(msg string) *types.Response

ProxyError builds a proxy error response.

func Redirect

func Redirect(url string) *types.Response

Redirect builds a redirect response.

func RefuseProxy

func RefuseProxy(msg string) *types.Response

RefuseProxy builds a "proxy request refused" response.

func RequireCert

func RequireCert(msg string) *types.Response

RequireCert builds a "client certificate required" response.

func SensitiveInput

func SensitiveInput(prompt string) *types.Response

SensitiveInput builds a password-prompting response.

func SlowDown

func SlowDown(seconds int) *types.Response

SlowDown builds a "slow down" response with the number of seconds until the resource is available.

func StatusName

func StatusName(status types.Status) string

func Success

func Success(mediatype string, body io.Reader) *types.Response

Success builds a success response with resource body.

func Unavailable

func Unavailable(msg string) *types.Response

Unavailable build a "server unavailable" response.

Types

type Client

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

Client is used for sending gemini requests and parsing gemini responses.

It carries no state and is usable and reusable simultaneously by multiple goroutines. The only reason you might create more than one Client is to support separate TLS-cert driven identities.

The zero value is a usable Client with no client TLS certificate and which will not follow redirects.

func NewClient

func NewClient(tlsConf *tls.Config) Client

NewClient creates a gemini Client with the given TLS configuration and default MaxRedirects.

func (Client) Fetch

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

Fetch parses a URL string and fetches the gemini resource.

It will resolve any redirects along the way, up to client.MaxRedirects.

func (Client) IsRedirect

func (c Client) IsRedirect(response *types.Response) bool

func (Client) RoundTrip

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

RoundTrip sends a single gemini request to the correct server and returns its response.

It also populates the TLSState and RemoteAddr fields on the request - the only field it needs populated beforehand is the URL.

This method will not automatically follow redirects or cache permanent failures or redirects.

type ResponseCategory

type ResponseCategory int

ResponseCategory represents the various types of gemini responses.

const (
	// ResponseCategoryInput is for responses which request additional input.
	//
	// The META line will be the prompt to display to the user.
	ResponseCategoryInput ResponseCategory = iota*10 + 10
	// ResponseCategorySuccess is for successful responses.
	//
	// The META line will be the resource's mime type.
	// This is the only response status which indicates the presence of a response body,
	// and it will contain the resource itself.
	ResponseCategorySuccess
	// ResponseCategoryRedirect is for responses which direct the client to an alternative URL.
	//
	// The META line will contain the new URL the client should try.
	ResponseCategoryRedirect
	// ResponseCategoryTemporaryFailure is for responses which indicate a transient server-side failure.
	//
	// The META line may contain a line with more information about the error.
	ResponseCategoryTemporaryFailure
	// ResponseCategoryPermanentFailure is for permanent failure responses.
	//
	// The META line may contain a line with more information about the error.
	ResponseCategoryPermanentFailure
	// ResponseCategoryCertificateRequired indicates client certificate related issues.
	//
	// The META line may contain a line with more information about the error.
	ResponseCategoryCertificateRequired
)

func ResponseCategoryForStatus

func ResponseCategoryForStatus(status types.Status) ResponseCategory