Add proxy rules list export/import format

[salarcode]

Description

Create a universal rules format that anyone can implement without hassle of writing a parser from scratch.
Requirements:

• As minimal as possible, one line per rule
• Be minimal and clean with default values
• Easy to read
• Parser libraries available for languages
• No tight coupling with specific implementation

[salarcode]

Options:

• KDL seems like a vary good candidate: https://kdl.dev/
• logfmt https://brandur.org/logfmt

rule=MatchPatternHost pattern="*.google.com" proxy=127.0.0.1:8888
rule=Exact pattern="my-site.com" whiteList=true

• Nginx Configuration Format https://nginx.org/en/docs/beginners_guide.html

rule *.google.com type=MatchPatternHost proxy=127.0.0.1:8888;
rule my-site.com type=Exact whiteList=true;

[salarcode]

KDL

Suggested format:

// [SmartProxy Rules KDL]
// SmartProxy 1.9

// Use the first argument for the pattern, properties for the rest
rule "*.google.com" type="MatchPatternHost" proxy="127.0.0.1:8888"
rule "my-site.com"  type="Exact" whiteList=true enabled=false

[salarcode]

KDL Parser, using kdljs library https://github.com/kdl-org/kdljs

Generator:

import { parse, Document } from "kdljs";

export class ProxyRule {
    constructor(
        public ruleType: ProxyRuleType,
        public pattern: string,
        public proxy: string = "",
        public whiteList: boolean = false
    ) {}

    // Static factory to load the whole file
    static fromKdl(kdlContent: string): ProxyRule[] {
        // 1. Validate Header
        if (!kdlContent.includes("// [SmartProxy Rules KDL]")) {
            throw new Error("Invalid SmartProxy header");
        }

        const { output, errors } = parse(kdlContent);
        if (errors.length > 0) throw new Error("KDL Parse Error");

        return output
            .filter(node => node.name === "rule")
            .map(node => {
                const attrs = node.properties;
                return new ProxyRule(
                    attrs.type as ProxyRuleType, // mapped from rule="MatchPatternHost"
                    attrs.pattern as string,
                    attrs.proxy as string || "",
                    Boolean(attrs.whiteList)
                );
            });
    }
}

Parser:

import { parse, Node } from "kdljs";

export enum ProxyRuleType {
    MatchPatternHost = "MatchPatternHost",
    MatchPatternUrl = "MatchPatternUrl",
    RegexHost = "RegexHost",
    RegexUrl = "RegexUrl",
    Exact = "Exact",
    DomainSubdomain = "DomainSubdomain",
    DomainExact = "DomainExact",
    DomainAndPath = "DomainAndPath",
    DomainSubdomainAndPath = "DomainSubdomainAndPath",
    SearchUrl = "SearchUrl"
}

export class ProxyRule {
    public ruleType: ProxyRuleType = ProxyRuleType.MatchPatternHost;
    public rule: string = "";
    public proxy: string = ""; // Expected format: "127.0.0.1:8888"
    public whiteList: boolean = false;
}

export class SmartProxyParser {
    private readonly HEADER = "// [SmartProxy Rules KDL]\n// SmartProxy 1.9";

    /**
     * Parses KDL into ProxyRule objects with ProxyServer validation
     */
    public parse(input: string): ProxyRule[] {
        if (!input.includes("[SmartProxy Rules KDL]")) {
            throw new Error("Missing SmartProxy identification header.");
        }

        const { output, errors } = parse(input);
        if (errors.length > 0) throw new Error(`KDL Error: ${errors[0].message}`);

        return output
            .filter(node => node.name === "rule")
            .map(node => {
                const r = new ProxyRule();
                const p = node.properties;

                // Map Enum safely
                r.ruleType = ProxyRuleType[p.rule as keyof typeof ProxyRuleType] || ProxyRuleType.MatchPatternHost;
                r.rule = String(p.pattern || "");
                r.whiteList = p.whiteList === true;
                
                // Handle Proxy Server:Port string
                const rawProxy = String(p.proxy || "");
                r.proxy = this.validateProxyFormat(rawProxy);

                return r;
            });
    }

    /**
     * Ensures the string is either empty or a valid server:port
     */
    private validateProxyFormat(proxyStr: string): string {
        if (proxyStr === "") return proxyStr;
        
        // Basic Regex for host:port (handles IPv4 and domains)
        const pattern = /^([a-zA-Z0-9.-]+|\[[a-fA-F0-9:]+\]):([0-9]{1,5})$/;
        if (!pattern.test(proxyStr)) {
            console.warn(`Invalid proxy format detected: ${proxyStr}. Defaulting to empty.`);
            return "";
        }
        return proxyStr;
    }

    /**
     * Serialises back to the KDL format
     */
    public stringify(rules: ProxyRule[]): string {
        const body = rules.map(r => 
            `rule rule="${r.ruleType}" pattern="${r.rule}" proxy="${r.proxy}" whiteList=${r.whiteList}`
        ).join("\n");

        return `${this.HEADER}\n\n${body}`;
    }
}

Refined Parser/Stringify

import { parse, Node } from "kdljs";

export class SmartProxyParser {
    private readonly HEADER = "// [SmartProxy Rules KDL]\n// SmartProxy 1.9\n\n// Use the first argument for the pattern, properties for the rest";

    /**
     * Serialises ProxyRule array to your specific KDL style
     */
    public stringify(rules: ProxyRule[]): string {
        const body = rules.map(r => {
            // First argument is the pattern (quoted)
            const patternArg = `"${r.rule}"`;
            
            // Properties follow
            const props = [
                `type="${r.ruleType}"`,
                r.whiteList ? `whiteList=true` : `proxy="${r.proxy}"`
            ];

            return `rule ${patternArg} ${props.join(" ")}`;
        }).join("\n");

        return `${this.HEADER}\n\n${body}`;
    }

    /**
     * Parser that handles positional arguments (the pattern) and properties
     */
    public parse(input: string): ProxyRule[] {
        if (!input.includes("[SmartProxy Rules KDL]")) {
            throw new Error("Invalid header.");
        }

        const { output, errors } = parse(input);
        if (errors.length > 0) throw new Error("KDL Parse Failed");

        return output
            .filter(node => node.name === "rule")
            .map(node => {
                const r = new ProxyRule();
                
                // KDL Positional Argument (the string right after 'rule')
                r.rule = String(node.values[0] || "");
                
                // KDL Properties
                const p = node.properties;
                r.ruleType = ProxyRuleType[p.type as keyof typeof ProxyRuleType] || ProxyRuleType.MatchPatternHost;
                r.whiteList = p.whiteList === true;
                r.proxy = r.whiteList ? "" : String(p.proxy || "");

                return r;
            });
    }
}

FYI Generated via Gemini, not reviewed

[salarcode]

SmartProxy Rules File Format Specification v1.0

Overview

SmartProxy Rules File Format is a minimal, line-oriented configuration format designed for defining proxy rules. Each line represents a single rule with a pattern and optional properties.

File Structure

• One rule per line
• Lines starting with # are comments and ignored
• Empty lines are ignored
• Each rule starts with the keyword rule

Syntax

rule <pattern> [key=value] [key=value] ...

Components

1. Keyword: Every rule must start with rule
2. Pattern: The first parameter after rule (required)
3. Properties: Zero or more space-separated key=value pairs (optional)

Token Parsing Rules

Tokens are separated by unquoted spaces. Each token (pattern or property value) follows these quoting rules:

Quoted Tokens

If a token **starts with "**:

The parser scans forward from the opening " to locate the last " that is immediately followed by a space, line-feed, or end-of-file.

The value is everything between the opening " and that closing ". Any " characters occurring between them are preserved as-is in the value.

Finding the Closing Quote: Examples

Closing quote followed by space:

rule "test" next           → pattern is: test
                            (closing quote is followed by the space before "next")

rule "a"b"c" type=Exact   → pattern is: a"b"c
                            (closing quote is the third one, followed by the space before "type")

rule "my site.com" next    → pattern is: my site.com
                            (closing quote is after "com", followed by the space before "next")

Closing quote followed by line-feed:

rule "test"
next line                → pattern is: test
                            (closing quote is followed by the line-feed)

rule "some"quoted"
                         → pattern is: some"quoted
                            (closing quote is followed by the line-feed)

Closing quote followed by end-of-file:

rule "test"              → pattern is: test
                            (closing quote is at EOF)

rule "final"rule"        → pattern is: final"rule
                            (closing quote is at EOF)

Quoted Token Examples

"my-site.com"           → my-site.com
"my site.com"           → my site.com
"some"quoted"value"     → some"quoted"value
""middle""              → "middle"
"test"                  → test
""                      → (empty string)

Whitespace Preservation

Whitespace (spaces, tabs) inside quotes is preserved exactly as written. To preserve whitespace in a value, enclose it in quotes.

"my site.com"           → my site.com (space preserved)
"   padded   "          →   padded   (spaces preserved)

Unquoted Tokens

If a token does not start with ":

The value is everything from the start until the next space, line-feed, or end-of-file. No quote processing occurs.

my-site.com             → my-site.com
127.0.0.1:8888          → 127.0.0.1:8888
test"has"quotes         → test"has"quotes

Properties

Properties are key=value pairs. Both keys and values follow the same token parsing rules described above.

type=Exact                          → key: type, value: Exact
proxy=127.0.0.1:8888                → key: proxy, value: 127.0.0.1:8888
proxy="127.0.0.1:8888"              → key: proxy, value: 127.0.0.1:8888
whiteList=true                      → key: whiteList, value: true
desc="some"quoted"value"            → key: desc, value: some"quoted"value
desc="my site.com"                  → key: desc, value: my site.com

Default Values

The format does not define default values for properties. Applications using this format define their own defaults and property semantics.

Complete Examples

# SmartProxy Rules v1.0

# Basic rule with just a pattern
rule my-site.com

# Rule with pattern and properties
rule "*.google.com" type=MatchPatternHost proxy=127.0.0.1:8888

# Rule with quoted pattern
rule "my-site.com" type=Exact whiteList=true

# Regex pattern (quotes preserve special characters)
rule "/^https?:\/\/.*/" type=RegexUrl

# Pattern with embedded quotes
rule "some"quoted"value" type=Exact

# Mixed quoted and unquoted properties
rule simple.com proxy="127.0.0.1:8888" type=Exact

# All properties quoted
rule "another.com" type="Exact" whiteList="true"

# Pattern with spaces (must use quotes)
rule "my site.com" type=DomainExact desc="my site.com"

# Empty pattern
rule "" whiteList=true

Token Termination

A token ends when one of the following is encountered:

• For unquoted tokens: A space character ( ), line-feed (\n), or end-of-file.
• For quoted tokens: The closing " that is directly followed by a space character ( ), line-feed (\n), or end-of-file.

Comments

Lines beginning with # (after trimming leading whitespace) are treated as comments and ignored by the parser.

# This is a comment
rule example.com  # This is NOT a comment, everything after 'rule' is parsed

Notes

• No escape sequences are supported. The quote mechanism handles all special characters.
• The format is case-sensitive.
• Property order does not matter.

[antonzakatov]

There is a clear internal contradiction between two points:

It is stated that quotation marks allow spaces to be preserved within values.

The parsing rule states that the value is taken "from the first to the last quotation mark before a space, a line break, or the end of the file."

These points contradict each other. If there is a space inside the quotation marks, a space will inevitably be encountered before the closing quotation mark. This means the parser must either stop at that space—failing to reach the closing quotation mark—or ignore spaces inside the quotation marks; however, the latter is inconsistent with the phrasing "before a space."

rule "my site.com" desc="my site.com"

[salarcode]

Thanks for catching that, it now says Tokens are separated by unquoted spaces
Also made some other changes regarding this.

Truth to be told I wanted to capture an ideal format for myself here.
But in reality it would be ideal to avoid creating yet another format just to solve some issues and limitations of others.
Also this new format creates a problem of adaptation because it needs a new parser/formatter.

As I stated in the first message I would like to use existing formats like KDL but still not convinced with any of them.

Do you think a new format has enough value to exist?