feat: add anonymous usage reporting, matching traefikoidc

Release builds send one anonymous "plugin loaded" ping per process, so the project can see roughly how many installs exist and which versions are in use. The payload is project name, version and timestamp. Nothing else leaves the pod: no identifiers, no hostname, no configuration, no provider names, no keys, no request data. Three things keep it from firing when it should not. Builds from source carry the devPluginVersion sentinel and stay silent, so developer checkouts and every test run never phone home. The ping is sent only after the plugin constructs successfully, so a rejected configuration is never counted as an install. A sync.Once holds it to one per process, because Traefik calls New once per route and oss-telemetry does not deduplicate on the client side. Operators of a release build opt out with DO_NOT_TRACK=1, OSS_TELEMETRY_DISABLED=1, or TRAEFIK_LLMGATEWAY_DISABLE_TELEMETRY=1. README.md documents the full payload and the opt-out; a plugin that phones home without saying so in its own README would be indefensible. oss-telemetry is the plugin's first non-stdlib RUNTIME dependency, which has consequences for the Yaegi gate: - vendor/ is no longer excluded from yaegi-check's GOPATH copy. It was excluded on the reasoning that it held only test-only testify and _test.go files are never interpreted. That reasoning no longer holds: leaving vendor out would make the interpreted copy fail to resolve an import the real plugin tree resolves fine, so the gate would stop representing production. - yaegi-check now stamps a fake release version into its GOPATH copy so New's telemetry gate is PASSED rather than short-circuited, and the vendored package is actually called under the interpreter. Import resolution alone is not coverage; a cross-package call into interpreted third-party code is its own risk. Telemetry is suppressed by env vars set before anything is interpreted, so the gate never emits a real ping. - A new assertion reads the version back through GET /admin/api/overview. Without it a silently failed stamp would leave the dev sentinel in place and the harness would still print OK while covering nothing. Verified by disabling the stamp and watching the gate fail. shouldSendTelemetry is split out from sendStartupTelemetry so the decision is table-testable without a network, since oss-telemetry's endpoint is deliberately not overridable from consuming code. Also brings the version-gated documentation up to date, since the same README edit touches it. The latest release is v1.0.3, so the pre-1.0 experimental warning has met its own stated condition and is replaced by a semver stability statement in README.md and dropped from .traefik.yml's catalog summary. The catalog now serves the released tags (verified: the v1.0.3 download endpoint returns 200), so the "not yet published" and "analyzer has not been run" claims are corrected, the catalog form of the static config is documented as usable, and examples/kubernetes.yaml pins v1.0.3 instead of v0.1.0.
2026-10-14 05:18:54 +00:00 · 2026-08-22 18:45:36 +01:00
parent 0346c3ed39
commit 9dc67dedbb
15 changed files with 938 additions and 54 deletions
@@ -0,0 +1 @@
+.docs
@@ -0,0 +1,36 @@
+version: "2"
+
+run:
+  timeout: 2m
+
+linters:
+  default: none
+  enable:
+    - bodyclose
+    - errcheck
+    - errorlint
+    - gocritic
+    - gocyclo
+    - govet
+    - ineffassign
+    - misspell
+    - prealloc
+    - revive
+    - staticcheck
+    - unconvert
+    - unused
+  settings:
+    gocyclo:
+      min-complexity: 12
+    revive:
+      rules:
+        - name: var-naming
+        - name: indent-error-flow
+        - name: superfluous-else
+        - name: unused-parameter
+        - name: redefines-builtin-id
+
+formatters:
+  enable:
+    - gofmt
+    - goimports
@@ -0,0 +1,42 @@
+# Configuration for lukaszraczylo/semver-generator.
+# Reference: https://github.com/lukaszraczylo/semver-generator
+#
+# Word matching is fuzzy + case-insensitive. The keywords below mirror the
+# Conventional Commits prefixes used in this repo's git history. Same pattern
+# as github.com/lukaszraczylo/go-telegram/.semver.yaml.
+
+version: 1
+
+# Respect existing v* tags as the version baseline. semver-generator finds
+# the highest existing tag and bumps from there. With no tags yet, the first
+# release computes from the empty base.
+force:
+  existing: true
+
+# Skip merge commits and machine-generated traffic that would otherwise
+# spuriously bump the version.
+blacklist:
+  - "Merge branch"
+  - "Merge pull request"
+  - "Merge remote-tracking branch"
+  - "go mod tidy"
+
+wording:
+  patch:
+    - "fix"
+    - "chore"
+    - "docs"
+    - "test"
+    - "style"
+    - "refactor"
+    - "build"
+    - "ci"
+    - "perf"
+  minor:
+    - "feat"
+  major:
+    # Match only the canonical Conventional Commits trailer. The bare word
+    # "breaking" is too greedy under semver-generator's fuzzy match — it
+    # triggers on substrings inside a commit body and wrongly produces a
+    # major bump.
+    - "BREAKING CHANGE"
@@ -0,0 +1,122 @@
+# oss-telemetry
+
+A tiny Go client that fires one anonymous "this binary started" ping at a
+central ingest endpoint. Designed to be embedded in your own open-source
+projects so you can see approximate adoption and version spread without
+collecting anything that could identify a user.
+
+This is the **client library only**. The ingest endpoint, server-side
+deduplication, rate limiting, and metrics are out of scope here.
+
+## What it sends
+
+A single HTTP `POST` per call to `Send`:
+
+```json
+{
+  "project": "my-tool",
+  "version": "1.2.3",
+  "ts": 1747782200
+}
+```
+
+No identifiers, no IP, no machine info, no user data. The server dedupes
+incoming requests; the client just fires and forgets.
+
+## Failproof by design
+
+- Never blocks the caller — work runs in a goroutine.
+- Never panics — the goroutine recovers internally.
+- Never returns errors — bad input and network failures are silently dropped.
+- Never retries, never persists state, never reads back.
+- 2-second hard timeout on every request.
+- Zero third-party dependencies (Go stdlib only).
+
+The endpoint is hardcoded and not overridable from consuming code, by design.
+
+## Install
+
+```bash
+go get github.com/lukaszraczylo/oss-telemetry
+```
+
+Requires Go 1.22+.
+
+## Usage
+
+```go
+package main
+
+import (
+    "time"
+
+    telemetry "github.com/lukaszraczylo/oss-telemetry"
+)
+
+const version = "1.2.3"
+
+func main() {
+    telemetry.Send("my-tool", version)
+
+    // ... your program runs ...
+
+    // Only needed for short-lived CLIs that may exit before the goroutine
+    // finishes its POST. Long-running services do not need this.
+    telemetry.Wait(2 * time.Second)
+}
+```
+
+Call `Send` once at boot. Calling it more often just sends more pings; the
+server deduplicates.
+
+## Disabling telemetry
+
+If you ship a binary that imports this library, link your users to this
+section (`https://github.com/lukaszraczylo/oss-telemetry#disabling-telemetry`)
+so they can find the opt-out paths.
+
+Any one of these turns it off:
+
+| Mechanism                                | How                                                              |
+| ---------------------------------------- | ---------------------------------------------------------------- |
+| Universal opt-out                        | `DO_NOT_TRACK=1`                                                 |
+| Library-wide opt-out                     | `OSS_TELEMETRY_DISABLED=1`                                       |
+| Project-specific opt-out                 | `<UPPER_PROJECT>_DISABLE_TELEMETRY=1`                            |
+| Programmatic (e.g. behind a `--no-telemetry` flag) | `telemetry.Disable()` before the first `Send`          |
+
+Project-specific env var derivation: uppercase the project name and replace
+`-` with `_`. For `my-tool` the variable is `MY_TOOL_DISABLE_TELEMETRY`.
+
+Truthy values: `1`, `true`, `yes`, `on` (case-insensitive). Anything else is
+treated as "not set".
+
+## Validation rules (silently dropped if violated)
+
+- `project`: matches `^[a-z0-9-]+$`, length 1–64.
+- `version`: matches `^[A-Za-z0-9.+_-]+$`, length 1–32.
+
+Bad input is a no-op — the library never logs, never errors, never crashes.
+
+## API
+
+```go
+// Fire a single ping in the background. Returns immediately.
+func Send(project, version string)
+
+// Suppress all subsequent Send calls in this process. Idempotent.
+func Disable()
+
+// Block until in-flight pings complete or timeout elapses, whichever first.
+// Useful for short-lived CLI processes.
+func Wait(timeout time.Duration)
+```
+
+## Testing
+
+```bash
+go test -race ./...
+```
+
+## License
+
+Pick one before publishing. None bundled.
@@ -0,0 +1,367 @@
+// Package telemetry sends anonymous usage pings for open-source Go projects.
+//
+// Wire format (POST application/json):
+//
+//	{"project":"<name>","version":"<ver>","ts":<unix-seconds>}
+//
+// Design contract (failproof):
+//   - never blocks the caller (work happens in a goroutine)
+//   - never panics (background goroutine recovers internally)
+//   - never returns errors (silently no-ops on bad input or network failure)
+//   - never retries, never deduplicates, never persists state — the client
+//     fires a single ping and forgets; the server is responsible for
+//     deduplication, abuse protection, and aggregation
+//
+// Typical usage at program startup:
+//
+//	telemetry.Send("my-tool", "1.2.3")
+//
+// For short-lived CLI processes that may exit before the goroutine finishes:
+//
+//	telemetry.Send("my-tool", "1.2.3")
+//	defer telemetry.Wait(2 * time.Second)
+//
+// Disablement (any one of these suppresses pings):
+//   - environment variable DO_NOT_TRACK=1
+//   - environment variable OSS_TELEMETRY_DISABLED=1
+//   - environment variable <UPPER_PROJECT>_DISABLE_TELEMETRY=1
+//     (project name uppercased, dashes replaced with underscores)
+//   - calling telemetry.Disable() at runtime
+package telemetry
+
+import (
+	"bytes"
+	"context"
+	"net/http"
+	"os"
+	"runtime/debug"
+	"strconv"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"time"
+)
+
+const (
+	defaultEndpoint = "https://oss.raczylo.com/v1/ping"
+	httpTimeout     = 2 * time.Second
+	maxProjectLen   = 64
+	maxVersionLen   = 32
+)
+
+// Yaegi note: this package is consumed by the traefikoidc Traefik plugin, which
+// Traefik interprets with Yaegi (it vendors and interprets dependency source).
+// It therefore avoids generic stdlib types (atomic.Pointer[T], atomic.Bool) and
+// range-over-int (Go 1.22), which some Traefik/Yaegi runtimes cannot interpret.
+// Endpoint mutation uses a mutex-guarded string; the disabled flag uses the
+// function-based sync/atomic int32 API (atomic.LoadInt32/StoreInt32).
+var (
+	// endpointURL holds the ingest URL. Production code never mutates it; the
+	// setter exists only so the test suite can retarget it at httptest servers
+	// while goroutines started by Send are still in flight.
+	endpointMu  sync.RWMutex
+	endpointURL = defaultEndpoint
+
+	disabled int32 // 0 = enabled, 1 = disabled; accessed via sync/atomic only
+	inflight sync.WaitGroup
+
+	client = &http.Client{Timeout: httpTimeout}
+)
+
+func currentEndpoint() string {
+	endpointMu.RLock()
+	defer endpointMu.RUnlock()
+	return endpointURL
+}
+
+func setEndpointURL(u string) {
+	endpointMu.Lock()
+	endpointURL = u
+	endpointMu.Unlock()
+}
+
+// Send fires a single anonymous telemetry ping in the background and returns
+// immediately. It never blocks, never panics, and never reports errors.
+// Invalid inputs, disabled state, and network failures are silently dropped.
+//
+// Version strings are validated against a SemVer-ish shape that mirrors the
+// receiver. An optional leading "v" or "V" is accepted and stripped before
+// transmission so that callers can pass either "v1.2.3" or "1.2.3"; the
+// wire form is always the unprefixed canonical version.
+//
+// Call once at program startup. Calling repeatedly will send repeated pings;
+// the server is responsible for deduplication.
+func Send(project, version string) {
+	if atomic.LoadInt32(&disabled) != 0 {
+		return
+	}
+	if isDisabledByEnv(project) {
+		return
+	}
+	if !validProject(project) || !validVersion(version) {
+		return
+	}
+	canonical := normalizeVersion(version)
+
+	inflight.Add(1)
+	go func() {
+		defer inflight.Done()
+		defer func() { _ = recover() }()
+		dispatch(project, canonical)
+	}()
+}
+
+// SendForModule is the recommended call form for Go libraries: it resolves
+// the version automatically from Go's build info for the given module path
+// so consumers do not need to maintain a hand-bumped version constant in
+// source. Behaviour and contract are otherwise identical to [Send].
+//
+// Resolution order:
+//
+//  1. debug.ReadBuildInfo Deps entry for modulePath (authoritative when the
+//     library is consumed via go.mod);
+//  2. debug.ReadBuildInfo Main when the library is itself the main module
+//     (e.g. running its own tests or examples);
+//  3. fallback parameter, used only when build info is unavailable or
+//     unhelpful (replace directives, detached `go run`, ldflag override).
+//
+// Any leading "v" reported by build info is stripped to match the canonical
+// wire form. Empty / "(devel)" build versions are skipped in favour of the
+// next resolution source. Typical usage:
+//
+//	telemetry.SendForModule("my-tool", "github.com/me/my-tool", "0.0.0-dev")
+func SendForModule(project, modulePath, fallback string) {
+	Send(project, ResolveModuleVersion(modulePath, fallback))
+}
+
+// ResolveModuleVersion implements the version resolution used by
+// SendForModule. Exposed for callers that need to format the resolved
+// version (e.g. logging) without firing a ping.
+func ResolveModuleVersion(modulePath, fallback string) string {
+	if info, ok := debug.ReadBuildInfo(); ok {
+		for _, d := range info.Deps {
+			if d != nil && d.Path == modulePath && isUsableBuildVersion(d.Version) {
+				return strings.TrimPrefix(d.Version, "v")
+			}
+		}
+		if info.Main.Path == modulePath && isUsableBuildVersion(info.Main.Version) {
+			return strings.TrimPrefix(info.Main.Version, "v")
+		}
+	}
+	return fallback
+}
+
+func isUsableBuildVersion(v string) bool {
+	return v != "" && v != "(devel)"
+}
+
+// Disable suppresses all subsequent Send calls in this process.
+// Idempotent and safe to call from any goroutine.
+func Disable() {
+	atomic.StoreInt32(&disabled, 1)
+}
+
+// Wait blocks until all in-flight pings have completed, or until timeout
+// elapses — whichever comes first. Useful for short-lived CLI processes
+// that may otherwise exit before the background goroutine finishes its POST.
+//
+// A non-positive timeout returns immediately.
+func Wait(timeout time.Duration) {
+	if timeout <= 0 {
+		return
+	}
+	done := make(chan struct{})
+	go func() {
+		inflight.Wait()
+		close(done)
+	}()
+	select {
+	case <-done:
+	case <-time.After(timeout):
+	}
+}
+
+func dispatch(project, version string) {
+	body := buildPayload(project, version, time.Now().Unix())
+
+	ctx, cancel := context.WithTimeout(context.Background(), httpTimeout)
+	defer cancel()
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, currentEndpoint(), bytes.NewReader(body))
+	if err != nil {
+		return
+	}
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := client.Do(req)
+	if err != nil {
+		return
+	}
+	_ = resp.Body.Close()
+}
+
+// buildPayload writes the JSON body without encoding/json. The validators
+// restrict project and version to characters that never require JSON
+// escaping, so direct concatenation is safe.
+func buildPayload(project, version string, ts int64) []byte {
+	// Wrapper text plus 20 chars for a signed int64.
+	const overhead = len(`{"project":"","version":"","ts":}`) + 20
+	buf := make([]byte, 0, len(project)+len(version)+overhead)
+	buf = append(buf, `{"project":"`...)
+	buf = append(buf, project...)
+	buf = append(buf, `","version":"`...)
+	buf = append(buf, version...)
+	buf = append(buf, `","ts":`...)
+	buf = strconv.AppendInt(buf, ts, 10)
+	buf = append(buf, '}')
+	return buf
+}
+
+func validProject(p string) bool {
+	n := len(p)
+	if n == 0 || n > maxProjectLen {
+		return false
+	}
+	for i := 0; i < n; i++ {
+		c := p[i]
+		switch {
+		case c >= 'a' && c <= 'z',
+			c >= '0' && c <= '9',
+			c == '-':
+		default:
+			return false
+		}
+	}
+	return true
+}
+
+// validVersion accepts SemVer-ish version strings with an optional leading
+// "v"/"V" prefix. Acceptable shape (after stripping the leading v):
+//
+//	MAJOR[.MINOR[.PATCH]] ("-"prerelease)? ("+"build)?
+//
+// where MAJOR/MINOR/PATCH are ASCII digit sequences and the prerelease/build
+// payloads are non-empty runs of [0-9A-Za-z.-]. This intentionally mirrors
+// the receiver's version regex so junk like "dev" or "git-2026-05-22" never
+// leaves the client (where it would only be rejected with HTTP 400 anyway).
+func validVersion(v string) bool {
+	n := len(v)
+	if n == 0 || n > maxVersionLen {
+		return false
+	}
+	if v[0] == 'v' || v[0] == 'V' {
+		v = v[1:]
+	}
+	if len(v) == 0 {
+		return false
+	}
+	return checkSemverShape(v)
+}
+
+// normalizeVersion strips an optional leading "v"/"V" so the on-the-wire
+// version matches the form stored server-side by the version refresher cron
+// (which also strips the leading v from release tags). Callers may pass
+// either "v1.2.3" or "1.2.3" — only the unprefixed form is transmitted.
+func normalizeVersion(v string) string {
+	if len(v) > 0 && (v[0] == 'v' || v[0] == 'V') {
+		return v[1:]
+	}
+	return v
+}
+
+func checkSemverShape(s string) bool {
+	i := 0
+	if !readDigitRun(s, &i) {
+		return false
+	}
+	for groups := 0; groups < 2 && i < len(s) && s[i] == '.'; groups++ {
+		i++
+		if !readDigitRun(s, &i) {
+			return false
+		}
+	}
+	if i < len(s) && s[i] == '-' {
+		i++
+		if !readIdentRun(s, &i, '+') {
+			return false
+		}
+	}
+	if i < len(s) && s[i] == '+' {
+		i++
+		if !readIdentRun(s, &i, 0) {
+			return false
+		}
+	}
+	return i == len(s)
+}
+
+func readDigitRun(s string, i *int) bool {
+	start := *i
+	for *i < len(s) && s[*i] >= '0' && s[*i] <= '9' {
+		*i++
+	}
+	return *i > start
+}
+
+// readIdentRun consumes [0-9A-Za-z.-] until end-of-string or until `stop`
+// is hit (stop=0 disables the early-stop check). Returns false if no
+// characters were consumed (i.e. empty payload).
+func readIdentRun(s string, i *int, stop byte) bool {
+	start := *i
+	for *i < len(s) {
+		c := s[*i]
+		if stop != 0 && c == stop {
+			break
+		}
+		valid := (c >= '0' && c <= '9') ||
+			(c >= 'A' && c <= 'Z') ||
+			(c >= 'a' && c <= 'z') ||
+			c == '.' || c == '-'
+		if !valid {
+			return false
+		}
+		*i++
+	}
+	return *i > start
+}
+
+func isDisabledByEnv(project string) bool {
+	if truthy(os.Getenv("DO_NOT_TRACK")) {
+		return true
+	}
+	if truthy(os.Getenv("OSS_TELEMETRY_DISABLED")) {
+		return true
+	}
+	if project == "" {
+		return false
+	}
+	key := projectEnvKey(project)
+	return truthy(os.Getenv(key))
+}
+
+// projectEnvKey returns "<UPPER_PROJECT>_DISABLE_TELEMETRY" using a single
+// allocation rather than chained strings.ToUpper(strings.ReplaceAll(...)).
+func projectEnvKey(project string) string {
+	const suffix = "_DISABLE_TELEMETRY"
+	buf := make([]byte, 0, len(project)+len(suffix))
+	for i := 0; i < len(project); i++ {
+		c := project[i]
+		switch {
+		case c == '-':
+			c = '_'
+		case c >= 'a' && c <= 'z':
+			c -= 'a' - 'A'
+		}
+		buf = append(buf, c)
+	}
+	buf = append(buf, suffix...)
+	return string(buf)
+}
+
+func truthy(s string) bool {
+	switch strings.ToLower(strings.TrimSpace(s)) {
+	case "1", "true", "yes", "on":
+		return true
+	}
+	return false
+}