Files

Gabriel Radureau 7fef564ba9 ✨ feat(server): api.v2_enabled hot-reload via middleware gate (ADR-0023 Phase 4)

Closes ADR-0023 — all 4 phases now shipped. Final field: api.v2_enabled.

Approach: always-register-with-middleware-gate.

- /api/v2/* routes are now registered UNCONDITIONALLY at startup
- new Server.v2EnabledGate middleware reads the live config on every
  request and returns 404 + {"error":"not_found","message":"v2 API is
  currently disabled"} when api.v2_enabled is false
- the existing Config.WatchAndApply hot-reload pipeline already keeps
  the config struct fresh — no extra plumbing needed
- flag flip takes effect on the NEXT request (not in-flight ones)
- no router rebuild, no restart

Tested via 3 unit tests in pkg/server/v2_gate_test.go:
- blocked-when-disabled: 404 + correct error message + JSON content-type
- passes-when-enabled: NOT 404, gate message ABSENT (handler executed)
- hot-reload-mid-life: same Server, same router, config flipped between
  two requests → 404 then 200, proves the gate reads live config

Race detector clean. Full BDD suite green. ADR-0023 status promoted to
"Implemented" (no more parenthetical phase tracking).

The original "deferred" rationale in ADR-0023 listed router refactor as
the cost. Turns out the cost was minimal: ~25 lines of middleware + 3
tests + an `if` block deletion.

2026-05-05 10:34:43 +02:00

5.4 KiB

Raw Blame History

Architecture Decision Records (ADRs)

This directory contains the Architecture Decision Records (ADRs) for the dance-lessons-coach project. Each ADR captures a structurally important decision, its context, and its consequences.

Index

ADR	Title	Status
0001	Use Go 1.26.1 as the standard Go version	Accepted
0002	Use Chi router for HTTP routing	Accepted
0003	Use Zerolog for structured logging	Accepted
0004	Adopt interface-based design pattern	Accepted
0005	Implement graceful shutdown with readiness endpoints	Accepted
0006	Use Viper for configuration management	Accepted
0007	Integrate OpenTelemetry for distributed tracing	Accepted
0008	Adopt BDD with Godog for behavioral testing	Accepted
0009	Combine BDD and Swagger-based testing	Implemented
0010	API v2 Feature Flag Implementation	Accepted
0012	Git Hooks: Staged-Only Formatting	Accepted
0013	OpenAPI/Swagger Toolchain Selection	Implemented
0015	CLI Subcommands and Flag Management with Cobra	Implemented
0016	CI/CD Pipeline Design for Multi-Platform Compatibility	Accepted
0017	Trunk-Based Development Workflow for CI/CD Safety	Approved
0018	User Management and Authentication System	Implemented
0019	PostgreSQL Database Integration	Implemented
0020	Docker Build Strategy: Traditional vs Buildx	Accepted
0021	JWT Secret Retention Policy	Implemented
0022	Rate Limiting and Cache Strategy	Implemented (Phase 1)
0023	Config Hot Reloading Strategy	Implemented
0024	BDD Test Organization and Isolation Strategy	Implemented
0025	BDD Scenario Isolation Strategies	Implemented
0026	Composite Info Endpoint vs Separate Calls	Implemented
0027	Ollama Tier 1 onboarding via meta-trainer-bootstrap	Proposed

Note

: numbers 0011 and 0014 are not currently in use. Reserved for future ADRs or representing previously deleted entries.

What is an ADR?

An ADR is a document capturing one significant architectural decision: the context that motivated it, the decision itself, and its consequences. ADRs are append-only — once published, an ADR is not edited (except for typo / status updates). New decisions that supersede previous ones are recorded as new ADRs that explicitly link back.

Canonical Format

All ADRs follow the canonical format below (homogenized 2026-05-03):

# NN. Short title summarising the decision

**Status:** <Proposed | Accepted | Implemented | Partially Implemented | Approved | Rejected | Deferred | Deprecated | Superseded by ADR-NNNN>
**Date:** YYYY-MM-DD
**Authors:** Name(s)

[Optional fields, all in `**Field:** value` format:]
**Decision Drivers:** ...
**Implementation Status:** ...
**Implementation Date:** ...
**Last Updated:** ...

## Context and Problem Statement

[Describe the context and problem statement.]

## Decision Drivers

* Driver 1
* Driver 2

## Considered Options

* Option 1
* Option 2

## Decision Outcome

Chosen option: "Option 1" because [justification].

## Pros and Cons of the Options

### Option 1

* Good, because [argument].
* Bad, because [argument].

### Option 2

* Good, because [argument].
* Bad, because [argument].

## Links

* Related ADR: [ADR-NNNN](NNNN-slug.md)
* Issue: [#NN](https://gitea.arcodange.lab/arcodange/dance-lessons-coach/issues/NN)

Status Legend

Status	Meaning
Proposed	Decision is being discussed; no implementation yet.
Accepted	Decision has been made; implementation may be pending or in progress.
Approved	Same as Accepted; alternative term used in some legacy ADRs.
Implemented	Decision is fully implemented and in production.
Partially Implemented	Decision is partly implemented; remainder is deferred or pending.
Rejected	Decision considered and explicitly rejected. The ADR documents why.
Deferred	Decision postponed; revisit later.
Deprecated	Decision is no longer relevant; system has moved on.
Superseded by ADR-NNNN	Decision has been replaced by another ADR. Always include the link.

How to Add a New ADR

Pick the next available number (currently next would be 0026).
Copy an existing ADR (e.g., 0001-go-1.26.1-standard.md) as a starting template.
Edit the title, status, date, authors, and content.
Update this README.md index with the new ADR.
Commit using gitmoji convention (e.g., 📝 docs(adr): add ADR-0026 about ...).
Open a PR for review.

5.4 KiB Raw Blame History