🪩 feat: Reload Config Across Replicas

[lia-by-librechat]

Summary

Operators can now validate and apply a changed librechat.yaml through POST /api/admin/config/reload without restarting the API process. The endpoint uses the same JWT and admin-capability middleware as the existing admin config routes, supports both local files and remote HTTP(S) CONFIG_PATH sources, and rejects invalid candidates before changing the cached base config.

With Redis enabled, a successful reload increments a deployment-scoped config generation. Every replica compares that durable generation at most once per second on its existing config-read path, drops its process-local base and override entries when the generation changes, and retries transient source failures until it has installed and acknowledged the generation. Without Redis, the validated config applies only to the handling replica and the response reports scope: local.

The response compares the old and new YAML by top-level section. It marks unchanged sections, sections applied live, and startup-only changes that still require a restart. Mixed sections also list the nested paths whose startup effects require a restart.

Depends on #16383.

How it works

POST /api/admin/config/reload
  read + validate local file or remote URL
  compare sections
  install validated base + clear local overrides
  INCR config:generation

other replica getAppConfig
  throttled generation GET
  newer generation -> clear base + overrides
  reload source -> acknowledge generation
  transient failure -> serve last good and retry

Type of change

• Feature
• Tests / tooling / CI

Testing

Tested environments/configuration:

• Redis-backed two-replica generation simulation
• Redis-disabled local-only reload
• Local and remote CONFIG_PATH loading inherited from 🏺 fix: Preserve Last Good Config on Reload #16383
• Admin and non-admin route access

Automated tests:

• cd packages/api && ../../node_modules/.bin/jest src/app/reload.spec.ts src/app/service.spec.ts src/admin/config.handler.spec.ts --coverage=false --runInBand
• cd api && ../node_modules/.bin/jest server/routes/admin/config.test.js server/services/Config/__tests__/invalidateConfigCaches.spec.js server/services/Config/loadCustomConfig.spec.js --coverage=false --runInBand
• cd packages/api && ../../node_modules/.bin/tsc --noEmit
• cd packages/api && ./node_modules/.bin/tsdown

Screenshots / recordings

No user-facing change.

Risk / compatibility

The generation key contains no config data or secrets. APP_CONFIG remains process-local; Redis only coordinates a monotonically increasing generation. Existing admin override merge precedence is unchanged. Startup-only subsystems are not reinitialized by this endpoint and are identified in the response instead.

Checklist

• I reviewed my own changes
• Relevant tests have been added or updated
• Existing relevant tests pass
• The change does not introduce new warnings or errors
• User-facing or complex behavior is documented where necessary
• Required dependency changes have been merged/published
• Required documentation PR: N/A

[lia-by-librechat]

Ready for review at 0455e36d7a7d5abe08c8b87cded1545e786cc6a3. This head validates local or remote config candidates before install, reports live versus restart-required sections, and propagates a durable Redis generation across process-local config caches with retry-safe acknowledgement.

[lia-by-librechat]

Ready for review at 1c41a57a12df4db331c1751dc33e4fec9c320a3f. This head also keeps Redis-disabled config reads on the original zero-I/O hot path.

[lia-by-librechat]

Review fixes are ready at a33d13d4ada6a9144d9c92a7d4965becd79f51c3: failed generation publication is retryable even after local install, stale read/bump races cannot regress the generation, replica reload logs are compact, and remote reload fetches are bounded without changing startup fetch behavior.