package module
Version: v0.13.0 Latest Latest

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

Go to latest
Published: Jan 11, 2023 License: MIT Imports: 29 Imported by: 9



GitHub Actions codecov Go Report Card PkgGoDev

A minimalist Go module proxy handler.

Goproxy has fully implemented the GOPROXY protocol. Our goal 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.



Open your terminal and execute

$ # Use it programmatically (RECOMMENDED).
$ go get
$ # Or use our minimalist CLI implementation.
$ go install
$ # Or use our minimalist Docker image.
$ docker pull


The only requirement is the Go, at least v1.13.

Quick Start

Create a file named goproxy.go

package main

import (


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

and run it

$ go run goproxy.go

then try it by setting GOPROXY to http://localhost:8080 by following the instructions below. In addition, we also recommend that you set GO111MODULE to on instead of auto when you are working with Go modules.

Open your terminal and execute

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


macOS or Linux

Open your terminal and execute

$ export GOPROXY=http://localhost:8080


$ echo "export GOPROXY=http://localhost:8080" >> ~/.profile && source ~/.profile



Open your PowerShell and execute

C:\> $env:GOPROXY = "http://localhost:8080"


1. Open the Start Search, type in "env"
2. Choose the "Edit the system environment variables"
3. Click the "Environment Variables…" button
4. Under the "User variables for <YOUR_USERNAME>" section (the upper half)
5. Click the "New..." button
6. Choose the "Variable name" input bar, type in "GOPROXY"
7. Choose the "Variable value" input bar, type in "http://localhost:8080"
8. Click the "OK" button



If you want to discuss Goproxy, or ask questions about it, simply post questions or ideas here.


If you want to help build Goproxy, simply follow this to send pull requests here.


This project is licensed under the MIT License.

License can be found here.



Package goproxy implements a minimalist Go module proxy handler.



This section is empty.


This section is empty.


This section is empty.


type Cacher

type Cacher interface {
	// Get gets the matched cache for the name. It returns the
	// [os.ErrNotExist] if not found.
	// It is the caller's responsibility to close the returned
	// [io.ReadCloser].
	// Note that the returned [io.ReadCloser] can optionally implement the
	// following interfaces:
	//   - [io.Seeker], for the Range request header.
	//   - interface{ ModTime() time.Time }, for the Last-Modified response
	//     header.
	//   - interface{ Checksum() []byte }, for the ETag response header.
	Get(ctx context.Context, name string) (io.ReadCloser, error)

	// Set sets the content as a cache with the name.
	Set(ctx context.Context, name string, content io.ReadSeeker) error

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

type DirCacher added in v0.4.0

type DirCacher string

DirCacher implements the Cacher using a directory on the local filesystem. If the directory does not exist, it will be created with 0750 permissions.

func (DirCacher) Get added in v0.4.0

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

Get implements the Cacher.

func (DirCacher) Set added in v0.4.0

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

Set implements the Cacher.

type Goproxy

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

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

	// GoBinMaxWorkers is the maximum number of commands allowed for the Go
	// binary to execute at the same time.
	// If the GoBinMaxWorkers is zero, there is no limit.
	GoBinMaxWorkers int

	// PathPrefix is the prefix of all request paths. It will be used to
	// trim the request paths via the [strings.TrimPrefix].
	// If the PathPrefix is not empty, it must start with "/", and usually
	// should also end with "/".
	PathPrefix string

	// Cacher is the [Cacher] that used to cache module files.
	// If the Cacher is nil, the module files will be temporarily stored
	// in the local disk and discarded as the request ends.
	Cacher Cacher

	// CacherMaxCacheBytes is the maximum number of bytes allowed for the
	// [Goproxy.Cacher] to store a cache.
	// If the CacherMaxCacheBytes is zero, there is no limit.
	CacherMaxCacheBytes int

	// ProxiedSUMDBs is the list of proxied checksum databases. See
	// If the ProxiedSUMDBs is not nil, each value should be given the
	// format of "<sumdb-name>" or "<sumdb-name> <sumdb-URL>". The first
	// format can be seen as a shorthand for the second format. In the case
	// of the first format, the corresponding checksum database URL will be
	// the checksum database name itself as a host with an "https" scheme.
	ProxiedSUMDBs []string

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

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

	// ErrorLogger is the [log.Logger] that logs errors that occur while
	// proxying.
	// If the ErrorLogger is nil, logging is done via the [log] package's
	// standard logger.
	ErrorLogger *log.Logger
	// contains filtered or unexported fields

Goproxy is the top-level struct of this project.

Note that the Goproxy will not mess with your environment variables, it will still follow your GOPROXY, GONOPROXY, GOSUMDB, GONOSUMDB and GOPRIVATE. It means that you can set GOPROXY to serve the Goproxy itself under other proxies, and by setting GONOPROXY and GOPRIVATE to indicate which modules the Goproxy should download directly instead of using those proxies. And of course, you can also set GOSUMDB, GONOSUMDB and GOPRIVATE to indicate how the Goproxy should verify the modules.

Since GOPROXY with comma-separated list support, GONOPROXY, GOSUMDB, GONOSUMDB and GOPRIVATE were first introduced in Go 1.13, so we implemented a built-in support for them. Now, you can set them even the version of the Go binary targeted by the [Goproxy.GoBinName] is before v1.13.

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

Make sure that all fields of the 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 the http.Handler.


Path Synopsis

Jump to

Keyboard shortcuts

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