github.com/v2fly/v2ray-core/v5@v5.16.2-0.20240507031116-8191faa6e095/common/strmatcher/strmatcher.go (about)

     1  package strmatcher
     2  
     3  // Type is the type of the matcher.
     4  type Type byte
     5  
     6  const (
     7  	// Full is the type of matcher that the input string must exactly equal to the pattern.
     8  	Full Type = 0
     9  	// Domain is the type of matcher that the input string must be a sub-domain or itself of the pattern.
    10  	Domain Type = 1
    11  	// Substr is the type of matcher that the input string must contain the pattern as a sub-string.
    12  	Substr Type = 2
    13  	// Regex is the type of matcher that the input string must matches the regular-expression pattern.
    14  	Regex Type = 3
    15  )
    16  
    17  // Matcher is the interface to determine a string matches a pattern.
    18  //   - This is a basic matcher to represent a certain kind of match semantic(full, substr, domain or regex).
    19  type Matcher interface {
    20  	// Type returns the matcher's type.
    21  	Type() Type
    22  
    23  	// Pattern returns the matcher's raw string representation.
    24  	Pattern() string
    25  
    26  	// String returns a string representation of the matcher containing its type and pattern.
    27  	String() string
    28  
    29  	// Match returns true if the given string matches a predefined pattern.
    30  	//   * This method is seldom used for performance reason
    31  	//     and is generally taken over by their corresponding MatcherGroup.
    32  	Match(input string) bool
    33  }
    34  
    35  // MatcherGroup is an advanced type of matcher to accept a bunch of basic Matchers (of certain type, not all matcher types).
    36  // For example:
    37  //   - FullMatcherGroup accepts FullMatcher and uses a hash table to facilitate lookup.
    38  //   - DomainMatcherGroup accepts DomainMatcher and uses a trie to optimize both memory consumption and lookup speed.
    39  type MatcherGroup interface {
    40  	// Match returns all matched matchers with their corresponding values.
    41  	Match(input string) []uint32
    42  
    43  	// MatchAny returns true as soon as one matching matcher is found.
    44  	MatchAny(input string) bool
    45  }
    46  
    47  // IndexMatcher is a general type of matcher thats accepts all kinds of basic matchers.
    48  // It should:
    49  //   - Accept all Matcher types with no exception.
    50  //   - Optimize string matching with a combination of MatcherGroups.
    51  //   - Obey certain priority order specification when returning matched Matchers.
    52  type IndexMatcher interface {
    53  	// Size returns number of matchers added to IndexMatcher.
    54  	Size() uint32
    55  
    56  	// Add adds a new Matcher to IndexMatcher, and returns its index. The index will never be 0.
    57  	Add(matcher Matcher) uint32
    58  
    59  	// Build builds the IndexMatcher to be ready for matching.
    60  	Build() error
    61  
    62  	// Match returns the indices of all matchers that matches the input.
    63  	//   * Empty array is returned if no such matcher exists.
    64  	//   * The order of returned matchers should follow priority specification.
    65  	// Priority specification:
    66  	//   1. Priority between matcher types: full > domain > substr > regex.
    67  	//   2. Priority of same-priority matchers matching at same position: the early added takes precedence.
    68  	//   3. Priority of domain matchers matching at different levels: the further matched domain takes precedence.
    69  	//   4. Priority of substr matchers matching at different positions: the further matched substr takes precedence.
    70  	Match(input string) []uint32
    71  
    72  	// MatchAny returns true as soon as one matching matcher is found.
    73  	MatchAny(input string) bool
    74  }