💾 Archived View for freeside.wntrmute.net › src › gemini.gmi captured on 2023-06-16 at 16:22:26. Gemini links have been rewritten to link to archived content

-=-=-=-=-=-=-

gemini (go)

Godoc

Getting

hg clone https://hg.sr.ht/~kisom/gemini && cd gemini && sudo make install
go get hg.sr.ht/~kisom/gemini/

Using the client library

Fetching pages

The easiest way to show how to use the client is to look at the

source for the gemcurl(1) utility.

func curl(c *gemini.Client, uri string) error {
        resp, err := c.Fetch(uri)
        if err != nil {
                return err
        }

        if resp.HasBody() {
                defer resp.Body.Close()
                io.Copy(os.Stdout, resp.Body)
                return nil
        }

        fmt.Fprintf(os.Stderr,
		"The server returned status %s.\n",
		resp.Status)
        return nil
}

StaticServer

The static server is a basic static file server. The gemsrvwd(1)

source code is 31 lines long:

package main

import (
	"crypto/tls"
	"flag"
	"log"

	"hg.sr.ht/~kisom/gemini"
)

func main() {
	s := &gemini.StaticServer{}
	flag.StringVar(&s.Address, "a", "localhost:1965", "address to listen on")
	flag.Parse()

	cert, key, err := gemini.GenCert(false, true)
	if err != nil {
		log.Fatal(err)
	}

	if flag.NArg() > 0 {
		s.Root = flag.Arg(0)
	}

	s.Certificate, err = tls.X509KeyPair(cert, key)
	if err != nil {
		log.Fatal(err)
	}

	log.Fatal(s.ListenAndServe())
}

Utilities

A couple of functions are useful for various tasks:

func CanonicalizeURL(uri string, subPaths ...string) (*url.URL, error)
func GenCert(legacy bool, asPEM bool, serverNames ...string) (cert, key []byte, err error)

CanonicalizeURL will take a base URI and clean it; if it doesn't have

an associated protocol, it will be given the gemini protocol. Any

provided subpaths will be append to the URL appropriately. Retrieving

the returned URL can be done with the `String()` method.

GenCert will generate a TLS certificate and private key; either a

legacy RSA-2048 or modern P521 key. If asPEM is true, the returned key

and certificate will be PEM-encoded; otherwise, they're DER-encoded.

Subscriptions

The package has support for simple Gemini subscriptions.

Companion spec for subscriptions

The Subscriptions struct is used to set up a subscription feed. At the

most basic level, only the Gemlogs field needs to be set; these should

be URLs pointing to the gemlogs to subscribe to. The Gemini client can

be customised via the Client field; the Title field is used to when

generating a listing page. After calling Fetch, the Feeds field will

contain the entries from the subscribed gemlogs.

Command line tools

gemcurl

gemcurl is a curl-like tool for gemini.

gemsrvwd

gemsrvwd serves a working directory over gemini.

gemcertgen

gemcertgen generates a TLS keypair for use with a gemini server.

gemsubs

gemsubs fetches the latest entries for a list of gemlogs and generates

a listing page. It can be used in CGI mode (e.g. it will write a

status header).