gemini

README

go-gemini

go-gemini is a library that provides an easy interface to create client and servers that speak the Gemini protocol.

This version of the library was forked from ~yotam/go-gemini to add additional features, as well as update it to support spec v0.12.3. At the time of forking, it had not seen any new commit for 5 months, and was based on v0.9.2. If there are any future upstream updates, I will make an effort to include them.

At the moment, this library focuses more on the client side of things, and support is not guaranteed. Please feel free to file issues though.

Improvements

This fork of the library improves on the original in several ways, some listed above already.

• Client supports self-signed certs sent by the server, but still allows other checks like expiry date and hostname
  • The original library could only work with self-signed certs by disabling all security.

Example Server

The repository comes with an example server that respond with an hardcoded text to the root page. To build the server run the following command:

make build

License

This library is under the ISC License, see the LICENSE file for details.

Documentation

Index

• Constants
• Variables
• func IsStatusValid(status int) bool
• func ListenAndServe(addr, certFile, keyFile string, handler Handler) error
• func SimplifyStatus(status int) int
• type Client
  • func (c *Client) Fetch(rawURL string) (*Response, error)
• type Error
  • func (e Error) Error() string
  • func (e Error) Unwrap() error
• type Handler
• type Request
• type Response
  • func ErrorResponse(err error) *Response
  • func Fetch(url string) (*Response, error)

Constants

const (
	StatusInput = 10

	StatusSuccess                              = 20
	StatusSuccessEndOfClientCertificateSession = 21

	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
	StatusTransientCertificateRequested = 61
	StatusAuthorisedCertificateRequired = 62
	StatusCertificateNotAccepted        = 63
	StatusFutureCertificateRejected     = 64
	StatusExpiredCertificateRejected    = 65
)

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

Variables

var DefaultClient = &Client{}

Functions

func IsStatusValid

func IsStatusValid(status int) bool

IsStatusValid checks whether an int status is covered by the spec.

func ListenAndServe

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

ListenAndServe create a TCP server on the specified address and pass new connections to the given handler. Each request is handled in a separate goroutine.

func SimplifyStatus

func SimplifyStatus(status int) int

SimplifyStatus simplify the response status by omiting the detailed second digit of the status code.

Types

type Client

type Client struct {
	// NoTimeCheck allows connections with expired or future certs if set to true.
	NoTimeCheck bool
	// NoHostnameCheck allows connections when the cert doesn't match the
	// requested hostname or IP.
	NoHostnameCheck bool
	// AllowInvalidStatuses means the client won't raise an error if a status
	// that is out of spec is returned.
	AllowInvalidStatuses bool
	// Insecure disables all TLS-based checks, use with caution.
	// It overrides all the variables above.
	Insecure bool
}

func (*Client) Fetch

func (c *Client) Fetch(rawURL string) (*Response, error)

Fetch a resource from a Gemini server with the given URL

type Error

type Error struct {
	Err    error
	Status int
}

func (Error) Error

func (e Error) Error() string

func (Error) Unwrap

func (e Error) Unwrap() error

type Handler

type Handler interface {
	Handle(r Request) *Response
}

Handler is the interface a struct need to implement to be able to handle Gemini requests

type Request

type Request struct {
	URL *url.URL
}

Request contains the data of the client request

type Response

type Response struct {
	Status int
	Meta   string
	Body   io.ReadCloser
}

Response represent the response from a Gemini server.

func ErrorResponse

func ErrorResponse(err error) *Response

ErrorResponse create a response from the given error with the error string as the Meta field. If the error is of type gemini.Error, the status will be taken from the status field, otherwise it will default to StatusTemporaryFailure. If the error is nil, the function will panic.

func Fetch

func Fetch(url string) (*Response, error)

Fetch a resource from a Gemini server with the default client