libgemini

package module
v0.0.0-...-86a058e Latest Latest
Warning

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

 Go to latest Published: Oct 21, 2024 License: BSD-3-Clause Imports: 16 Imported by: 0

README

CI status License Go Report Card

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

View Source 
const (
	StdOutKey = ":stdout:"
	StdErrKey = ":stderr:"
)
View Source 
const (
	DefaultTimeout         = time.Second * 30
	DefaultFollowRedirects = false
	DefaultInsecure        = false
	InMemoryStoreVal       = ":memory:"
)
View Source 
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"
)
View Source 
const (
	ConfigFollowRedirects = "follow"
	ConfigStore           = "store"
	ConfigDumpHeaders     = "dump-headers"
	ConfigTrace           = "trace"
	ConfigInsecure        = "insecure"
)
View Source 
const (
	UserRWAllR     = fs.FileMode(0o644)
	UserRWXAllNone = fs.FileMode(0o700)
)
View Source 
const (
	CRLF = "\r\n"
)
View Source 
const (
	TerminatorSize = 2 // Size of \r\n.

)

Variables

This section is empty.

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 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(_ []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

Source Files

View all Source files

Directories

Path Synopsis
examples
simpleclient

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.