Shortlinks and go-get redirects
git clone git://git.danielmoch.com/go-shrt.git
Log | Files | Refs | README | LICENSE

commit 0385c3532de24268a336a7704cc8ecee77c1e63a
parent abd45c8bb0d1a36197f7782f8afd05c58aa9ceb6
Author: Daniel Moch <daniel@danielmoch.com>
Date:   Sun,  6 Dec 2020 20:16:15 -0500

Add go doc documentation

Mcmd/shrt/main.go | 28++++++++++++++++++++++++++++
Adoc.go | 4++++
Mshrtfile.go | 24++++++++++++++++++++++++
3 files changed, 56 insertions(+), 0 deletions(-)

diff --git a/cmd/shrt/main.go b/cmd/shrt/main.go @@ -1,3 +1,31 @@ +// See LICENSE file for copyright and license details + +// shrt is a URL shortener service (much like bit.ly without the +// trackers) that also handles go-get requests. The latter are a +// specific GET request query used by the Go programming language +// toolchain to aid in the downloading of utilities and libraries +// prior to build and installation. +// +// Upon invocation, shrt does one of two things depending +// on the presence or absence of the init argument. If the init +// argument is present, a series of questions is asked, the responses +// are recorded in a configuration file, and the program exits. If +// the init argument is absent, shrt reads the configuration and +// database files into memory, binds to the port specified by the +// -l flag, and begins serving requests. +// +// Shortlinks are recorded in the database, and any request path +// not matching a shortlink is assumed to be a go-get request. This +// is by design, but can result in specious redirects. Additionally, +// subdirectory paths are not allowed. +// +// Shortlinks generate an HTTP 301 response. Go-get requests generate +// an HTTP 200 response. If configured, requests to the base path +// (i.e., "/") generate an HTTP 302 response. +// +// In order to add a new shortlink to the database, simply edit the +// file. After saving, send SIGHUP to a running server process to +// reload the file. package main import ( diff --git a/doc.go b/doc.go @@ -0,0 +1,4 @@ +// The shrt module implements a simple (perhaps simplistic) URL +// shortener. It also handles go-get requests. See the cmd/shrt +// package documentation for a fuller explanation of the server. +package shrt diff --git a/shrtfile.go b/shrtfile.go @@ -7,11 +7,23 @@ import ( "strings" ) +// The ShrtFile struct contains the data read from a specially-formatted +// file. The syntax of the file is human readable. Each line +// represents a key-value pair. The key is everything to the left +// of the first equals sign, and the value is everything to the +// right. Whitespace is trimmed from the beginning and end of both +// keys and values. type ShrtFile struct { m map[string]string path string } +// The NewShrtFile function creates a new ShrtFile. The filesystem +// is checked for the existence of a node at the specified path, +// and the NewShrtFile returns an error if something is there. This +// constitutes a weak check, since a file could easily be created +// before Write() is called, in which case the existing file will +// be truncated. func NewShrtFile(path string) (*ShrtFile, error) { // we fail if the file already exists, so the logic is reversed // from the usual here @@ -25,6 +37,9 @@ func NewShrtFile(path string) (*ShrtFile, error) { return &ShrtFile{m: make(map[string]string), path: path}, nil } +// The ReadShrtFile function reads an existing ShrtFile from the +// filesystem and returns a pointer to a ShrtFile object. See the +// ShrtFile documentation for the expected file format. func ReadShrtFile(db string) (*ShrtFile, error) { var newFile ShrtFile newFile.m = make(map[string]string) @@ -47,14 +62,23 @@ func ReadShrtFile(db string) (*ShrtFile, error) { return &newFile, nil } +// The Get method gets the value of the specified key. If the key +// does not exist, an empty string is returned. func (s *ShrtFile) Get(key string) string { return s.m[key] } +// The Put method adds a the specified value, associating it with +// the specified key. The value is overwritten if the key already +// exists. func (s *ShrtFile) Put(key, value string) { s.m[key] = value } +// The Write method serializes the contents of the ShrtFile to the +// file path specified when the ShrtFile was created. If a file +// already exists at the specified path, it is truncated and +// overwritten. func (s *ShrtFile) Write() error { f, err := os.Create(s.path) if err != nil {