Document OPA/Rego feature support

[anderseknert]

It would be helpful if the docs (the README, or elsewhere) included a section documenting what features (built-ins and language constructs) this project currently supports.

I'm thinking something like a table for all built-in functions, with one column showing whether they're implemented, and perhaps another column for implementation details and gotchas (if there are any). For anyone finding this issue looking for this, the list of implemented builtins can be found here.

If there are language constructs not implemented, that'd be good to document too.

Finally, if we published a capabilities.json file for this project, users could leverage that to have opa build fail when trying to build swift-opa bundles using unsupported features and builtin functions. And we could use it for creating a swift-opa target in Regal, making the linter and language server aware of the limitations (for example, by not auto-completing names of unsupported built-in functions).

[tsandall]

I'd love to see the supported builtins indicated in the OPA docs under in the built-in function page: https://www.openpolicyagent.org/docs/policy-reference/builtins.

+1 for generating a capabilities.json file in this repo that could be referenced somehow by opa build. Perhaps there's something that could be done on the opa side to make it easy to refer to different targets (even if the target implementation doesn't existing inside of opa proper...)

[anderseknert]

in the OPA docs under in the built-in function page

Ah, yeah, that'd be great. If we had a capabilities.json published here, we could render a new column for swift-opa support based on that.

Perhaps there's something that could be done on the opa side to make it easy to refer to different targets (even if the target implementation doesn't existing inside of opa proper...)

We've done some work in Regal in the past to make linting work seamlessly with EOPA and those built-in functions. Some of that may not be ideal for OPA (like embedding capabilities files of other projects) but some would. Like allowing capabilities to be fetched from a URL rather than a local file.

opa build --bundle --target plan --capabilities https://github.com/open-policy-agent/swift-opa/path/to/capabilities.json bundle

Long URLs aren't nice to work with though, and as evident from above, don't look great in docs and examples. Ideally we'd have a better option than having to provide capabilities via command line. How about remote URL support and allowing this information to be provided via the .manifest file? That would also help document the requirements of a bundle as declared by the bundle itself:

.manifest

{
  "roots": ["foo/bar"],
  "capabilities": "https://github.com/open-policy-agent/swift-opa/path/to/capabilities.json"
}

Now you could just do:

opa build --bundle --target plan bundle

And have the build (or any bundle-aware) command run with whatever capabilities it found in bundle/.manifest, if any. Just like we could have regal lint bundle pick up the capabilities from there. Could also be a local file for those who prefer to include even the capabilities.json as part of the bundle.

(tangentially related, me and @johanfylling have previously discussed doing this for schemas — i.e. letting a bundle author provide schemas as part of their bundle and have a .manifest entry tell tooling where to look for them).

[charlieegan3]

I think adding the capabilities option to the .manifest sounds like a good approach. I guess when OPA opens the bundle it can/must validate that it has overlapping capabilities.

If there existed a capabilities.json file for the project we should be quite easily be able to load this into the OPA site and generate the tables correctly. 👍

[tsandall]

Is there a reason we wouldn't want opa build --target=swift bundle/? Where swift is an alias for the plan IR + swift-opa capabilities?

[anderseknert]

In addition to what was suggested or as the only option? As the only option, it would be an opa build exclusive thing, not self-documenting and with no benefit to other tools — including even OPA's own if you'd still have to run opa check --capabilities https://github.com/open-policy-agent/swift-opa/path/to/capabilities.json (or whatever) elsewhere.

Also, which version of swift-opa would that magic summon? 🧙 Having the reference in the .manifest would allow you to point at any tag/commit.

[johanfylling]

A drawback of a swift target is that its associated capabilities would be fixed in place for every OPA release, whereas the actual capabilities of swift-opa is presumably a moving target. Supplying a capabilities file supports better cross-version compatibility, I think.

[tsandall]

In addition to what was suggested or as the only option?

They're not mutually exclusive. I was just thinking about it from the perspective of someone building an OPA bundle for another runtime they were familiar with. It seemed nice to have the shorthand to refer to the capabilities of that runtime, especially when it's an official runtime that's part of the project (not some custom thing that someone built privately), documented on the website, etc.

Having said that, the "capabilities in .manifest" approach is nice because it's minimal and covers a bunch of use case (pinning versions, custom implementations, etc.) Let's just go with that and come back to shorthand targets in the future if we think it's too hard for people to use the "capabilities in manifest" option (which seems unlikely).

Integrating the capabilities into openpolicyagent.org/docs feels like it would be high ROI and would help set the standard for other implementations (e.g., EOPA VM).

[anderseknert]

Sounds good. I'll create an issue for this in OPA in the weekend or early next week. Adding support for --capabilities <url> as part of an implementation sounds like it would be fairly cheap. We can ponder some more on what an aliased form would look like and how it would work.

[shomron]

What's the use case for a capabilities field in the bundle manifest? Isn't the bundle (or at least the plan) already self-describing in terms of which capabilities are required?

We should also think through any potential security implications of referencing remote urls in a bundle manifest, which might come from an untrusted source.

[anderseknert]

Isn't the bundle (or at least the plan) already self-describing in terms of which capabilities are required?

Sure — the idea is to prevent even creating a bundle which isn't compatible with the target system (like swift-opa). Provided that we (swift-opa) publish a capabilities.json file listing all built-in functions supported by our evaluator, users can then tell opa build or tools like Regal "here's the target I'm building for" and have bundle compilation fail if a policy contains a built-in function not implemented by swift-opa ... or have Regal's language server only provide completion suggestions for supported functions, disable linters that relate to unsupported features... and so on.