sc-expression

README

https://pkg.go.dev/zxq.co/howl/sc-expression

Dual-licensed under MIT and Unlicense.

Documentation

Overview

Command sc-expressions provides status code expression, which are simple expressions to match to HTTP status codes, or any status code which has 3 digits exactly. It allows to generate from a string a function job system, providing an expression to specify on which API responses we which matches only a certain set of codes. Useful application includes, in a should mark the request as errored and in which circumstances we should retry it.

For instance, an error condition could be specified with the expression 4XX,5XX - and a retry condition on 429,5XX (seeing as all other 4XX responses are likely to be permanent errors).

Syntax

Syntax is as follows:

• Empty: # No status code matches
• Equal: 400 # The status code must == 400
• Placeholder: 4XX # The status code must be 3 digits and start with 4
• Catch-all: XXX # Match all status codes
• Not equal: !200 # The status code must != 200 !2XX # The status code must not (have 3 digits and start with 2)
• OR for equal: 400,401 # The status code must == 400 || == 401
• AND for neq: !200,!204 # The status code must != 200 && != 204
• Combination: 4XX,!401 # The status code must be like 4XX && != 401 4XX,5XX,!402,!42X # (like 4XX || like 5XX) && (!= 402 && not like 42X)
• Illegal: !400,4XX # Positives must come before negations 2X0 # Placeholders only at the end of the code.

Negations may only be specified once. Note that the empty expression also has another equivalent, that is !XXX.

Performance

Parse+execution performance (which is what would happen in most cases, as the generated functions are not meant to be cached) generally can execute within ~2µs on modern CPUs. Go benchmarks for my computer:

cpu: AMD Ryzen 7 PRO 4750U with Radeon Graphics
BenchmarkStatusCodeExpressionParseAndRun-16              1880427               689.1 ns/op
BenchmarkStatusCodeExpressionParseAndRun_Long-16          580285              1877 ns/op

Command

A simple main() program is provided with this implementation, as this is not a package that is meant to be imported due to its low complexity (remember the Go proverb - "a little copying is better than a little dependency"). The 3 functions are less than 100LOC of code you might benefit from customising, so it's worth the effort...