Go Module Proxies - Practical Go Lessons https://www.practical-go-lessons.

com/chap-18-go-module-proxies

Chapter 18: Go Module Proxies

1 What will you learn in this chapter?

• What is a module proxy?

• The reasons behind the creation of a module proxy.

• How to configure the go Module proxy.

1.1 Technical concepts covered

• Proxy Server

• Forward Proxy

• Server / Client

2 Introduction
The go get command uses a proxy to fetch the latest releases of modules. In this section, we will detail how this proxy works.

3 What is a proxy server?

• A server is an application that provides functionality for other programs which are called clients1

◦ Clients are, for instance, web browsers

• When this application provides functionality via the internet, we call it a “Web Server”.

• A Proxy Server is a special kind of server.

• It will act as an intermediary between the clients and one or more servers.

A proxy server will receive requests for resources those request can for instance :

• handle the request directly

• forward it to the servers behind it (we call this kind of proxy server “Forward proxy”)

• stop the request

1 of 6 02/01/2023, 02:10
Go Module Proxies - Practical Go Lessons https://www.practical-go-lessons.com/chap-18-go-module-proxies

Sequence diagram of a forward proxy

Proxy servers have many use cases :

• Filter and monitor internet traffic.

◦ Companies intensively use forward proxies to keep an eye on employees activity

◦ They may also block some requests to forbidden websites

• Caching

◦ We can use proxies to cache resources.

◦ Instead of calling the server targeted, they will send a cached response to the client.

The paper and the digital edition of this book are available here. ×
I also filmed a video course to build a real world project with Go.

4 The reasons behind the birth of the Go Module Proxy

The Go Module Proxy is a recent addition to the language tooling. Before the go get command downloaded, the module directly from the
code-sharing website. It has some drawbacks :

• A module can be deleted from the site sharing website by the developer.

• A version can also be deleted.

◦ A tag was deleted...

◦ A commit can be removed...

If your application depends on this module building your Go application might be impossible.

5 How does it Work

The go get command can fetch dependencies from a module proxy server without touching the original server that hosts the code (GitHub,
GitLab,...).

The Go Command (go get) try to fetch modules from the proxy server

When the code is not available on the proxy server, Go can download it directly from the hosting server.

2 of 6 02/01/2023, 02:10
Go Module Proxies - Practical Go Lessons https://www.practical-go-lessons.com/chap-18-go-module-proxies

When the module is not on the proxy

We can change this behavior through an environment variable.

6 Configuration of the Go Module Proxy

The proxy configuration is set into the environment variable GOPROXY.

By typing the command

go env GOPROXY

you can check its current value. At the time of writing, the default value is :

https://proxy.golang.org,direct

• The value of GOPROXY is a list

• The list is separated by commas “,” or pipes “|”

• It is composed of URLs of Go modules proxy and/or special keywords.

• The keywords available are

“off” : it means turn off the feature

“direct” : it instructs the tool to download it directly from the code hosting server.

Go will attempt to download new modules from each specified Go Module Proxy URLs from left to right. When it encounters the keyword
“direct” it will try to download the module directly from the source hosting website.

GOPROXY environment configuration

6.1 Disable Go Module Proxy

To disable the feature completely set the GOPROXY env to the value “off”

7 The four endpoints of a Go Module Proxy (advanced)

A go module proxy will expose four endpoints (all GET) /<module>/@v/list : get the list of versions known by the proxy server.

3 of 6 02/01/2023, 02:10
Go Module Proxies - Practical Go Lessons https://www.practical-go-lessons.com/chap-18-go-module-proxies

1. Ex : https://proxy.golang.org/ gitlab.com/loir402/bluesodium/@v/ list

v1.0.0
v1.0.1

/<module>/@latest : get the latest version info formated in JSON

1. Ex : https://proxy.golang.org/ gitlab.com/loir402/bluesodium/@v/latest

{"Version":"v1.0.1","Time":"2021-01-20T18:49:34Z"}

/<module>/@v/<version>.info : get the metadata about the module’s version and the time at which it was committed.

1. Ex : https://proxy.golang.org/ gitlab.com/loir402/bluesodium/@v/v1.0.1 .info

{"Version":"v1.0.1","Time":"2021-01-20T18:49:34Z"}

/<module>/@v/<version>.mod : return the go.mod file of the given version

1. Ex : https://proxy.golang.org/ gitlab.com/loir402/bluesodium/@v/v1.0.1 .mod

/<module>/@v/<version>.zip : return the zipped version of the module.

1. Ex : https://proxy.golang.org/ gitlab.com/loir402/bluesodium/@v/v1.0.1 .zip

The paper and the digital edition of this book are available here. ×
I also filmed a video course to build a real world project with Go.

8 Common error: the newest version is not downloaded

When a newer minor or patch is available for the module, the command

go get -u modulePath

will not always download it immediately. The service has a cache in place to improve performance. Hence to solve this, you have two
solutions :

• Wait and try later (the cache will be invalidated)

• Target specifically the version you want to use in the go get command

go get -u modulePath@v1.0.2

9 Useful links to debug issues

• How to get the list of available versions for a module on a proxy?

https://PROXY_URL/MODULE_PATH/@v/list

◦ Ex : https://proxy.golang.org/gitlab.com/loir402/bluesodium/@v/list

▪ Will output the list of versions available for a given module

◦ For major version 2 the link is :

"https://proxy.golang.org/gitlab.com/loir402/bluesodium/v2/@v/list"

• How to download source code of a module at a specific version

https://PROXY_URL/MODULE_PATH/@v/VERSION.zip

◦ Ex : https://proxy.golang.org/gitlab.com/loir402/bluesodium/@v/v1.0.1.zip

▪ Will trigger the download of the source code

10 Test yourself
10.0.1 Questions

4 of 6 02/01/2023, 02:10
Go Module Proxies - Practical Go Lessons https://www.practical-go-lessons.com/chap-18-go-module-proxies

1. What is the name of the environment variable that controls the Go Module Proxy usage?

2. How to disable the usage of module proxies in a go get command?

10.1 Answers
1. What is the name of the environment variable that controls the Go Module Proxy usage?

1. GOPROXY.
2. How to disable the usage of module proxies in a go get command?

$ GOPROXY="off" go get gitlab.com/loir402/foo

Key takeaways
• A Go module proxy is a proxy server that will store Go modules’ code.

• Instead of downloading the source code directly from the code hosting server (ex: GitHub), the go command can download it from
the proxy server.

• Some modules might be unknown to the proxy; in that case, the server will generally add them afterward.

◦ For instance, the official Go Module Proxy has that system in place

◦ Other Go Module Proxies might implement different strategies

• There is an official Go Proxy available to all, which is https://proxy.golang.org/

• You can also deploy your own Go Module Proxy Server / or use a hosted alternative

• To use a specific proxy, you will have to modify the GOPROXY variable.

1. Definition from Wikipedia, see https://en.wikipedia.org/wiki/Server_(computing)↩

The paper and the digital edition of this book are available here. ×
I also filmed a video course to build a real world project with Go.

Bibliography
Previous Next

Go modules Unit Tests

Table of contents

Did you spot an error ? Want to give me feedback ? Here is the feedback page! ×

Newsletter:
Like what you read ? Subscribe to the newsletter.

I will keep you informed about the book updates.

@ my@email.com

Practical Go Lessons
By Maximilien Andile
Copyright (c) 2023
Follow me Contents
Posts
Book
Support the author Video Tutorial

5 of 6 02/01/2023, 02:10
Go Module Proxies - Practical Go Lessons https://www.practical-go-lessons.com/chap-18-go-module-proxies

About
The author
Legal Notice
Feedback
Buy paper or digital copy
Terms and Conditions

6 of 6 02/01/2023, 02:10