spacecookie

Haskell gopher server daemon and library.

Features

• implements RFC1436
• optionally supports common protocol extensions:
  • informational entries via the i-type
  • h-type and URL entries
• supports gophermaps (see below)
• supports systemd socket activation
• provides a library for custom gopher applications (see documentation)

Non-Features

spacecookie intentionally does not support:

• HTTP, Gemini: Multi protocol support is a non-goal for spacecookie. For HTTP you can proxy pretty easily, however.
• Search: Gopher supports search transactions, but the spacecookie daemon doesn't offer the possibility to add a search engine to a gopherspace. It is however entirely possible to implement an index search server using the spacecookie library

Installation

• Nix(OS): pkgs.haskellPackages.spacecookie (see also below)
• Cabal: cabal v2-install spacecookie (see also hackage package)

Documentation

• User Documentation: spacecookie(1)
• Developer Documentation

Configuration

spacecookie is configured via a JSON configuration file. All available options are documented in spacecookie.json(5). This repository also contains an example configuration file in etc/spacecookie.json.

Running

After you've created your config file just start spacecookie like this:

spacecookie /path/to/spacecookie.json

spacecookie runs as a simple process and doesn't fork or write a PID file. Therefore any supervisor (systemd, daemontools, ...) can be used to run it as a daemon.

With systemd

spacecookie supports systemd socket activation. To set it up you'll need to install spacecookie.service and spacecookie.socket like so:

cp ./etc/spacecookie.{service,socket} /etc/systemd/system/
systemctl daemon-reload
systemctl enable spacecookie.socket
systemctl start  spacecookie.socket
systemctl start  spacecookie.service # optional, started by the socket automatically if needed

Of course make sure that all the used paths are correct!

How the systemd integration works is explained in spacecookie(1).

On NixOS

NixOS provides a service module for spacecookie: services.spacecookie. Setting up spacecookie is as simple as adding the following line to your configuration.nix:

services.spacecookie.enable = true;

For all available options, refer to the NixOS manual:

• NixOS stable
• NixOS unstable

Adding Content

spacecookie acts as a simple file server, only excluding files or directories that start with a dot. It generates gopher menus automatically, but you can also use custom ones by adding a gophermap file.

spacecookie checks for .gophermap in every directory it serves and, if present, uses the menu specified in there.

Such a file looks like this:

You can just start writing text that
will be displayed by the gopher client
without a link to a file. Empty lines are
also possible.

1Menu Entry for a directory full of funny stuff	/funny
IFunny Image	/funny.jpg
gcat gif	/cat.gif
0about me	/about.txt
1Floodgap's gopher server	/	gopher.floodgap.com	70

As you can see, it largely works like the actual gopher menu a server will send to clients, but allows to omit redundant information and to insert lines that are purely informational and not associated with a file. spacecookie.gophermap(5) explains syntax and semantics in more detail.

The format is compatible with the ones supported by Bucktooth and pygopherd. If you notice any incompatibilities, please open an issue.

Portability

spacecookie is regularly tested on GNU/Linux via CI, but should also work on other Unix-like operating systems. Most portability problems arise due to haskell-socket which is for example known not to work on OpenBSD.

Windows support would be possible, but could be tricky as gopher expects Unix-style directory separators in paths. I personally don't want to invest time into it, but would accept patches adding Windows support.