LibreChat/api/server/services/Config/app.js
Danny Avila 9f617fc4ad
🧬 feat: Re-Derive Azure Groups, Vertex AI, Custom Parameters and Spec Defaults for Config Profiles (#17399)
* 🧬 feat: Re-Derive Azure Groups, Vertex AI, Custom Parameters and Spec Defaults for Config Profiles

AppService derives part of the served config from librechat.yaml at startup, and config
profiles merged into that output without deriving it again. Azure `groups` now merge by `group`
like `endpoints.custom` by `name`: a profile's partial group merges over the group of that
name, groups it does not name stay, indexed writes are refused, change batches take entry ops
on them, and groups that do not resolve over librechat.yaml and Base (or whose written `${VAR}`
is not set) answer `invalid_azure_groups`. Each merged group keeps the key below it unless the
profile supplies one, so the rebinding guard drops a key a partial item moves and a key a lower
layer dropped stays dropped; Azure re-entry compares groups merged the same way.

With `CONFIG_REDERIVE_ENDPOINTS=true` (opt-in for this release), a profile's Azure `groups`
resolve into what the Azure clients read (unconditional before, now behind the switch so stored
group overrides do not go live on upgrade), a profile's `endpoints.anthropic.vertex` derives
`vertexConfig` and the Anthropic models it serves where librechat.yaml configures Vertex AI, and
the Azure Assistants endpoint follows a profile's `assistants`. Startup logs the documents that
hold such overrides, the groups that would not resolve over librechat.yaml and Base, and the
Vertex AI overrides that never apply. Always on: Vertex AI's key file and region are base-only,
a profile may turn Vertex AI on only where librechat.yaml configures it, its settings may
reference only librechat.yaml's own Vertex AI variables (reads return them resolved), a
profile's `vertexConfig` is never applied and writes skip it (`derived_path`,
`rules.derivedPaths`), a model's own `deploymentName` resolves its `${VAR}` like the default one,
the region, project ID and the deployment name each model's requests send (the model name where
the client sends it as written) must stay in their URL host label or path segment, a `${VAR}`
there is a whole `${NAME}` reference only, the Anthropic client refuses any other deployment name
before building a request, and an invalid setup answers `invalid_vertex_config`. The rebinding
guard no longer binds the derived Vertex AI region, which is librechat.yaml's.

Custom endpoint `customParams` are expanded by `expandCustomEndpoint` into the served copy, so
`appConfig.config` stays librechat.yaml as written, and each endpoint a profile writes is
expanded again from its merged form (a changed `defaultParamsEndpoint`, OpenRouter defaults
for a profile's own endpoint); invalid definitions answer `invalid_param_definitions`. After
tenant scoping, `getAppConfig` derives `modelSelect`, `parameters` and `presets` again for the
specs a principal is served where nothing sets them, the agents `memory` capability follows
the merged memory config, and a model spec naming an unconfigured endpoint answers
`unknown_spec_endpoint`. Meta flags: `azureGroupMergeKey`, `customParamsExpansion`,
`specInterfaceRederive` and `endpointRederive`.

* 🪜 fix: Judge Re-Derived Config on What Every Profile Layer Leaves

Two re-derivations decided whether a profile had set a field from whether any layer ever set
it, so a lower profile's value tombstoned by a higher one still counted as set.

- Vertex AI (CONFIG_REDERIVE_ENDPOINTS=true): the marker that keeps a profile's
  `endpoints.anthropic.models` over Vertex AI's is cleared by a later tombstone of those
  models (or of `endpoints.anthropic` or `endpoints`), and such a tombstone derives Vertex AI
  again, so the Anthropic endpoint serves Vertex AI's models instead of none. A tombstone of
  librechat.yaml's own models does the same.
- Spec-dependent controls: `modelSelect`, `parameters` and `presets` are derived again where
  their served value differs from the base config's, not only where the librechat.yaml-shaped
  value does, so a control one profile sets and a higher one tombstones, or a tombstone of one
  librechat.yaml leaves unset, follows the specs served instead of being dropped.

The memory capability, Azure Assistants, Azure groups and custom parameters already derive
from the merged result; tests now cover each set in one layer and tombstoned in a higher one,
and the reverse.

* 🧮 fix: Derive Each Config Part From What the Layers Leave

A tombstone of an object above a derived part's inputs, alone or followed by a layer that
recreates part of that object, left the part without what startup derives it to:

- An Azure endpoint recreated after a tombstone of `endpoints.azureOpenAI` or `endpoints` had
  no groupMap, modelGroupMap or model lists, so its model lists fell back to the environment's
  default Azure models, which requests could not map to a group. It now serves no group, with or
  without CONFIG_REDERIVE_ENDPOINTS (completeAzureResolution).
- A tombstone of the whole `interface` left modelSelect, parameters and presets out, which the
  client reads as off. They are derived from the specs served into a new interface.
- A tombstone of `endpoints.agents` or `endpoints` left no agents endpoint, while a tombstone of
  its capabilities served the defaults. The agents endpoint startup derives is served there.
- A tombstone of a Vertex AI setting that leaves the setup unable to load kept the vertexConfig
  derived below it. Vertex AI is off there, with a warning.

A table in service.spec.ts runs every derived part against every way a layer changes its inputs
(set, unset, a tombstone of the path and of each object above it, a layer recreating after such
a tombstone, Base on either side, tenant scoping, the switch off) through getAppConfig, and
compares each cell with what startup derives from the librechat.yaml the layers leave.

* 🧭 fix: Serve Only Model Specs Whose Endpoint the Layers Leave

A tombstone of `endpoints.custom` or `endpoints` in a higher profile (or the Base profile)
left the model specs of the custom endpoints it removes served, librechat.yaml's or a lower
profile's: the spec list pointed at endpoints /api/endpoints no longer offers, with the model
selector, parameters and presets still off for them. The write check only ran when the write
held `modelSpecs.list`, and the merge served stored specs as they were.

After the last layer, the merge now serves only the specs whose endpoint is a built-in endpoint
or a custom endpoint the YAML-shaped config the layers leave defines, the rule startup skips
librechat.yaml's specs by (deriveServedSpecs). A removed endpoint hides its specs until a layer
defines it again; where no spec is left, none is served (as with a tenant-hidden endpoint) and
the spec-dependent controls come back on. Tombstones of a built-in endpoint's settings keep its
specs, as startup does, and `addedEndpoints` stays as merged. A stored spec for an endpoint that
is not configured is left out on its own instead of being served; writes of one still answer
400 unknown_spec_endpoint.

The derived-part table in service.spec.ts gains the model specs served (with addedEndpoints and
the controls they decide) against tombstones of `endpoints.custom`, `endpoints`, and each of
`endpoints.openAI`, `azureOpenAI` and `anthropic`: by a profile, by Base under a profile, a lower
profile under a higher one, recreated above or by the same layer, with no spec left, and with
the switch off.

* 🧩 fix: Reconcile Re-Derived Config With Dev's Keyed Tombstones, Write Report and Read APIs

- Keyed tombstones of Azure groups (endpoints.azureOpenAI.groups["g"], now merged by key)
  resolve the groups left again where the merge resolves them, and stay inert without
  CONFIG_REDERIVE_ENDPOINTS.
- Keyed tombstones count as touching endpoints.custom, so served specs and custom parameters
  are derived again after one.
- The served-spec derivation keeps modelSpecs while added endpoints remain, as the hidden
  endpoint scoping does; hidden endpoint names leave addedEndpoints.
- Derived paths join the held paths every write skips, built on first use.
- Tests follow the merged behaviour: Azure groups merge by group, the agents endpoint is
  derived again below a tombstone.
2026-10-24 11:46:01 +02:00

139 lines
4.6 KiB
JavaScript

const mongoose = require('mongoose');
const { CacheKeys } = require('librechat-data-provider');
const { AppService } = require('@librechat/data-schemas');
const {
isEnabled,
expandCustomEndpoint,
createAppConfigService,
clearMcpConfigCache,
createCodeEnvironmentRegistry,
createConfigCacheInvalidation,
createRedisConfigInvalidationPubSub,
mergeAccessibleCodeEnvironments,
ioredisClient,
cacheConfig,
standardCache,
} = require('@librechat/api');
const { setCachedTools } = require('./getCachedTools');
const { loadAndFormatTools } = require('~/server/services/start/tools');
const loadCustomConfig = require('./loadCustomConfig');
const getLogStores = require('~/cache/getLogStores');
const paths = require('~/config/paths');
const db = require('~/models');
let codeEnvironmentRegistry;
function getCodeEnvironmentRegistry() {
if (codeEnvironmentRegistry == null) {
codeEnvironmentRegistry = createCodeEnvironmentRegistry(mongoose, {
configurationCache: cacheConfig.USE_REDIS
? standardCache('CODE_ENVIRONMENT_CONFIG')
: undefined,
});
}
return codeEnvironmentRegistry;
}
async function invalidateCodeEnvironmentConfigCache(tenantId) {
await getCodeEnvironmentRegistry().invalidateAccessibleConfigurations(tenantId);
}
const loadBaseConfig = async (mode) => {
/** @type {TCustomConfig} */
const config = (await loadCustomConfig(true, { mode })) ?? {};
/** @type {Record<string, FunctionTool>} */
const systemTools = loadAndFormatTools({
adminFilter: config.filteredTools,
adminIncluded: config.includedTools,
directory: paths.structuredTools,
});
return AppService({ config, paths, systemTools, expandCustomEndpoint });
};
const appConfigService = createAppConfigService({
loadBaseConfig,
setCachedTools,
getCache: getLogStores,
cacheKeys: CacheKeys,
getApplicableConfigs: db.getApplicableConfigs,
getUserPrincipals: db.getUserPrincipals,
overrideEnvAllowlist: process.env.CONFIG_OVERRIDE_ENV_ALLOWLIST,
rederiveEndpoints: isEnabled(process.env.CONFIG_REDERIVE_ENDPOINTS),
augmentConfig: ({ appConfig, baseConfig, principals, options }) => {
if (!options.userId) return appConfig;
return mergeAccessibleCodeEnvironments({
appConfig,
deploymentConfig: baseConfig,
actor: {
userId: options.userId,
role: options.role ?? null,
idOnTheSource: options.idOnTheSource ?? null,
principals,
},
registry: getCodeEnvironmentRegistry(),
});
},
});
const {
getAppConfig,
resolveConfigLayers,
clearAppConfigCache,
clearOverrideCache,
reloadBaseConfig,
overrideCacheTtl,
rederiveEndpoints,
} = appConfigService;
// Config owns the reader; models never import this module to obtain it.
db.initializeMessageBudget(getAppConfig);
/**
* Admin config writes clear the per-principal override caches, the MCP config-source servers
* and the YAML base config. Base-only sections such as `filters` and `messageFilter` exist only
* in librechat.yaml, and an admin write is how a running server picks up an edit to them: the
* next read reloads the YAML (keeping the last good config if it fails) and republishes the
* tools derived from it. With Redis, the clear is broadcast so every instance reloads its YAML
* and drops its in-process merged config.
*/
const configCacheInvalidation = createConfigCacheInvalidation({
clears: [
{ label: 'clearAppConfigCache', clear: () => clearAppConfigCache() },
{ label: 'clearOverrideCache', clear: clearOverrideCache },
{ label: 'clearMcpConfigCache', clear: () => clearMcpConfigCache() },
],
load: reloadBaseConfig,
pubsub: createRedisConfigInvalidationPubSub({
useRedis: cacheConfig.USE_REDIS,
client: ioredisClient,
namespace: cacheConfig.REDIS_KEY_PREFIX,
}),
});
/**
* Invalidate the config caches an admin config mutation affects, on every instance.
* @param {string} [tenantId] - Optional tenant ID to scope override cache clearing.
*/
function invalidateConfigCaches(tenantId) {
return configCacheInvalidation.invalidate(tenantId);
}
/**
* The same clear for the admin reload route, then librechat.yaml loaded again here and, when it
* loaded, the broadcast; resolves with what each step reached.
* @param {string} [tenantId] - Optional tenant ID to scope override cache clearing.
* @returns {Promise<import('@librechat/api').ConfigReloadReport>}
*/
function reloadConfigCaches(tenantId) {
return configCacheInvalidation.reload(tenantId);
}
module.exports = {
getAppConfig,
resolveConfigLayers,
overrideCacheTtl,
rederiveEndpoints,
invalidateConfigCaches,
reloadConfigCaches,
getCodeEnvironmentRegistry,
invalidateCodeEnvironmentConfigCache,
};