How FlClash Validates Clash Configuration Files: Methods and Implementation

FlClash validates Clash configuration files by delegating parsing duties to the native ClashMeta core, exposing two asynchronous Dart methods that return either "ok" or a descriptive error string.

FlClash is a cross-platform Flutter GUI for the Clash proxy ecosystem that requires robust configuration validation before applying network rules. When users import subscription files or edit configurations in-app, the application must verify YAML syntax, required fields, and rule consistency without exposing invalid settings to the runtime. The validation architecture leverages a bidirectional communication layer between Dart and the embedded Go core, ensuring all checks utilize the authoritative ClashMeta parser.

The Validation Pipeline Architecture

FlClash delegates all configuration parsing to the ClashMeta core rather than reimplementing validation logic in Dart. This ensures compatibility with the latest Clash configuration specifications and eliminates parsing discrepancies between the validator and the active runtime.

The validation flow follows a strict pipeline: UI Layer → CoreController → CoreHandlerInterface → Go Action Dispatcher → ClashMeta Parser. Each stage transforms the request into the appropriate format for the next layer, ultimately returning a simple string result indicating success or failure.

Dart API Methods for Configuration Validation

The public API exposes two methods in lib/core/controller.dart that handle different input scenarios. Both return a Future<String> containing either "ok" or an error description.

Validating File-Based Configurations

The validateConfig method accepts a file-system path and forwards it to the native core. Located at line 85 in lib/core/controller.dart, this method is ideal for validating downloaded subscription files or locally saved configurations.

Future<String> validateConfig(String path) async {
  final res = await _interface.validateConfig(path);
  return res;
}

Validating In-Memory Configurations

For configurations edited directly in the UI text editor, validateConfigWithData (line 90 in lib/core/controller.dart) accepts raw YAML or JSON strings. This avoids temporary file creation when validating user input before saving.

Future<String> validateConfigWithData(String data) async {
  final res = await _interface.validateConfigWithData(data);
  return res;
}

Native Core Implementation

The Dart interface translates these calls into structured action requests processed by the Go backend.

Action Method Routing

In lib/core/interface.dart, the CoreHandlerInterface maps validation requests to ActionMethod.validateConfig, defined in lib/enum/enum.dart. The interface constructs an action request that crosses the Flutter/platform channel boundary.

On the Go side, core/constant.go registers the handler as validateConfigMethod, while core/action.go (line 65) dispatches the request:

case validateConfigMethod:
    // Core parses the supplied file / data and returns "ok" or an error string

ClashMeta Parser Integration

The native implementation relies on ClashMeta's built-in configuration parser to perform comprehensive validation. According to the source code in core/action.go, the parser verifies:

• Syntax integrity: Valid YAML or JSON structure
• Required fields: Presence of port, socks-port, proxies, and other mandatory top-level keys
• Proxy definitions: Valid server addresses, ports, encryption methods, and authentication parameters
• Rule formats: Proper rule types, domain suffixes, and IP CIDR notation
• Logical consistency: Absence of duplicate rule IDs and valid group references

If validation succeeds, the core returns the string "ok". Upon detecting malformed syntax or logical errors, it returns a detailed error message describing the specific failure.

Practical Usage Examples

When implementing configuration validation in your FlClash workflow, use these patterns to handle both file and text-based validation.

Validate a downloaded subscription before activation:

final controller = CoreController.instance;
final result = await controller.validateConfig('/storage/emulated/0/Clash/config.yaml');
print(result); // "ok" or error description

Validate configuration text during in-app editing:

final raw = '''
port: 7890
socks-port: 7891
proxies:
  - name: "US-1"
    type: ss
    server: example.com
    port: 443
    cipher: aes-128-gcm
    password: "secret"
rules:
  - DOMAIN-SUFFIX,google.com,Proxy
''';
final result = await controller.validateConfigWithData(raw);
print(result);

Summary

• FlClash validates Clash configuration files through two Dart methods: validateConfig for file paths and validateConfigWithData for raw strings.
• The validation pipeline delegates all parsing to the native ClashMeta core via the action dispatcher pattern implemented in core/action.go.
• Source files involved include lib/core/controller.dart for the public API, lib/core/interface.dart for method mapping, and core/constant.go for native method registration.
• The core performs comprehensive checks including YAML/JSON syntax, required fields, proxy definitions, and rule consistency.
• Both methods return simple string responses: "ok" indicates success, while any other value describes the specific validation error returned by the ClashMeta parser.

Frequently Asked Questions

Does FlClash validate configurations locally or remotely?

FlClash performs all validation locally using the embedded ClashMeta core. The validation happens entirely on-device through the Go native library, ensuring no configuration data is transmitted to external servers for verification.

What happens if the Clash configuration contains unsupported proxy types?

If the configuration includes proxy types not supported by the ClashMeta core version embedded in FlClash, the validateConfig or validateConfigWithData method returns an error string describing the invalid proxy type. The validation fails before the configuration is applied to the active connection.

Can I validate a configuration without saving it to disk first?

Yes. Use the validateConfigWithData method in lib/core/controller.dart to validate raw YAML or JSON strings directly. This method is specifically designed for validating in-memory configurations during text editing, eliminating the need for temporary file creation.

What string value indicates successful validation in FlClash?

When validation succeeds, both validateConfig and validateConfigWithData return the exact string "ok". Any other return value represents an error condition and contains a descriptive message explaining which validation check failed according to the ClashMeta parser logic.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}