vanity

README

Vanity

A vanity import path is any import path that can be downloaded with go get but isn't otherwise blessed by the go tool (e.g. GitHub, BitBucket, etc.). A commonly used vanity import path is "golang.org/x/...". This package attempts to mimic the behavior of "golang.org/x/..." as closely as possible.

Features

• Redirects browsers to godoc.org (or somewhere else)
• Redirects Go tool to VCS
• Redirects godoc.org to browsable files

Installation

go get go.jonnrb.io/vanity

Specification

• Remote Import Paths
• GDDO Source Code Links
• Custom Import Path Checking

Contributing

Shoot me an email with a repo and branch to pull (or even better, use git-request-pull).

Documentation

Overview

Package vanity implements custom import paths (Go vanity URLs) as an HTTP handler that can be installed at the vanity URL.

Index

• func GitHubHandler(importPath, user, repo, gitScheme string) http.Handler
• func GogsHandler(importPath, host, user, repo, gitScheme string) http.Handler
• func Handler(opts ...Option) http.Handler
• type Option
  • func WithGitHubStyleSource(importPath, repoPath, ref string) Option
  • func WithGogsStyleSource(importPath, repoPath, ref string) Option
  • func WithImport(importPath, vcs, vcsRoot string) Option
  • func WithRedirector(redir Redirector) Option
  • func WithSource(prefix, home, directory, file string) Option
• type Redirector

Examples

• GitHubHandler

Functions

func GitHubHandler

func GitHubHandler(importPath, user, repo, gitScheme string) http.Handler

Creates a Handler that serves a GitHub repository at a specific importPath.

Example

// Redirects the vanity import path "go.jonnrb.io/vanity" to the code hosted
// on GitHub by user (or organization) "jonnrb" in repo "vanity" using the
// git over "https".
h := GitHubHandler("go.jonnrb.io/vanity", "jonnrb", "vanity", "https")

http.Handle("/vanity", h)
http.Handle("/vanity/", h) // to handle requests for subpackages.

http.ListenAndServe(":http", nil)

func GogsHandler

func GogsHandler(importPath, host, user, repo, gitScheme string) http.Handler

Creates a Handler that serves a repository hosted with Gogs at host at a specific importPath.

func Handler

func Handler(opts ...Option) http.Handler

Returns an http.Handler that serves the vanity URL information for a single repository. Each Option gives additional information to agents about the repository or provides help to browsers that may have navigated to the vanity URL. The WithImport Option is mandatory since the go tool requires it to fetch the repository.

Types

type Option

type Option func(*config)

Configures the Handler. The only required option is WithImport.

func WithGitHubStyleSource

func WithGitHubStyleSource(importPath, repoPath, ref string) Option

Redirects gddo to browsable source files for GitHub hosted repositories.

func WithGogsStyleSource

func WithGogsStyleSource(importPath, repoPath, ref string) Option

Redirects gddo to browsable source files for Gogs hosted repositories.

func WithImport

func WithImport(importPath, vcs, vcsRoot string) Option

Instructs the go tool where to fetch the repo at vcsRoot and the importPath that tree should be rooted at.

func WithRedirector

func WithRedirector(redir Redirector) Option

func WithSource

func WithSource(prefix, home, directory, file string) Option

Instructs gddo (godoc.org) how to direct browsers to browsable source code for packages and their contents rooted at prefix.

home specifies the home page of prefix, directory gives a format for how to browse a directory, and file gives a format for how to view a file and go to specific lines within it.

More information can be found at https://github.com/golang/gddo/wiki/Source-Code-Links.

type Redirector

type Redirector func(pkg string) (url string)

When a browser navigates to the vanity URL of pkg, this function rewrites pkg to a browsable URL.