Skip to content

TODO.md

Latest commit

 

History

History
126 lines (107 loc) · 5.79 KB

TODO.md

File metadata and controls

126 lines (107 loc) · 5.79 KB
Raw

TODO — Agent Integration Readiness

STATUS: COMPLETED in v3.0.0 (released 2026-04-12) — see CHANGELOG.md

All standardization tasks listed below have been delivered. This file is kept as a historical record of the work that landed in v3.0.0. New tasks should go to GitHub Issues, not back into this file.

The repository has since been renamed go-snmp-olt-zte-c320 → snmp-olt-zte (v3.2.0); the old name below is accurate for the era this record describes.

Result

go-snmp-olt-zte-c320 v3.0.0 is now the second compliant adapter (after freeradius-api v1.2.0) for the ISP adapter standard — see wiki:

  • [[go-snmp-olt-zte-c320]] — entity page
  • [[isp-adapter-standard]] — JSON contract
  • [[isp-logging-standard]] — zap schema
  • [[isp-development-requirements]] — full dev requirements

Delivered (all priorities below shipped in v3.0.0)

Priority 1 — Response Format ✅

  • error_code flattened from error.type to top level
  • error.message renamed to data (string or {message,details} map)
  • Success status "OK" → "success"
  • All handlers updated, OpenAPI spec regenerated, unit tests updated

Priority 2 — Logging ✅

  • Migrated github.com/rs/zerolog → go.uber.org/zap (146 call sites across 13 files)
  • Centralized pkg/logger/logger.go with Init, WithRequestID, WithModule, SetForTest
  • Required base fields (service, version) auto-attached
  • WithRequestID(ctx) helper for per-request loggers
  • ISO8601 UTC timestamps with ms precision
  • snake_case keys, _ms suffix for durations
  • Standard field names: request_id, operation, error_code, device_id, etc.
  • Skip logging /health, /healthz, /ready, /readyz, /metrics endpoints
  • Audit log middleware for POST/PUT/PATCH/DELETE via "audit" named sub-logger

Priority 3 — Request ID ✅

  • request_id field added to error response body (was header-only)
  • internal/reqctx leaf package created to break import cycle
  • Context propagated through usecase → repository layer
  • X-Request-ID echoed in response header AND error body

Priority 4 — Health Endpoints ✅

  • /health kept as backwards-compat alias
  • /healthz added (k8s liveness probe)
  • /readyz added with cached dependency probes (Redis 5s TTL, SNMP 30s TTL)
  • Returns 503 + {"status":"not_ready", "dependencies":{...}} when down
  • /version endpoint added with build metadata (uses ldflags)

Priority 5 — Prometheus Metrics ✅

  • pkg/metrics/prometheus.go created
  • HTTP middleware records request counter + duration histogram + in-flight gauge
  • SNMP operation metrics: snmp_operations_total, snmp_operation_duration_seconds
  • Cache metrics: snmp_cache_hits_total, snmp_cache_misses_total
  • /metrics endpoint mounted (unauthenticated)
  • Path normalization to avoid label cardinality explosion

Priority 6 — Framework Migration (chi → Fiber)

  • Decision: SKIP — chi works fine, JSON contract is what matters
  • Documented in CLAUDE.md §Framework notes for future contributors

Priority 7 — CI/CD Verification ✅

  • golangci-lint v2 — 0 issues
  • govulncheck — 0 vulnerabilities
  • Multi-arch Docker build (amd64, arm64, arm/v7) verified on Docker Hub
  • Dockerfile ldflags fix: main.Version (uppercase, never matched) → main.version + main.commit + main.buildTime
  • CI passes APP_COMMIT and APP_BUILD_TIME to docker build-push-action

Priority 8 — Documentation ✅

  • CLAUDE.md created (project overview, architecture, import boundaries, patterns)
  • OpenAPI spec updated to v3.0.0 with new ErrorResponse schema + /healthz, /readyz, /version, /metrics paths
  • CHANGELOG.md [3.0.0] section with migration table
  • README.md updated (zerolog → zap in tech stack, v3.0.0 in image tag)
  • test.http updated with new endpoints + error envelope examples + X-Request-ID tracing example
  • k6-load-test.js updated for v3.0.0 (per-scenario thresholds, contract_check scenario, validateErrorEnvelope helper)
  • Wiki entity page go-snmp-olt-zte-c320 created
  • Wiki isp-adapter-standard and isp-logging-standard compliance tables updated

Priority 9 — Dependencies & Security ✅

  • go mod tidy clean
  • govulncheck ./... — 0 vulnerabilities

Acceptance Criteria — all met

[x] Response: status/data/code format (success="success", error_code top-level)
[x] Logging: zap JSON, standard fields, request_id propagated
[x] Health: /healthz (minimal) + /readyz (with deps check)
[x] Request ID in error response body
[x] Audit log for write operations
[x] Tests: 97.9% coverage (vs 98.6% baseline; gap is logger.Fatal os.Exit + Init cfg.Build error path)
[x] golangci-lint v2: 0 issues
[x] govulncheck: 0 vulnerabilities
[x] OpenAPI spec regenerated
[x] CLAUDE.md created
[x] CI/CD passes end-to-end (PR #38 merged, v3.0.0 tag CI passed)

k6 Load Test Baseline (2026-04-12)

3542 requests over 3m30s
16.79 req/s sustained, 8 VUs peak
Cache hit rate: 99.5%
p95 cached:     4ms
p99 cached:     7ms
SNMP cold path: ~7s avg, 12s p95 (OLT bottleneck, not adapter)
Validation:     1ms p95
Health probes:  1ms p95 (sub-millisecond)
Real failure rate: 0
All 12 thresholds passed.

Lessons Learned

See [[go-snmp-olt-zte-c320]] wiki page §Lessons Learned for the full list. Highlights:

  • ldflags injection silently broken for entire 2.x series due to capitalisation typo
  • Naive context-key placement caused import cycle; fixed by extracting to leaf package
  • k6 default http_req_failed threshold false-alarms on intentional 4xx
  • zap chosen over zerolog despite zerolog being faster (consistency wins)
  • Cache pre-warming pays off massively (99.5% hit rate from cold start)