authzed / api Goto Github PK

This will avoid the BSR showing HEAD by default and instead will show releases only

Background

(take this explanation with a grain of salt; I would not call myself an expert on protobuf and generated code)

You can see the problem here: https://github.com/authzed/authzed-java/blob/main/examples/v1/App.java#L10-L25

This is apparently related to an old behavior of protoc where you could only have a single top-level proto def in a file because you can only have a single top-level class def in a java file. The solution to this was to have protoc generate a wrapper class to bundle up the various definitions in a proto file, which produces the FooOuterClass definitions in the generated Java code.

This ends up being confusing to a user of the library, because whether you need to use FooService or FooServiceOuterClass is entirely down to how many things are defined in the source proto file, which isn't visible to a user of the library without diving into either the jar definition or the proto files.

Proposed fix

Using java_multiple_files in the proto definition as an option should fix this and make the produced code less janky.

Caveat

This will be a breaking change to authzed-java, because all code that referenced FooServiceOuterClass will need to now reference FooService (or something like that).

The generated OpenAPI currently pulls in these all APIs, the older ones (v0, v1alpha1) which have no OpenAPI configuration and conflicting names.

Here: https://github.com/authzed/api/blob/main/authzed/api/v1/permission_service.proto#L269

If I use buf generate buf.build/authzed/api, it will only generate authzed/api/ c++ code, without dependencies needed like google/api.
How I fix this problem now is I copy all the .proto files into following folder structure:

Protos
├── authzed
│   └── api
│       └── v1
│           ├── core.proto
│           ├── debug.proto
│           ├── error_reason.proto
│           ├── openapi.proto
│           ├── permission_service.proto
│           ├── schema_service.proto
│           └── watch_service.proto
├── google
│   └── api
│       ├── annotations.proto
│       └── http.proto
├── protoc-gen-openapiv2
│   └── options
│       ├── annotations.proto
│       └── openapiv2.proto
└── validate
    └── validate.proto

But I think it's not an elegant way to do that if authzed dependencies and itself have updates, then I need to redo those copy again.
I think it would be nice that buf generate will also generate dependencies minimal set needed.
Is there a better way to achieve this?

The current regex:

^(([a-zA-Z0-9/_|\\-=+]{1,})|\\*)$

Doesn't allow for object ids that include : as separators, which are sometimes used in user identifiers.

See: https://github.com/authzed/api/blob/main/authzed/api/v1/permission_service.proto#L118

Should be changed to match the proper regex

Once we've published a timeline for formally dropping support for the v0 API, we'll mark the gRPC services as deprecated.

I'm not sure if this is something formally supported by the buf registry.

cc @bufdev

ReadSchema has schemaText and WriteSchema has schema. We should probably add schemaText to WriteSchema and deprecate schema

The BulkCheckPermission API is stable and is ready to move out of experimental.