Update pipeline and sidebar docs

ozontech · Nov 14, 2023 · aabf927 · aabf927
1 parent bdc5b16
commit aabf927
Show file tree

Hide file tree

Showing 5 changed files with 321 additions and 2 deletions.
diff --git a/Insanedocfile b/Insanedocfile
@@ -2,10 +2,16 @@ extractors:
   config-params: '"config-params" /json:\"([a-z_]+)\"/ #2 /default:\"([^"]+)\"/ /(required):\"true\"/  /options:\"([^"]+)\"/'
   fn-list: '"fn-list" #4 /Plugin\)\s(.+)\s{/'
   match-modes: '"match-modes" /MatchMode(.*),/ /\"(.*)\"/'
+  do-if-node: '"do-if-node" /DoIfNode(\w+)\s/'
+  do-if-field-op: '"do-if-field-op" /doIfField(\w+)OpBytes\s/'
+  do-if-logical-op: '"do-if-logical-op" /doIfLogical(\w+)Bytes\s/'
 decorators:
   config-params: '_ _ /*`%s`* / /*`default=%s`* / /*`%s`* / /*`options=%s`* /'
   fn-list: '_ _ /`%s`/'
   match-modes: '_ /%s/ /`match_mode: %s`/'
+  do-if-node: '_ /%s/'
+  do-if-field-op: '_ /%s/'
+  do-if-logical-op: '_ /%s/'
 templates:
   - template: docs/*.idoc.md
     files: ["../pipeline/*.go"]

diff --git a/_sidebar.idoc.md b/_sidebar.idoc.md
@@ -19,6 +19,10 @@
   - Output
 @global-contents-table-plugin-output|links-list
 
+- **Pipeline**
+  - [Match modes](pipeline/README.md#match-modes)
+  - [Experimental: Do If rules](pipeline/README.md#experimental-do-if-rules)
+
 - **Other**
   - [Contributing](/docs/contributing.md)
   - [License](/docs/license.md)
diff --git a/_sidebar.md b/_sidebar.md
@@ -56,6 +56,10 @@
     - [stdout](plugin/output/stdout/README.md)
 
 
+- **Pipeline**
+  - [Match modes](pipeline/README.md#match-modes)
+  - [Experimental: Do If rules](pipeline/README.md#experimental-do-if-rules)
+
 - **Other**
   - [Contributing](/docs/contributing.md)
   - [License](/docs/license.md)
diff --git a/pipeline/README.idoc.md b/pipeline/README.idoc.md
@@ -1,2 +1,24 @@
-### Match modes
+## Match modes
 @match-modes|header-description
+
+## Experimental: Do If rules
+
+This is experimental feature and represents an advanced version of `match_fields`.
+The Do If rules are a tree of nodes. The tree is stored in the Do If Checker instance.
+When Do If Checker's Match func is called it calls to the root Match func and then
+the chain of Match func calls are performed across the whole tree.
+
+### Node types
+@do-if-node|description
+
+### Field op node
+@do-if-field-op-node
+
+### Field operations
+@do-if-field-op|description
+
+### Logical op node
+@do-if-logical-op-node
+
+### Logical operations
+@do-if-logical-op|description
diff --git a/pipeline/README.md b/pipeline/README.md
@@ -1,4 +1,4 @@
-### Match modes
+## Match modes
 #### And
 `match_mode: and` — matches fields with AND operator
 
@@ -105,4 +105,287 @@ result:
 <br>
 
 
+## Experimental: Do If rules
+
+This is experimental feature and represents an advanced version of `match_fields`.
+The Do If rules are a tree of nodes. The tree is stored in the Do If Checker instance.
+When Do If Checker's Match func is called it calls to the root Match func and then
+the chain of Match func calls are performed across the whole tree.
+
+### Node types
+**`FieldOp`** Type of node where matching rules for fields are stored.
+
+<br>
+
+**`LogicalOp`** Type of node where logical rules for applying other rules are stored.
+
+<br>
+
+
+### Field op node
+DoIf field op node is considered to always be a leaf in the DoIf tree.
+It contains operation to be checked on the field value, the field name to extract data and
+the values to check against.
+
+Params:
+  - `field_op` - value from field operations list. Required.
+  - `field` - name of the field to apply operation. Required.
+  - `values` - list of values to check field. Required non-empty.
+  - `case_sensitive` - flag indicating whether checks are performed in case sensitive way. Default `true`.
+    Note: case insensitive checks can cause CPU and memory overhead since every field value will be converted to lower letters.
+
+Example:
+```yaml
+pipelines:
+  tests:
+	actions:
+	  - type: discard
+	    do_if:
+	      - field_op: suffix
+	        field: pod
+	        values: [pod-1, pod-2]
+			case_sensitive: true
+```
+
+
+### Field operations
+**`Equal`** checks whether the field value is equal to one of the elements in the values list.
+
+Example:
+```yaml
+pipelines:
+  test:
+    actions:
+      - type: discard
+        do_if:
+          - field_op: equal
+            field: pod
+            values: [test-pod-1, test-pod-2]
+```
+
+result:
+```
+{"pod":"test-pod-1","service":"test-service"}   # discarded
+{"pod":"test-pod-2","service":"test-service-2"} # discarded
+{"pod":"test-pod","service":"test-service"}     # not discarded
+{"pod":"test-pod","service":"test-service-1"}   # not discarded
+```
+
+<br>
+
+**`Contains`** checks whether the field value contains one of the elements the in values list.
+
+Example:
+```yaml
+pipelines:
+  test:
+    actions:
+      - type: discard
+        do_if:
+          - field_op: contains
+            field: pod
+            values: [my-pod, my-test]
+```
+
+result:
+```
+{"pod":"test-my-pod-1","service":"test-service"}     # discarded
+{"pod":"test-not-my-pod","service":"test-service-2"} # discarded
+{"pod":"my-test-pod","service":"test-service"}       # discarded
+{"pod":"test-pod","service":"test-service-1"}        # not discarded
+```
+
+<br>
+
+**`Prefix`** checks whether the field value has prefix equal to one of the elements in the values list.
+
+Example:
+```yaml
+pipelines:
+  test:
+    actions:
+      - type: discard
+        do_if:
+          - field_op: prefix
+            field: pod
+            values: [test-1, test-2]
+```
+
+result:
+```
+{"pod":"test-1-pod-1","service":"test-service"}   # discarded
+{"pod":"test-2-pod-2","service":"test-service-2"} # discarded
+{"pod":"test-pod","service":"test-service"}       # not discarded
+{"pod":"test-pod","service":"test-service-1"}     # not discarded
+```
+
+<br>
+
+**`Suffix`** checks whether the field value has suffix equal to one of the elements in the values list.
+
+Example:
+```yaml
+pipelines:
+  test:
+    actions:
+      - type: discard
+        do_if:
+          - field_op: suffix
+            field: pod
+            values: [pod-1, pod-2]
+```
+
+result:
+```
+{"pod":"test-1-pod-1","service":"test-service"}   # discarded
+{"pod":"test-2-pod-2","service":"test-service-2"} # discarded
+{"pod":"test-pod","service":"test-service"}       # not discarded
+{"pod":"test-pod","service":"test-service-1"}     # not discarded
+```
+
+<br>
+
+**`Regex`** checks whether the field matches any regex from the values list.
+
+Example:
+```yaml
+pipelines:
+  test:
+    actions:
+      - type: discard
+        do_if:
+          - field_op: regex
+            field: pod
+            values: [pod-\d, my-test.*]
+```
+
+result:
+```
+{"pod":"test-1-pod-1","service":"test-service"}       # discarded
+{"pod":"test-2-pod-2","service":"test-service-2"}     # discarded
+{"pod":"test-pod","service":"test-service"}           # not discarded
+{"pod":"my-test-pod","service":"test-service-1"}      # discarded
+{"pod":"my-test-instance","service":"test-service-1"} # discarded
+{"pod":"service123","service":"test-service-1"}       # not discarded
+```
+
+<br>
+
+
+### Logical op node
+DoIf logical op node is a node considered to be the root or an edge between nodes.
+It always has at least one operand which are other nodes and calls their checks
+to apply logical operation on their results.
+
+Params:
+  - `logical_op` - value from logical operations list. Required.
+  - `operands` - list of another do-if nodes. Required non-empty.
+
+Example:
+```yaml
+pipelines:
+  test:
+    actions:
+      - type: discard
+        do_if:
+          - logical_op: and
+            operands:
+              - field_op: equal
+                field: pod
+                values: [test-pod-1, test-pod-2]
+				case_sensitive: true
+              - field_op: equal
+                field: service
+                values: [test-service]
+				case_sensitive: true
+```
+
+
+### Logical operations
+**`Or`** accepts at least one operand and returns true on the first returned true from its operands.
+
+Example:
+```yaml
+pipelines:
+  test:
+    actions:
+      - type: discard
+        do_if:
+          - logical_op: or
+            operands:
+              - field_op: equal
+                field: pod
+                values: [test-pod-1, test-pod-2]
+              - field_op: equal
+                field: service
+                values: [test-service]
+```
+
+result:
+```
+{"pod":"test-pod-1","service":"test-service"}   # discarded
+{"pod":"test-pod-2","service":"test-service-2"} # discarded
+{"pod":"test-pod","service":"test-service"}     # discarded
+{"pod":"test-pod","service":"test-service-1"}   # not discarded
+```
+
+<br>
+
+**`And`** accepts at least one operand and returns true if all operands return true
+(in other words returns false on the first returned false from its operands).
+
+Example:
+```yaml
+pipelines:
+  test:
+    actions:
+      - type: discard
+        do_if:
+          - logical_op: and
+            operands:
+              - field_op: equal
+                field: pod
+                values: [test-pod-1, test-pod-2]
+              - field_op: equal
+                field: service
+                values: [test-service]
+```
+
+result:
+```
+{"pod":"test-pod-1","service":"test-service"}   # discarded
+{"pod":"test-pod-2","service":"test-service-2"} # not discarded
+{"pod":"test-pod","service":"test-service"}     # not discarded
+{"pod":"test-pod","service":"test-service-1"}   # not discarded
+```
+
+<br>
+
+**`Not`** accepts exactly one operand and returns inverted result of its operand.
+
+Example:
+```yaml
+pipelines:
+  test:
+    actions:
+      - type: discard
+        do_if:
+          - logical_op: not
+            operands:
+              - field_op: equal
+                field: service
+                values: [test-service]
+```
+
+result:
+```
+{"pod":"test-pod-1","service":"test-service"}   # not discarded
+{"pod":"test-pod-2","service":"test-service-2"} # discarded
+{"pod":"test-pod","service":"test-service"}     # not discarded
+{"pod":"test-pod","service":"test-service-1"}   # discarded
+```
+
+<br>
+
+
 <br>*Generated using [__insane-doc__](https://github.com/vitkovskii/insane-doc)*