libgemini

README

Libgemini

Introduction

Libgemini is a simple Gemini client library for Go, allowing you to interact with Gemini servers and retrieve content over the Gemini protocol.

Support for writing servers and gemtext parsing is on the roadmap.

Features

• Supports a geminirc file as well as environment variables for controlling behavior.
• Simple and easy-to-use API for interacting with Gemini servers.
• 0 dependencies, only stdlib.

Installation

$ go get -u github.com/aalbacetef/libgemini

Usage

For a working example, see examples/simpleclient.

geminirc

The geminirc is meant to be an analogue of the curlrc, but supported by libgemini.

This enables users to manage settings for apps using libgemini. It also makes development a bit simpler.

These settings can also be controlled with environment variables.

The default location for the geminirc file, in order, is:

1. The location specified by the LIBGEMINI_RC environment variable.
2. $HOME/.config/libgemini/geminirc

If it is not found, the directory will be created and the file will be created.

To see a full example check data/geminirc

Environment Variables

The following environment variables are supported:

• LIBGEMINI_RC
• LIBGEMINI_FOLLOW_REDIRECTS
• LIBGEMINI_STORE_PATH
• LIBGEMINI_DUMP_HEADERS
• LIBGEMINI_TRACE
• LIBGEMINI_INSECURE

See the below section for their usage.

Sample geminirc file.

Note: for boolean fields, uncomment to enable, comment to disable. Comments are set using '#'.

Redirects

Env: LIBGEMINI_FOLLOW_REDIRECTS

Enable this option to automatically follow redirects.

--follow 

Trace

Env: LIBGEMINI_TRACE

Dump the trace to a file. Set this option to the path of the file.

Note: that the file will be overwritten on each request.

--trace /tmp/libgemini-trace.txt

Dump headers

Env: LIBGEMINI_DUMP_HEADERS

Dump headers of last request to a file.

Note: that the file will be overwritten on each request.

--dump-headers /tmp/libgemini-headers.txt

Insecure mode

Env: LIBGEMINI_INSECURE

Skip TOFU verification. Overrides --store.

 --insecure

Store location

Env: LIBGEMINI_STORE_PATH

Set Store location.

 --store ~/.config/libgemini/known_hosts

To use an in-memory store:

 --store :memory:

Contributing

If you find any issues or have suggestions for improvements, feel free to open an issue or submit a pull request.

Documentation

Index

• Constants
• func NewLoggerFromPath(ctx context.Context, fpath string) (*slog.Logger, error)
• type Client
  • func NewClient(userOpts ...OptsFn) (*Client, error)
  • func (c *Client) Do(req Request) (Response, error)
  • func (c *Client) DoWithContext(_ctx context.Context, req Request) (Response, error)
  • func (c *Client) Get(rawURL string) (Response, error)
  • func (c *Client) GetWithContext(ctx context.Context, rawURL string) (Response, error)
• type FileHandler
  • func NewFileHandler(ctx context.Context, wc io.WriteCloser) FileHandler
• type Header
  • func (hdr Header) String() string
• type NoopCloser
  • func (NoopCloser) Close() error
• type NoopHandler
  • func (NoopHandler) Enabled(context.Context, slog.Level) bool
  • func (NoopHandler) Handle(context.Context, slog.Record) error
  • func (NoopHandler) WithAttrs(attrs []slog.Attr) slog.Handler
  • func (NoopHandler) WithGroup(string) slog.Handler
• type Options
• type OptsFn
  • func WithInMemoryStore() OptsFn
  • func WithInsecure() OptsFn
  • func WithStore(val string) OptsFn
• type Request
  • func NewRequest(rawURL string) (Request, error)
  • func (r Request) String() string
  • func (r Request) Valid() error
  • func (r Request) Write(w io.Writer) error
• type Response
  • func ReadResponse(r io.Reader) (Response, error)
• type StatusCode
  • func (code StatusCode) IsSuccess() bool
  • func (code StatusCode) String() string

Constants

const (
	StdOutKey = ":stdout:"
	StdErrKey = ":stderr:"
)

const (
	DefaultTimeout         = time.Second * 30
	DefaultFollowRedirects = false
	DefaultInsecure        = false
	InMemoryStoreVal       = ":memory:"
)

const (
	EnvRC              = "LIBGEMINI_RC"
	EnvFollowRedirects = "LIBGEMINI_FOLLOW_REDIRECTS"
	EnvStorePath       = "LIBGEMINI_STORE_PATH"
	EnvDumpHeaders     = "LIBGEMINI_DUMP_HEADERS"
	EnvTrace           = "LIBGEMINI_TRACE"
	EnvInsecure        = "LIBGEMINI_INSECURE"
	KeyRC              = "RC"
	KeyFollowRedirects = "FollowRedirects"
	KeyStorePath       = "StorePath"
	KeyDumpHeaders     = "DumpHeaders"
	KeyTrace           = "Trace"
	KeyInsecure        = "Insecure"
)

const (
	ConfigFollowRedirects = "follow"
	ConfigStore           = "store"
	ConfigDumpHeaders     = "dump-headers"
	ConfigTrace           = "trace"
	ConfigInsecure        = "insecure"
)

const (
	UserRWAllR     = fs.FileMode(0o644)
	UserRWXAllNone = fs.FileMode(0o700)
)

const (
	CRLF = "\r\n"
)

const (
	TerminatorSize = 2 // Size of \r\n.

)

Functions

func NewLoggerFromPath

func NewLoggerFromPath(ctx context.Context, fpath string) (*slog.Logger, error)

NewLoggerFromPath will take in a path and if it's empty it will return a logger using a NoopHandler, otherwise it will try to initialize a FileHandler based on the filepath. It is expected to be used alongside a context. Use :stderr: or :stdout: to use StdErr or StdOut as outputs.

Types

type Client

type Client struct {
	TLSConfig *tls.Config

	Options
	// contains filtered or unexported fields
}

func NewClient

func NewClient(userOpts ...OptsFn) (*Client, error)

func (*Client) Do

func (c *Client) Do(req Request) (Response, error)

Do will call DoWithContext, passing in a context.WithTimeout set to c.Timeout. See: DoWithContext for more information.

func (*Client) DoWithContext

func (c *Client) DoWithContext(_ctx context.Context, req Request) (Response, error)

DoWithContext will dial the host, connect to it, finally writing the request on the connection.

func (*Client) Get

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

Get will call GetWithContext, passing in a context.WithTimeout using c.Timeout.

func (*Client) GetWithContext

func (c *Client) GetWithContext(ctx context.Context, rawURL string) (Response, error)

GetWithContext will create a Request for the given rawURL and call DoWithContext on it.

type FileHandler

type FileHandler struct {
	slog.Handler
	// contains filtered or unexported fields
}

func NewFileHandler

func NewFileHandler(ctx context.Context, wc io.WriteCloser) FileHandler

type Header

type Header struct {
	Meta   string
	Status StatusCode
}

func (Header) String

func (hdr Header) String() string

type NoopCloser

type NoopCloser struct {
	io.Writer
}

func (NoopCloser) Close

func (NoopCloser) Close() error

type NoopHandler

type NoopHandler struct{}

func (NoopHandler) Enabled

func (NoopHandler) Enabled(context.Context, slog.Level) bool

func (NoopHandler) Handle

func (NoopHandler) Handle(context.Context, slog.Record) error

func (NoopHandler) WithAttrs

func (NoopHandler) WithAttrs(attrs []slog.Attr) slog.Handler

func (NoopHandler) WithGroup

func (NoopHandler) WithGroup(string) slog.Handler

type Options

type Options struct {
	StorePath       string
	RCFilepath      string
	DumpHeaders     string
	Trace           string
	Timeout         time.Duration
	FollowRedirects bool
	Insecure        bool
}

type OptsFn

type OptsFn func(*Options)

func WithInMemoryStore

func WithInMemoryStore() OptsFn

func WithInsecure

func WithInsecure() OptsFn

func WithStore

func WithStore(val string) OptsFn

type Request

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

Request is a simple struct which wraps around a url.URL, providing a few methods around it.

func NewRequest

func NewRequest(rawURL string) (Request, error)

NewRequest will take a raw url and parse it into a url.URL version. It will take care of setting some fields, like the scheme and port, if they are blank.

func (Request) String

func (r Request) String() string

func (Request) Valid

func (r Request) Valid() error

func (Request) Write

func (r Request) Write(w io.Writer) error

Write will take any io.Writer and write the request on it in the format of: <URL>\r\n returning errors if the bytes written did not match the expected amount.

type Response

type Response struct {
	Header  Header
	MIME    string
	Content []byte
}

func ReadResponse

func ReadResponse(r io.Reader) (Response, error)

type StatusCode

type StatusCode uint16

const (
	Unset                      StatusCode = 0
	Input                      StatusCode = 10
	SensitiveInput             StatusCode = 11
	Success                    StatusCode = 20
	RedirectTemporary          StatusCode = 30
	RedirectPermanent          StatusCode = 31
	TemporaryFailure           StatusCode = 40
	ServerUnavailable          StatusCode = 41
	CGIError                   StatusCode = 42
	ProxyError                 StatusCode = 43
	SlowDown                   StatusCode = 44
	PermanentFailure           StatusCode = 50
	NotFound                   StatusCode = 51
	ClientCertificatedRequired StatusCode = 60
	CertificateNotAuthorized   StatusCode = 61
	CertificateNotValid        StatusCode = 62
)

func (StatusCode) IsSuccess

func (code StatusCode) IsSuccess() bool

func (StatusCode) String

func (code StatusCode) String() string