package module
Version: v0.1.0 Latest Latest

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

Go to latest
Published: Sep 16, 2018 License: BSD-3-Clause Imports: 13 Imported by: 0



GoDoc Build Status

Gum is a personal short URL resolver written in Go. It is primarily designed to be used with statically generated sites.

This is the URL resolver I run behind (and my short domain For example, redirects to this project on GitHub. So far, I've only implemented those handlers I use on my own site, but everything should be easily usable by others.

Building with go 1.11 is recommended.

Getting Started

Install the package using:

go get

Once installed, ensure $GOPATH/bin is in your $PATH, then run using:


This will start gum on port 4594. Test this by navigating to http://localhost:4594/ and you should see a blank page (since no redirects have been configured yet).

Path Redirects

Path redirects allow a specified path prefix, and all URLs under that prefix, to be redirected to a destination URL. The portion of the URL after the prefix is resolved relative to the destination. Note that this means that the destination should normally include a trailing slash.

Path redirects are specified with the redirect flag, which takes a value of the form prefix=destination. For example, to redirect all /w URLs to the English version of Wikipedia, run:

gum -redirect "w="

Load http://localhost:4594/w/URL_shortening and you should be redirected to the appropriate Wikipedia article. An empty prefix or a value of "/" will redirect all URLs.

The redirect flag can be repeated multiple times. Longer prefix values will take precedence over shorter ones following the behavior of http.ServeMux.

Static File Redirects

Gum can parse HTML file and automatically register redirects based on the links specified in the files. Gum will look for files with both a rel="canonical" and rel="shortlink" link. If found, it will configure redirects from the shortlink URL path to the canonical URL. For example, assume an HTML file with the contents:

  <link rel="canonical" href="">
  <link rel="shortlink" href="">

Gum will configure a redirect from /t123 to Note that only the path of the shortlink is used for creating the redirect.

Static file redirects are configured with the static_dir flag, which identifies the root directory containing the HTML files. Gum will recursively parse all files with a .html file extension, looking for the appropriate link tags. It will additionally watch the specified directory for any changes and will automatically load new or updated files.

Note that when using gum with a static site generator, static_dir should identify the folder containing the generated HTML files (for example, the _site folder when using jekyll), not the source files.

Static file redirects will take precedence over equivalent path redirects.

Alternate Short URLs

An HTML file can also specify multiple alternate short URLs to register for a given canonical URL. This is useful, for example, if you have legacy short URLs that you want to continue resolving. Alternate short URLs are specified on the rel="shortlink" link as a space separated list of URLs in the data-alt-href attribute. For example:

<link rel="shortlink" href=""

Gum will resolve all of the shortlinks /t123, /b/123, and /b/456 to the relevant canonical URL.


Gum is copyright Google, but is not an official Google product. It is available under a BSD License.



Package gum provides the gum personal short URL resolver.



This section is empty.


This section is empty.


This section is empty.


type Handler

type Handler interface {
	// Register the handler with the provided ServeMux.  This method will be
	// called when the handler is added to the mux, and allows the
	// handler to specify the kinds of short URLs it can handle.
	// Typically, but not always, this will be URLs of the form "/x" and
	// /x/*" where x is a particular content type.
	Register(*http.ServeMux) error

	// Mappings provides a write only channel for the handler to write
	// static Mapping values onto.  These mappings are then registered with
	// and the redirects handled by the Server.
	Mappings(chan<- Mapping) error

A Handler serves requests for short URLs. Typically, a handler will register itself for an entire path prefix using the Register func, or provide a list of static mappings using the Mappings func.

type Mapping

type Mapping struct {
	// ShortPath is the path of the short URL (including leading slash) to
	// be mapped.
	ShortPath string

	// Permalink is the destination URL being mapped to.
	Permalink string

Mapping represents a mapping between a short URL path and the permalink URL it is for.

type RedirectHandler

type RedirectHandler struct {
	// Prefix is the path component prefix this handler should handle.
	// Prefix should not contain leading or trailing slashes.
	Prefix string

	// Destination is the base URL to redirect requests to.  If Destination
	// includes a path, it should typically include a trailing slash.
	Destination *url.URL

	// Status is the HTTP status to return in redirect responses.
	Status int

RedirectHandler redirects requests that match a given path component prefix to a specified destination base URL. For example, given a RedirectHandler:

    Prefix: "x",
    Destination: "http://example/",

The following URLs would be redirected:

/x          =>  http://example/
/x/         =>  http://example/
/x/a/b?c=d  =>  http://example/a/b?c=d

The request URL "/x123" would not be handled by this handler.

func NewRedirectHandler

func NewRedirectHandler(prefix, destination string) (*RedirectHandler, error)

NewRedirectHandler constructs a new RedirectHandler with the specified prefix and destination, and a 301 (Moved Permanently) response status.

func (*RedirectHandler) Mappings

func (h *RedirectHandler) Mappings(mappings chan<- Mapping) error

Mappings implements the Handler interface.

func (*RedirectHandler) Register

func (h *RedirectHandler) Register(mux *http.ServeMux) error

Register this handler with the provided ServeMux.

func (*RedirectHandler) ServeHTTP

func (h *RedirectHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)

type Server

type Server struct {
	// contains filtered or unexported fields

Server is a short URL redirection server.

func NewServer

func NewServer() *Server

NewServer constructs a new Server.

func (*Server) AddHandler

func (s *Server) AddHandler(h Handler) error

AddHandler adds the provided Handler to the server.

func (*Server) ServeHTTP

func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements http.Handler.

type StaticHandler

type StaticHandler struct {
	// contains filtered or unexported fields

StaticHandler handles short URLs parsed from static HTML files. Files are parsed and searched for rel="shortlink" and rel="canonical" links. If both are found, a redirect is registered for the pair.

func NewStaticHandler

func NewStaticHandler(base string) (*StaticHandler, error)

NewStaticHandler constructs a new StaticHandler with the specified base path of HTML files.

func (*StaticHandler) Mappings

func (h *StaticHandler) Mappings(mappings chan<- Mapping) error

Mappings implements Handler.

func (*StaticHandler) Register

func (h *StaticHandler) Register(mux *http.ServeMux) error

Register is a noop for this handler.


Path Synopsis
The gum binary starts up a gum server.
The gum binary starts up a gum server.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL