Naming convention for "internal" variables and rules

[ievgenii-shepeliuk]

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
}

[anderseknert]

For variables declared inside of rules, there's no reason I can think of to use _ for a prefix. They aren't visible outside of the rule anyway, and will shadow variables of the same name declared in the outer scope, so that e.g.

x := 5

my_rule {
    x := 10
    print(x) # prints 10
}

However, one place where I think this question is highly relevant, and one I know have come up in the past, is whether there should be a way to mark top level variables and rules as "private". This could either be done by naming convention, like you suggest:

allow {
    _my_helper_rule
}

_my_helper_rule {
    # some logic here
}

While this would provide a hint to the reader, there's currently nothing to "enforce" this, unless one wants to be creative with e.g. an authz policy that denies requests to any path with a _ prefix.

package system.authz

default allow := {"allowed": true}

allow := {"allowed": false, "reason": "access to documents prefixed with '_' not allowed"} {
    startswith(input.path[count(input.path) -1], "_")
}

allow := {"allowed": false, "reason": "access to 'data' not allowed"} {
    input.path == ["v1", "data"]
}

Although you could easily retrieve these by querying for a parent document, so you'd need to expand on the above for a real use case, whether a good idea or not.

For the future, we could either consider a keyword to mark rules as private/internal, or extend the metadata annotations to include an attribute that would do this, e.g.

# METADATA
# description: helper rule that helps
# visibility: private
my_helper_rule {
    # some logic here
}

This could be done today already using custom annotations, but if we wanted the server to enforce this, we'd need to work on making that happen. I think this approach is probably the one I'd prefer.