API Versioning

package v2

import (
	"encoding/json"
	"net/http"

	"github.com/hoa-platform/backend/services/maintenance-service/internal/domain"
)

// chargeResponse replaces v1's flat amount_cents integer with a typed
// money object — the exact kind of change that cannot ship as an
// in-place edit to v1's handler without breaking every existing client
// parsing amount_cents today.
type chargeResponse struct {
	ID     string      `json:"id"`
	FlatID string      `json:"flat_id"`
	Amount moneyPayload `json:"amount"`
	Status string      `json:"status"`
}

type moneyPayload struct {
	Cents    int64  `json:"cents"`
	Currency string `json:"currency"`
}

func newChargeResponse(charge domain.Charge) chargeResponse {
	return chargeResponse{
		ID:     charge.ID.String(),
		FlatID: charge.FlatID.String(),
		Amount: moneyPayload{Cents: charge.AmountCents, Currency: "USD"},
		Status: string(charge.Status),
	}
}

func (h *ChargeHandler) Get(w http.ResponseWriter, r *http.Request) {
	charge, err := h.service.FindByID(r.Context(), tenantFrom(r), chargeIDFrom(r))
	if err != nil {
		writeError(w, err)
		return
	}
	w.Header().Set("Content-Type", "application/json")
	_ = json.NewEncoder(w).Encode(newChargeResponse(charge))
}

package proxy

import "net/http"

// Route maps a URI version prefix to the upstream service and the
// deprecation metadata that applies to every request under that
// prefix. A route with no deprecatedAt is fully supported; one with
// deprecatedAt but no sunsetAt is deprecated but not yet scheduled for
// removal; one with both is on a clock.
type Route struct {
	Prefix       string
	Upstream     string
	DeprecatedAt string // RFC 1123, empty if not deprecated
	SunsetAt     string // RFC 1123, empty if no removal date is set
}

var chargeRoutes = []Route{
	{Prefix: "/v1/charges", Upstream: "http://maintenance.hoa.svc.cluster.local:8080/v1/charges",
		DeprecatedAt: "Mon, 01 Apr 2024 00:00:00 GMT", SunsetAt: "Mon, 01 Jul 2024 00:00:00 GMT"},
	{Prefix: "/v2/charges", Upstream: "http://maintenance.hoa.svc.cluster.local:8080/v2/charges"},
}

func withDeprecationHeaders(route Route, next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		if route.DeprecatedAt != "" {
			w.Header().Set("Deprecation", route.DeprecatedAt)
		}
		if route.SunsetAt != "" {
			w.Header().Set("Sunset", route.SunsetAt)
			w.Header().Set("Link", `</v2/charges>; rel="successor-version"`)
		}
		next.ServeHTTP(w, r)
	})
}

ALTER TABLE maintenance.charges ADD COLUMN amount_currency text;
ALTER TABLE maintenance.charges ADD COLUMN amount_minor_units bigint;

UPDATE maintenance.charges
SET amount_currency = 'USD', amount_minor_units = amount_cents
WHERE amount_currency IS NULL;

-- A trigger, not application code, keeps both representations in sync
-- for every future write, including ones from v1 handlers that never
-- learn the new column exists.
CREATE OR REPLACE FUNCTION maintenance.sync_charge_amount() RETURNS trigger AS $$
BEGIN
    NEW.amount_currency := coalesce(NEW.amount_currency, 'USD');
    NEW.amount_minor_units := NEW.amount_cents;
    RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER charges_sync_amount
    BEFORE INSERT OR UPDATE ON maintenance.charges
    FOR EACH ROW EXECUTE FUNCTION maintenance.sync_charge_amount();

DROP TRIGGER IF EXISTS charges_sync_amount ON maintenance.charges;
DROP FUNCTION IF EXISTS maintenance.sync_charge_amount();
ALTER TABLE maintenance.charges DROP COLUMN IF EXISTS amount_currency;
ALTER TABLE maintenance.charges DROP COLUMN IF EXISTS amount_minor_units;