vanity

Vanity

Vanity is a simple Go vanity URL server.

Concepts

Go tools like the go get and go install commands use a Go package's import path to locate the repository containing that package. When locating a package, go get makes an HTTP GET request to the URL designated by the import path and looks for a <meta> tag in the response. The contents of this tag tells go get where the repository containing that package is located and what type of version control system is used. (For more information about how Go locates a repository, see the Go Modules Reference).

Popular code hosting providers like SourceHut and GitHub serve this <meta> tag automatically, so import paths like github.com/johndoe/mymodule/mypkg need no configuration to work with go get. However, many package authors prefer to use their own domain name in the package path to make it possible to switch code hosting providers without changing the import path. These custom import paths are more informally known as vanity URLs. Vanity is a bare-bones web server that serves the necessary <meta> tag so that go get can locate the package's repository.

In order to function, Vanity requires a single piece of information: the repository base URL. Vanity assumes that all repositories are immediate children of this base URL. For example, if you store your code in GitHub and your GitHub username is johndoe, then the repository base URL would be https://github.com/johndoe.

When receiving an HTTP request, Vanity extracts the first path segment from the request URL and uses this as the repository name. Any additional path segments would correspond to repository subdirectories and are ignored by Vanity. This repository name is appended to the repository base URL to form the full repo URL that is returned in the response. If the repository name is not the first path segment after the domain, as in golang.org/x/mymodule, use a reverse proxy to remove the path prefix before passing the request to Vanity (e.g. GET /x/mymodule HTTP/1.1 should be rewritten to GET /mymodule HTTP/1.1).

Note that Vanity can work on multiple domains simultaneously; Vanity obtains the domain name from the Host request header. The only requirement is that the first path segment match the repository name.

Installation

To install the self-contained Vanity binary, run:

go install dwh.moe/vanity/cmd/vanity@latest

Usage

To start a vanity server, simply pass the repository base URL on the command line:

vanity [flags] repo-base-url

The server will listen for requests on port 8000 by default. Use the -p flag to change this. For example, to run a server on port 4000 pointing to the GitHub repositories of johndoe, run:

vanity -p 4000 https://github.com/johndoe

Use the -vcs flag to specify the version control system (defaults to Git). The supported options are bzr, fossil, git, hg, or svn.

Integration

To integrate Vanity into an existing Go web app, import dwh.moe/vanity and create a server with vanity.New():

package main

import "dwh.moe/vanity"

const (
	repoBaseURL = "https://git.sr.ht/~johndoe"
	vcs         = vanity.VCSGit
)

func main() {
	// vanitySrv implements net/http.Handler
	vanitySrv := vanity.New(repoBaseURL, vcs)
	http.Handle("/", vanitySrv)
}