Merge branch 'project-kessel:main' into iqe_deploy

README.md

@@ -1,16 +1,32 @@
-# Rebac Service
+# Kessel Relations API
 
-## Build
-`make build`
+Kessel Relations API is a Zanzibar-inspired frontend for relationship-based access control.
 
-## Run
-`make run`
+## Contributing
+
+### Prerequisites
+
+To get necessary build and generation dependencies:
 
-## Install Kratos
 ```
-go install github.com/go-kratos/kratos/cmd/kratos/v2@latest
+make init
 ```
-## Create a service
+
+See also:
+
+- https://protobuf.dev/getting-started/gotutorial/#compiling-protocol-buffers
+- https://go-kratos.dev/en/docs/getting-started/start/
+
+### Build
+
+`make build`
+
+### Run
+
+`make run`
+
+### Create a service
+
 ```
 # Create a template project
 kratos new server
@@ -27,16 +43,18 @@ go generate ./...
 go build -o ./bin/ ./...
 ./bin/server -conf ./configs
 ```
-## Generate other auxiliary files by Makefile
+
+### Generate other auxiliary files by Makefile
+
 ```
-# Download and update dependencies
-make init
 # Generate API files (include: pb.go, http, grpc, validate, swagger) by proto file
 make api
 # Generate all files
 make all
 ```
-## Automated Initialization (wire)
+
+### Automated Initialization (wire)
+
 ```
 # install wire
 go get github.com/google/wire/cmd/wire
@@ -48,19 +66,24 @@ wire
 
 ## Spicedb using docker/podman
 
-## Run the spicedb
+### Run the spicedb
+
 `make spicedb`
 
-## Run the insights-rebac with docker compose
+### Run the insights-rebac with docker compose
+
 `make rebac`
 
-## teardown spicedb and postgresql db
+### teardown spicedb and postgresql db
+
 `make spicedb/teardown`
 
-## Deploy Rebac and Spicedb using kind/kubernetes
+### Deploy Rebac and Spicedb using kind/kubernetes
+
 `make kind/rebac`
 
-## Docker
+### Docker
+
 ```bash
 # build
 docker build -t <your-docker-image-name> .
@@ -71,19 +94,21 @@ docker run --rm -p 8000:8000 -p 9000:9000 -v </path/to/your/configs>:/data/conf
 
 ## Deploy to a openshift cluster that has Clowder
 
-### Prerequisite 
+### Prerequisite
+
 [bonfire](https://github.com/RedHatInsights/bonfire)
 
 NOTE: The minimum required version of [bonfire](https://github.com/RedHatInsights/bonfire)
 is specified in the MIN_BONFIRE_VERSION variable in the deploy.sh script
 Bonfire could be upgraded by command:
+
 ```asciidoc
 pip install --upgrade crc-bonfire
 ```
-Latest version of [bonfire](https://github.com/RedHatInsights/bonfire) could be found [here](https://github.com/RedHatInsights/bonfire/releases).
 
+Latest version of [bonfire](https://github.com/RedHatInsights/bonfire) could be found [here](https://github.com/RedHatInsights/bonfire/releases).
 
-[oc](https://docs.openshift.com/container-platform/4.8/cli_reference/openshift_cli/getting-started-cli.html) 
+[oc](https://docs.openshift.com/container-platform/4.8/cli_reference/openshift_cli/getting-started-cli.html)
 
 You should have logged into a valid openshift cluster using the oc login command
 
@@ -108,11 +133,11 @@ The [deploy script](deploy/deploy.sh) under the [deploy](deploy) folder, will de
 
 - Creates a postgres pod and service (Note: No PVC)
 - Creates a spiceDB secret - that contains: a preshared key and Postgres connection URI
-- Creates a Configmap object  - that serves as a bootstrap schema for spiceDB (by default it uses the schema.yaml file under deploy)
+- Creates a Configmap object - that serves as a bootstrap schema for spiceDB (by default it uses the schema.yaml file under deploy)
 - Creates the spiceDB service
 - Creates the relations service
 
-You should be able to use the public route (relations-*) created by the clowder in your namespace, to use the service.
+You should be able to use the public route (relations-\*) created by the clowder in your namespace, to use the service.
 
 #### Deploying the components with rbac
 
@@ -125,6 +150,7 @@ This is demonstrating calling relationship api from rbac service in ephemeral en
 `path_to_local_copy_of_insights_rbac` is this [repository](https://github.com/RedHatInsights/insights-rbac)
 
 Example:
+
 ```
 ./deploy.sh rbac /Projects/insights-rbac
 ```

api/README.md

@@ -0,0 +1,51 @@
+# API Design
+
+API design should refer to the following style guides, in this order of precedence:
+
+- https://protobuf.dev/programming-guides/proto3/
+- https://protobuf.dev/programming-guides/dos-donts/
+- https://protobuf.dev/programming-guides/api
+- https://buf.build/docs/best-practices/style-guide
+- https://cloud.google.com/apis/design
+
+## Notes
+
+These are some specific call outs from the above docs which are useful or surprising in case you
+didn't spend the required time to go through all of those links.
+
+### Service names
+
+Service names should be globally disambiguated, even regardless of package, hence the inclusion of
+"Kessel" in the names (https://protobuf.dev/programming-guides/api/#service-name-globally-unique).
+
+### Comments
+
+Comment fields using Markdown (https://buf.build/docs/bsr/documentation#supported-formatting-syntax).
+
+### Method names
+
+These generally follow Google Cloud's guidance, with VerbNoun, in imperative mood, with a standard
+set of verbs. Custom method names are allowed outside of this.
+
+- https://cloud.google.com/apis/design/naming_convention#method_names
+- https://cloud.google.com/apis/design/standard_methods
+
+Note that "List" uses paged messages, _not_ streams,
+so "List" should be avoided for methods with streaming responses.
+
+It does not appear there is any other convention for methods with streaming responses,
+[based on querying all of GCP's APIs][1].
+
+[1]: https://github.com/search?q=repo:googleapis/googleapis+%22returns+(stream+%22+language:%22Protocol+Buffer%22&type=code&p=1
+
+## Troubleshooting
+
+### Using VSCode proto extension and seeing import errors?
+
+Add this to your settings.json:
+
+```
+   "protoc": {
+    "options": ["--proto_path=api", "--proto_path=third_party"]
+  }
+```

api/health/v1/health.proto

@@ -1,14 +1,14 @@
 syntax = "proto3";
 
-package api.health.v1;
+package kessel.relations.v1;
 
 import "google/api/annotations.proto";
 
 option go_package = "ciam-rebac/api/health/v1;v1";
 option java_multiple_files = true;
-option java_package = "api.health.v1";
+option java_package = "org.project_kessel.api.relations.v1";
 
-service Health {
+service KesselHealth {
 	rpc GetLivez (GetLivezRequest) returns (GetLivezReply){
 		option (google.api.http) = {
 			get: "/livez"