没有不值得去解决的问题,也没有不值得去学习的技术!

A Tour of Go Multilingual Project: Add a Unique User-Agent to the Playground Proxy and Notify the Official Go Team

[Figure 4: Sending a Playground usage notification email to the golang-dev public mailing list and successful delivery]

作者:

在

Previously, I completed the Playground browser direct connection adjustment for the A Tour of Go multilingual project, allowing the “Run” and “Format” requests from the browser to be forwarded to the official Go service through an independent Playground proxy.

The deployment process is documented here:

A Tour of Go Playground Browser Direct Connection Proxy Records

After this pipeline went live and ran stably, I noticed an issue I had not specifically addressed before:

When third-party websites call the Go Playground, the official documentation expects the caller to use a unique User-Agent so the request source can be identified, and to contact the official team in advance to explain the usage.

Therefore, this time I did not adjust the overall Playground architecture. Instead, I added the caller identity and sent a brief notification email to the Go official public mailing list.

1. First, Confirm the Go Playground Requirements for Third-Party Calls

The official Go Playground page states clearly in “About the Playground” that the Playground is not exclusively for official Go use; other websites are welcome to use the service.

However, the official documentation also sets out a few requirements:

  • Contact them before third-party use;
  • Use a unique User-Agent in requests to facilitate caller identification;
  • The service itself should be beneficial to the Go community.

For the current go-tour-i18n, these conditions are actually a good fit.

The project itself is a community multilingual translation project for A Tour of Go, currently providing a Simplified Chinese version first, with plans to expand to other languages later.

Therefore, I felt the most important thing to add was not a new proxy feature, but rather to ensure that when the Go team sees these requests, they can clearly know:

These /compile and /fmt requests come from the go-tour-i18n project.

[Figure 1: Official Go Playground page regarding third-party use, contacting the official team, and unique User-Agent]
[Figure 1: Official Go Playground page regarding third-party use, contacting the official team, and unique User-Agent]

2. The User-Agent Should Represent the Entire Multilingual Project

The first thing to decide was what exactly to use as the User-Agent.

If I were only considering the currently live Simplified Chinese version, I could have used something like:

Plaintext
go-tour-i18n-zh-CN/1.0

But that would not fit the long-term positioning of this project.

go-tour-i18n has been a multilingual project since its architectural design, and zh-CN is just the language delivered in the first phase. If other languages are added in the future, they will still belong to the same project and may share the same Playground proxy infrastructure.

Therefore, I ultimately did not include the specific language in the User-Agent, and instead uniformly adopted:

Plaintext
go-tour-i18n/1.0 (+https://github.com/shuijingwan/go-tour-i18n)

Here:

  • go-tour-i18n represents the project identity;
  • 1.0 serves as the current proxy caller version;
  • The GitHub repository address allows server administrators to directly understand what this project is when they see the requests.

Similarly, I did not include the current proxy server or specific infrastructure name in the User-Agent.

Servers might be migrated in the future, but the project identity should not change because of a server change.

3. Uniformly Override User-Agent in the ZgoCloud Playground Proxy

The current production Playground main pipeline is:

Plaintext
Browser
→ play.go-dev.shuijingwanwq.com:8443
→ ZgoCloud Nginx Playground Proxy
→ play.golang.org

The two interfaces actually used are:

Plaintext
/compile
/fmt

After checking the existing Nginx configuration, I found that User-Agent had not been explicitly set before.

In this case, the browser’s own User-Agent would continue to be forwarded by the proxy to play.golang.org.

While this does not affect the Run and Format functions themselves, to the Go team the requests would look more like they came from various different browsers rather than a stable third-party project.

Therefore, I added the following to the proxy configurations for /compile and /fmt respectively:

Nginx
proxy_set_header User-Agent "go-tour-i18n/1.0 (+https://github.com/shuijingwan/go-tour-i18n)";

This way, regardless of whether the user is actually using Firefox, Chrome, or another browser, the requests ultimately sent from the Playground proxy to the Go team will all use the same project-level identity.

[Figure 2: Uniformly setting the go-tour-i18n User-Agent for both /compile and /fmt in ZgoCloud Nginx]
[Figure 2: Uniformly setting the go-tour-i18n User-Agent for both /compile and /fmt in ZgoCloud Nginx]

This time, I did not take the opportunity to extract the two location into a common include, nor did I adjust other proxy structures.

The reason is simple:

The current goal was only to add the User-Agent.

There is no need to expand the scope of Nginx refactoring just to add a single request header.

4. Redo Production Acceptance Testing After Modifications

After modifying the production Nginx configuration, I first re-ran the configuration check:

Plaintext
nginx: the configuration file /usr/local/nginx/conf/nginx.conf syntax is ok
nginx: configuration file /usr/local/nginx/conf/nginx.conf test is successful

I then confirmed that the target User-Agent appears a total of the following times in the final configuration:

Plaintext
2

That is, one each for /compile and /fmt.

Next, I re-ran the actual functional tests.

Compile

The test program executed normally and returned:

Plaintext
ua-ok

At the same time:

Plaintext
Status: 0
VetOK: true

This indicates that the compilation and execution pipeline remains normal.

Format

/fmt also returned HTTP 200, successfully formatted the test Go code, and the error message in the response was empty.

[Figure 3: Nginx configuration check, User-Agent count, and Compile / Format production acceptance results]
[Figure 3: Nginx configuration check, User-Agent count, and Compile / Format production acceptance results]

In addition to the core verification shown in the screenshot, I also re-confirmed the existing access controls:

  • OPTIONS requests for /compile and /fmt still return 204;
  • CORS responses for the correct Origin are normal;
  • Non-allowed Origins still return 403;
  • GET requests to /compile and /fmt still return 405.

Therefore, adding the User-Agent this time did not change the previously deployed interface behavior.

5. Proactively Explain Usage to the Go Official Public Mailing List

After completing the production configuration, there was one more thing to handle.

Since the official Go Playground page explicitly states that third-party users should contact them first, simply setting the User-Agent was not enough.

The contact address provided on the official page is:

Plaintext
golang-dev@googlegroups.com

This is a public mailing list.

Therefore, I used the site’s own:

Plaintext
admin@shuijingwanwq.com

to send a brief English email.

The email subject was:

Plaintext
Go Playground usage by the go-tour-i18n project

The email primarily explained a few things:

  • go-tour-i18n is a community multilingual translation project for A Tour of Go;
  • It currently provides a Simplified Chinese version, with plans to support more languages in the future;
  • The project uses /compile and /fmt to call the Go Playground;
  • A unique User-Agent has been set for these requests;
  • The project is used for Go learning and community localization.

The User-Agent used was also explicitly listed in the email:

Plaintext
go-tour-i18n/1.0 (+https://github.com/shuijingwan/go-tour-i18n)

The email was ultimately shown as delivered successfully.

[Figure 4: Sending a Playground usage notification email to the golang-dev public mailing list and successful delivery]
[Figure 4: Sending a Playground usage notification email to the golang-dev public mailing list and successful delivery]

Here, I deliberately kept things simple.

This email was solely to notify the actual usage and identity of the third-party service as required by the Playground page, without mixing in other domain, trademark, or brand issues into the same email.

This keeps the boundaries between different issues clearer.

6. Why I Think This Small Step Is Worth Taking

From a purely technical perspective, Compile and Format would work fine without setting this User-Agent.

In fact, the entire Playground proxy had already been running stably before this.

But for production services, beyond “can it work right now”, we also need to consider:

When the upstream sees these requests, can they tell who sent them?

Now, with the uniform setting in place:

Plaintext
Browser User-Agent
        ↓
ZgoCloud Playground Proxy
        ↓
Uniform override
        ↓
go-tour-i18n/1.0
        ↓
play.golang.org

No matter how many languages the project supports in the future, and regardless of what browser the user uses, these requests will have a stable project identity for the Go Playground.

If service policies, traffic management, or API usage rules change in the future, an identifiable community project is clearly easier to account for than a batch of browser requests with indeterminable sources.

Of course, this does not mean that after setting the User-Agent and sending the email, the Playground API has gained a permanent, unchanging guarantee.

It solves a different problem:

As a third-party caller, clearly explaining your identity and purpose in accordance with the official public documentation.

7. Current Playground Call Chain Status

After this addition, the current production status can be summarized as:

Plaintext
A Tour of Go Browser
        ↓
play.go-dev.shuijingwanwq.com:8443
        ↓
ZgoCloud Nginx Playground Proxy
        ↓
User-Agent:
go-tour-i18n/1.0
(+https://github.com/shuijingwan/go-tour-i18n)
        ↓
play.golang.org
        ↓
/compile
/fmt

The following have now been completed:

  • /compile production forwarding;
  • /fmt production forwarding;
  • CORS restrictions;
  • Request method restrictions;
  • Independent Playground domain;
  • HTTPS;
  • Unique project-level User-Agent;
  • Usage notification to the Go official public mailing list;
  • Compile / Format production regression verification.

At this point, the Playground proxy component not only “runs normally” but has also been supplemented with the third-party caller identity layer.

Conclusion

This change actually consisted of only two lines of Nginx configuration.

But it solves an issue easily overlooked during the initial deployment phase:

When third-party services call a public upstream, they should not only consider whether the request is successful, but also how to let the upstream clearly identify their identity.

For go-tour-i18n, using a project-level rather than a language-level User-Agent also leaves room for future multilingual expansion.

Simplified Chinese is just the first language right now.

No matter how many locales are added in the future, as long as they still belong to the go-tour-i18n project, this Playground caller identity can remain stable.

关于作者 · 持续学习与技术实践

我是一名拥有 15 年以上开发经验的技术从业者,自 2013 年起持续运营个人技术博客,记录工作与个人项目中遇到的真实问题,以及解决问题过程中的探索、实践和思考。

除了技术写作,我也在持续开发和维护自己的独立项目,探索新技术和新工具在实际场景中的应用。我始终相信,没有不值得去解决的问题,也没有不值得去学习的技术。

如果这篇文章对你有所帮助,欢迎浏览博客中的其他文章,也欢迎交流技术经验与想法。

关于我  ·  GitHub  ·  邮件联系