Configuration Management & Validation
Relevant source files
The following files were used as context for generating this wiki page:
Configuration Management & Validation in OneBots provides a structured system for creating, verifying, and applying settings across platform adapters and wire protocols. The system isolates the management service from the gateway runtime to ensure that configuration failures do not crash active bot services. Users edit configurations in private drafts, which the system validates against strict schemas before they become active immutable versions.
Sources: AGENTS.md:16-17, packages/web/src/components/ControlConfigurationPanel.vue:152-154
System Architecture
The configuration system follows a two-tier architecture. The Management Service handles the Control Panel UI, draft persistence, and schema validation. The Gateway Service consumes verified configuration versions and maintains the active connection state for IM accounts.
The diagram shows the lifecycle of a configuration change from the user interface to the runtime gateway.
Sources: README.en.md:28-39, AGENTS.md:12-25
Configuration Storage and Integrity
OneBots manages configuration persistence through the ConfigurationStore class. This class maintains a private directory for JSON-based drafts, ensuring each draft remains isolated.
Draft Management
The system identifies each configuration draft by a unique UUID. Every draft contains a revision hash (SHA256) and a base reference to prevent concurrent edit conflicts. If the underlying file changes while a user is editing, the system throws a ConfigurationConflictError.
Sources: packages/onebots/src/configuration/configuration-store.ts:18-35, packages/onebots/src/configuration/configuration-store.ts:89-94
Deterministic Serialization
To ensure stable hash generation, the system uses the canonicalConfiguration function. This function recursively sorts all object keys alphabetically before generating the revision string. This process ensures that two identical configurations produce the same hash regardless of the key order in the source JSON.
Sources: packages/onebots/src/configuration/configuration-store.ts:130-143
Validation System
The ConfigValidator performs structural and value-level checks. It ensures that inputs meet the requirements defined by platform adapters and core services.
Validation Rules
The validator supports several constraint types:
| Rule Type | Description | Example Constraints |
|---|---|---|
| Type | Enforces data types | string, number, boolean, array |
| Range | Restricts numerical values | min: 1, max: 65535 |
| Pattern | Validates strings via Regex | /^https?:\/\// (URLs) |
| Choices | Limits input to specific values | ['low', 'medium', 'high'] |
| Custom | Executes arbitrary logic | Custom validator functions |
Sources: packages/core/src/tests/config-validator.test.ts:9-140, packages/core/ARCHITECTURE.md:65-90
Nested Schemas
The system validates complex objects recursively. If a required field is missing in a nested object, the validator reports the specific path (e.g., server / host) to the user.
Sources: packages/core/src/tests/config-validator.test.ts:173-189
Management Workflow
The Web Management UI (Control Panel) guides users through a mandatory four-step lifecycle to prevent operational errors.
- Edit: Modify fields in the browser. The system tracks these as "Dirty" local changes.
- Save: Commit local changes to the server-side draft. This updates the draft ID and revision.
- Validate: Run the
ConfigValidatoragainst the saved draft. The system checks mandatory parameters and connection settings. - Apply: Promote the validated draft to the active gateway version.
The sequence diagram illustrates the required steps for a user to move from editing a configuration to making it active.
Sources: packages/web/src/components/ControlConfigurationPanel.vue:204-236, packages/web/src/components/ControlConfigurationPanel.vue:274-279
Atomic File Operations
To prevent data corruption during crashes or power failures, the core system performs atomic writes to configuration files.
- The system writes new data to a temporary file (
.tmp). - It calls
fsyncSyncto ensure data reaches physical storage. - It renames the temporary file to the final destination (
config.yaml). - It maintains the previous version as a backup (
.bak) if the backup option is enabled.
Sources: packages/core/src/config-file.spec.ts:20-43, packages/onebots/src/configuration/configuration-store.ts:110-120
Summary
Configuration Management & Validation in OneBots provides a safe, revision-controlled environment for IM gateway settings. By utilizing canonical serialization, atomic file operations, and a mandatory "Save-Validate-Apply" workflow, the system maintains high reliability. It ensures that only structurally sound configurations reach the runtime adapters, protecting the bot's availability.
Sources: packages/core/ARCHITECTURE.md:144-150, AGENTS.md:120-125