feat: first API draft and generation (#315)

Co-authored-by: zepatrik <[email protected]>

Makefile

@@ -64,6 +64,31 @@ docker: deps
 		rm keto
 		packr clean
 
-.PHONY: gen-protobuf
-gen-protobuf:
-		protoc --go_out=. --go_opt=paths=source_relative --go-grpc_out=. --go-grpc_opt=paths=source_relative relationtuple/*.proto
+#
+# Generate APIs and client stubs from the definitions
+#
+.PHONY: buf-gen
+buf-gen:
+		buf generate \
+		--config buf/api/buf.yaml \
+		--template buf/api/buf.gen.yaml \
+		&& \
+		echo "TODO: generate gapic client at ./client" \
+		&& \
+		echo "All code was generated successfully!"
+
+#
+# Lint API definitions
+#
+.PHONY: buf-lint
+buf-lint:
+		buf check lint \
+		--config buf/api/buf.yaml \
+		&& \
+		echo "All lint checks passed successfully!"
+
+#
+# Generate after linting succeeded
+#
+.PHONY: buf
+buf: buf-lint buf-gen

api/keto/README.md

@@ -0,0 +1,35 @@
+# Notes
+
+> ORY Keto is still a `sandbox` project and
+the included APIs are unstable until we reach `v1` 
+and release `v1.0.0` of Keto!
+>
+> Older API versions, such as `v1alpha1`, will still
+> get support for a reasonable amount of time after release
+> of `v1`!
+
+This directory contains the ProtoBuf & gRPC definitions
+for the Access Control APIs.
+
+**ACL is the flexible and scalable "base system"
+all other access control schemes built upon.**
+
+## Directory layout
+
+```shell script
+keto
+└── acl / rbac / ...
+    ├── node
+    │   └── v1 - Intercommunication API (cluster internal)
+    ├── admin
+    │   └── v1 - Admin API definitions
+    └── v1 - "Base" API definitions
+```
+
+- `admin` - API for critical administrative tasks
+  - namespace config management
+  - retrieval of cluster system statistics / analysis
+  - etc.
+- `base/v1` - Base APIs / models
+  - read/write/watch/... services
+- `node` - Intercommunication of cluster nodes

api/keto/acl/admin/v1alpha1/admin_service.proto

@@ -0,0 +1,16 @@
+syntax = "proto3";
+
+package keto.acl.admin.v1alpha1;
+
+option go_package = "github.com/ory/keto/api/keto/acl/admin/v1alpha1;admin";
+option csharp_namespace = "Ory.Keto.Acl.Admin.V1Alpha1";
+option java_multiple_files = true;
+option java_outer_classname = "AdminServiceProto";
+option java_package = "sh.ory.keto.acl.admin.v1alpha1";
+option php_namespace = "Ory\\Keto\\Acl\\Admin\\V1alpha1";
+
+// The admin service for administrative tasks in the ACL system.
+service AdminService {
+  // ...RPCs are coming here in (near) future...
+}
+

api/keto/acl/node/v1alpha1/node_service.proto

@@ -0,0 +1,28 @@
+syntax = "proto3";
+
+package keto.acl.node.v1alpha1;
+
+option go_package = "github.com/ory/keto/api/keto/acl/node/v1alpha1;node";
+option csharp_namespace = "Ory.Keto.Acl.Node.V1Alpha1";
+option java_multiple_files = true;
+option java_outer_classname = "NodeServiceProto";
+option java_package = "sh.ory.keto.acl.node.v1alpha1";
+option php_namespace = "Ory\\Keto\\Acl\\Node\\V1alpha1";
+
+// The internal service for intercommunication
+// between ACL servers in a cluster.
+//
+// Implementing this service principally allows any program
+// in the network to participate as a node in an ACL cluster.
+service NodeService {
+  // ...RPCs for inter-node-communication are coming here...
+  //
+  // e.g.:
+  //  - the expand API to load off deep checks to other nodes
+  //    - we can attach meta to CheckResponses to gain greater knowledge of relationships
+  //      and measure statistics to integrate with Prometheus and Grafana
+  //  - schema node election
+  //  - replace groupcache's normal http server with protobuf grpc protocol!!!
+  //    - https://github.com/mailgun/groupcache/blob/8672aac324c41ba3909ad69e1a76b678894d378b/http.go#L160
+}
+