feat(admin): add Prometheus-backed /admin/metrics SSE endpoint

[Ferryx349]

Description

Add GET /admin/metrics as an authenticated SSE stream for the admin console.

Note: This PR is stacked on Phase 1 until #641 merges to main.

Related Issue

Fixes - #655

Motivation and Context

How Has This Been Tested?

Screenshots (if appropriate):

Types of changes

• Non-functional change (docs, style, minor refactor)
• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my code changes.
• I added a changeset, or this is docs-only and I added an empty changeset.
• All new and existing tests passed.

[changeset-bot]

🦋 Changeset detected

Latest commit: 18d6f07

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
nostream	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coveralls]

coverage: 67.674% (-0.07%) from 67.747% — Ferryx349:ADMIN-CONSOLE-2-SSE into cameri:main

[Copilot]

Pull request overview

Adds a disabled-by-default admin API surface including an authenticated SSE endpoint (GET /admin/metrics) that periodically streams a cluster-wide metrics snapshot sourced from Prometheus, alongside supporting admin auth/session utilities and OTEL metric instrumentation.

Changes:

• Introduces /admin/login, /admin/session, /admin/health, and /admin/metrics (SSE) routes guarded by enablement, auth, and admin-specific rate limiting.
• Adds Prometheus client + metrics snapshot aggregation (PromQL) plus dependency health (DB/Redis) folded into each snapshot.
• Instruments event acceptance/rejection and WebSocket connection counts with OpenTelemetry metric instruments.

Reviewed changes

Copilot reviewed 50 out of 50 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
test/unit/utils/prometheus-client.spec.ts	Unit coverage for Prometheus URL handling, scalar parsing, and instant-query behavior.
test/unit/utils/http.spec.ts	Adds tests for new isSecureRequest() behavior behind trusted proxies.
test/unit/utils/admin-session.spec.ts	Unit coverage for admin session token/cookie helpers and TTL fallback behavior.
test/unit/utils/admin-rate-limit.spec.ts	Unit coverage for admin/login scoped rate limiting and key construction.
test/unit/utils/admin-metrics.spec.ts	Unit coverage for metrics snapshot composition and interval parsing.
test/unit/routes/admin.spec.ts	Router-level tests for admin enablement, auth, login, health, and metrics wiring.
src/utils/prometheus-client.ts	Prometheus base URL resolution, instant query execution, and scalar parsing.
src/utils/http.ts	Adds isSecureRequest() helper for Secure-cookie decisions behind trusted proxies.
src/utils/admin-session.ts	Signed admin session tokens + cookie header construction.
src/utils/admin-rate-limit.ts	Admin/login scoped rate limit decision logic using existing limiter.
src/utils/admin-password.ts	Password hashing + verification utilities (scrypt).
src/utils/admin-metrics.ts	PromQL snapshot aggregation + SSE interval configuration.
src/utils/admin-health.ts	DB/Redis dependency health snapshot for admin endpoints.
src/telemetry/event-metrics.ts	OTEL counters/gauges updates for event results and WS connection tracking.
src/schemas/admin-login-schema.ts	Zod schema for admin login request body.
src/routes/index.ts	Mounts the admin router at /admin.
src/routes/admin/index.ts	Defines admin routes and middleware ordering (rate limit, enablement, auth).
src/handlers/request-handlers/with-admin-controller-request-handler.ts	Admin controller wrapper that normalizes errors to JSON 500.
src/handlers/request-handlers/admin-rate-limit-middleware.ts	Express middleware applying admin-specific rate limiting.
src/handlers/request-handlers/admin-enabled-middleware.ts	Feature gate middleware returning 404 when admin is disabled.
src/handlers/request-handlers/admin-auth-middleware.ts	Auth middleware using the admin auth provider and returning 401/500 on failure.
src/handlers/event-strategies/vanish-event-strategy.ts	Switches to telemetry-aware command result emission.
src/handlers/event-strategies/timestamp-event-strategy.ts	Switches to telemetry-aware command result emission.
src/handlers/event-strategies/replaceable-event-strategy.ts	Switches to telemetry-aware command result emission.
src/handlers/event-strategies/parameterized-replaceable-event-strategy.ts	Switches to telemetry-aware command result emission.
src/handlers/event-strategies/group-event-strategy.ts	Switches to telemetry-aware command result emission.
src/handlers/event-strategies/gift-wrap-event-strategy.ts	Switches to telemetry-aware command result emission.
src/handlers/event-strategies/ephemeral-event-strategy.ts	Switches to telemetry-aware command result emission.
src/handlers/event-strategies/delete-event-strategy.ts	Switches to telemetry-aware command result emission.
src/handlers/event-strategies/default-event-strategy.ts	Switches to telemetry-aware command result emission.
src/handlers/event-message-handler.ts	Switches to telemetry-aware command result emission; small control-flow formatting tweak.
src/factories/controllers/post-admin-login-controller-factory.ts	Wires login controller with auth provider.
src/factories/controllers/get-admin-session-controller-factory.ts	Wires session controller with auth provider.
src/factories/controllers/get-admin-metrics-controller-factory.ts	Wires metrics SSE controller.
src/factories/controllers/get-admin-health-controller-factory.ts	Wires health controller.
src/factories/admin-auth-provider-factory.ts	Factory for the password-based admin auth provider.
src/controllers/admin/post-login-controller.ts	Delegates login handling to the auth provider.
src/controllers/admin/get-session-controller.ts	Returns authenticated session info (expiresAt).
src/controllers/admin/get-metrics-controller.ts	SSE controller that streams periodic admin metrics snapshots.
src/controllers/admin/get-health-controller.ts	Returns dependency health snapshot.
src/admin/password-admin-auth-provider.ts	Implements password login + session cookie issuance + request auth.
src/adapters/web-socket-adapter.ts	Adds WS connection opened/closed metric tracking.
src/@types/settings.ts	Extends settings types for admin config + admin limits.
src/@types/admin.ts	Defines the IAdminAuthProvider interface.
resources/default-settings.yaml	Adds default admin limits and default disabled admin settings.
docker-compose.yml	Adds Prometheus URL + SSE interval env wiring for local compose.
.env.example	Documents new Prometheus and SSE interval environment variables.
.changeset/admin-metrics-sse-endpoint.md	Changeset for the admin metrics SSE endpoint.
.changeset/admin-metrics-handler-instrumentation.md	Changeset for OTEL instrumentation additions.
.changeset/admin-console-phase-1.md	Changeset for the admin API foundation (enablement/auth/session/health).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Ferryx349]

"Missing rate limiting" on admin routes, likely seems a false positive.

Rate limiting is already in place:-

Router-level :- rateLimiterMiddleware (connection limits)
Per-route:- adminRateLimitMiddleware / adminLoginRateLimitMiddleware before auth
Backed by Redis via isAdminRateLimited() (same approach as invoice/admission controllers).

CodeQL doesn’t recognize our custom middleware, it does only for packages like express-rate-limit.

@cameri should we dismiss this as false positive, or would u prefer something else.
Happy to go ahead with whatever you prefer.

[Ferryx349]

This PR is now based on top of #654.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 4 comments.