Simple webring implementation
a month ago

0b80d60 handlers: Fix off-by-one in previous endpoint

a month ago


REUSE status Donate with fosspay Time spent on project

Simple webring implementation created for the Fediring

git clone https://git.sr.ht/~amolith/go-webring
cd go-webring
pandoc -s index.md -o index.html
go build


$ ./go-webring -h
Usage of ./go-webring
  -c, --contact string         Contact instructions for errors (default "contact the admin and let them know what's up")
  -h, --host string            Host this webring runs on, primarily used for validation
  -i, --index string           Path to home page template (default "index.html")
  -l, --listen string          Host and port go-webring will listen on (default "")
  -m, --members string         Path to list of webring members (default "list.txt")
  -v, --validationlog string   Path to validation log, see docs for requirements (default "validation.log")

This webring implementation handles four paths:

  • Root: returns the home page template replacing the string "{{ . }}" with an HTML table of ring members
  • Next: returns a 302 redirect pointing to the next site in the list
  • Previous: returns a 302 redirect pointing to the previous site in the list
  • Random: returns a 302 redirect pointing to a random site in the list
  • $validationlog: displays the validation log at the path specified in the command line flags
    • For example, with -v validationlog -h example.com, the path would be example.com/validationlog

The next and previous paths require a ?host= parameter containing a URL-encoded URI of the site being visited. For example, if Sam is a member of a webring on example.com and her site is sometilde.com/~sam, she will need the following links on her page for directing visitors to the next/previous ring members.

  • https://example.com/next?host=sometilde.com%2F~sam
  • https://example.com/previous?host=sometilde.com%2F~sam

#With provided examples

See the included list.txt and index.md for examples of a webring setup. To run go-webring with those examples, first install pandoc then generate index.html from index.md like so:

$ pandoc -s index.md -o index.html

Next, you'll need to install Go and build the project.

$ go build

After that, simply execute the binary then open localhost:2857 in your browser.

$ ./go-webring

#With custom files

To run your own webring, you'll first need a template homepage. This should be any HTML file with the string "{{ . }}" placed wherever you want the table of members inserted. This table is plain HTML so you can style it with CSS.

Pandoc produces very pleasing (in my opinion) standalone HTML pages; if you just want something simple, I would recommend modifying the included index.md and generating your homepage as in section above.

To serve other assets, such as styles in a separate .css file, images, etc., place them in the static/ directory; a file at static/favicon.ico will be accessible at https://example.com/static/favicon.ico.

Next, you'll need a text file containing a list of members. On each line should be the member's unique identifer (such as their username) followed by a single space followed by their site's URI omitting the scheme. For example, if a user is bob and his site is https://bobssite.com, his line would look like the following.

bob bobssite.com

If the user was sam and her site was https://sometilde.com/~sam, her line would look like this:

sam sometilde.com/~sam

With those two members in the text file, the HTML inserted into the home page will be the following.

  <td><a href="https://bobssite.com">bobssite.com</a><td>
  <td><a href="https://sometilde.com/~sam">sometilde.com/~sam</a><td>

Assuming this webring is on example.com, Bob will need to have the following links on his page.

  • https://example.com/next?host=bobssite.com
  • https://example.com/previous?host=bobssite.com

Because Sam has a forward slash in her URI, she'll need to percent-encode it so browsers interpret the parameter correctly.

  • https://example.com/next?host=sometilde.com%2F~sam
  • https://example.com/previous?host=sometilde.com%2F~sam


At startup, a concurrent process spins off, checks every member's site for issues, generates a report, and serves the report at the location specified in the command line flag. It rechecks sites every 24 hours and identifies TLS errors, unreachable sites, and sites with missing links. It will eventually follow redirects too, allowing members to move their site without having to notify ring maintainers.

There are some false positives right now, but I'm working on correcting those.

#Questions & Contributions

Questions, comments, and patches can always be sent to my public inbox, but I'm also in my IRC channel/XMPP room pretty much 24/7. However, I might not see messages right away because I'm working on something else (or sleeping) so please stick around!

If you're wanting to introduce a new feature and I don't feel like it fits with this project's goal, I encourage you to fork the repo and make whatever changes you like!

If you haven't used mailing lists before, please take a look at SourceHut's documentation, especially the etiquette section.