styrainc / rego-style-guide Goto Github PK

As these new keywords help make rules more readable, we should recommend using them.

I would like to have a dedicated section/paragraph/etc explicitly defining naming convention for "internal" variable names inside functions/rules. i.e. should they be prefixed with _ as I saw in some guides.

e.g. - should we use _t or t for those variables

jwt_payload := _t[2] {
  print("jwt_payload")
  _t := io.jwt.decode_verify(jwt_raw, {"cert": jwks_request})
  _t[0] == true
}

Since we've seen a few issues where existing rules or functions have clashed with the "catch all" import future.keywords at OPA version upgrades, it makes sense to recommend the more explicit alternative, i.e. declare one import per keyword used.

Some thoughts

• Extend general advice to recommend test driven development
• And add an "Exceptions" part to the recommendation on imports stating that importing rules directly is fine for tests.

Test section

• Use different package name, and imports, for tests
  • Recommendation for naming test packages: same as the package under test, with either .test or _test appended?
  • Recommendation for naming test files: _test.rego suffix?

Additionally, I've seen a few questions about how to best organize tests, i.e. should they be in the same directory as packages being tested, or in a separate one? While not strictly about "Rego" the language, I think it makes sense to consider this for the guide as well.

Some of these style recommendations lend themselves well to automated checking. Building on you great blog post on the subject, would it be worth adding Rego policies that deny Rego that doesn't conform to these style rules?

I've seen this pattern in many policies out in the "wild":

package policy

deny["input.foo must be true"] {
    not input.foo == true
}

Compared to using input.foo != true, this pattern also handles the undefined case, and as such extends the recommendation to use negation to handle undefined.

The question is whether we should include this as a general recommendation, perhaps just as an example included in the current recommendation? 🤔

Where things tend to get complicated, is when using "double negation" like not input.foo != true ... and I don't think that's something I'd like to read myself 😅 But granted that not + equality works without caveats, perhaps it should be preferred over !=?

Although documented, even experienced users get confused by the default constraints (aud in particular) provided by io.jwt.decode_verify. I think we might want to consider recommending verifying and decoding as a two-step process, i.e.

Avoid

claims := payload {
    [valid, _, payload] := io.jwt.decode_verify("my_jwt_token", {"cert": "my certificate"})
    valid
}

Prefer

claims := payload {
    io.jwt.verify_rs256("my_jwt_token", "my certificate")
    [_, payload, _] := io.jwt.decode("my_jwt_token")
}

We should add suggestions for package related subjects:

• Naming convention
• How to organize support/helper packages
• When to split a policy into multiple files
• How folder structure relates to package hierarchy
• Where tests are recommended to be put in the package structure