spec: Feature-flag gates for analytics and experiment endpoints (#37659)

[freddyDOTCMS]

📐 Spec Viewer

👉 Open the interactive spec — Feature-Flag Gates for Analytics and Experiment Endpoints

Navigable spec with contract diagrams, traceability, and commit-level change history.

---

⚠️ Breaking Change

FEATURE_FLAG_EXPERIMENTS default flips true → false. Any deployment that does not explicitly set this flag will have experiments blocked after this ships. Every active customer must have the flag explicitly set to true before release.

FEATURE_FLAG_CONTENT_ANALYTICS is not changed — it remains in place for AnalyticsTrackWebInterceptor (legacy page-view tracking). Analytics availability in the new gate logic is driven by Analytics App configuration, not by this flag.

---

Summary

• Replaces two-flag gate model with FEATURE_FLAG_EXPERIMENTS (experiment tier) + per-site Analytics App configuration (analytics availability)
• Limited experiment mode: one free experiment, max 10 days, when flag=false and App is configured
• App-not-configured gates activation and analytics reads with 503; health endpoints always return a structured response
• Event ingest gated by App credential presence only — no event filtering, no payload mutation
• GET /api/v1/analytics/health changed from raw CAEM proxy to dotCMS-evaluated { "health": "OK" | "NOT_CONFIGURED" | "CONFIGURATION_ERROR" }
• FEATURE_FLAG_EXPERIMENTS live-toggle removed system-wide; restart required for flag changes

Closes

Closes #37659

Test plan

• Spec reviewed and approved by a second developer before /speckit-plan runs

🤖 Generated with Claude Code

[claude]

Claude finished @freddyDOTCMS's task in 2m 37s —— View job

---

Code Review — Feature-flag gates for analytics/experiment endpoints

I reviewed the gate logic, error paths, and the new ExperimentsResource / ExperimentLimitedModeGate / ContentAnalyticsUtil / EventAnalyticsProxyResource code against the spec contracts. Findings below.

New Issues

• 🟡 Medium: dotCMS/src/main/java/com/dotcms/rest/api/v1/experiments/ExperimentLimitedModeGate.java:83 — The duration cap uses ChronoUnit.DAYS.between(Instant.now(), endDate) > MAX_DAYS. DAYS.between truncates toward zero, so a user-supplied endDate up to just under 11 days away (e.g. 10 days 23h) returns 10, which is not > 10 and passes the gate. The limited-mode cap is "at most 10 days" (experiment-gate.md:16), but this admits experiments measurably beyond it. The API's own startLimitedScheduling() sets exactly LIMITED_MODE_MAX_DAYS, so the gate is the looser of the two paths. Prefer an instant comparison: endDate.isAfter(Instant.now().plus(MAX_DAYS, ChronoUnit.DAYS)). Fix this →

• 🟡 Medium: dotCMS/src/main/java/com/dotcms/rest/api/v1/experiments/ExperimentLimitedModeGate.java:97 — defaultEndDate(Instant) is dead code — nothing calls it (verified across the repo). The auto-end-date behavior it documents is actually implemented inside ExperimentsAPIImpl.startLimitedScheduling() (ExperimentsAPIImpl.java:1672). Worse, the javadoc on ExperimentsResource.start() (lines 305-307) claims the resource auto-sets the end date "When no endDate is set" — but start() never does this; it relies entirely on the API. Either remove the unused method or wire it in, and correct the misleading javadoc so a future reader doesn't assume the resource owns that logic. Fix this →

• 🟡 Medium: dotCMS/src/main/java/com/dotcms/rest/api/v1/experiments/ExperimentLimitedModeGate.java:81-85 — The cap is measured from Instant.now(), but when scheduling has an explicit startDate (allowed as long as it is not after now) and an endDate, the true experiment duration is start → end, not now → end. The gate also only checks duration when endDate is present: a limited-mode experiment submitted with a startDate (now/past) and no endDate passes the gate and then falls into the SCHEDULED else-branch of ExperimentsAPIImpl.start() (:603-610), which keeps the user's scheduling verbatim and never applies startLimitedScheduling() — so no 10-day cap is enforced on that path. The common "start now, no scheduling" case is correctly capped; this is the partial-scheduling edge. Assumption: partial scheduling (startDate without endDate) is reachable through the form. What to verify: whether a limited-mode start with startDate-only scheduling should also be capped at 10 days.

Existing

• 🟡 Medium: dotCMS/src/main/java/com/dotcms/rest/api/v1/experiments/ExperimentsResource.java:650 / ExperimentsHealthView.java — API contract change already flagged by the rollback-safety bot: GET /v1/experiments/health changed from Map<String,Health> to ExperimentsHealthView, and start/archive/end/cancel now return raw Response with new gated error shapes. This is intentional per the spec (experiment-gate.md:70) and the FEATURE_FLAG_EXPERIMENTS default flip is called out as a breaking change in the PR body — noting here only so it stays visible: a frontend reading tier/freeExperimentUsed will see those fields vanish on rollback to N-1 (Jackson silently omits them). Not a code defect; a rollout-sequencing concern.

Notes (non-blocking)

• ExperimentsAPIImpl.isFreeSlotUsed() counts {RUNNING, SCHEDULED, ENDED} but excludes ARCHIVED, so archiving an ended experiment frees the "one free experiment" slot again. Confirm this matches the intended lifetime semantics in data-model.md (it may be the intended escape hatch, but it's worth an explicit test).
• Gate ordering in start() (App-config → limited-mode) and in getResult() (503 when App absent) matches the decision matrix in experiment-gate.md. EventAnalyticsProxyResource correctly resolves the site and permission-gates reads via resolveSiteForUser before the App-config 503, and keeps /health + /content/siteauth/generate on dedicated methods so they bypass the catch-all gate. No issues there.

No critical or high-severity defects found. The two Medium items on the gate are worth tightening before merge but are non-blocking.
· branch issue-37659-analytics-experiment-flag-gates

[claude]

Pull Request Unsafe to Rollback!!!

• Category: M-3 — REST / GraphQL / Headless API Contract Change
• Risk Level: 🟡 MEDIUM
• Why it's unsafe: GET /api/v1/experiments/health changed its response shape from ResponseEntityView<Map<String, Health>> (a flat {"health": "OK"} map) to ResponseEntityView<ExperimentsHealthView>, a POJO that adds tier, freeExperimentUsed, and warning fields alongside health. The OpenAPI schema confirms this: the endpoint's schema ref moved from ResponseEntityViewMapStringHealth to ResponseEntityViewExperimentsHealthView. The javadoc on ExperimentsHealthView explicitly states the new tier/freeExperimentUsed fields "drive portlet button state in the frontend" — i.e., a client (admin UI) is expected to read these new fields. If a frontend build cached/deployed against N's contract calls this endpoint after a rollback to N-1, the tier and freeExperimentUsed fields will be absent from N-1's response, and any button-state logic depending on them will break or default incorrectly (silently, since Jackson just omits missing fields — no error is thrown).
  Separately, ExperimentsResource.start/archive/end/cancel changed their return type from strongly-typed ResponseEntityExperimentView/ResponseEntitySingleExperimentView to a generic javax.ws.rs.core.Response, and now return new gated error shapes (403 FEATURE_DISABLED, 400 DURATION_EXCEEDED, 503 ANALYTICS_NOT_CONFIGURED) that did not exist in N-1. The OpenAPI diff shows the success schema for these four endpoints was dropped entirely ($ref: ResponseEntitySingleExperimentView → {}), meaning N's documented contract for these operations is no longer the same as N-1's.
• Code that makes it unsafe:
  • dotCMS/src/main/java/com/dotcms/rest/api/v1/experiments/ExperimentsResource.java — healthcheck() now returns ResponseEntityView<ExperimentsHealthView> instead of ResponseEntityView<Map<String, Health>>; start(), archive(), end(), cancel() now return Response with new featureDisabledResponse(), durationExceededResponse(), analyticsNotConfiguredResponse() branches instead of always returning a success entity view.
  • dotCMS/src/main/java/com/dotcms/rest/api/v1/experiments/ExperimentsHealthView.java (new file) — new response POJO with tier, freeExperimentUsed, warning fields not present in N-1's Map<String, Health> shape.
  • dotCMS/src/main/webapp/WEB-INF/openapi/openapi.yaml — schema refs for /experiments/{id}/_start, /_archive, /_end, and /scheduled/{id}/_cancel changed from a defined success schema to {}; /experiments/health schema ref changed from ResponseEntityViewMapStringHealth to ResponseEntityViewExperimentsHealthView.
• Alternative (if possible): Keep health as the sole top-level key for backward compatibility and add the new tier/freeExperimentUsed/warning data as a nested, additively-introduced object (or ship the new fields one release ahead of any frontend code that reads them, per the "warm the contract" guidance in H-8/M-3) so N-1 and N-era frontends can both parse the response. For start/archive/end/cancel, keep returning the original typed ResponseEntityExperimentView/ResponseEntitySingleExperimentView on the success path and only use the new error entity shapes on the new gated-rejection paths, so the documented success contract is unchanged.

[claude]

Pull Request Unsafe to Rollback!!!

• Category: M-3 — REST / GraphQL / Headless API Contract Change
• Risk Level: 🟡 MEDIUM
• Why it's unsafe: GET /v1/experiments/health changes its response entity type from Map<String, Health> (e.g. {"health":"OK"}) to a new structured ExperimentsHealthView object carrying health, tier, freeExperimentUsed, and warning. The new DTO's own Javadoc states it "Carries the existing health state plus the new tier fields that drive portlet button state in the frontend" — i.e. this is an API contract change meant to be consumed by a UI. If a frontend build that reads tier/freeExperimentUsed/warning is active during N's rollout and the backend is then rolled back to N-1, those fields vanish from the response (N-1 only returns the old Map<String, Health> shape), so any UI logic gating on tier or freeExperimentUsed silently receives undefined.
• Code that makes it unsafe:
  • dotCMS/src/main/java/com/dotcms/rest/api/v1/experiments/ExperimentsResource.java — healthcheck() now returns ResponseEntityView<ExperimentsHealthView> instead of ResponseEntityView<Map<String, Health>>.
  • dotCMS/src/main/java/com/dotcms/rest/api/v1/experiments/ExperimentsHealthView.java — new response DTO (health, tier, freeExperimentUsed, warning), explicitly intended to drive frontend button state.
  • dotCMS/src/main/webapp/WEB-INF/openapi/openapi.yaml — /v1/experiments/health response schema changed from ResponseEntityViewMapStringHealth to ResponseEntityViewExperimentsHealthView.
• Alternative (if possible): Per M-3 guidance, give the shape change a backward-compatible transition — e.g. keep serializing a health top-level value compatible with the old Map<String, Health> consumers while the new tier/freeExperimentUsed/warning fields are additive-only, and avoid shipping frontend code that requires the new fields until N-1 is fully outside the rollback window.

Note: no database migrations, Elasticsearch mapping changes, or structural storage changes were found in this PR (FEATURE_FLAG_EXPERIMENTS default flip from true→false and the new limited-mode gating are pure in-memory/config and REST-layer behavior changes with no persisted schema impact).