Prism DSL & YAML Overrides
Relevant source files
The following files were used as context for generating this wiki page:
Prism DSL and YAML Overrides constitute a core part of the Zephyr Rule Engine, providing a declarative method to modify Mihomo configurations. This system allows users to patch existing configurations using specific directives such as $prepend, $append, and $filter, alongside conditional logic via __when__ blocks. The engine supports both local and remote YAML patches, enabling flexible rule management and synchronization across different proxy profiles.
Sources: FEATURES.md:88-100, apps/desktop/src-tauri/src/prism/overrides_commands.rs:18-35
Architecture and Data Flow
The system operates as a pipeline that intercepts the Mihomo configuration process. When a profile is applied, the Prism Engine compiles enabled overrides and applies them as patches to the base YAML.
Override Application Pipeline
The application process follows a multi-phase commit strategy to ensure configuration integrity:
- Collection: The engine identifies all enabled overrides based on their scope (Global or Profile-specific).
- Compilation: Prism YAML patches are written to the workspace and compiled via the
ext.apply()method. - Injection: The resulting patches modify the
run_config.yamlfile. - Hot-Reload: The system triggers a Mihomo core reload to activate the new configuration.
Core Components
Override Model
The OverrideItem data structure represents a single patch. It tracks metadata, content location, and execution status.
| Field | Type | Description |
|---|---|---|
name | String | User-defined name for the override |
ext | OverrideExt | File type: Js or PrismYaml |
type | OverrideType | Source: Local or Remote |
global | Boolean | If true, applies to all profiles |
enabled | Boolean | Current activation state |
last_success | Option | Result of the last execution |
Sources: apps/desktop/src-tauri/src/prism/overrides_commands.rs:20-30, apps/desktop/src-tauri/src/prism/types.rs:15-35
Rule Library Management
The Rule Library provides CRUD operations for .prism.yaml files. It handles file sanitization, source detection, and rule normalization.
Rule Normalization and Extraction
The engine converts standard proxy rules (Clash or Surge formats) into Prism-compatible YAML. This process involves replacing hardcoded proxy groups with the {{proxy}} template, allowing rules to be reused across different subscriptions.
Extraction Process
When extracting rules from an existing profile, the system:
- Parses the profile YAML.
- Identifies the
rulessequence. - Reconstructs rule strings, substituting non-built-in policies with
{{proxy}}. - Wraps the output in a
$appenddirective to ensure rules are added at the end of the final configuration.
// Reconstruct: replace only the policy_index field with {{proxy}}
let rebuilt = parts
.iter()
.enumerate()
.map(|(i, part)| if i == policy_index { "{{proxy}}" } else { part })
.collect::<Vec<_>>()
.join(",");
lines.push(format!(" - {rebuilt}"));
Sources: apps/desktop/src-tauri/src/prism/rule_library.rs:160-205, apps/desktop/src-tauri/src/prism/types.rs:210-230
Security and Validation
The system implements several layers of validation to prevent injection attacks and resource exhaustion:
- Filename Sanitization: Only allows alphanumeric characters, hyphens, underscores, dots, spaces, CJK characters, and parentheses.
- SSRF Protection: Remote override downloads use
fetch_url_contentwith DNS validation and IP pinning to block access to private networks. - Input Size Limits: All user-supplied text inputs are restricted to a maximum of 10 MB (
MAX_INPUT_SIZE). - Content Validation: The system detects and rejects HTML content (e.g.,
<!doctype) when downloading remote overrides to ensure only valid scripts or YAML are processed.
Sources: apps/desktop/src-tauri/src/prism/types.rs:10-12, 70-100, apps/desktop/src-tauri/src/prism/overrides_commands.rs:105-125
Conclusion
The Prism DSL & YAML Overrides system provides Zephyr with a robust, secure, and declarative configuration management layer. By separating rule logic from specific profiles and utilizing a template-based substitution system, it allows users to maintain complex routing policies with minimal redundancy. The combination of local and remote patching ensures that configurations remain synchronized and adaptable to changing network environments.