Project Athens: The Download Protocol

If you didn’t check out my previous intro post on project, go check it out! If you’re lazy like me and don’t want to, here’s the tl;dr:

Athens is a Go package repository that implements the vgo download protocol

Come one, come all and learn about the vgo download protocol!

Some folks reached out to me after reading the post and were surprised to hear that vgo has a download protocol, so before I move on to future more Athens-ey posts, I wanted to take today to explain the actual download protocol.

The most important thing here is the download protocol is a pretty simple HTTP API. Athens just implements it with no trickery.

The Endpoints

One of the vgo posts has a section called “Download Protocol.” This section is pretty much copying that into another blog post and adding some extra commentary.

Here they are:

Listing Versions

GET arschles.com/my/module/@v/list

I’m assuming in all these examples that I have an Athens server at arschles.com

This endpoint returns a list of versions that Athens knows about for my/module. The list is just separated by newlines:

v0.0.1
v1.0.0
v1.0.1
v1.1.0

Getting Version Info

GET arschles.com/my/module/@v/v1.0.0.info

This returns JSON with information about v1.0.0. It looks like this:

{
    "Name": "v1.0.0",
    "Short": "v1.0.0",
    "Version": "v1.0.0",
    "Time": "1972-07-18T12:34:56Z"
}

Getting the go.mod File

GET arschles.com/my/module/@v/v1.0.0.mod

This returns the go.mod file for version v1.0.0. If arschles.com/my/module version v1.0.0 has no dependencies, the response body would look like this:

module "arschles.com/my/module"

Getting the Source Code

GET arschles.com/my/module/@v/v1.0.0.zip

This is what it sounds like — it sends back a zip file with the source code for arschles.com/my/module version v1.0.0

More Stuff

There are two other endpoints that the paper talks about but they’re kinda a “maybe” for now, so I’m gonna leave them out.

That’s It!

I told you it was pretty simple. If you have a module, it’s still pretty easy to put it up on a CDN somewhere and make it vgo compatible!

Interested in getting involved with Athens? Come to our weekly development meetings! They are a great way to meet folks, ask questions, find some stuff to work on, or just hang out if you want to.

Keep on rockin’

— Aaron