docs: add array.concat and array.slice examples to array.mdx#8669
docs: add array.concat and array.slice examples to array.mdx#8669omribz156 wants to merge 1 commit into
Conversation
Adds two PlaygroundExample entries to the Arrays built-ins page, which previously had no examples at all. - array.concat: merging base and environment-specific label requirements in a Kubernetes admission policy - array.slice: extracting a fixed-length route prefix from a variable-length request path Closes part of open-policy-agent#3786. Signed-off-by: Omri SirComp <omribz156@gmail.com>
✅ Deploy Preview for openpolicyagent ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
johanfylling
left a comment
johanfylling
left a comment
There was a problem hiding this comment.
Thank you for contributing! 🙂
Maybe we could reduce the complexity of these examples a bit? So the target functions don't get lost in the overall complexity.
| @@ -0,0 +1,5 @@ | |||
| <!-- markdownlint-disable MD041 --> | |||
|
|
|||
| `array.concat` joins two arrays in order. A common use is building a complete | |||
There was a problem hiding this comment.
Since this'll be injected into the content in array.mdx, the reader will experience a bit of a hiccup in the text. E.g.:
### array.concat
array.concat joins two arrays in order, producing a new array that contains all elements of the first array followed by all elements of the second.
#### Merging base and environment label requirements
array.concat joins two arrays in order. A common use is building a complete validation list by merging a shared base set of rules with environment-specific additions, then iterating the result in a single deny rule.Consider dropping the redundant text from here to make it read a bit better. Same for array.slice.
There was a problem hiding this comment.
Consider reducing the complexity of this rule, as the important part (array.concat) might get lost in the weeds for the reader.
| package play | ||
|
|
||
| # Split a request path into segments. | ||
| # e.g. "/api/v1/users/123" → ["api", "v1", "users", "123"] |
There was a problem hiding this comment.
This arrow won't transition well when the user open's the example in the playground. Consider not using any "special" characters.
| api_version := path_segments[1] | ||
|
|
||
| # The first two segments identify the route, regardless of how long the path is. | ||
| route_prefix := array.slice(path_segments, 0, 2) |
There was a problem hiding this comment.
Similar to the other example policy, I wonder if this policy isn't a bit too complicated for its intended purpose. route_prefix will contain the result of the function we want to demo, but it's not used anywhere in the example.
| deny contains msg if { | ||
| api_version != "v1" | ||
| msg := sprintf("unsupported API version %q; only v1 is allowed", [api_version]) | ||
| } |
There was a problem hiding this comment.
If the final example policies end up using generated strings, consider using string-templates instead of sprintf, as it might reduce the apparent complexity for the reader, making it easier to focus on what's important.
| deny contains msg if { | |
| api_version != "v1" | |
| msg := sprintf("unsupported API version %q; only v1 is allowed", [api_version]) | |
| } | |
| deny contains $"unsupported API version {api_version}; only v1 is allowed" if { | |
| api_version != "v1" | |
| } |
2 participants
Why the changes in this PR are needed?
The Arrays built-ins page has no examples at all — only the
<BuiltinTable>. Issue #3786 tracks adding more examples across built-ins to help users get started faster.array.concatandarray.sliceare practical functions used in real admission policies and there is nothing to show how to call them.What are the changes in this PR?
Adds two
PlaygroundExampleentries toarray.mdx:array.concat— merging a base label-requirement list with an environment-specific list in a Kubernetes admission policy deny rule.array.slice— extracting a fixed-length route prefix from a variable-length request path after splitting on/.Each example follows the existing pattern from
aggregates/andstrings/:policy.rego,input.json,data.json,output.json,intro.md,title.txt,config.json.Notes to assist PR review:
Further comments:
Closes part of #3786. Happy to add more array built-in examples (
array.reverse,array.set_diff) in a follow-up if this shape looks right.