feat: JSON Snippet Merging

[bayard]

JSON Snippet Merging for Advanced Xray Configuration

Background

Xray's configuration schema evolves rapidly, with new fields, options, and syntax changes introduced in almost every release. GUI clients inevitably lag behind these changes, preventing users from adopting new Xray features until the application itself is updated. This often results advanced users unable to use this application in scenarios which need some config tweaks .

A generic configuration snippet mechanism would largely eliminate this problem while requiring relatively little implementation effort.

Proposed Feature

Allow users to define one or more JSON configuration snippets that are automatically applied to the generated Xray configuration before it is written or launched.

Each snippet consists of:

• A JSONPath expression that identifies the target node(s).

• A merge strategy.

• The value to apply.

Supported Merge Strategies

The merge engine should support several strategies to cover most configuration scenarios:

Strategy | Description replace | Replace the target value entirely. merge | Merge object properties, preserving unspecified fields. append | Append elements to an existing array. prepend | Insert elements at the beginning of an existing array. remove | Remove matching object properties or array elements. create | Create the target node if it does not already exist.

These operations provide enough flexibility to adapt to nearly any future Xray configuration change without requiring GUI updates.

Example

Suppose XrayUI-dev generates a TUN configuration.

In XrayUI v1.17, I want Chrome (chrome.exe) to bypass TUN while still using its own SOCKS proxy configured via ZeroOmega. The GUI currently cannot express the newly introduced configuration required for this behavior.

A snippet such as:

{
  "snippets": [
    {
      "path": "$.inbounds[?(@.tag=='tun-in')].sniffing",
      "strategy": "merge",
      "value": {
        "excludedOutboundTags": [
          "direct"
        ],
        "routeOnly": true
      }
    }
  ]
}

would locate the target object using JSONPath and merge the supplied properties into the generated configuration.

Other examples include:

• Appending a new routing rule without replacing existing rules.

• Removing an obsolete configuration field after upgrading Xray.

• Creating newly introduced configuration sections before the GUI supports them.

• Overriding only a single property while preserving the rest of the generated configuration.

Benefits

• Decouples GUI releases from Xray configuration changes.

• Enables users to adopt newly introduced Xray features immediately.

• Add dashboard similar to clash's yacd by introducing "api" config.

• Enables users to adopt newly introduced Xray features immediately.

• Supports experimental or custom Xray features without waiting for GUI implementation.

• Provides a future-proof extension mechanism with minimal maintenance burden.

• Keeps the GUI simple for typical users while giving advanced users complete control.

• Further function improvements like re-order of routing elements can be implemented in the future.

Impact

This feature would fundamentally improve the extensibility of the application.

Instead of exposing only the subset of Xray functionality implemented by the GUI, the application becomes an extensible configuration platform capable of supporting virtually any current or future Xray feature through user-defined snippets.

The result is a significantly longer-lived, more flexible application that can evolve alongside Xray without requiring frequent GUI updates, effectively turning it into a "Swiss Army knife" for advanced Xray users.

[PhoenixNil]

good proposition!