README
¶
gum
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 willnorris.com (and my short domain wjn.me). For example, wjn.me/c/gum 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 willnorris.com/go/gum/cmd/gum
Once installed, ensure $GOPATH/bin is in your $PATH, then run using:
gum
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=https://en.wikipedia.org/wiki/"
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:
<html>
<link rel="canonical" href="http://example.com/post/123">
<link rel="shortlink" href="http://x.com/t123">
</html>
Gum will configure a redirect from /t123 to http://example.com/post/123.
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="http://x.com/t123"
data-alt-href="http://x.com/b/123 http://x.com/b/456">
Gum will resolve all of the shortlinks /t123, /b/123, and /b/456 to the
relevant canonical URL.
License
Gum is copyright Google, but is not an official Google product. It is available under a BSD License.
Documentation
¶
Overview ¶
Package gum provides the gum personal short URL resolver.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
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:
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 (*Server) AddHandler ¶
AddHandler adds the provided Handler to the server.
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.
Source Files
Directories