From cb12bcb34f1f43ae48e1b6c0ef5ea3d248b7cd1a Mon Sep 17 00:00:00 2001 From: binarylogic Date: Tue, 2 Feb 2021 13:39:54 -0600 Subject: [PATCH 01/14] chore(remap, external docs): Document compile-time errors Signed-off-by: binarylogic --- docs/reference/remap.cue | 5 ++ docs/reference/remap/errors.cue | 20 +++++++ .../errors/100_unhandled_root_expression.cue | 41 +++++++++++++ .../errors/101_malformed_regex_literal.cue | 41 +++++++++++++ ...102_non_boolean_if_statement_predicate.cue | 46 +++++++++++++++ .../103_unhandled_fallible_assignment.cue | 57 +++++++++++++++++++ .../errors/104_unneeded_error_assignment.cue | 39 +++++++++++++ .../remap/errors/105_undefined_function.cue | 36 ++++++++++++ .../106_function_argument_arity_mismatch.cue | 36 ++++++++++++ ...107_required_function_argument_missing.cue | 36 ++++++++++++ docs/reference/remap/expressions/if.cue | 6 +- docs/reference/remap/functions.cue | 1 + 12 files changed, 361 insertions(+), 3 deletions(-) create mode 100644 docs/reference/remap/errors.cue create mode 100644 docs/reference/remap/errors/100_unhandled_root_expression.cue create mode 100644 docs/reference/remap/errors/101_malformed_regex_literal.cue create mode 100644 docs/reference/remap/errors/102_non_boolean_if_statement_predicate.cue create mode 100644 docs/reference/remap/errors/103_unhandled_fallible_assignment.cue create mode 100644 docs/reference/remap/errors/104_unneeded_error_assignment.cue create mode 100644 docs/reference/remap/errors/105_undefined_function.cue create mode 100644 docs/reference/remap/errors/106_function_argument_arity_mismatch.cue create mode 100644 docs/reference/remap/errors/107_required_function_argument_missing.cue diff --git a/docs/reference/remap.cue b/docs/reference/remap.cue index 12ab2fddf453c..dff859a446c71 100644 --- a/docs/reference/remap.cue +++ b/docs/reference/remap.cue @@ -26,6 +26,10 @@ package metadata output?: #Event } + if raises != _|_ { + diff?: string + } + notes?: [string, ...string] warnings?: [string, ...string] } @@ -34,6 +38,7 @@ package metadata concepts: _ description: string + errors: _ examples: [#Example, ...#Example] expressions: _ features: _ diff --git a/docs/reference/remap/errors.cue b/docs/reference/remap/errors.cue new file mode 100644 index 0000000000000..b12eb84956205 --- /dev/null +++ b/docs/reference/remap/errors.cue @@ -0,0 +1,20 @@ +package metadata + +import "strconv" + +remap: { + #Error: { + anchor: "#\(code)" + code: >=100 & <1000 & int + description: string + rationale: string | null + resolution: string + title: string + + examples: [remap.#Example, ...remap.#Example] + } + + errors: [Code=string]: #Error & { + code: strconv.ParseInt(Code, 0, 8) + } +} diff --git a/docs/reference/remap/errors/100_unhandled_root_expression.cue b/docs/reference/remap/errors/100_unhandled_root_expression.cue new file mode 100644 index 0000000000000..25221fed9ecda --- /dev/null +++ b/docs/reference/remap/errors/100_unhandled_root_expression.cue @@ -0,0 +1,41 @@ +package metadata + +remap: errors: "100": { + title: "Unhandled root expression" + description: """ + A root expression is effectively dead code; it does not change the result of your program. + """ + rationale: """ + Dead code is unecessary and needlessly contributes to the execution time of your program. Removing it will + make your program simpler and faster. + """ + resolution: """ + This error is usually accidental and caused by improper white-space usage. To resolve this error, use the + expression in a way that contributes to your program's result, or remove the expression. + """ + + examples: [ + { + "title": "\(title) (bad comment)" + source: #""" + # .new_key = 100 + \ + (5 / 2) + """# + raises: compiletime: #""" + error: \#(title) + ┌─ :1:1 + │ + 1 │ (5 / 2) + │ ^^^^^ + │ │ + │ this expression is unhandled + │ + """# + diff: #""" + # .new_key = 100 + \ + - (5 / 2) + +# (5 / 2) + """# + }, + ] +} diff --git a/docs/reference/remap/errors/101_malformed_regex_literal.cue b/docs/reference/remap/errors/101_malformed_regex_literal.cue new file mode 100644 index 0000000000000..64b858f99fd3a --- /dev/null +++ b/docs/reference/remap/errors/101_malformed_regex_literal.cue @@ -0,0 +1,41 @@ +package metadata + +remap: errors: "101": { + title: "Malformed regex literal" + description: """ + A [regex literal expression](\(urls.vrl_expressions)\(remap.literals.regular_expression.anchor)) is malformed + and not a valid Regular Expression. + """ + rationale: """ + Invalid regular expressions will not compile. + """ + resolution: """ + Regular expressions are difficult to write and commonly result in syntax errors. If you're parsing a common + log format then we recommend using one of VRL's [`parse_*` functions](\(urls.vrl_functions)#parsing). If + you do not see a fucntion for your format please [request it](\(urls.new_feature_request)). Otherwise, use the + [Rust regex tester](\(urls.regex_tester)) to test and correct your regular expression. + """ + + examples: [ + { + "title": "\(title) (common format)" + source: #""" + . |= parse_regex!(.message, r'^(?P[\w\.]+) - (?P[\w]+) (?P[\d]+) \[?P.*)\] "(?P[\w]+) (?P.*)" (?P[\d]+) (?P[\d]+)$') + """# + raises: compiletime: #""" + error: \#(title) + ┌─ :1:1 + │ + 1 │ . |= parse_regex(.message, r'^(?P[\w\.]+) - (?P[\w]+) (?P[\d]+) \[?P.*)\] "(?P[\w]+) (?P.*)" (?P[\d]+) (?P[\d]+)$') + │ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + │ │ + │ this regular expression is invalid + │ + """# + diff: #""" + -. |= parse_regex!(.message, r'^(?P[\w\.]+) - (?P[\w]+) (?P[\d]+) \[?P.*)\] "(?P[\w]+) (?P.*)" (?P[\d]+) (?P[\d]+)$') + +. |= parse_common_log!(.message) + """# + }, + ] +} diff --git a/docs/reference/remap/errors/102_non_boolean_if_statement_predicate.cue b/docs/reference/remap/errors/102_non_boolean_if_statement_predicate.cue new file mode 100644 index 0000000000000..2ef5a9a19f794 --- /dev/null +++ b/docs/reference/remap/errors/102_non_boolean_if_statement_predicate.cue @@ -0,0 +1,46 @@ +package metadata + +remap: errors: "102": { + title: "Non-boolean if expression predicate" + description: """ + An [if expression](\(urls.vrl_expressions)\(remap.literals.regular_expression.anchor)) predicate does not + evaluate to a boolean. + """ + rationale: """ + VRL does not implement "truthy" values (non-boolean values that resolve to a boolean, such as `1`) since these + are common foot-guns that can result in unexpected behavior when used in if expressions. This decision + contributes to VRL's [safety principle](\(urls.vrl_safety)). + """ + resolution: """ + Adjust your if expression predicate to resolve to a boolean. Helpful functions include + [`exists`](\(urls.vrl_functions)\(remap.functions.exists.anchor)). + """ + + examples: [ + { + "title": "\(title) (strings)" + input: log: message: "key=value" + source: #""" + if .message { + . |= parse_key_value!(.message) + } + """# + raises: compiletime: #""" + error: \#(title) + ┌─ :1:1 + │ + 1 │ if .message { + │ ^^^^^^^^ + │ │ + │ if expression predicates must resolve to a strict boolean + │ + """# + diff: #""" + -if .message { + +if exists(.message) { + . |= parse_key_value!(.message) + } + """# + }, + ] +} diff --git a/docs/reference/remap/errors/103_unhandled_fallible_assignment.cue b/docs/reference/remap/errors/103_unhandled_fallible_assignment.cue new file mode 100644 index 0000000000000..d637f248cfd6f --- /dev/null +++ b/docs/reference/remap/errors/103_unhandled_fallible_assignment.cue @@ -0,0 +1,57 @@ +package metadata + +remap: errors: "103": { + title: "Unhandled fallible assignment" + description: """ + The right-hand side of an [assignment expression](\(urls.vrl_expressions)\(remap.literals.regular_expression.anchor)) + can fail and the error is not being [handled](\(urls.vrl_error_handling)). + """ + rationale: """ + VRL is [fail-safe](\(urls.vrl_error_safety)) and requires that all possible runtime errors be handled. This + contributes heavily to VRL's [safety principle](\(urls.vrl_safety)). + """ + resolution: """ + Handle the error using one of the [documented error handling strategies](\(urls.vrl_error_handling)). + """ + + examples: [...{ + input: log: message: "key=value" + source: #""" + . |= parse_key_value(.message) + """# + raises: compiletime: #""" + error: \#(title) + ┌─ :1:1 + │ + 1 │ . |= parse_key_value(.message) + │ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + │ │ + │ This assingment does not handle errors + │ + """# + }] + + examples: [ + { + "title": "\(title) (coalesce)" + diff: #""" + -. |= parse_key_value(.message) + +. |= parse_key_value(.message) ?? {} + """# + }, + { + "title": "\(title) (raise & abort)" + diff: #""" + -. |= parse_key_value(.message) + +. |= parse_key_value!(.message) + """# + }, + { + "title": "\(title) (assignment)" + diff: #""" + -. |= parse_key_value(.message) + +., err |= parse_key_value(.message) + """# + }, + ] +} diff --git a/docs/reference/remap/errors/104_unneeded_error_assignment.cue b/docs/reference/remap/errors/104_unneeded_error_assignment.cue new file mode 100644 index 0000000000000..52bc6d483336f --- /dev/null +++ b/docs/reference/remap/errors/104_unneeded_error_assignment.cue @@ -0,0 +1,39 @@ +package metadata + +remap: errors: "104": { + title: "Unneeded error assignment" + description: """ + The right-hand side of an [assignment expression](\(urls.vrl_expressions)\(remap.literals.regular_expression.anchor)) + _cannot_ fail, therefore, error assignment is not required. + """ + rationale: """ + Assigning errors when one is not possible is effectively dead code that makes your program difficult to follow. + Removing the error assignment will simplify your program. + """ + resolution: """ + Remove the error assignment. + """ + + examples: [ + { + "title": "\(title) (strings)" + source: #""" + .message, err = downcase(.message) + """# + raises: compiletime: #""" + error: \#(title) + ┌─ :1:1 + │ + 1 │ .message, err = downcase(.message) + │ ^^^ + │ │ + │ unneeded error assignment + │ + """# + diff: #""" + -.message, err = downcase(.message) + +.message = downcase(.message) + """# + }, + ] +} diff --git a/docs/reference/remap/errors/105_undefined_function.cue b/docs/reference/remap/errors/105_undefined_function.cue new file mode 100644 index 0000000000000..4e6739c6a72a1 --- /dev/null +++ b/docs/reference/remap/errors/105_undefined_function.cue @@ -0,0 +1,36 @@ +package metadata + +remap: errors: "105": { + title: "Undefined function" + description: """ + A [function call expression](\(urls.vrl_expressions)\(remap.literals.regular_expression.anchor)) invokes an + unknown function. + """ + rationale: null + resolution: """ + This is typically due to a typo, correcting the function name will resolve this. + """ + + examples: [ + { + "title": "\(title) (typo)" + source: #""" + parse_keyvalue(.message) + """# + raises: compiletime: #""" + error: \#(title) + ┌─ :1:1 + │ + 1 │ parse_keyvalue(.message) + │ ^^^^^^^^^^^^^^ + │ │ + │ Undefined function + │ + """# + diff: #""" + -parse_keyvalue(.message) + +parse_key_value(.message) + """# + }, + ] +} diff --git a/docs/reference/remap/errors/106_function_argument_arity_mismatch.cue b/docs/reference/remap/errors/106_function_argument_arity_mismatch.cue new file mode 100644 index 0000000000000..30506b6999b93 --- /dev/null +++ b/docs/reference/remap/errors/106_function_argument_arity_mismatch.cue @@ -0,0 +1,36 @@ +package metadata + +remap: errors: "106": { + title: "Function argument arity mismatch" + description: """ + A [function call expression](\(urls.vrl_expressions)\(remap.literals.regular_expression.anchor)) invokes a + function with too many arguments. + """ + rationale: null + resolution: """ + Remove the extra arguments to adhere to the function's documented signature. + """ + + examples: [ + { + "title": "\(title)" + source: #""" + parse_json(.message, pretty: true) + """# + raises: compiletime: #""" + error: \#(title) + ┌─ :1:1 + │ + 1 │ parse_json(.message, pretty: true) + │ ^^^^^^^^^^^^ + │ │ + │ This argument exceeds the function arity + │ + """# + diff: #""" + -parse_json(.message, pretty: true) + +parse_json(.message) + """# + }, + ] +} diff --git a/docs/reference/remap/errors/107_required_function_argument_missing.cue b/docs/reference/remap/errors/107_required_function_argument_missing.cue new file mode 100644 index 0000000000000..1c3a7b5c4fa92 --- /dev/null +++ b/docs/reference/remap/errors/107_required_function_argument_missing.cue @@ -0,0 +1,36 @@ +package metadata + +remap: errors: "107": { + title: "Required function argument missing" + description: """ + A [function call expression](\(urls.vrl_expressions)\(remap.literals.regular_expression.anchor)) fails to pass + a required argument. + """ + rationale: null + resolution: """ + Supply all required function arguments to adhere to the function's documented signature. + """ + + examples: [ + { + "title": "\(title)" + source: #""" + parse_timestamp(.timestamp) + """# + raises: compiletime: #""" + error: \#(title) + ┌─ :1:1 + │ + 1 │ parse_timestamp(.timestamp) + │ ^^^^^^^^^^^^^^^^^^^^^^^^^^ + │ │ + │ The required `format` argument is missing + │ + """# + diff: #""" + -parse_timestamp(.timestamp) + +parse_timestamp(.timestamp, "%D") + """# + }, + ] +} diff --git a/docs/reference/remap/expressions/if.cue b/docs/reference/remap/expressions/if.cue index a40241dc58fd9..49195d713ccf0 100644 --- a/docs/reference/remap/expressions/if.cue +++ b/docs/reference/remap/expressions/if.cue @@ -13,12 +13,12 @@ remap: expressions: if: { grammar: { source: """ - "if" ~ boolean_expression ~ block ~ ("else if" ~ boolean_expression ~ block)* ~ ("else" ~ block)? + "if" ~ predicate ~ block ~ ("else if" ~ predicate ~ block)* ~ ("else" ~ block)? """ definitions: { - boolean_expression: { + predicate: { description: """ - The `boolean_expression` must be an expression that resolves to a boolean. If a boolean is not + The `predicate` _must_ be an expression that resolves to a boolean. If a boolean is not returned a compile-time error will be raised. """ } diff --git a/docs/reference/remap/functions.cue b/docs/reference/remap/functions.cue index 91bf994189d0d..cbec5824b7cb1 100644 --- a/docs/reference/remap/functions.cue +++ b/docs/reference/remap/functions.cue @@ -12,6 +12,7 @@ remap: { } #Function: { + anchor: "#\(name)" name: string category: #FunctionCategory description: string From ef3902f9d148df17942df542f7b22d3806f014d9 Mon Sep 17 00:00:00 2001 From: binarylogic Date: Tue, 2 Feb 2021 15:21:49 -0600 Subject: [PATCH 02/14] Add remaining errors Signed-off-by: binarylogic --- .../errors/100_unhandled_root_expression.cue | 2 +- .../errors/101_malformed_regex_literal.cue | 2 +- ...102_non_boolean_if_statement_predicate.cue | 8 ++- .../103_unhandled_fallible_assignment.cue | 3 +- .../errors/104_unneeded_error_assignment.cue | 4 +- .../108_unknown_function_argument_keyword.cue | 36 +++++++++++ .../errors/109_cannot_abort_function.cue | 37 ++++++++++++ .../errors/110_invalid_argument_type.cue | 59 +++++++++++++++++++ 8 files changed, 143 insertions(+), 8 deletions(-) create mode 100644 docs/reference/remap/errors/108_unknown_function_argument_keyword.cue create mode 100644 docs/reference/remap/errors/109_cannot_abort_function.cue create mode 100644 docs/reference/remap/errors/110_invalid_argument_type.cue diff --git a/docs/reference/remap/errors/100_unhandled_root_expression.cue b/docs/reference/remap/errors/100_unhandled_root_expression.cue index 25221fed9ecda..a762421eadf3c 100644 --- a/docs/reference/remap/errors/100_unhandled_root_expression.cue +++ b/docs/reference/remap/errors/100_unhandled_root_expression.cue @@ -3,7 +3,7 @@ package metadata remap: errors: "100": { title: "Unhandled root expression" description: """ - A root expression is effectively dead code; it does not change the result of your program. + A unhandled root expression is effectively dead code; it does not contribute the result of your program. """ rationale: """ Dead code is unecessary and needlessly contributes to the execution time of your program. Removing it will diff --git a/docs/reference/remap/errors/101_malformed_regex_literal.cue b/docs/reference/remap/errors/101_malformed_regex_literal.cue index 64b858f99fd3a..7c006732b446f 100644 --- a/docs/reference/remap/errors/101_malformed_regex_literal.cue +++ b/docs/reference/remap/errors/101_malformed_regex_literal.cue @@ -4,7 +4,7 @@ remap: errors: "101": { title: "Malformed regex literal" description: """ A [regex literal expression](\(urls.vrl_expressions)\(remap.literals.regular_expression.anchor)) is malformed - and not a valid Regular Expression. + and does not result in a valid Regular Expression. """ rationale: """ Invalid regular expressions will not compile. diff --git a/docs/reference/remap/errors/102_non_boolean_if_statement_predicate.cue b/docs/reference/remap/errors/102_non_boolean_if_statement_predicate.cue index 2ef5a9a19f794..e451f6918a813 100644 --- a/docs/reference/remap/errors/102_non_boolean_if_statement_predicate.cue +++ b/docs/reference/remap/errors/102_non_boolean_if_statement_predicate.cue @@ -9,11 +9,13 @@ remap: errors: "102": { rationale: """ VRL does not implement "truthy" values (non-boolean values that resolve to a boolean, such as `1`) since these are common foot-guns that can result in unexpected behavior when used in if expressions. This decision - contributes to VRL's [safety principle](\(urls.vrl_safety)). + contributes to VRL's [safety principle](\(urls.vrl_safety)), ensuring that VRL programs are reliable once + deployed. """ resolution: """ - Adjust your if expression predicate to resolve to a boolean. Helpful functions include - [`exists`](\(urls.vrl_functions)\(remap.functions.exists.anchor)). + Adjust your if expression predicate to resolve to a boolean. Helpful functions to solve this include + [`exists`](\(urls.vrl_functions)\(remap.functions.exists.anchor)) and + [`is_nullish`](\(urls.vrl_functions)\(remap.functions.is_nullish.anchor)). """ examples: [ diff --git a/docs/reference/remap/errors/103_unhandled_fallible_assignment.cue b/docs/reference/remap/errors/103_unhandled_fallible_assignment.cue index d637f248cfd6f..55e921a08d2ad 100644 --- a/docs/reference/remap/errors/103_unhandled_fallible_assignment.cue +++ b/docs/reference/remap/errors/103_unhandled_fallible_assignment.cue @@ -8,7 +8,8 @@ remap: errors: "103": { """ rationale: """ VRL is [fail-safe](\(urls.vrl_error_safety)) and requires that all possible runtime errors be handled. This - contributes heavily to VRL's [safety principle](\(urls.vrl_safety)). + contributes heavily to VRL's [safety principle](\(urls.vrl_safety)), ensuring that VRL programs are reliable + once deployed. """ resolution: """ Handle the error using one of the [documented error handling strategies](\(urls.vrl_error_handling)). diff --git a/docs/reference/remap/errors/104_unneeded_error_assignment.cue b/docs/reference/remap/errors/104_unneeded_error_assignment.cue index 52bc6d483336f..89df0c57b4aae 100644 --- a/docs/reference/remap/errors/104_unneeded_error_assignment.cue +++ b/docs/reference/remap/errors/104_unneeded_error_assignment.cue @@ -3,8 +3,8 @@ package metadata remap: errors: "104": { title: "Unneeded error assignment" description: """ - The right-hand side of an [assignment expression](\(urls.vrl_expressions)\(remap.literals.regular_expression.anchor)) - _cannot_ fail, therefore, error assignment is not required. + The left-hand side of an [assignment expression](\(urls.vrl_expressions)\(remap.literals.regular_expression.anchor)) + needlessly handles errors when the right-hand side _cannot_ fail. """ rationale: """ Assigning errors when one is not possible is effectively dead code that makes your program difficult to follow. diff --git a/docs/reference/remap/errors/108_unknown_function_argument_keyword.cue b/docs/reference/remap/errors/108_unknown_function_argument_keyword.cue new file mode 100644 index 0000000000000..8201f0a1d00ce --- /dev/null +++ b/docs/reference/remap/errors/108_unknown_function_argument_keyword.cue @@ -0,0 +1,36 @@ +package metadata + +remap: errors: "108": { + title: "Unknown function argument keyword" + description: """ + A [function call expression](\(urls.vrl_expressions)\(remap.literals.regular_expression.anchor)) passes an + unknown named argument. + """ + rationale: null + resolution: """ + Correct the name to align with the documented argument names for the function. + """ + + examples: [ + { + "title": "\(title)" + source: #""" + parse_timestamp(.timestamp, fmt: "%D") + """# + raises: compiletime: #""" + error: \#(title) + ┌─ :1:1 + │ + 1 │ parse_timestamp(.timestamp, fmt: "%D") + │ ^^^ + │ │ + │ The `fmt` argument is unknown + │ + """# + diff: #""" + -parse_timestamp(.timestamp) + +parse_timestamp(.timestamp, "%D") + """# + }, + ] +} diff --git a/docs/reference/remap/errors/109_cannot_abort_function.cue b/docs/reference/remap/errors/109_cannot_abort_function.cue new file mode 100644 index 0000000000000..e25bd57e0107b --- /dev/null +++ b/docs/reference/remap/errors/109_cannot_abort_function.cue @@ -0,0 +1,37 @@ +package metadata + +remap: errors: "109": { + title: "Cannot abort function" + description: """ + A [function call expression](\(urls.vrl_expressions)\(remap.literals.regular_expression.anchor)) cannot end + with `!` unless it _fallible_. If a function does not error, then it will not have an abort variant that ends + with `!`. + """ + rationale: null + resolution: """ + Remove the `!` from the end of the function name. + """ + + examples: [ + { + "title": "\(title)" + source: #""" + downcase!(.message) + """# + raises: compiletime: #""" + error: \#(title) + ┌─ :1:1 + │ + 1 │ downcase!(.message) + │ ^ + │ │ + │ This function is not fallible + │ + """# + diff: #""" + -downcase!(.message) + +downcase(.message) + """# + }, + ] +} diff --git a/docs/reference/remap/errors/110_invalid_argument_type.cue b/docs/reference/remap/errors/110_invalid_argument_type.cue new file mode 100644 index 0000000000000..33c28616350fd --- /dev/null +++ b/docs/reference/remap/errors/110_invalid_argument_type.cue @@ -0,0 +1,59 @@ +package metadata + +remap: errors: "110": { + title: "Invalid argument type" + description: """ + An argument passed to a [function call expression](\(urls.vrl_expressions)\(remap.literals.regular_expression.anchor)) + is not a supported type. + """ + rationale: """ + VRL is [type-safe](\(urls.vrl_type_safety)) and requires that types align upon compilation. This contributes + heavily to VRL's [safety principle](\(urls.vrl_safety)), ensuring that VRL programs are reliable once deployed. + """ + resolution: #""" + You must guarantee the type of the variable by using the appropriate [type](\(urls.vrl_functions)#type) or + [coercion](\(urls.vrl_functions)#coerce) function. + """# + + examples: [...{ + source: #""" + downcase(.message) + """# + raises: compiletime: #""" + error: \#(title) + ┌─ :1:1 + │ + 1 │ downcase(.message) + │ ^^^^^^^^ + │ │ + │ this expression resolves to unknown type + | but the parameter "value" expects the exact type "string" + │ + """# + }] + + examples: [ + { + "title": "\(title) (guard with defaults)" + diff: #""" + +.message = string(.message) ?? "" + downcase(.message) + """# + }, + { + "title": "\(title) (guard with errors)" + diff: #""" + +string!(.message) + downcase(.message) + """# + }, + { + "title": "\(title) (guard with if expressions)" + diff: #""" + +if is_string(.message) { + downcase(.message) + + } + """# + }, + ] +} From 4185036da753666bcc9c8c6987f77fae482a6321 Mon Sep 17 00:00:00 2001 From: binarylogic Date: Tue, 2 Feb 2021 17:21:32 -0600 Subject: [PATCH 03/14] Fix VRL type safety link Signed-off-by: binarylogic --- docs/reference/remap/concepts/function.cue | 2 +- .../remap/errors/103_unhandled_fallible_assignment.cue | 2 +- docs/reference/urls.cue | 4 +++- 3 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/reference/remap/concepts/function.cue b/docs/reference/remap/concepts/function.cue index bb184237a70d3..714af2a8167e7 100644 --- a/docs/reference/remap/concepts/function.cue +++ b/docs/reference/remap/concepts/function.cue @@ -11,7 +11,7 @@ remap: concepts: function: { fallibility: { title: "Fallibility" description: """ - Of particular note for functions is fallibility. [Error-safety](\(urls.vrl_error_safety)) is a defining + Of particular note for functions is fallibility. [Fail-safety](\(urls.vrl_fail_safety)) is a defining characteristic of VRL and function fallibility is core to achieving that feature. """ } diff --git a/docs/reference/remap/errors/103_unhandled_fallible_assignment.cue b/docs/reference/remap/errors/103_unhandled_fallible_assignment.cue index 55e921a08d2ad..72828039c73c0 100644 --- a/docs/reference/remap/errors/103_unhandled_fallible_assignment.cue +++ b/docs/reference/remap/errors/103_unhandled_fallible_assignment.cue @@ -7,7 +7,7 @@ remap: errors: "103": { can fail and the error is not being [handled](\(urls.vrl_error_handling)). """ rationale: """ - VRL is [fail-safe](\(urls.vrl_error_safety)) and requires that all possible runtime errors be handled. This + VRL is [fail-safe](\(urls.vrl_fail_safety)) and requires that all possible runtime errors be handled. This contributes heavily to VRL's [safety principle](\(urls.vrl_safety)), ensuring that VRL programs are reliable once deployed. """ diff --git a/docs/reference/urls.cue b/docs/reference/urls.cue index af935f33faa68..b9dd36e5f6a56 100644 --- a/docs/reference/urls.cue +++ b/docs/reference/urls.cue @@ -482,8 +482,9 @@ urls: { vrl_announcement: "\(vector_website)/blog/vector-remap-language" vrl_error_handling: "\(vrl_errors_reference)#handling" vrl_errors_reference: "\(vrl_reference)errors/" - vrl_error_safety: "\(vrl_intro)#error_safety" + vrl_fail_safety: "\(vrl_intro)#fail-safety" vrl_expressions: "\(vrl_reference)expressions/" + vrl_fail_safety: "\(vrl_intro)#fail-safety" vrl_features: "\(vrl_intro)#features" vrl_functions: "\(vrl_reference)functions/" vrl_intro: "\(vrl_reference)introduction/" @@ -493,6 +494,7 @@ urls: { vrl_performance: "\(vector_website)/docs/reference/vrl/#performance" vrl_reference: "\(vector_website)/docs/reference/vrl/" vrl_safety: "\(vector_website)/docs/reference/vrl/#safety" + vrl_type_safety: "\(vrl_intro)#type-safety" vote_feature: "\(vector_repo)/issues?q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc+label%3A%22Type%3A+New+Feature%22" wasm: "https://webassembly.org/" wasm_languages: "\(github)/appcypher/awesome-wasm-langs" From adc037b67dd4831875974a95e43937221c1a99a4 Mon Sep 17 00:00:00 2001 From: binarylogic Date: Tue, 2 Feb 2021 20:44:29 -0600 Subject: [PATCH 04/14] Remove hash from anchors Signed-off-by: binarylogic --- docs/reference/remap.cue | 2 +- docs/reference/remap/concepts.cue | 2 +- docs/reference/remap/concepts/program.cue | 2 +- docs/reference/remap/errors.cue | 2 +- docs/reference/remap/errors/101_malformed_regex_literal.cue | 2 +- .../remap/errors/102_non_boolean_if_statement_predicate.cue | 6 +++--- .../remap/errors/103_unhandled_fallible_assignment.cue | 2 +- .../remap/errors/104_unneeded_error_assignment.cue | 2 +- docs/reference/remap/errors/105_undefined_function.cue | 2 +- .../remap/errors/106_function_argument_arity_mismatch.cue | 2 +- .../remap/errors/107_required_function_argument_missing.cue | 2 +- .../remap/errors/108_unknown_function_argument_keyword.cue | 2 +- docs/reference/remap/errors/109_cannot_abort_function.cue | 2 +- docs/reference/remap/errors/110_invalid_argument_type.cue | 2 +- docs/reference/remap/expressions.cue | 2 +- docs/reference/remap/features.cue | 2 +- docs/reference/remap/features/compilation.cue | 4 ++-- docs/reference/remap/features/ergonomic_safety.cue | 2 +- docs/reference/remap/features/type_safety.cue | 4 ++-- docs/reference/remap/functions.cue | 2 +- docs/reference/remap/literals.cue | 2 +- docs/reference/remap/principles.cue | 2 +- 22 files changed, 26 insertions(+), 26 deletions(-) diff --git a/docs/reference/remap.cue b/docs/reference/remap.cue index dff859a446c71..87a8802428a0f 100644 --- a/docs/reference/remap.cue +++ b/docs/reference/remap.cue @@ -2,7 +2,7 @@ package metadata #Remap: { #Characteristic: { - anchor: "#\(name)" + anchor: name name: string title: string description: string diff --git a/docs/reference/remap/concepts.cue b/docs/reference/remap/concepts.cue index df9ec3c230242..ce86c6d3f3987 100644 --- a/docs/reference/remap/concepts.cue +++ b/docs/reference/remap/concepts.cue @@ -2,7 +2,7 @@ package metadata remap: { #Concept: { - anchor: "#\(name)" + anchor: name name: string title: string description: string diff --git a/docs/reference/remap/concepts/program.cue b/docs/reference/remap/concepts/program.cue index 91eddd57fca41..e00f4634732ff 100644 --- a/docs/reference/remap/concepts/program.cue +++ b/docs/reference/remap/concepts/program.cue @@ -2,6 +2,6 @@ remap: concepts: program: { title: "Program" description: """ A VRL program is the highest-level concept. It is the end result of combining - [expressions](\(concepts.expression.anchor)). + [expressions](#\(concepts.expression.anchor)). """ } diff --git a/docs/reference/remap/errors.cue b/docs/reference/remap/errors.cue index b12eb84956205..ed180943fbdcd 100644 --- a/docs/reference/remap/errors.cue +++ b/docs/reference/remap/errors.cue @@ -4,7 +4,7 @@ import "strconv" remap: { #Error: { - anchor: "#\(code)" + anchor: "\(code)" code: >=100 & <1000 & int description: string rationale: string | null diff --git a/docs/reference/remap/errors/101_malformed_regex_literal.cue b/docs/reference/remap/errors/101_malformed_regex_literal.cue index 7c006732b446f..f14bcc82825b6 100644 --- a/docs/reference/remap/errors/101_malformed_regex_literal.cue +++ b/docs/reference/remap/errors/101_malformed_regex_literal.cue @@ -3,7 +3,7 @@ package metadata remap: errors: "101": { title: "Malformed regex literal" description: """ - A [regex literal expression](\(urls.vrl_expressions)\(remap.literals.regular_expression.anchor)) is malformed + A [regex literal expression](\(urls.vrl_expressions)#\(remap.literals.regular_expression.anchor)) is malformed and does not result in a valid Regular Expression. """ rationale: """ diff --git a/docs/reference/remap/errors/102_non_boolean_if_statement_predicate.cue b/docs/reference/remap/errors/102_non_boolean_if_statement_predicate.cue index e451f6918a813..f92d3ed107471 100644 --- a/docs/reference/remap/errors/102_non_boolean_if_statement_predicate.cue +++ b/docs/reference/remap/errors/102_non_boolean_if_statement_predicate.cue @@ -3,7 +3,7 @@ package metadata remap: errors: "102": { title: "Non-boolean if expression predicate" description: """ - An [if expression](\(urls.vrl_expressions)\(remap.literals.regular_expression.anchor)) predicate does not + An [if expression](\(urls.vrl_expressions)#\(remap.literals.regular_expression.anchor)) predicate does not evaluate to a boolean. """ rationale: """ @@ -14,8 +14,8 @@ remap: errors: "102": { """ resolution: """ Adjust your if expression predicate to resolve to a boolean. Helpful functions to solve this include - [`exists`](\(urls.vrl_functions)\(remap.functions.exists.anchor)) and - [`is_nullish`](\(urls.vrl_functions)\(remap.functions.is_nullish.anchor)). + [`exists`](\(urls.vrl_functions)#\(remap.functions.exists.anchor)) and + [`is_nullish`](\(urls.vrl_functions)#\(remap.functions.is_nullish.anchor)). """ examples: [ diff --git a/docs/reference/remap/errors/103_unhandled_fallible_assignment.cue b/docs/reference/remap/errors/103_unhandled_fallible_assignment.cue index 72828039c73c0..12777444093a9 100644 --- a/docs/reference/remap/errors/103_unhandled_fallible_assignment.cue +++ b/docs/reference/remap/errors/103_unhandled_fallible_assignment.cue @@ -3,7 +3,7 @@ package metadata remap: errors: "103": { title: "Unhandled fallible assignment" description: """ - The right-hand side of an [assignment expression](\(urls.vrl_expressions)\(remap.literals.regular_expression.anchor)) + The right-hand side of an [assignment expression](\(urls.vrl_expressions)#\(remap.literals.regular_expression.anchor)) can fail and the error is not being [handled](\(urls.vrl_error_handling)). """ rationale: """ diff --git a/docs/reference/remap/errors/104_unneeded_error_assignment.cue b/docs/reference/remap/errors/104_unneeded_error_assignment.cue index 89df0c57b4aae..c2ef153283608 100644 --- a/docs/reference/remap/errors/104_unneeded_error_assignment.cue +++ b/docs/reference/remap/errors/104_unneeded_error_assignment.cue @@ -3,7 +3,7 @@ package metadata remap: errors: "104": { title: "Unneeded error assignment" description: """ - The left-hand side of an [assignment expression](\(urls.vrl_expressions)\(remap.literals.regular_expression.anchor)) + The left-hand side of an [assignment expression](\(urls.vrl_expressions)#\(remap.literals.regular_expression.anchor)) needlessly handles errors when the right-hand side _cannot_ fail. """ rationale: """ diff --git a/docs/reference/remap/errors/105_undefined_function.cue b/docs/reference/remap/errors/105_undefined_function.cue index 4e6739c6a72a1..e852cbe9d58c8 100644 --- a/docs/reference/remap/errors/105_undefined_function.cue +++ b/docs/reference/remap/errors/105_undefined_function.cue @@ -3,7 +3,7 @@ package metadata remap: errors: "105": { title: "Undefined function" description: """ - A [function call expression](\(urls.vrl_expressions)\(remap.literals.regular_expression.anchor)) invokes an + A [function call expression](\(urls.vrl_expressions)#\(remap.literals.regular_expression.anchor)) invokes an unknown function. """ rationale: null diff --git a/docs/reference/remap/errors/106_function_argument_arity_mismatch.cue b/docs/reference/remap/errors/106_function_argument_arity_mismatch.cue index 30506b6999b93..883f559e74f5c 100644 --- a/docs/reference/remap/errors/106_function_argument_arity_mismatch.cue +++ b/docs/reference/remap/errors/106_function_argument_arity_mismatch.cue @@ -3,7 +3,7 @@ package metadata remap: errors: "106": { title: "Function argument arity mismatch" description: """ - A [function call expression](\(urls.vrl_expressions)\(remap.literals.regular_expression.anchor)) invokes a + A [function call expression](\(urls.vrl_expressions)#\(remap.literals.regular_expression.anchor)) invokes a function with too many arguments. """ rationale: null diff --git a/docs/reference/remap/errors/107_required_function_argument_missing.cue b/docs/reference/remap/errors/107_required_function_argument_missing.cue index 1c3a7b5c4fa92..78cd8101f98ff 100644 --- a/docs/reference/remap/errors/107_required_function_argument_missing.cue +++ b/docs/reference/remap/errors/107_required_function_argument_missing.cue @@ -3,7 +3,7 @@ package metadata remap: errors: "107": { title: "Required function argument missing" description: """ - A [function call expression](\(urls.vrl_expressions)\(remap.literals.regular_expression.anchor)) fails to pass + A [function call expression](\(urls.vrl_expressions)#\(remap.literals.regular_expression.anchor)) fails to pass a required argument. """ rationale: null diff --git a/docs/reference/remap/errors/108_unknown_function_argument_keyword.cue b/docs/reference/remap/errors/108_unknown_function_argument_keyword.cue index 8201f0a1d00ce..947f47ab3df47 100644 --- a/docs/reference/remap/errors/108_unknown_function_argument_keyword.cue +++ b/docs/reference/remap/errors/108_unknown_function_argument_keyword.cue @@ -3,7 +3,7 @@ package metadata remap: errors: "108": { title: "Unknown function argument keyword" description: """ - A [function call expression](\(urls.vrl_expressions)\(remap.literals.regular_expression.anchor)) passes an + A [function call expression](\(urls.vrl_expressions)#\(remap.literals.regular_expression.anchor)) passes an unknown named argument. """ rationale: null diff --git a/docs/reference/remap/errors/109_cannot_abort_function.cue b/docs/reference/remap/errors/109_cannot_abort_function.cue index e25bd57e0107b..6f9cf6480e5fb 100644 --- a/docs/reference/remap/errors/109_cannot_abort_function.cue +++ b/docs/reference/remap/errors/109_cannot_abort_function.cue @@ -3,7 +3,7 @@ package metadata remap: errors: "109": { title: "Cannot abort function" description: """ - A [function call expression](\(urls.vrl_expressions)\(remap.literals.regular_expression.anchor)) cannot end + A [function call expression](\(urls.vrl_expressions)#\(remap.literals.regular_expression.anchor)) cannot end with `!` unless it _fallible_. If a function does not error, then it will not have an abort variant that ends with `!`. """ diff --git a/docs/reference/remap/errors/110_invalid_argument_type.cue b/docs/reference/remap/errors/110_invalid_argument_type.cue index 33c28616350fd..36fed0cd6559b 100644 --- a/docs/reference/remap/errors/110_invalid_argument_type.cue +++ b/docs/reference/remap/errors/110_invalid_argument_type.cue @@ -3,7 +3,7 @@ package metadata remap: errors: "110": { title: "Invalid argument type" description: """ - An argument passed to a [function call expression](\(urls.vrl_expressions)\(remap.literals.regular_expression.anchor)) + An argument passed to a [function call expression](\(urls.vrl_expressions)#\(remap.literals.regular_expression.anchor)) is not a supported type. """ rationale: """ diff --git a/docs/reference/remap/expressions.cue b/docs/reference/remap/expressions.cue index 7743cde5e1886..8fa38b7fd51f5 100644 --- a/docs/reference/remap/expressions.cue +++ b/docs/reference/remap/expressions.cue @@ -2,7 +2,7 @@ package metadata remap: { #Expression: { - anchor: "#\(name)" + anchor: name name: string title: string description: string diff --git a/docs/reference/remap/features.cue b/docs/reference/remap/features.cue index 1325401fde609..897aa80559516 100644 --- a/docs/reference/remap/features.cue +++ b/docs/reference/remap/features.cue @@ -2,7 +2,7 @@ package metadata remap: { #Feature: { - anchor: "#\(name)" + anchor: name name: string title: string description: string diff --git a/docs/reference/remap/features/compilation.cue b/docs/reference/remap/features/compilation.cue index c1438c2c4823b..e631f6eb03676 100644 --- a/docs/reference/remap/features/compilation.cue +++ b/docs/reference/remap/features/compilation.cue @@ -14,7 +14,7 @@ remap: features: compilation: { fail_safety_checks: { title: "Fail-safety checks" description: """ - At compile-time, Vector will perform [fail-safety](\(features.fail_safety.anchor)) checks to ensure all + At compile-time, Vector will perform [fail-safety](#\(features.fail_safety.anchor)) checks to ensure all possible errors are handled. For example, failing to pase a string with the `parse_syslog` function. This forces you to [handle errors](\(urls.vrl_error_handling)), explicitly deciding what to do in the event of malformed data instead of being surprised by them after deploying Vector. @@ -24,7 +24,7 @@ remap: features: compilation: { type_safety_checks: { title: "Type-safety checks" description: """ - At compile-time, Vector will perform [type-safety](\(features.type_safety.anchor)) checks to catch runtime + At compile-time, Vector will perform [type-safety](#\(features.type_safety.anchor)) checks to catch runtime errors due to type mismatches. For example, passing an integer to the `parse_syslog` function. This not only protects against human error while writing the program, but also malformed data that deviates from expected types. This makes it easy to forgo transformation and route malformed data for easy inspection. diff --git a/docs/reference/remap/features/ergonomic_safety.cue b/docs/reference/remap/features/ergonomic_safety.cue index 92b14a4a4c2c3..0b66b8c818ac9 100644 --- a/docs/reference/remap/features/ergonomic_safety.cue +++ b/docs/reference/remap/features/ergonomic_safety.cue @@ -2,7 +2,7 @@ remap: features: ergonomic_safety: { title: "Ergonomic-safety" description: """ VRL is ergonomically safe, preventing the production of slow and unmaintainable VRL programs. While VRL's - [compile-time checks](\(features.compilation.anchor)) prevent runtime errors, they do not prevent more + [compile-time checks](#\(features.compilation.anchor)) prevent runtime errors, they do not prevent more ellusive problems that result from program complexity, like performance or maintainability problems. These are pernicious problems that result in pipeline instability and high cost. To protect against this, VRL is *intentionally* designed with the thoughtful ergonomics that come in the form of limitations. diff --git a/docs/reference/remap/features/type_safety.cue b/docs/reference/remap/features/type_safety.cue index 456e7f5f29b00..cadf5ad632bf8 100644 --- a/docs/reference/remap/features/type_safety.cue +++ b/docs/reference/remap/features/type_safety.cue @@ -1,8 +1,8 @@ remap: features: type_safety: { title: "Type-safety" description: """ - VRL implements [_progressive_](\(characteristics.progressive.anchor)) [type safety](\(urls.type_safety)), - erroring at [compilation-time](\(features.compilation.anchor)) if a type mismatch is detected. + VRL implements [_progressive_](#\(characteristics.progressive.anchor)) [type safety](\(urls.type_safety)), + erroring at [compilation-time](#\(features.compilation.anchor)) if a type mismatch is detected. """ principles: { diff --git a/docs/reference/remap/functions.cue b/docs/reference/remap/functions.cue index cbec5824b7cb1..7c77fbc6eee92 100644 --- a/docs/reference/remap/functions.cue +++ b/docs/reference/remap/functions.cue @@ -12,7 +12,7 @@ remap: { } #Function: { - anchor: "#\(name)" + anchor: name name: string category: #FunctionCategory description: string diff --git a/docs/reference/remap/literals.cue b/docs/reference/remap/literals.cue index e2fd331d30f6c..7e504e770a1db 100644 --- a/docs/reference/remap/literals.cue +++ b/docs/reference/remap/literals.cue @@ -2,7 +2,7 @@ package metadata remap: { #Literal: { - anchor: "#\(name)" + anchor: name name: string title: string description: string diff --git a/docs/reference/remap/principles.cue b/docs/reference/remap/principles.cue index f92cbfa3903f3..db606179dc26d 100644 --- a/docs/reference/remap/principles.cue +++ b/docs/reference/remap/principles.cue @@ -2,7 +2,7 @@ package metadata remap: { #Principle: { - anchor: "#\(name)" + anchor: name name: string title: string description: string From 00d0e5c2ca5f264c04e9ba5a4720d30c0a52a404 Mon Sep 17 00:00:00 2001 From: binarylogic Date: Tue, 2 Feb 2021 21:18:44 -0600 Subject: [PATCH 05/14] Fix logical title Signed-off-by: binarylogic --- docs/reference/remap/expressions/logical.cue | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/remap/expressions/logical.cue b/docs/reference/remap/expressions/logical.cue index 6aac3c6dcc6d3..7bf3891b7446e 100644 --- a/docs/reference/remap/expressions/logical.cue +++ b/docs/reference/remap/expressions/logical.cue @@ -1,7 +1,7 @@ package metadata remap: expressions: logical: { - title: "Assignment" + title: "Logical" description: """ A _logical_ expression compares two expressions (operands), short-circuiting on the last expression evaluated as defined by the operator. From 58286327ad03afced35d50b440250170fa8a31ec Mon Sep 17 00:00:00 2001 From: Binary Logic Date: Wed, 3 Feb 2021 08:45:05 -0600 Subject: [PATCH 06/14] Update docs/reference/remap/errors/101_malformed_regex_literal.cue Co-authored-by: Pablo Sichert --- docs/reference/remap/errors/101_malformed_regex_literal.cue | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/remap/errors/101_malformed_regex_literal.cue b/docs/reference/remap/errors/101_malformed_regex_literal.cue index f14bcc82825b6..6009182a2a1b0 100644 --- a/docs/reference/remap/errors/101_malformed_regex_literal.cue +++ b/docs/reference/remap/errors/101_malformed_regex_literal.cue @@ -4,7 +4,7 @@ remap: errors: "101": { title: "Malformed regex literal" description: """ A [regex literal expression](\(urls.vrl_expressions)#\(remap.literals.regular_expression.anchor)) is malformed - and does not result in a valid Regular Expression. + and does not result in a valid regular expression. """ rationale: """ Invalid regular expressions will not compile. From 8e96ddd4e8f64cde5bdd9ac32addef948abd6483 Mon Sep 17 00:00:00 2001 From: binarylogic Date: Wed, 3 Feb 2021 09:07:53 -0600 Subject: [PATCH 07/14] Fix root unhandled error Signed-off-by: binarylogic --- .../errors/100_unhandled_root_expression.cue | 41 ------------------- .../100_unhandled_root_runtime_error.cue | 41 +++++++++++++++++++ ...03_unhandled_assignment_runtime_error.cue} | 15 ++++--- docs/reference/urls.cue | 20 +++++---- 4 files changed, 61 insertions(+), 56 deletions(-) delete mode 100644 docs/reference/remap/errors/100_unhandled_root_expression.cue create mode 100644 docs/reference/remap/errors/100_unhandled_root_runtime_error.cue rename docs/reference/remap/errors/{103_unhandled_fallible_assignment.cue => 103_unhandled_assignment_runtime_error.cue} (68%) diff --git a/docs/reference/remap/errors/100_unhandled_root_expression.cue b/docs/reference/remap/errors/100_unhandled_root_expression.cue deleted file mode 100644 index a762421eadf3c..0000000000000 --- a/docs/reference/remap/errors/100_unhandled_root_expression.cue +++ /dev/null @@ -1,41 +0,0 @@ -package metadata - -remap: errors: "100": { - title: "Unhandled root expression" - description: """ - A unhandled root expression is effectively dead code; it does not contribute the result of your program. - """ - rationale: """ - Dead code is unecessary and needlessly contributes to the execution time of your program. Removing it will - make your program simpler and faster. - """ - resolution: """ - This error is usually accidental and caused by improper white-space usage. To resolve this error, use the - expression in a way that contributes to your program's result, or remove the expression. - """ - - examples: [ - { - "title": "\(title) (bad comment)" - source: #""" - # .new_key = 100 + \ - (5 / 2) - """# - raises: compiletime: #""" - error: \#(title) - ┌─ :1:1 - │ - 1 │ (5 / 2) - │ ^^^^^ - │ │ - │ this expression is unhandled - │ - """# - diff: #""" - # .new_key = 100 + \ - - (5 / 2) - +# (5 / 2) - """# - }, - ] -} diff --git a/docs/reference/remap/errors/100_unhandled_root_runtime_error.cue b/docs/reference/remap/errors/100_unhandled_root_runtime_error.cue new file mode 100644 index 0000000000000..8d9d58013f9c5 --- /dev/null +++ b/docs/reference/remap/errors/100_unhandled_root_runtime_error.cue @@ -0,0 +1,41 @@ +package metadata + +remap: errors: "100": { + title: "Unhandled root runtime error" + description: """ + A root expression is fallible and its runtime error is not handled. + """ + rationale: """ + VRL is [fail-safe](\(urls.vrl_fail_safety)) and requires that all possible runtime errors be handled. This + contributes heavily to VRL's [safety principle](\(urls.vrl_safety)), ensuring that VRL programs are reliable + once deployed. + """ + resolution: """ + [Handle](\(urls.vrl_error_handling)) the runtime error by [assigning](\(urls.vrl_error_handling_assigning)), + [coalescing](\(urls.vrl_error_handling_coalescing)), or [raising](\(urls.vrl_error_handling_raising)) the + error. + """ + + examples: [ + { + "title": "\(title) (assigning)" + source: #""" + get_env_var("HOST") + """# + raises: compiletime: #""" + error: \#(title) + ┌─ :1:1 + │ + 1 │ (5 / 2) + │ ^^^^^ + │ │ + │ this expression is unhandled + │ + """# + diff: #""" + - get_env_var("HOST") + +# .host = get_env_var("HOST") + """# + }, + ] +} diff --git a/docs/reference/remap/errors/103_unhandled_fallible_assignment.cue b/docs/reference/remap/errors/103_unhandled_assignment_runtime_error.cue similarity index 68% rename from docs/reference/remap/errors/103_unhandled_fallible_assignment.cue rename to docs/reference/remap/errors/103_unhandled_assignment_runtime_error.cue index 12777444093a9..12d625a96f875 100644 --- a/docs/reference/remap/errors/103_unhandled_fallible_assignment.cue +++ b/docs/reference/remap/errors/103_unhandled_assignment_runtime_error.cue @@ -1,10 +1,11 @@ package metadata remap: errors: "103": { - title: "Unhandled fallible assignment" + title: "Unhandled assignment runtime error" description: """ The right-hand side of an [assignment expression](\(urls.vrl_expressions)#\(remap.literals.regular_expression.anchor)) - can fail and the error is not being [handled](\(urls.vrl_error_handling)). + is fallible and can produce a [runtime error](\(urls.vrl_runtime_errors)), but the error is not being + [handled](\(urls.vrl_error_handling)). """ rationale: """ VRL is [fail-safe](\(urls.vrl_fail_safety)) and requires that all possible runtime errors be handled. This @@ -12,7 +13,9 @@ remap: errors: "103": { once deployed. """ resolution: """ - Handle the error using one of the [documented error handling strategies](\(urls.vrl_error_handling)). + [Handle](\(urls.vrl_error_handling)) the runtime error by [assigning](\(urls.vrl_error_handling_assigning)), + [coalescing](\(urls.vrl_error_handling_coalescing)), or [raising](\(urls.vrl_error_handling_raising)) the + error. """ examples: [...{ @@ -34,21 +37,21 @@ remap: errors: "103": { examples: [ { - "title": "\(title) (coalesce)" + "title": "\(title) (coalescing)" diff: #""" -. |= parse_key_value(.message) +. |= parse_key_value(.message) ?? {} """# }, { - "title": "\(title) (raise & abort)" + "title": "\(title) (raising)" diff: #""" -. |= parse_key_value(.message) +. |= parse_key_value!(.message) """# }, { - "title": "\(title) (assignment)" + "title": "\(title) (assigning)" diff: #""" -. |= parse_key_value(.message) +., err |= parse_key_value(.message) diff --git a/docs/reference/urls.cue b/docs/reference/urls.cue index b9dd36e5f6a56..2a404e81c31b9 100644 --- a/docs/reference/urls.cue +++ b/docs/reference/urls.cue @@ -481,20 +481,22 @@ urls: { vector_website: "https://vector.dev" vrl_announcement: "\(vector_website)/blog/vector-remap-language" vrl_error_handling: "\(vrl_errors_reference)#handling" + vrl_error_handling_assigning: "\(vrl_errors_reference)#assigning" + vrl_error_handling_coalescing: "\(vrl_errors_reference)#coalesing" + vrl_error_handling_raising: "\(vrl_errors_reference)#raising" vrl_errors_reference: "\(vrl_reference)errors/" - vrl_fail_safety: "\(vrl_intro)#fail-safety" vrl_expressions: "\(vrl_reference)expressions/" - vrl_fail_safety: "\(vrl_intro)#fail-safety" - vrl_features: "\(vrl_intro)#features" + vrl_fail_safety: "\(vrl_reference)#fail-safety" + vrl_features: "\(vrl_reference)#features" vrl_functions: "\(vrl_reference)functions/" - vrl_intro: "\(vrl_reference)introduction/" - vrl_literals: "\(vrl_reference)literals/" + vrl_literals: "\(vrl_expressions)#literal-expressions" vrl_parsing_functions: "\(vrl_functions)#parse-functions" - vrl_path_expressions: "\(vrl_expressions)#path_expressions" - vrl_performance: "\(vector_website)/docs/reference/vrl/#performance" + vrl_path_expressions: "\(vrl_expressions)#path" + vrl_performance: "\(vrl_reference)#performance" vrl_reference: "\(vector_website)/docs/reference/vrl/" - vrl_safety: "\(vector_website)/docs/reference/vrl/#safety" - vrl_type_safety: "\(vrl_intro)#type-safety" + vrl_runtime_errors: "\(vrl_errors_reference)#runtime-errors" + vrl_safety: "\(vrl_reference)#safety" + vrl_type_safety: "\(vrl_reference)#type-safety" vote_feature: "\(vector_repo)/issues?q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc+label%3A%22Type%3A+New+Feature%22" wasm: "https://webassembly.org/" wasm_languages: "\(github)/appcypher/awesome-wasm-langs" From 0445c25746a1344b58f743ba8c7ec1e8e337d351 Mon Sep 17 00:00:00 2001 From: Binary Logic Date: Wed, 3 Feb 2021 09:09:12 -0600 Subject: [PATCH 08/14] Update docs/reference/remap/errors/106_function_argument_arity_mismatch.cue Co-authored-by: Pablo Sichert --- .../remap/errors/106_function_argument_arity_mismatch.cue | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/remap/errors/106_function_argument_arity_mismatch.cue b/docs/reference/remap/errors/106_function_argument_arity_mismatch.cue index 883f559e74f5c..f788afdf9550b 100644 --- a/docs/reference/remap/errors/106_function_argument_arity_mismatch.cue +++ b/docs/reference/remap/errors/106_function_argument_arity_mismatch.cue @@ -13,7 +13,7 @@ remap: errors: "106": { examples: [ { - "title": "\(title)" + "title": title source: #""" parse_json(.message, pretty: true) """# From bea6f8a2a3e87cbfa005485f046762209a428872 Mon Sep 17 00:00:00 2001 From: Binary Logic Date: Wed, 3 Feb 2021 09:09:20 -0600 Subject: [PATCH 09/14] Update docs/reference/remap/errors/107_required_function_argument_missing.cue Co-authored-by: Pablo Sichert --- .../remap/errors/107_required_function_argument_missing.cue | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/remap/errors/107_required_function_argument_missing.cue b/docs/reference/remap/errors/107_required_function_argument_missing.cue index 78cd8101f98ff..850c07f3f1f2d 100644 --- a/docs/reference/remap/errors/107_required_function_argument_missing.cue +++ b/docs/reference/remap/errors/107_required_function_argument_missing.cue @@ -13,7 +13,7 @@ remap: errors: "107": { examples: [ { - "title": "\(title)" + "title": title source: #""" parse_timestamp(.timestamp) """# From 991c52be68f0e206d397c3bc90622a70b65acb95 Mon Sep 17 00:00:00 2001 From: Binary Logic Date: Wed, 3 Feb 2021 09:09:28 -0600 Subject: [PATCH 10/14] Update docs/reference/remap/errors/108_unknown_function_argument_keyword.cue Co-authored-by: Pablo Sichert --- .../remap/errors/108_unknown_function_argument_keyword.cue | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/remap/errors/108_unknown_function_argument_keyword.cue b/docs/reference/remap/errors/108_unknown_function_argument_keyword.cue index 947f47ab3df47..efdd70db923a0 100644 --- a/docs/reference/remap/errors/108_unknown_function_argument_keyword.cue +++ b/docs/reference/remap/errors/108_unknown_function_argument_keyword.cue @@ -13,7 +13,7 @@ remap: errors: "108": { examples: [ { - "title": "\(title)" + "title": title source: #""" parse_timestamp(.timestamp, fmt: "%D") """# From 9e17ebbec149953b7a0fc96af2e667cacc356e64 Mon Sep 17 00:00:00 2001 From: Binary Logic Date: Wed, 3 Feb 2021 09:09:48 -0600 Subject: [PATCH 11/14] Update docs/reference/remap/errors/109_cannot_abort_function.cue Co-authored-by: Pablo Sichert --- docs/reference/remap/errors/109_cannot_abort_function.cue | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/remap/errors/109_cannot_abort_function.cue b/docs/reference/remap/errors/109_cannot_abort_function.cue index 6f9cf6480e5fb..193b957bb1964 100644 --- a/docs/reference/remap/errors/109_cannot_abort_function.cue +++ b/docs/reference/remap/errors/109_cannot_abort_function.cue @@ -4,7 +4,7 @@ remap: errors: "109": { title: "Cannot abort function" description: """ A [function call expression](\(urls.vrl_expressions)#\(remap.literals.regular_expression.anchor)) cannot end - with `!` unless it _fallible_. If a function does not error, then it will not have an abort variant that ends + with `!` unless it is _fallible_. If a function does not error, then it will not have an abort variant that ends with `!`. """ rationale: null From 2a6997b994c80648b0117d04a88d131d2ea6ca7c Mon Sep 17 00:00:00 2001 From: Binary Logic Date: Wed, 3 Feb 2021 09:09:58 -0600 Subject: [PATCH 12/14] Update docs/reference/remap/errors/109_cannot_abort_function.cue Co-authored-by: Pablo Sichert --- docs/reference/remap/errors/109_cannot_abort_function.cue | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/remap/errors/109_cannot_abort_function.cue b/docs/reference/remap/errors/109_cannot_abort_function.cue index 193b957bb1964..e6717718fc260 100644 --- a/docs/reference/remap/errors/109_cannot_abort_function.cue +++ b/docs/reference/remap/errors/109_cannot_abort_function.cue @@ -14,7 +14,7 @@ remap: errors: "109": { examples: [ { - "title": "\(title)" + "title": title source: #""" downcase!(.message) """# From 289fd9d59c7a1d6eafed2adbb091ed4fd753da82 Mon Sep 17 00:00:00 2001 From: Binary Logic Date: Wed, 3 Feb 2021 09:11:18 -0600 Subject: [PATCH 13/14] Update docs/reference/remap/errors/108_unknown_function_argument_keyword.cue Co-authored-by: Jean Mertz --- .../remap/errors/108_unknown_function_argument_keyword.cue | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/remap/errors/108_unknown_function_argument_keyword.cue b/docs/reference/remap/errors/108_unknown_function_argument_keyword.cue index efdd70db923a0..50dfb4fbcfaef 100644 --- a/docs/reference/remap/errors/108_unknown_function_argument_keyword.cue +++ b/docs/reference/remap/errors/108_unknown_function_argument_keyword.cue @@ -29,7 +29,7 @@ remap: errors: "108": { """# diff: #""" -parse_timestamp(.timestamp) - +parse_timestamp(.timestamp, "%D") + +parse_timestamp(.timestamp, format: "%D") """# }, ] From 18260a27f3b745840ea9410c30ab2843a6809ade Mon Sep 17 00:00:00 2001 From: binarylogic Date: Wed, 3 Feb 2021 09:17:37 -0600 Subject: [PATCH 14/14] Use runtime error Signed-off-by: binarylogic --- .../remap/errors/100_unhandled_root_runtime_error.cue | 8 ++++---- ...te.cue => 102_non_boolean_if_expression_predicate.cue} | 0 .../errors/107_required_function_argument_missing.cue | 2 +- docs/reference/remap/errors/109_cannot_abort_function.cue | 4 ++-- docs/reference/remap/errors/110_invalid_argument_type.cue | 3 +-- docs/reference/urls.cue | 8 ++++---- 6 files changed, 12 insertions(+), 13 deletions(-) rename docs/reference/remap/errors/{102_non_boolean_if_statement_predicate.cue => 102_non_boolean_if_expression_predicate.cue} (100%) diff --git a/docs/reference/remap/errors/100_unhandled_root_runtime_error.cue b/docs/reference/remap/errors/100_unhandled_root_runtime_error.cue index 8d9d58013f9c5..c790a26c2bf25 100644 --- a/docs/reference/remap/errors/100_unhandled_root_runtime_error.cue +++ b/docs/reference/remap/errors/100_unhandled_root_runtime_error.cue @@ -1,16 +1,16 @@ package metadata remap: errors: "100": { - title: "Unhandled root runtime error" + title: "Unhandled root runtime error" description: """ - A root expression is fallible and its runtime error is not handled. + A root expression is fallible and its [runtime error](\(urls.vrl_runtime_errors)) is not handled. """ - rationale: """ + rationale: """ VRL is [fail-safe](\(urls.vrl_fail_safety)) and requires that all possible runtime errors be handled. This contributes heavily to VRL's [safety principle](\(urls.vrl_safety)), ensuring that VRL programs are reliable once deployed. """ - resolution: """ + resolution: """ [Handle](\(urls.vrl_error_handling)) the runtime error by [assigning](\(urls.vrl_error_handling_assigning)), [coalescing](\(urls.vrl_error_handling_coalescing)), or [raising](\(urls.vrl_error_handling_raising)) the error. diff --git a/docs/reference/remap/errors/102_non_boolean_if_statement_predicate.cue b/docs/reference/remap/errors/102_non_boolean_if_expression_predicate.cue similarity index 100% rename from docs/reference/remap/errors/102_non_boolean_if_statement_predicate.cue rename to docs/reference/remap/errors/102_non_boolean_if_expression_predicate.cue diff --git a/docs/reference/remap/errors/107_required_function_argument_missing.cue b/docs/reference/remap/errors/107_required_function_argument_missing.cue index 850c07f3f1f2d..a8085df95b1bb 100644 --- a/docs/reference/remap/errors/107_required_function_argument_missing.cue +++ b/docs/reference/remap/errors/107_required_function_argument_missing.cue @@ -29,7 +29,7 @@ remap: errors: "107": { """# diff: #""" -parse_timestamp(.timestamp) - +parse_timestamp(.timestamp, "%D") + +parse_timestamp(.timestamp, format: "%D") """# }, ] diff --git a/docs/reference/remap/errors/109_cannot_abort_function.cue b/docs/reference/remap/errors/109_cannot_abort_function.cue index e6717718fc260..72144a640e726 100644 --- a/docs/reference/remap/errors/109_cannot_abort_function.cue +++ b/docs/reference/remap/errors/109_cannot_abort_function.cue @@ -4,8 +4,8 @@ remap: errors: "109": { title: "Cannot abort function" description: """ A [function call expression](\(urls.vrl_expressions)#\(remap.literals.regular_expression.anchor)) cannot end - with `!` unless it is _fallible_. If a function does not error, then it will not have an abort variant that ends - with `!`. + with `!` unless it is _fallible_. If a function cannot produce a runtime error, then it will not have an abort + variant that ends with `!`. """ rationale: null resolution: """ diff --git a/docs/reference/remap/errors/110_invalid_argument_type.cue b/docs/reference/remap/errors/110_invalid_argument_type.cue index 36fed0cd6559b..0a412bedc7a31 100644 --- a/docs/reference/remap/errors/110_invalid_argument_type.cue +++ b/docs/reference/remap/errors/110_invalid_argument_type.cue @@ -43,8 +43,7 @@ remap: errors: "110": { { "title": "\(title) (guard with errors)" diff: #""" - +string!(.message) - downcase(.message) + downcase(string!(.message)) """# }, { diff --git a/docs/reference/urls.cue b/docs/reference/urls.cue index 2a404e81c31b9..4ed475e1aa995 100644 --- a/docs/reference/urls.cue +++ b/docs/reference/urls.cue @@ -481,9 +481,9 @@ urls: { vector_website: "https://vector.dev" vrl_announcement: "\(vector_website)/blog/vector-remap-language" vrl_error_handling: "\(vrl_errors_reference)#handling" - vrl_error_handling_assigning: "\(vrl_errors_reference)#assigning" - vrl_error_handling_coalescing: "\(vrl_errors_reference)#coalesing" - vrl_error_handling_raising: "\(vrl_errors_reference)#raising" + vrl_error_handling_assigning: "\(vrl_errors_reference)#assigning" + vrl_error_handling_coalescing: "\(vrl_errors_reference)#coalesing" + vrl_error_handling_raising: "\(vrl_errors_reference)#raising" vrl_errors_reference: "\(vrl_reference)errors/" vrl_expressions: "\(vrl_reference)expressions/" vrl_fail_safety: "\(vrl_reference)#fail-safety" @@ -494,7 +494,7 @@ urls: { vrl_path_expressions: "\(vrl_expressions)#path" vrl_performance: "\(vrl_reference)#performance" vrl_reference: "\(vector_website)/docs/reference/vrl/" - vrl_runtime_errors: "\(vrl_errors_reference)#runtime-errors" + vrl_runtime_errors: "\(vrl_errors_reference)#runtime-errors" vrl_safety: "\(vrl_reference)#safety" vrl_type_safety: "\(vrl_reference)#type-safety" vote_feature: "\(vector_repo)/issues?q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc+label%3A%22Type%3A+New+Feature%22"