feat: Add /version endpoint reporting build and version info

[mloskot]

Refs:

• feat: Add /version endpoint and command line argument -version #188
• VERSION in Makefile resolved to Git hash instead of tag #190

---

Tasks

• Add -version command line option to return the gitVersion or the whole VersonInfo like /version endpoint
• Add tests for /version
• Add tests for go-httpbin -version

[mccutchen]

Okay, I think this will be pretty tricky to get right.

Let's zoom out and look at the ways go-httpbin is currently built:

1. When a new release is tagged, the "release" GitHub Action workflow builds, tags, and pushes multi-architecture docker images to docker hub

   • This uses docker/metadata-action to automagically set tags on the image based on the release tag
   • While the Dockerfile calls make to build the go-httpbin binary, the local git checkout is not available in the docker build context, so we cannot rely on being able to look up commit/tag info in the Makefile

2. When a developer runs make/make build/make image on their local laptop

   • In the make/make build case, we're building on the host machine and can likely expect that we're building in a local checkout (but we can't guarantee that, e.g. if someone downloads a tar.gz snapshot of a release from GitHub)
   • in the make image case, as above, the local git checkout is not available in the docker build context

3. When a user runs go install github.com/mccutchen/go-httpbin/v2/cmd/go-httpbin@latest

   • In this case, AFAIK the Makefile is ignored altogether so has no opportunity to inject build-time metadata

---

I think the published docker images in (1) are the most relevant for our purposes here. I think we'll want to come up with a mechanism that works with both the GitHub Actions automation and the manual make image target, which can be used as a "break-glass" mechanism if GH Actions is broken or we need an out-of-band image pushed.

To make that work, I think we might need to add ARGs to the Dockerfile to allow us to pass in the relevant version metadata at build time, either in GH Actions or in the makefile.

---

What do you think? I may be missing other options we have here, please let me know!

[mloskot]

Thank you @mccutchen for the extensive explanation - I have learned a lot.

When I started working on the idea of /version my first thought was "What is the canonical golang way?" and I learned about the ldflags and -X, got excited and submitted this PR.

However, perhaps a more explicit and old-school way would be appropriate to handle all the cases you mention, i.e. VERSION file which is read by Makefile.

For example,

• tag v2.15.0 has VERSION file containing 2.15.0
• main branch has VERSION file containing dev or main

Perhaps there is a golang way to achieve similar, but I am unaware Go newbie.

[mccutchen]

However, perhaps a more explicit and old-school way would be appropriate to handle all the cases you mention, i.e. VERSION file which is read by Makefile.

For example,

* tag `v2.15.0` has `VERSION` file containing `2.15.0`

* main branch has `VERSION` file containing `dev` or `main`

I'm not sure I like that approach either, just because it will be tricky to juggle different contents of a VERSION file and make it more complicated to cut a new release. (What would that look like, one commit to bump VERSION, tag release, follow-up commit to revert VERSION back to dev or main?)

I'm sorry, while I do think this would be a good feature to add, I still don't quite have a clear idea in my own head for how we might implement it in a way that doesn't add too much complexity/burden to the development and release process. I'll think about it a bit more; happy to keep working through ideas here if you come up with other approaches!

[mloskot]

@mccutchen I perfectly understand your reluctance as the tradeoffs or complications are clear and obvious.

I'm just thinking out loud that Go ecosystem must have solved such problem of setting version in a way that is nicely integrated with Git workflow, binaries build and container images build workflows.

By the way, I've been looking for inspirations what other established Go projects do, e.g. Flux CD seems to rely on goreleaser which relies on tagging, so AFAIU everything starts from creating a semver-based tag:

• https://github.com/fluxcd/flux2/blob/cf26cf25f149e864b17598c0d0125f424e7bd25a/cmd/flux/main.go#L41
• https://github.com/fluxcd/flux2/blob/cf26cf25f149e864b17598c0d0125f424e7bd25a/.goreleaser.yml#L7
• https://github.com/fluxcd/flux2/blob/cf26cf25f149e864b17598c0d0125f424e7bd25a/Makefile#L1

while building from non-relased snapshot sets the so called dev version

• https://github.com/fluxcd/flux2/blob/cf26cf25f149e864b17598c0d0125f424e7bd25a/Makefile#L2