importshttp

package module
v0.0.0-...-ab6f6c1 Latest Latest
Warning

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

Go to latest
Published: Sep 4, 2021 License: MIT Imports: 9 Imported by: 0

README

go.dpb.io/importshttp

Utilities for hosting Go packages on custom/vanity domains.

  • automatic go-import and go-source parameters used by Go tooling
  • theming with professional listing and package views by default
  • configurable action links for packages (e.g. pkg.go.dev, repository source, custom URLs)
  • used as a server, static site generator, or generic http.Handler
  • YAML-based or programmatic configuration

Usage

For a live example, visit go.dpb.io (source; automated via Cloud Build and deployed to Cloud Run).

To run a server locally, use the cmd/server package...

go run go.dpb.io/importshttp/cmd/server \
  -pkg=go.example.com/firstpackage=github.com/golang/go/tree/master \
  -pkg=go.example.com/secondpackage=bitbucket.org/example/secondpackage/src/master

To publish a static site with GitHub Pages + Actions, use the dpb587/go-importshttp-for-github template.

Learn more from the examples directory and code documentation.

License

MIT License

Documentation

Index

Constants

This section is empty.

Variables

View Source
var ErrRepositoryConfigNotSupported = errors.New("repository config not supported")

ErrRepositoryConfigNotSupported indicates the config is not supported (e.g. expects git, but got svn; or server does not match).

View Source
var ThemeFilePrefix = "/_theme/"

ThemeFilePrefix is the location relative to Handler where custom files are available from.

Functions

func IsGoGetRequest

func IsGoGetRequest(r *http.Request) bool

IsGoGetRequest checks if the request has the expected "go-get=1" param in the query string.

Types

type BestEffortRepositoryFactory

type BestEffortRepositoryFactory []RepositoryFactory

BestEffortRepositoryFactory uses multiple repository factories in attempting to convert a RepositoryConfig, ignoring some expected conversion errors in favor of trying another factory.

func (BestEffortRepositoryFactory) NewRepository

func (rfl BestEffortRepositoryFactory) NewRepository(config RepositoryConfig) (Repository, error)

type CustomLinker

type CustomLinker struct {
	// Ordering which will be propagated to any generated Link.
	Ordering int

	// Label which will be propagated to any generated Link.
	Label string

	// PkgTemplate may use the `{/pkg}` placeholder.
	PkgTemplate string

	// DirTemplate may use the `{/pkg}` and `{/dir}` placeholders. If empty, PkgTemplate is used.
	DirTemplate string
}

CustomLinker generates a link with a configurable URL template.

func (l CustomLinker) Link(pkg Package) *Link

type CustomRepository

type CustomRepository struct {
	VCS  VCS
	Root string
}

CustomRepository supports any VCS and repository root.

Consider using service-specific Repository types, when applicable, since they include built-in SourceRepository behaviors.

func (CustomRepository) RepositoryRoot

func (r CustomRepository) RepositoryRoot() string

func (CustomRepository) RepositoryVCS

func (r CustomRepository) RepositoryVCS() VCS

type CustomRepositoryFactory

type CustomRepositoryFactory struct{}

CustomRepositoryFactory supports creating a CustomRepository from a RepositoryConfig.

TODO this is not fully following specs yet; weird mix of go vs url pkg parsing; https://github.com/golang/go/blob/2ebe77a2fda1ee9ff6fd9a3e08933ad1ebaea039/src/cmd/go/internal/vcs/vcs_test.go

func (CustomRepositoryFactory) NewRepository

func (rf CustomRepositoryFactory) NewRepository(config RepositoryConfig) (Repository, error)

type CustomSourceRepository

type CustomSourceRepository struct {
	Repository
	URL             string
	DirTemplateURL  string
	FileTemplateURL string
}

CustomSourceRepository supports configuring source URLs for a given Repository.

func (CustomSourceRepository) RepositoryRoot

func (r CustomSourceRepository) RepositoryRoot() string

func (CustomSourceRepository) RepositoryVCS

func (r CustomSourceRepository) RepositoryVCS() VCS

func (CustomSourceRepository) SourceDirTemplateURL

func (r CustomSourceRepository) SourceDirTemplateURL() string

func (CustomSourceRepository) SourceFileTemplateURL

func (r CustomSourceRepository) SourceFileTemplateURL() string

func (CustomSourceRepository) SourceURL

func (r CustomSourceRepository) SourceURL() string

type GoImportSpec

type GoImportSpec struct {
	Prefix   string
	VCS      VCS
	RepoRoot string
}

func (GoImportSpec) MetaContent

func (v GoImportSpec) MetaContent() string

type GoSourceSpec

type GoSourceSpec struct {
	RepoRootPrefix string
	RepoURL        string
	DirTemplate    string
	FileTemplate   string
}

func (GoSourceSpec) MetaContent

func (v GoSourceSpec) MetaContent() string

type Handler

type Handler struct {
	// contains filtered or unexported fields
}

func NewHandler

func NewHandler(site Site, theme Theme, packageList PackageList) *Handler

func (Handler) ServeHTTP

func (h Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
type Link struct {
	// Ordering is used to sort multiple links - lower values imply more importance.
	Ordering int

	// Label is the text shown for the link.
	Label string

	// URL is the destination address.
	URL string
}

Link is an address for finding more information.

type LinkList []Link

LinkList adds utility to a list of links.

func (LinkList) SortByOrdering

func (ll LinkList) SortByOrdering()

SortByOrdering reorders the list by Ordering in ascending, numeric order.

type Linker

type Linker interface {
	Link(pkg Package) *Link
}

Linker

type LinkerList

type LinkerList []Linker

LinkerList adds utility to a list of linkers.

func (ll LinkerList) GetPackageLinks(pkg Package) LinkList

GetPackageLinks will return a list of any generated links for the package.

func (LinkerList) MapPackageList

func (ll LinkerList) MapPackageList(pkgs PackageList) PackageList

type Package

type Package struct {
	// Import should be a module path - the canonical name for a module. For older, non-module repos this is typically the
	// repository root path. There must not be a leading or trailing slash.
	Import string

	// ImportSubpackage is an optional subpackage within the import. There must not be a leading or trailing slash.
	//
	// Typically this should be empty when configuring Package - this is mostly used when subpackage routing is enabled to
	// support dynamic subpackage information.
	ImportSubpackage string

	// Repository provides repository details for the Import.
	//
	// Note that ImportSubpackage would be considered a value for the "{/dir}" attribute and Repository should not already
	// be including it.
	Repository Repository

	// Deprecated indicates the go.mod file has the deprecated directive.
	Deprecated bool

	// Unlisted indicates this package should not be shown in any lists when rendering. Direct routes to this package or
	// its subpackages continue to work.
	Unlisted bool

	// Links are a list of relevant resources for this package. The lowest-order link is considered primary and may be
	// featured more prominently.
	Links LinkList

	// Metadata is arbitrary data intended for themes.
	Metadata map[string]interface{}
}

Package represents a Go package which can be imported and includes details about its repository, deprecation status, and useful metadata for rendering information to users.

These values require more explicit configuration since this package does not perform any of the dynamic resolution steps of, for example, the package argument given to "go get".

func (Package) GoImport

func (i Package) GoImport() *GoImportSpec

GoImport builds the go-import spec.

func (Package) GoSource

func (i Package) GoSource() *GoSourceSpec

GoSource builds the go-source spec (if possible).

func (Package) Path

func (i Package) Path() string

Path is the package path - the combination of Import and ImportSubpackage.

type PackageList

type PackageList []Package

PackageList adds utility to a list of packages.

func (PackageList) FilterByListed

func (pl PackageList) FilterByListed() PackageList

FilterByListed will drop any packages whose Unlisted field is true.

func (PackageList) FilterByParent

func (pl PackageList) FilterByParent(parentpkgpath string) PackageList

FilterByParent returns all packages which appear as a direct subpackage of the input.

func (PackageList) Find

func (pl PackageList) Find(expected string) (Package, bool, bool)

Find will search the list for a package by the expected import. If an exact match is not found, the longest matching package will be returned (with the ImportSubpackage field including the unmatched path, assuming it is a subpackage). If still no match can be found, Package will be empty and bool will be false.

func (PackageList) SortByImport

func (pl PackageList) SortByImport()

SortByImport reorders the list by Path in ascending, lexicographic order.

type Repository

type Repository interface {
	RepositoryVCS() VCS
	RepositoryRoot() string
}

Repository represents a supported location for downloading a package.

type RepositoryConfig

type RepositoryConfig struct {
	// contains filtered or unexported fields
}

RepositoryConfig contains configuration for building a Repository - either by a URI or key-values. Unlike the package value which is passed to `go get`, we assume it can be a full URL since this prefers more details (e.g. to get hints about the branch).

func NewRepositoryConfigProperties

func NewRepositoryConfigProperties(vcs VCS, properties map[string]string) RepositoryConfig

func NewRepositoryConfigURL

func NewRepositoryConfigURL(vcs VCS, url *url.URL) RepositoryConfig

func (RepositoryConfig) Properties

func (rc RepositoryConfig) Properties() (map[string]string, bool)

func (RepositoryConfig) URL

func (rc RepositoryConfig) URL() (*url.URL, bool)

func (RepositoryConfig) VCS

func (rc RepositoryConfig) VCS() (VCS, bool)

type RepositoryFactory

type RepositoryFactory interface {
	NewRepository(config RepositoryConfig) (Repository, error)
}

RepositoryFactory supports converting an untyped RepositoryConfig to a Repository.

type Site

type Site struct {
	// URL allows providing an absolute address (instead of using /).
	URL string

	// Title overrides the default import-host value on some pages.
	Title string

	// Generator is a value to be shown in meta tags.
	Generator string

	// ContentLanguage is the primary language value used by themes and packages.
	ContentLanguage string

	// PackagePathPrefix determines the part of the package path which should be removed when building site links.
	// Typically this is the first segment of the remote package imports - the hostname.
	PackagePathPrefix string

	// PackageLinkers are used for generating links for dynamically-discovered subpackages.
	PackageLinkers LinkerList

	// Links apply to all pages.
	Links LinkList

	// Metadata is arbitrary data which may be used by themes.
	Metadata map[string]interface{}
}

Site contains global settings that apply to the entire site.

func (Site) AbsoluteURL

func (s Site) AbsoluteURL(rawurl string) string

AbsoluteURL always prepends the input with the site URL.

func (Site) PackageURL

func (s Site) PackageURL(pkgpath string) string

PackageURL returns the AbsoluteURL for the given package path, respecting the site's PackagePathPrefix.

func (Site) TrimPackagePath

func (s Site) TrimPackagePath(pkgpath string) string

type SourceRepository

type SourceRepository interface {
	SourceURL() string
	SourceDirTemplateURL() string
	SourceFileTemplateURL() string
}

SourceRepository represents a repository where its source code can be found.

type SourceRepositoryLinker

type SourceRepositoryLinker struct {
	Ordering int
	Label    string
}

SourceRepositoryLinker generates a link based on a Package's SourceRepository, as available.

func (l SourceRepositoryLinker) Link(pkg Package) *Link

type Theme

type Theme struct {
	// Version optional value which will be appended to theme files (i.e. for cache-busting).
	Version string

	// Files contains any static files used by the theme.
	Files fs.FS

	// ErrorTemplate is used for HTTP error pages.
	ErrorTemplate *template.Template

	// PackageTemplate is used when a package has been found.
	PackageTemplate *template.Template

	// PackageListTemplate is used when there is a list of packages available.
	PackageListTemplate *template.Template
}

Theme contains the settings

func (Theme) FileURL

func (t Theme) FileURL(file string) string

FileURL accepts a path relative to the theme files directory, prepends it with the prefix, and appends a version.

type VCS

type VCS string

VCS is any go mod-supported version control system.

const (
	UnknownVCS    VCS = ""
	BazaarVCS     VCS = "bzr"
	FossilVCS     VCS = "fossil"
	GitVCS        VCS = "git"
	MercurialVCS  VCS = "hg"
	ModVCS        VCS = "mod"
	SubversionVCS VCS = "svn"
)

Directories

Path Synopsis
cmd
ssg
The config package offers methods for consistently loading settings from files and command line flags.
The config package offers methods for consistently loading settings from files and command line flags.
defaults provides the most common, recommended configurations.
defaults provides the most common, recommended configurations.
examples
embedded
main shows how to configure this programmatically and attach the handler only to its package-specific endpoints.
main shows how to configure this programmatically and attach the handler only to its package-specific endpoints.
internal
themeless is a very minimal, unstyled theme.
themeless is a very minimal, unstyled theme.
themepro is a simple, professional theme.
themepro is a simple, professional theme.

Jump to

Keyboard shortcuts

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