version: derive in cmake, not docker; filter non-release tags

Addresses review on #505.

Why docker-only was wrong: the version was a docker --build-arg, so only
published images carried a real one — local builds, release tarballs and
the artifact tarball all reported the static project version (0.1.0).
Derivation now lives in cmake/MoqxVersion.cmake with an explicit
precedence chain:

  1. -DMOQX_VERSION_STRING   explicit (release workflow passes the tag)
  2. <src>/VERSION           stamped by CI; docker + source tarballs have
                             no .git, so this is how they resolve
  3. git describe            any clone, including local dev builds
  4. v${PROJECT_VERSION}     last resort

Tag filtering is load-bearing. The repo carries moving non-version tags
(snapshot-latest, build-*, archive/*); an unfiltered describe returns
"snapshot-latest" as the version of every image built from main —
demonstrated on 4969f8c, where naive describe gives snapshot-latest and
--match 'v[0-9]*' gives the sha. The v prefix is kept: the string is a
git identifier and round-trips into git checkout / gh release view.

Generalization payoff, all verified in a container build:
- moqx --version            -> moqx version v0.2.1-2-g59fe6a9b
- admin /info               -> {"service":"moqx","version":"v0.2.1-2-g59fe6a9b"}
- startup log banner        -> first line attributes the log stream to a build
- /usr/local/VERSION        -> identify an image without executing it
- install tree VERSION      -> release + snapshot tarballs carry the id

The version is now an interface target (moqx_version) carrying a
generated header, so any target can use it — not a private compile
definition on moqx_core.

Author: gmarzot

.github/workflows/ci-main.yml

@@ -382,18 +382,26 @@ jobs:
           fi
           echo "short=$SHORT" >> "$GITHUB_OUTPUT"
           echo "rolling=${LABEL}-latest" >> "$GITHUB_OUTPUT"
-          # Version baked into the binary's /info (relay dashboard badge):
-          # exact tag on release commits, tag-distance-sha on snapshots.
-          # Leading "v" stripped — /info reports bare semver-style ("0.2.1",
-          # "0.2.1-14-gabc1234"); display layers add their own "v".
-          echo "describe=$(git describe --tags --always | sed 's/^v//')" >> "$GITHUB_OUTPUT"
+
+      - name: Stamp build version
+        run: |
+          # Single source of truth for the version baked into the binary
+          # (/info, --version, log banner) and shipped in artifacts. The
+          # docker build context excludes .git, so cmake reads this file —
+          # see cmake/MoqxVersion.cmake for the full resolution order.
+          #
+          # --match 'v[0-9]*' is load-bearing: the repo also carries moving,
+          # non-version tags (snapshot-latest, build-*, archive/*) and an
+          # unfiltered describe returns e.g. "snapshot-latest" as the version
+          # of every image built from main.
+          git describe --tags --match 'v[0-9]*' --always > VERSION
+          echo "==> build version: $(cat VERSION)"
 
       - name: Build Docker image
         run: |
           IMAGE="ghcr.io/${{ github.repository }}"
           ARCH="${{ matrix.arch }}"
           docker build -f docker/Dockerfile \
-            --build-arg MOQX_VERSION_STRING="${{ steps.tags.outputs.describe }}" \
             -t "${IMAGE}:${{ steps.tags.outputs.short }}-${ARCH}" \
             -t "${IMAGE}:${{ steps.tags.outputs.rolling }}-${ARCH}" \
             .

.github/workflows/version-release.yml

@@ -324,8 +324,13 @@ jobs:
           # path. Combined with the bundle step below this produces a
           # self-contained tarball that runs on noble / RHEL 9 / AL2023
           # without needing distro-specific packages installed.
+          # Stamp the exact release tag rather than deriving it: this job's
+          # checkout is shallow (no tags) and the tag may not exist yet when
+          # the build runs, so `git describe` would yield a bare sha. See
+          # cmake/MoqxVersion.cmake.
           cmake -S . -B _build -G Ninja \
             -DCMAKE_BUILD_TYPE=Release \
+            -DMOQX_VERSION_STRING="${{ needs.validate.outputs.tag }}" \
             -DCMAKE_PREFIX_PATH="$(cat .scratch/cmake_prefix_path.txt)" \
             -DCMAKE_MODULE_PATH="${GITHUB_WORKSPACE}/cmake;${GITHUB_WORKSPACE}/deps/moxygen/build/fbcode_builder/CMake" \
             -DCMAKE_C_FLAGS="${{ matrix.cxx_flags }}" \

.gitignore

@@ -39,3 +39,6 @@ docker/cloudflare.ini
 # gh-pages dashboard (lives on gh-pages branch, not main)
 /gh-pages/
 docker/grafana/provisioning/dashboards/archive/
+
+# Build-version stamp written by CI (cmake/MoqxVersion.cmake reads it).
+/VERSION

CMakeLists.txt

@@ -11,6 +11,11 @@ if(NOT CMAKE_BUILD_TYPE)
   set(CMAKE_BUILD_TYPE RelWithDebInfo CACHE STRING "" FORCE)
 endif()
 
+# Build identifier (git describe / VERSION file / -DMOQX_VERSION_STRING).
+# Defines the moqx_version interface target carrying the generated
+# moqx/Version.h, and writes ${CMAKE_BINARY_DIR}/VERSION for packaging.
+include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/MoqxVersion.cmake)
+
 option(MOQX_BUILD_TESTS "Build tests" ON)
 option(MOQX_BUILD_BENCHMARKS "Build benchmarks" OFF)
 option(MOQX_ENABLE_SANITIZERS "Enable ASAN/UBSAN (non-Release)" OFF)
@@ -202,14 +207,10 @@ target_link_libraries(moqx_core PUBLIC
 )
 
 target_compile_options(moqx_core PRIVATE -Wall -Wextra -Wpedantic)
-# Version reported by /info (and the relay dashboard badge). CI passes
-# `git describe --tags` here: the bare tag on release commits (v0.2.1),
-# tag-distance-sha on snapshots (v0.2.1-14-g2ed29c8). Local builds fall
-# back to the static project version.
-if(NOT MOQX_VERSION_STRING)
-  set(MOQX_VERSION_STRING "${PROJECT_VERSION}")
-endif()
-target_compile_definitions(moqx_core PRIVATE MOQX_VERSION="${MOQX_VERSION_STRING}")
+# Build identifier — see cmake/MoqxVersion.cmake. PUBLIC so consumers (the
+# moqx binary, tests, tools) can include moqx/Version.h too: the version is
+# no longer a private compile definition on this one library.
+target_link_libraries(moqx_core PUBLIC moqx_version)
 
 # --- Config types (resolved Config structs, header-only, no rfl dependency) ---
 # Library consumers that only need the Config API link this.
@@ -326,3 +327,8 @@ endif()
 include(${PROJECT_SOURCE_DIR}/cmake/Lint.cmake)
 
 install(TARGETS moqx moqx-issuer moqx_core moqx_config_loader)
+
+# Ship the build identifier alongside the binaries so an unpacked release or
+# snapshot tarball can be identified with `cat VERSION` — no git history, and
+# no need to run the binary (wrong arch, no libs, or a container layer).
+install(FILES ${CMAKE_BINARY_DIR}/VERSION DESTINATION .)

cmake/MoqxVersion.cmake

@@ -0,0 +1,92 @@
+# Version derivation for moqx.
+#
+# Produces MOQX_VERSION_STRING: one canonical identifier consumed by every
+# binary (admin /info, --version, the startup log banner) and embedded in
+# build artifacts as a VERSION file, so a tarball or container can be
+# identified without its git history.
+#
+# Format is git-describe output with the "v" tag prefix retained, so the
+# string round-trips into `git checkout` / `gh release view`:
+#
+#   v0.2.1                     exact release tag
+#   v0.2.1-14-gabc1234         14 commits past v0.2.1
+#   v0.2.1-14-gabc1234-dirty   ...with uncommitted changes (local builds)
+#   abc1234                    no reachable v* tag (shallow clone, fork)
+#
+# Resolution order, first hit wins:
+#
+#   1. -DMOQX_VERSION_STRING=...  explicit override (CI, docker --build-arg)
+#   2. <source root>/VERSION      source tarballs and the docker build context
+#                                 carry no .git; CI writes this file for them
+#   3. git describe               any real clone, including local dev builds
+#   4. v${PROJECT_VERSION}        last resort, e.g. v0.1.0
+#
+# Only v-prefixed numeric tags are considered. The repo also carries moving
+# tags (snapshot-latest, build-*, archive/*) that are NOT versions; an
+# unfiltered `git describe` happily returns "snapshot-latest" and poisons
+# the version of every artifact built from main.
+#
+# Derivation happens at configure time. A dev who commits without re-running
+# cmake keeps the previous string until the next configure; CI configures
+# fresh every run, so published artifacts are always exact.
+
+function(_moqx_version_from_git out_var)
+  set(${out_var} "" PARENT_SCOPE)
+
+  find_package(Git QUIET)
+  if(NOT GIT_FOUND)
+    return()
+  endif()
+
+  # A worktree's .git is a file, not a directory — EXISTS covers both.
+  if(NOT EXISTS "${PROJECT_SOURCE_DIR}/.git")
+    return()
+  endif()
+
+  execute_process(
+    COMMAND "${GIT_EXECUTABLE}" describe --tags --match "v[0-9]*" --always --dirty
+    WORKING_DIRECTORY "${PROJECT_SOURCE_DIR}"
+    OUTPUT_VARIABLE _described
+    OUTPUT_STRIP_TRAILING_WHITESPACE
+    ERROR_QUIET
+    RESULT_VARIABLE _rc
+  )
+  if(_rc EQUAL 0 AND _described)
+    set(${out_var} "${_described}" PARENT_SCOPE)
+  endif()
+endfunction()
+
+if(MOQX_VERSION_STRING)
+  set(_moqx_version_source "explicit -DMOQX_VERSION_STRING")
+elseif(EXISTS "${PROJECT_SOURCE_DIR}/VERSION")
+  file(READ "${PROJECT_SOURCE_DIR}/VERSION" MOQX_VERSION_STRING)
+  string(STRIP "${MOQX_VERSION_STRING}" MOQX_VERSION_STRING)
+  set(_moqx_version_source "VERSION file")
+else()
+  _moqx_version_from_git(MOQX_VERSION_STRING)
+  if(MOQX_VERSION_STRING)
+    set(_moqx_version_source "git describe")
+  else()
+    set(MOQX_VERSION_STRING "v${PROJECT_VERSION}")
+    set(_moqx_version_source "project() fallback")
+  endif()
+endif()
+
+message(STATUS "moqx version: ${MOQX_VERSION_STRING} (from ${_moqx_version_source})")
+
+# Generated header — any target may link moqx_version to use it, so the
+# version is not welded to one library the way a target_compile_definitions
+# would be.
+set(MOQX_VERSION_HEADER_DIR "${CMAKE_BINARY_DIR}/generated")
+configure_file(
+  "${PROJECT_SOURCE_DIR}/cmake/Version.h.in"
+  "${MOQX_VERSION_HEADER_DIR}/moqx/Version.h"
+  @ONLY
+)
+
+add_library(moqx_version INTERFACE)
+target_include_directories(moqx_version INTERFACE "${MOQX_VERSION_HEADER_DIR}")
+
+# Artifact-side copy: `cat VERSION` identifies an unpacked tarball or an
+# image layer with no binary to run and no git history to consult.
+file(WRITE "${CMAKE_BINARY_DIR}/VERSION" "${MOQX_VERSION_STRING}\n")

cmake/Version.h.in

@@ -0,0 +1,25 @@
+/*
+ * Copyright (c) OpenMOQ contributors.
+ * This source code is licensed under the Apache 2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * GENERATED FILE — do not edit. Source template: cmake/Version.h.in,
+ * derivation: cmake/MoqxVersion.cmake.
+ */
+
+#pragma once
+
+#include <string_view>
+
+// Macro form: usable in string-literal concatenation (e.g. the admin /info
+// JSON body). Prefer openmoq::moqx::kVersion in new code.
+#define MOQX_VERSION "@MOQX_VERSION_STRING@"
+
+namespace openmoq::moqx {
+
+// Canonical build identifier: a git describe string with the "v" tag prefix
+// retained (v0.2.1, v0.2.1-14-gabc1234, v0.2.1-14-gabc1234-dirty), or a bare
+// commit sha when no v* tag is reachable.
+inline constexpr std::string_view kVersion{MOQX_VERSION};
+
+} // namespace openmoq::moqx

docker/Dockerfile

@@ -13,16 +13,21 @@ WORKDIR /src
 # Moxygen tarball (pre-extracted bookworm build)
 COPY .docker-deps/moxygen /opt/moxygen
 
-# MoQX source — only what cmake needs
-COPY CMakeLists.txt CMakePresets.json ./
+# MoQX source — only what cmake needs.
+# VERSIO[N] is an optional-copy glob: CI stamps a VERSION file into the build
+# context (the context excludes .git, so cmake can't run git describe here),
+# but a bare `docker build` has none and must still work. The glob matches
+# nothing in that case, and the COPY still succeeds because CMakeLists.txt
+# does — a plain `COPY VERSION` would hard-fail instead.
+COPY CMakeLists.txt CMakePresets.json VERSIO[N] ./
 COPY cmake/ cmake/
 COPY src/ src/
 COPY deps/catapult/ deps/catapult/
 COPY deps/moxygen/build/fbcode_builder/CMake deps/moxygen/build/fbcode_builder/CMake
 
-# Version string baked into /info — CI passes `git describe --tags` (the
-# build context has no .git, so it can't be derived here). Empty means the
-# CMake fallback (static project version) applies.
+# Explicit override for one-off builds; normally empty, in which case cmake
+# falls through to the VERSION file copied above (then to the static project
+# version if that is absent too). See cmake/MoqxVersion.cmake.
 ARG MOQX_VERSION_STRING=""
 
 RUN cmake -S . -B _build --preset default \
@@ -44,6 +49,10 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 
 COPY --from=builder /install/bin/moqx /usr/local/bin/moqx
 COPY --from=builder /install/bin/moqx-issuer /usr/local/bin/moqx-issuer
+# Build identifier as a plain file, so an image can be identified without
+# executing it — inspecting a layer, or a foreign-arch image that cannot run
+# here. `docker run --rm <image> moqx --version` reports the same string.
+COPY --from=builder /install/VERSION /usr/local/VERSION
 COPY docker/entrypoint.sh /usr/local/bin/entrypoint.sh
 COPY docker/config.docker.yaml /usr/local/share/moqx/config.docker.yaml
 RUN chmod +x /usr/local/bin/entrypoint.sh

src/admin/BuiltinRoutes.cpp

@@ -11,6 +11,7 @@
 #include <proxygen/lib/http/HTTPMessage.h>
 
 #include "admin/AdminServer.h"
+#include "moqx/Version.h"
 
 namespace openmoq::moqx::admin {
 

src/main.cpp

@@ -15,6 +15,7 @@
 #include "bpf/QuicReuseportSteering.h"
 #include "config/loader/ConfigInit.h"
 #include "logging/LogSetup.h"
+#include "moqx/Version.h"
 #include "stats/StatsRegistry.h"
 
 #include <csignal>
@@ -76,6 +77,10 @@ int main(int argc, char* argv[]) {
       "  serve                Start the relay (default)\n" +
       cfg::configSubcommandUsage() + "\nUsage: moqx [subcommand] --config <path>"
   );
+  // Powers `moqx --version` (gflags handles the flag inside folly::Init).
+  // Works with no config file present, so an image or tarball can be
+  // identified without deploying it.
+  google::SetVersionString(MOQX_VERSION);
   // MOQX_LOGGING is the moqx-namespaced alias for folly's own FOLLY_LOGGING env
   // var (folly::Init reads FOLLY_LOGGING). Promote it here — before folly::Init
   // — so the knob works for any launch method (docker, systemd, bare metal)
@@ -89,6 +94,10 @@ int main(int argc, char* argv[]) {
   combineLoggingArgs(argc, argv);
   folly::Init init(&argc, &argv, true);
 
+  // First line in every relay's log: attributes the whole log stream to an
+  // exact build (see cmake/MoqxVersion.cmake for the identifier's format).
+  XLOG(INFO) << "moqx " << kVersion << " starting";
+
   std::string_view subcommand = kServeCommand;
   if (argc > 1) {
     subcommand = argv[1];