goproxy

README

Goproxy

A minimalist Go module proxy handler.

Goproxy has fully implemented the GOPROXY protocol. The goal of this project is to find the most dead simple way to provide a minimalist handler that can act as a full-featured Go module proxy for those who want to build their own proxies. Yeah, there is no Makefile, no configuration files, no crazy file organization, no lengthy documentation, no annoying stuff, just a goproxy.Goproxy that implements the http.Handler.

Features

• Extremely easy to use
  • Two structs: goproxy.Goproxy and goproxy.DirCacher
  • One interface: goproxy.Cacher
• Built-in support for GOPROXY, GONOPROXY, GOSUMDB, GONOSUMDB, and GOPRIVATE
• Supports serving under other Go module proxies by setting GOPROXY
• Supports proxying checksum databases
• Supports Disable-Module-Fetch header

Installation

• To use this project programmatically, go get it:

go get github.com/goproxy/goproxy

• To use this project from the command line, download the pre-built binaries from here or build it from source:

go install github.com/goproxy/goproxy/cmd/goproxy@latest

• To use this project with Docker, pull the pre-built images from here:

docker pull ghcr.io/goproxy/goproxy

Quick Start

Write code

Create a file named goproxy.go:

package main

import (
	"net/http"

	"github.com/goproxy/goproxy"
)

func main() {
	http.ListenAndServe("localhost:8080", &goproxy.Goproxy{})
}

Then run it:

go run goproxy.go

Finally, set GOPROXY to try it out:

go env -w GOPROXY=http://localhost:8080,direct

For more details, refer to the documentation.

Run from command line

Refer to the Installation section to download the binary.

Then run it:

goproxy --address localhost:8080

Finally, set GOPROXY to try it out:

go env -w GOPROXY=http://localhost:8080,direct

For more details, check its usage:

goproxy --help

Run with Docker

Refer to the Installation section to pull the image.

Then run it:

docker run -p 8080:8080 ghcr.io/goproxy/goproxy --address :8080

Finally, set GOPROXY to try it out:

go env -w GOPROXY=http://localhost:8080,direct

For more details, check its usage:

docker run ghcr.io/goproxy/goproxy --help

Community

If you have any questions or ideas about this project, feel free to discuss them here.

Contributing

If you would like to contribute to this project, please submit issues here or pull requests here.

License

This project is licensed under the MIT License.

Documentation

Overview

Package goproxy implements a minimalist Go module proxy handler.

Index

• type Cacher
• type DirCacher
  • func (dc DirCacher) Get(ctx context.Context, name string) (io.ReadCloser, error)
  • func (dc DirCacher) Put(ctx context.Context, name string, content io.ReadSeeker) error
• type Goproxy
  • func (g *Goproxy) ServeHTTP(rw http.ResponseWriter, req *http.Request)

Types

type Cacher

type Cacher interface {
	// Get gets the matched cache for the name. It returns [fs.ErrNotExist]
	// if not found.
	//
	// Note that the returned [io.ReadCloser] can optionally implement the
	// following interfaces:
	//  1. [io.Seeker], mainly for the Range request header.
	//  2. interface{ LastModified() time.Time }, mainly for the
	//     Last-Modified response header. Also for the If-Unmodified-Since,
	//     If-Modified-Since, and If-Range request headers when 1 is
	//     implemented.
	//  3. interface{ ModTime() time.Time }, same as 2 but with lower
	//     priority.
	//  4. interface{ ETag() string }, mainly for the ETag response header.
	//     Also for the If-Match, If-None-Match, and If-Range request
	//     headers when 1 is implemented. Note that the return value will be
	//     assumed to have complied with RFC 7232, section 2.3, so it will
	//     be used directly without further processing.
	Get(ctx context.Context, name string) (io.ReadCloser, error)

	// Put puts a cache for the name with the content.
	Put(ctx context.Context, name string, content io.ReadSeeker) error
}

Cacher defines a set of intuitive methods used to cache module files for Goproxy.

type DirCacher

type DirCacher string

DirCacher implements Cacher using a directory on the local disk. If the directory does not exist, it will be created with 0755 permissions. Cache files will be created with 0644 permissions.

func (DirCacher) Get

func (dc DirCacher) Get(ctx context.Context, name string) (io.ReadCloser, error)

Get implements Cacher.

func (DirCacher) Put

func (dc DirCacher) Put(ctx context.Context, name string, content io.ReadSeeker) error

Put implements Cacher.

type Goproxy

type Goproxy struct {
	// GoBinName is the name of the Go binary.
	//
	// If GoBinName is empty, "go" is used.
	//
	// Note that the version of the Go binary targeted by GoBinName must be
	// at least version 1.11.
	GoBinName string

	// GoBinEnv is the environment of the Go binary. Each entry is in the
	// form "key=value".
	//
	// If GoBinEnv is nil, [os.Environ] is used.
	//
	// If GoBinEnv contains duplicate environment keys, only the last value
	// in the slice for each duplicate key is used.
	//
	// Note that GOPROXY, GONOPROXY, GOSUMDB, GONOSUMDB, and GOPRIVATE are
	// built-in supported. This means they can be set, even if the version
	// of the Go binary targeted by [Goproxy.GoBinName] is before version
	// 1.13.
	GoBinEnv []string

	// GoBinMaxWorkers is the maximum number of concurrently executing
	// commands for the Go binary.
	//
	// If GoBinMaxWorkers is zero, there is no limit.
	GoBinMaxWorkers int

	// PathPrefix is the prefix for all request paths. It is used to trim
	// the request paths using [strings.TrimPrefix].
	//
	// If PathPrefix is not empty, it must start with "/" and typically end
	// with "/".
	PathPrefix string

	// Cacher is used to cache module files.
	//
	// If Cacher is nil, module files will be temporarily stored on the
	// local disk and discarded when the request ends.
	Cacher Cacher

	// CacherMaxCacheBytes is the maximum number of bytes allowed for
	// storing a new module file in [Goproxy.Cacher].
	//
	// If CacherMaxCacheBytes is zero, there is no limit.
	CacherMaxCacheBytes int

	// ProxiedSUMDBs is a list of proxied checksum databases (see
	// https://go.dev/design/25530-sumdb#proxying-a-checksum-database). Each
	// entry is in the form "<sumdb-name>" or "<sumdb-name> <sumdb-URL>".
	// The first form is a shorthand for the second, where the corresponding
	// <sumdb-URL> will be the <sumdb-name> itself as a host with an "https"
	// scheme.
	//
	// If ProxiedSUMDBs contains duplicate checksum database names, only the
	// last value in the slice for each duplicate checksum database name is
	// used.
	ProxiedSUMDBs []string

	// Transport is used to perform all requests except those initiated by
	// calling the Go binary targeted by [Goproxy.GoBinName].
	//
	// If Transport is nil, [http.DefaultTransport] is used.
	Transport http.RoundTripper

	// TempDir is the directory for storing temporary files.
	//
	// If TempDir is empty, [os.TempDir] is used.
	TempDir string

	// ErrorLogger is used to log errors that occur during proxying.
	//
	// If ErrorLogger is nil, [log.Default] is used.
	ErrorLogger *log.Logger
	// contains filtered or unexported fields
}

Goproxy is the top-level struct of this project.

Note that Goproxy will still adhere to your environment variables. This means you can set GOPROXY to serve Goproxy itself under other proxies. By setting GONOPROXY and GOPRIVATE, you can instruct Goproxy on which modules to fetch directly, rather than using those proxies. Additionally, you can set GOSUMDB, GONOSUMDB, and GOPRIVATE to specify how Goproxy should verify the modules it has just fetched. Importantly, all of these mentioned environment variables are built-in supported, resulting in fewer external command calls and a significant performance boost.

For requests involving the download of a large number of modules (e.g., for bulk static analysis), Goproxy supports a non-standard header, "Disable-Module-Fetch: true", which instructs it to return only cached content.

Make sure that all fields of Goproxy have been finalized before calling any of its methods.

func (*Goproxy) ServeHTTP

func (g *Goproxy) ServeHTTP(rw http.ResponseWriter, req *http.Request)

ServeHTTP implements http.Handler.