From d42a78cba9c12bf4be52279b0be25302c7c82737 Mon Sep 17 00:00:00 2001
From: Cuong Manh Le <cuong@windscribe.com>
Date: Mon, 22 Sep 2025 14:10:06 +0700
Subject: [PATCH] docs: add comprehensive package documentation for rulematcher

- Add detailed package documentation to engine.go explaining the rule matching
  system, supported rule types (Network, MAC, Domain), and priority ordering
- Include usage example demonstrating typical API usage patterns
- Remove unused Type() method from RuleMatcher interface and implementations
- Maintain backward compatibility while improving code documentation

The documentation explains the policy-based DNS routing system and how different
rule types interact with configurable priority ordering.
---
 config.go                       |  2 +-
 internal/rulematcher/domain.go  |  5 -----
 internal/rulematcher/engine.go  | 37 +++++++++++++++++++++++++++++++++
 internal/rulematcher/mac.go     |  5 -----
 internal/rulematcher/network.go |  5 -----
 internal/rulematcher/types.go   |  1 -
 6 files changed, 38 insertions(+), 17 deletions(-)

diff --git a/config.go b/config.go
index 73ffbee..3e6548d 100644
--- a/config.go
+++ b/config.go
@@ -317,7 +317,7 @@ func (lc *ListenerConfig) IsDirectDnsListener() bool {
 
 // MatchingConfig defines the configuration for rule matching behavior
 type MatchingConfig struct {
-	Order []string `mapstructure:"order" toml:"order,omitempty" json:"order" yaml:"order"`
+	Order []string `mapstructure:"order" toml:"order,omitempty"`
 }
 
 // ListenerPolicyConfig specifies the policy rules for ctrld to filter incoming requests.
diff --git a/internal/rulematcher/domain.go b/internal/rulematcher/domain.go
index 72ee291..e70ea58 100644
--- a/internal/rulematcher/domain.go
+++ b/internal/rulematcher/domain.go
@@ -7,11 +7,6 @@ import (
 // DomainRuleMatcher handles matching of domain-based rules
 type DomainRuleMatcher struct{}
 
-// Type returns the rule type for domain matcher
-func (d *DomainRuleMatcher) Type() RuleType {
-	return RuleTypeDomain
-}
-
 // Match evaluates domain rules against the requested domain
 func (d *DomainRuleMatcher) Match(ctx context.Context, req *MatchRequest) *MatchResult {
 	if req.Policy == nil || len(req.Policy.Rules) == 0 {
diff --git a/internal/rulematcher/engine.go b/internal/rulematcher/engine.go
index 4c81b08..8a5b951 100644
--- a/internal/rulematcher/engine.go
+++ b/internal/rulematcher/engine.go
@@ -1,3 +1,40 @@
+// Package rulematcher provides a flexible rule matching engine for DNS request routing.
+//
+// The rulematcher package implements a policy-based DNS routing system that allows
+// configuring different types of rules to determine which upstream DNS servers should
+// handle specific requests. It supports three types of rules:
+//
+//   - Network rules: Match requests based on source IP address ranges
+//   - MAC rules: Match requests based on source MAC addresses
+//   - Domain rules: Match requests based on requested domain names
+//
+// The matching engine uses a configurable priority order to determine which rules
+// take precedence when multiple rules match. By default, the priority order is:
+// Network -> MAC -> Domain, with Domain rules having the highest priority and
+// overriding all other matches.
+//
+// Example usage:
+//
+//	config := &MatchingConfig{
+//		Order: []RuleType{RuleTypeNetwork, RuleTypeMac, RuleTypeDomain},
+//	}
+//	engine := NewMatchingEngine(config)
+//
+//	request := &MatchRequest{
+//		SourceIP:  net.ParseIP("192.168.1.100"),
+//		SourceMac: "aa:bb:cc:dd:ee:ff",
+//		Domain:    "example.com",
+//		Policy:    policyConfig,
+//		Config:    appConfig,
+//	}
+//
+//	result := engine.FindUpstreams(ctx, request)
+//	if result.Matched {
+//		// Use result.Upstreams to route the request
+//	}
+//
+// The package maintains backward compatibility with existing behavior while
+// providing a clean, extensible interface for adding new rule types.
 package rulematcher
 
 import (
diff --git a/internal/rulematcher/mac.go b/internal/rulematcher/mac.go
index d0b1412..ff20e81 100644
--- a/internal/rulematcher/mac.go
+++ b/internal/rulematcher/mac.go
@@ -8,11 +8,6 @@ import (
 // MacRuleMatcher handles matching of MAC address-based rules
 type MacRuleMatcher struct{}
 
-// Type returns the rule type for MAC matcher
-func (m *MacRuleMatcher) Type() RuleType {
-	return RuleTypeMac
-}
-
 // Match evaluates MAC address rules against the source MAC address
 func (m *MacRuleMatcher) Match(ctx context.Context, req *MatchRequest) *MatchResult {
 	if req.Policy == nil || len(req.Policy.Macs) == 0 {
diff --git a/internal/rulematcher/network.go b/internal/rulematcher/network.go
index 8114fe1..1c20406 100644
--- a/internal/rulematcher/network.go
+++ b/internal/rulematcher/network.go
@@ -8,11 +8,6 @@ import (
 // NetworkRuleMatcher handles matching of network-based rules
 type NetworkRuleMatcher struct{}
 
-// Type returns the rule type for network matcher
-func (n *NetworkRuleMatcher) Type() RuleType {
-	return RuleTypeNetwork
-}
-
 // Match evaluates network rules against the source IP address
 func (n *NetworkRuleMatcher) Match(ctx context.Context, req *MatchRequest) *MatchResult {
 	if req.Policy == nil || len(req.Policy.Networks) == 0 {
diff --git a/internal/rulematcher/types.go b/internal/rulematcher/types.go
index 9e426ef..073830e 100644
--- a/internal/rulematcher/types.go
+++ b/internal/rulematcher/types.go
@@ -19,7 +19,6 @@ const (
 // RuleMatcher defines the interface for matching different types of rules
 type RuleMatcher interface {
 	Match(ctx context.Context, request *MatchRequest) *MatchResult
-	Type() RuleType
 }
 
 // MatchRequest contains all the information needed for rule matching