Naming convention for "internal" variables and rules
ievgenii-shepeliuk opened this issue · comments
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
}
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.