1syntax = "proto3";
2
3package xds.type.matcher.v3;
4
5import "xds/annotations/v3/status.proto";
6import "xds/core/v3/cidr.proto";
7import "xds/type/matcher/v3/matcher.proto";
8
9import "validate/validate.proto";
10
11option java_package = "com.github.xds.type.matcher.v3";
12option java_outer_classname = "IPMatcherProto";
13option java_multiple_files = true;
14option go_package = "github.com/cncf/xds/go/xds/type/matcher/v3";
15
16option (xds.annotations.v3.file_status).work_in_progress = true;
17
18// [#protodoc-title: IP matcher]
19
20// Matches a specific IP address against a set of possibly overlapping subnets using a trie.
21message IPMatcher {
22  // Specifies a list of IP address ranges and a match action.
23  message IPRangeMatcher {
24    // A non-empty set of CIDR ranges.
25    repeated core.v3.CidrRange ranges = 1 [(validate.rules).repeated = {min_items: 1}];
26
27    // Match action to apply when the IP address is within one of the CIDR ranges.
28    Matcher.OnMatch on_match = 2;
29
30    // Indicates whether this match option should be considered if there is a
31    // more specific matcher. Exclusive matchers are not selected whenever a
32    // more specific matcher exists (e.g. matcher with a longer prefix) even
33    // when the more specific matcher fails its nested match condition.
34    // Non-exclusive matchers are considered if the more specific matcher
35    // exists but its nested match condition does not entirely match.
36    // Non-exclusive matchers are selected in the order of their specificity
37    // first (longest prefix first), then the order of declaration next.
38    //
39    // For example, consider two range matchers: an exclusive matcher *X* on
40    // ``0.0.0.0/0`` and a matcher *Y* on ``192.0.0.0/2`` with a nested match
41    // condition *Z*. For the input IP ``192.168.0.1`` matcher *Y* is the most
42    // specific. If its nested match condition *Z* does not accept the input,
43    // then the less specific matcher *X* does not apply either despite the
44    // input being within the range, because matcher *X* is exclusive.
45    //
46    // The opposite is true if matcher *X* is not marked as exclusive. In that
47    // case matcher *X* always matches whenever matcher "*Y* rejects the input.
48    bool exclusive = 3;
49  }
50
51  // Match IP address by CIDR ranges.
52  repeated IPRangeMatcher range_matchers = 1;
53}
54