Imported from stolostron/console (backend/AGENTS.md). Install upstream with npx skills add stolostron/console --skill backend. Copyright stays with the author.

Backend

Node.js ESM proxy server. Sits between the browser and the hub cluster API server, handling authentication, RBAC enforcement, resource watching, and API proxying.

Key Technologies

• Runtime: Node.js with native ESM ("type": "module")
• Router: find-my-way for HTTP/2 route matching
• Proxy: node:https + pipeline for main API proxy; http2-proxy for managed cluster proxy
• Logging: Pino with structured JSON output (use pino-zen for dev formatting)
• Metrics: Prometheus metrics proxied via metricsProxy route
• HTTP Client: got for outbound requests
• WebSocket: upgrade handler routes to search (bidirectional relay via ws with token injection) and managed cluster proxy (via http2-proxy)

Source Layout

Commands

Run from the backend/ directory, or use the npm run *:backend variants from the repo root.

Architecture

Browser → Backend (HTTP/2 proxy) → Hub Cluster API Server
                ↓
          Watches resources via service account
          Enforces RBAC via user token + SubjectAccessReview
          Streams events to frontend via SSE

Route Handlers

• Route handler signature: (req: Http2ServerRequest, res: Http2ServerResponse): Promise<void>
• Router uses maxParamLength: 500 for long Kubernetes resource names
• URL rewriting: /multicloud prefix is stripped before routing in app.ts for HTTP and server.ts for WebSocket upgrades (e.g., /multicloud/proxy/search → /proxy/search)
• Use pipeline() from node:stream for proxy and streaming operations to ensure proper backpressure and cleanup
• Use getEncodeStream() for SSE compression

Security

• Never log sensitive data (tokens, passwords, credentials)
• Validate and sanitize all inputs
• Guard against injection vulnerabilities (command injection, path traversal)
• Ensure proper authentication and authorization checks on all routes
• Use SelfSubjectAccessReview for permission checks
• Log at appropriate levels with Pino (error, warn, info, debug) — include relevant context but never sensitive data

Configuration

Environment Variables (.env)

Generated by npm run setup from the repo root. These are cluster-specific and should not be set manually unless overriding for special cases:

Optional development/debug variables (not in .env by default):

Settings (config/ directory)

Files in config/ are loaded at startup and watched for dynamic updates. Changes are pushed to the frontend via SSE SETTINGS events. Only specific keys are promoted to process.env:

• LOG_* keys (LOG_LEVEL, LOG_ACCESS, LOG_EVENTS, LOG_MEMORY, LOG_WATCH) — control logging behavior
• APP_SEARCH_* keys (APP_SEARCH_INTERVAL, APP_SEARCH_LIMIT) — application search tuning
• globalSearchFeatureFlag — enables federated search endpoint
• UPGRADE_RISKS_PREDICTION_URL — override for upgrade risk prediction service

Other config files (e.g., singleNodeOpenshift, ansibleIntegration, awsPrivateWizardStep) are sent to the frontend as settings but not promoted to backend env vars. The frontend uses these to toggle UI features like single-node cluster creation and Ansible automation options.

Feature Flags

Feature flags come from two mechanisms:

• MultiClusterHub components — the /multiclusterhub/components route exposes MCH component status, used by the frontend to determine which features are installed
• Config settings — files in config/ act as feature toggles (e.g., singleNodeOpenshift, ansibleIntegration), pushed to the frontend via SSE and checked with settings.<flag> === 'enabled'

Testing

• Test files are in test/
• Tests should meaningfully cover behavior, not just achieve coverage metrics
• Properly mock and isolate dependencies
• Async tests must handle promises correctly

Environment

The backend requires a .env file for cluster connection. Generate it with npm run setup from the repo root. Key variables include the cluster API URL, OAuth credentials, and service account token.