goproxyclient

README

Goproxyclient

This is goproxyclient, a library and command-line tool for communicating with a Go module proxy, such as the public one operated by Google at proxy.golang.org.

Installation

For the command-line tool:

go install github.com/bobg/goproxyclient/cmd/goproxyclient@latest

For the library:

go get github.com/bobg/goproxyclient@latest

Usage

For library usage please see the package doc.

Command-line usage:

goproxyclient [-proxy URL] COMMAND ARG ARG...

where COMMAND is one of info, latest, list, mod, and zip. If -proxy is given, it is the base URL of the Go module proxy server to query. The default is the first element of the GOPROXY environment variable, or https://proxy.golang.org if that’s not set.

The info command produces JSON-encoded metadata about each argument. Each argument must be in the form MODPATH@VERSION.

The latest command produces JSON-encoded metadata about the latest version of each argument. Each argument must be a bare module path.

The list command produces a sorted list of available versions for each argument. Each argument must be a bare module path.

The mod command produces the go.mod file for its argument, which must be in the form MODPATH@VERSION.

The zip command produces a zip file with the module contents for its argument, which must be in the form MODPATH@VERSION.

Documentation

Overview

Package goproxyclient provides a client for talking to Go module proxies.

Index

• func IsNotFound(err error) bool
• func Parse(goproxy string) iter.Seq2[string, bool]
• type Client
  • func New(goproxy string, hc *http.Client) Client
  • func (cl Client) Info(ctx context.Context, mod, ver string) (string, time.Time, map[string]json.RawMessage, error)
  • func (cl Client) Latest(ctx context.Context, mod string) (string, time.Time, map[string]json.RawMessage, error)
  • func (cl Client) List(ctx context.Context, mod string) ([]string, error)
  • func (cl Client) Mod(ctx context.Context, mod, ver string) (io.ReadCloser, error)
  • func (cl Client) Zip(ctx context.Context, mod, ver string) (io.ReadCloser, error)
• type CodeErr

Functions

func IsNotFound

func IsNotFound(err error) bool

IsNotFound tests an error to see if it is a CodeErr and has status code 404 (Not Found) or 410 (Gone).

func Parse

func Parse(goproxy string) iter.Seq2[string, bool]

Parse parses a GOPROXY string structured as described at https://go.dev/ref/mod#goproxy-protocol: a sequence of strings separated by commas (,) or pipes (|). The strings are URLs to use in Go module proxy queries, or the special strings "direct" or "off". Comma means "try the next proxy only if the previous one failed with a 404 (Not Found) or 410 (Gone) error." Pipe means "try the next proxy regardless of the previous error."

The result is a sequence of pairs: the string, and boolean meaning "after any error" (i.e., whether the preceding separator was a pipe). The boolean is false for the first element in the sequence.

Types

type Client

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

Client is a client for talking to a sequence of one or more Go module proxies. Create one with New.

func New

func New(goproxy string, hc *http.Client) Client

New creates a new Client talking to a sequence of one or more Go module proxies.

It calls Parse on the input string to get the sequence of proxies, ignoring any "direct," "off," or empty entries. If no proxies are specified, it uses https://proxy.golang.org by default.

If hc is non-nil, it will use that HTTP client for all requests, otherwise it will use a default HTTP client (but a distinct one from http.DefaultClient).

func (Client) Info

func (cl Client) Info(ctx context.Context, mod, ver string) (string, time.Time, map[string]json.RawMessage, error)

Info gets information about a specific version of a Go module. A Go module proxy produces a JSON object with Version and Time fields, and possibly others.

This function returns the canonical version string, the timestamp for that version, and a map of all the fields parsed from the JSON object.

The returned version may be different from the one supplied as an argument, which is not required to be canonical. (It may be a branch name or commit hash, for example.)

The values in the map are unparsed JSON that can be further decoded with calls to json.Unmarshal.

func (Client) Latest

func (cl Client) Latest(ctx context.Context, mod string) (string, time.Time, map[string]json.RawMessage, error)

Latest gets info about the latest version of a Go module. Its return values are the same as for Client.Info.

func (Client) List

func (cl Client) List(ctx context.Context, mod string) ([]string, error)

List lists the available versions of a Go module. The result is sorted in semver order (see semver.Sort).

func (Client) Mod

func (cl Client) Mod(ctx context.Context, mod, ver string) (io.ReadCloser, error)

Mod gets the go.mod file for a specific version of a Go module.

func (Client) Zip

func (cl Client) Zip(ctx context.Context, mod, ver string) (io.ReadCloser, error)

Zip gets the contents of a specific version of a Go module as a zip file.

type CodeErr

type CodeErr interface {
	error
	Code() int
}

CodeErr is the type of an error that has an associated HTTP status code. This interface is satisfied by mid.CodeErr from github.com/bobg/mid.