Configuration Validation Rules¶

Doc Version: 1.0.0 Last Updated: 2026-07-17 Git Commit: ca98a2ee Author: Lincoln

Overview¶

Configuration validation in JAiRouter comes in two kinds, with different timing and consequences:

⚠️ This page was rewritten from the code (issue #374). The previous version listed 7 named rules (rate-limit-capacity, circuit-breaker-threshold, jwt-expiration, thread-pool-size, …), matching export RATE_LIMIT_* examples, and a ConfigurationValidationRule extension interface — none of those three exist in this repository. Every statement below can be traced to a file:line.

1. Startup validation¶

Both startup validators are ApplicationListener<ApplicationReadyEvent> beans that run once the context is ready (so a failure shows up as the process exiting).

Master switches¶

jairouter:
  config:
    validation:
      enabled: true       # false => neither startup validator runs
      strict-mode: false  # true  => the sensitive-value findings become startup failures

1.1 ConfigIntegrityValidator — any error fails the startup¶

config/core/validator/ConfigIntegrityValidator.java (class at :45, switch read at :79-87). Findings go into two buckets and then (:107-112):

• any error ⇒ log each one, then throw IllegalStateException("配置校验失败，存在 N 个错误") ⇒ the application fails to start;
• warnings only ⇒ logged, startup is unaffected.

Rules (value sets and bounds are taken from the code, :129-206):

How it reads the switch: @Value("${jairouter.config.validation.enabled:true}") (:79); when false it logs one line and returns immediately (:84-87).

📌 The class javadoc carries its own rule list, but with smaller value sets than the code (4 load-balancer types / 2 rate-limit algorithms / 2 store types). This page follows the code; the javadoc has been aligned in the same batch as issue #374.

1.2 SensitiveConfigValidator — sensitive-value check-up (warnings only by default)¶

config/core/validator/SensitiveConfigValidator.java. It is @ConditionalOnProperty(name = "jairouter.config.validation.enabled", havingValue = "true", matchIfMissing = true) (:28) — note the difference from the validator above: this one is enabled when the switch is absent.

It checks three environment variables (read through Spring placeholders of the form ${JWT_SECRET:}, :33-40):

"Looks hard-coded" (:153-169): contains your- / placeholder / example / test / demo / changeme, or equals secret / password (case-insensitive).

Failure semantics (easy to misread — this is what the code does): the errors bucket is always printed, but it only blocks startup when strict-mode=true (printing and blocking are decoupled, since issue #381). Therefore:

• strict-mode=false (default): both warnings and errors are printed (error-level findings such as a hard-coded-looking JWT_SECRET are now visible), but they do not block startup;
• strict-mode=true: a non-empty errors bucket ⇒ each entry is logged with log.error and the startup fails.

📌 Relation to the production startup gate: under the prod / production profile, stricter checks on JWT_SECRET and INITIAL_ADMIN_PASSWORD happen earlier — auth/security/config/StartupSecurityGate.java fails fast during the CommandLineRunner phase (missing value, factory default, or weak strength all abort the process). Production therefore usually never reaches this validator; it mainly helps in dev/test environments.

2. Runtime validation (configuration-API path)¶

These validators are not part of startup; they are wired into configuration-change call sites:

What each call site does with a validation result (reject the save / return an error / just warn) is decided by that call site; this page is an inventory only. Per-rule consequences follow each validator's javadoc and call-site code.

3. Disabling validation / enabling strict mode¶

# Turn off both startup validators (not recommended: you lose the startup check-up)
jairouter:
  config:
    validation:
      enabled: false

# Enable strict mode only (let the sensitive-value findings actually block startup)
jairouter:
  config:
    validation:
      strict-mode: true

Environment-variable form (Spring Boot relaxed binding — framework behavior, equivalent to the YAML above):

export JAIRouter_CONFIG_VALIDATION_ENABLED=true
export JAIRouter_CONFIG_VALIDATION_STRICT_MODE=true

⚠️ strict-mode affects only SensitiveConfigValidator. The errors of ConfigIntegrityValidator are always fatal for startup; there is no strict-mode switch for them.

4. Extending validation (the real shape)¶

There is no ConfigurationValidationRule interface in this repository. To add a startup check, follow the two real validators:

@Component
public class MyConfigValidator implements ApplicationListener<ApplicationReadyEvent> {

    private static final Logger log = LoggerFactory.getLogger(MyConfigValidator.class);

    @Value("${jairouter.config.validation.enabled:true}")
    private boolean validationEnabled;

    @Override
    public void onApplicationEvent(ApplicationReadyEvent event) {
        if (!validationEnabled) {
            return;
        }
        // collect errors / warnings yourself; to block startup on an error, throw
        // (template: ConfigIntegrityValidator:107-112)
        log.info("✓ custom validation finished");
    }
}

Key points:

1. Register with @Component + ApplicationListener<ApplicationReadyEvent> (both real validators do this);
2. Throw IllegalStateException when an error must block startup (ConfigIntegrityValidator's approach); log.warn when it is informational only;
3. Please read jairouter.config.validation.enabled as well, so the master switch applies to your check.

5. Troubleshooting¶

Related code¶

Related documentation¶

• Configuration reference
• Deployment · Production
• Troubleshooting · Common issues