refactor: API paths (#862)

This change refactors the API paths to be consistent with the rest of the Ory ecosystem. This step is required for the unified Ory SDK. Additionally, as we plan to add high level APIs, e.g. for RBAC. The check and expand API paths changed to allow adding those.

BREAKING CHANGES: `/check` is now `/relation-tupes/check`
BREAKING CHANGES: `/expand` is now `/relation-tuples/expand`
BREAKING CHANGES: `/relation-tuples` is now `/admin/relation-tuples` for write APIs
BREAKING CHANGES: gRPC package is now called `ory.keto.relation_tuples.v1alpha2`
BREAKING CHANGES: gRPC relation-tuple-delta action enum names are prefixed with `ACTION_`

README.md

@@ -37,9 +37,9 @@ for your colleagues, and much more!
 
 ### :mega: Community gets Ory Cloud for Free! :mega:
 
-Ory community members get the Ory Cloud Start Up plan **free for six months**, with
-all quality-of-life features available, such as custom domains and giving your
-team members access.
+Ory community members get the Ory Cloud Start Up plan **free for six months**,
+with all quality-of-life features available, such as custom domains and giving
+your team members access.
 [Sign up with your GitHub account](https://console.ory.sh/registration?preferred_plan=start-up&utm_source=github&utm_medium=banner&utm_campaign=keto-readme-first900)
 and use the coupon code **`FIRST900`** on the _"Start-Up Plan"_ checkout page to
 claim your free project now! Make sure to be signed up to the

buf.yaml

@@ -9,7 +9,7 @@ lint:
     - google
   ignore_only:
     ENUM_VALUE_PREFIX:
-      - ory/keto/acl/v1alpha1/write_service.proto
+      - ory/keto/relation_tuples/v1alpha2/write_service.proto
 breaking:
   use:
     - PACKAGE

cmd/check/root.go

@@ -3,9 +3,9 @@ package check
 import (
 	"fmt"
 
-	"github.com/ory/keto/internal/check"
+	rts "github.com/ory/keto/proto/ory/keto/relation_tuples/v1alpha2"
 
-	acl "github.com/ory/keto/proto/ory/keto/acl/v1alpha1"
+	"github.com/ory/keto/internal/check"
 
 	"github.com/ory/x/cmdx"
 	"github.com/spf13/cobra"
@@ -42,11 +42,9 @@ func newCheckCmd() *cobra.Command {
 				return err
 			}
 
-			cl := acl.NewCheckServiceClient(conn)
-			resp, err := cl.Check(cmd.Context(), &acl.CheckRequest{
-				Subject: &acl.Subject{
-					Ref: &acl.Subject_Id{Id: args[0]},
-				},
+			cl := rts.NewCheckServiceClient(conn)
+			resp, err := cl.Check(cmd.Context(), &rts.CheckRequest{
+				Subject:   rts.NewSubjectID(args[0]),
 				Relation:  args[1],
 				Namespace: args[2],
 				Object:    args[3],

cmd/expand/root.go

@@ -3,14 +3,15 @@ package expand
 import (
 	"fmt"
 
+	rts "github.com/ory/keto/proto/ory/keto/relation_tuples/v1alpha2"
+
 	"github.com/ory/x/flagx"
 
 	"github.com/ory/x/cmdx"
 	"github.com/spf13/cobra"
 
 	"github.com/ory/keto/cmd/client"
 	"github.com/ory/keto/internal/expand"
-	acl "github.com/ory/keto/proto/ory/keto/acl/v1alpha1"
 )
 
 const FlagMaxDepth = "max-depth"
@@ -33,17 +34,9 @@ func NewExpandCmd() *cobra.Command {
 				return err
 			}
 
-			cl := acl.NewExpandServiceClient(conn)
-			resp, err := cl.Expand(cmd.Context(), &acl.ExpandRequest{
-				Subject: &acl.Subject{
-					Ref: &acl.Subject_Set{
-						Set: &acl.SubjectSet{
-							Relation:  args[0],
-							Namespace: args[1],
-							Object:    args[2],
-						},
-					},
-				},
+			cl := rts.NewExpandServiceClient(conn)
+			resp, err := cl.Expand(cmd.Context(), &rts.ExpandRequest{
+				Subject:  rts.NewSubjectSet(args[1], args[2], args[0]),
 				MaxDepth: maxDepth,
 			})
 			if err != nil {

cmd/relationtuple/create.go

@@ -8,7 +8,7 @@ import (
 	"os"
 	"path/filepath"
 
-	acl "github.com/ory/keto/proto/ory/keto/acl/v1alpha1"
+	rts "github.com/ory/keto/proto/ory/keto/relation_tuples/v1alpha2"
 
 	"github.com/ory/keto/internal/relationtuple"
 
@@ -25,7 +25,7 @@ func newCreateCmd() *cobra.Command {
 			"A directory will be traversed and all relation tuples will be created.\n" +
 			"Pass the special filename `-` to read from STD_IN.",
 		Args: cobra.MinimumNArgs(1),
-		RunE: transactRelationTuples(acl.RelationTupleDelta_INSERT),
+		RunE: transactRelationTuples(rts.RelationTupleDelta_ACTION_INSERT),
 	}
 	cmd.Flags().AddFlagSet(packageFlags)
 

cmd/relationtuple/delete.go

@@ -3,12 +3,13 @@ package relationtuple
 import (
 	"fmt"
 
+	rts "github.com/ory/keto/proto/ory/keto/relation_tuples/v1alpha2"
+
 	"github.com/ory/x/cmdx"
 	"github.com/spf13/cobra"
 
 	"github.com/ory/keto/cmd/client"
 	"github.com/ory/keto/internal/relationtuple"
-	acl "github.com/ory/keto/proto/ory/keto/acl/v1alpha1"
 )
 
 func newDeleteCmd() *cobra.Command {
@@ -19,39 +20,39 @@ func newDeleteCmd() *cobra.Command {
 			"A directory will be traversed and all relation tuples will be deleted.\n" +
 			"Pass the special filename `-` to read from STD_IN.",
 		Args: cobra.MinimumNArgs(1),
-		RunE: transactRelationTuples(acl.RelationTupleDelta_DELETE),
+		RunE: transactRelationTuples(rts.RelationTupleDelta_ACTION_DELETE),
 	}
 	cmd.Flags().AddFlagSet(packageFlags)
 
 	return cmd
 }
 
-func transactRelationTuples(action acl.RelationTupleDelta_Action) func(*cobra.Command, []string) error {
+func transactRelationTuples(action rts.RelationTupleDelta_Action) func(*cobra.Command, []string) error {
 	return func(cmd *cobra.Command, args []string) error {
 		conn, err := client.GetWriteConn(cmd)
 		if err != nil {
 			return err
 		}
 
 		var tuples []*relationtuple.InternalRelationTuple
-		var deltas []*acl.RelationTupleDelta
+		var deltas []*rts.RelationTupleDelta
 		for _, fn := range args {
 			tuple, err := readTuplesFromArg(cmd, fn)
 			if err != nil {
 				return err
 			}
 			for _, t := range tuple {
 				tuples = append(tuples, t)
-				deltas = append(deltas, &acl.RelationTupleDelta{
+				deltas = append(deltas, &rts.RelationTupleDelta{
 					Action:        action,
 					RelationTuple: t.ToProto(),
 				})
 			}
 		}
 
-		cl := acl.NewWriteServiceClient(conn)
+		cl := rts.NewWriteServiceClient(conn)
 
-		_, err = cl.TransactRelationTuples(cmd.Context(), &acl.TransactRelationTuplesRequest{
+		_, err = cl.TransactRelationTuples(cmd.Context(), &rts.TransactRelationTuplesRequest{
 			RelationTupleDeltas: deltas,
 		})
 		if err != nil {

cmd/relationtuple/delete_all.go

@@ -3,14 +3,15 @@ package relationtuple
 import (
 	"fmt"
 
+	rts "github.com/ory/keto/proto/ory/keto/relation_tuples/v1alpha2"
+
 	"github.com/ory/x/pointerx"
 
 	"github.com/ory/x/cmdx"
 	"github.com/ory/x/flagx"
 	"github.com/spf13/cobra"
 
 	"github.com/ory/keto/cmd/client"
-	acl "github.com/ory/keto/proto/ory/keto/acl/v1alpha1"
 )
 
 const (
@@ -53,9 +54,9 @@ func deleteRelationTuplesFromQuery(cmd *cobra.Command, args []string) error {
 		return err
 	}
 	defer conn.Close()
-	cl := acl.NewWriteServiceClient(conn)
-	_, err = cl.DeleteRelationTuples(cmd.Context(), &acl.DeleteRelationTuplesRequest{
-		Query: (*acl.DeleteRelationTuplesRequest_Query)(query),
+	cl := rts.NewWriteServiceClient(conn)
+	_, err = cl.DeleteRelationTuples(cmd.Context(), &rts.DeleteRelationTuplesRequest{
+		Query: (*rts.DeleteRelationTuplesRequest_Query)(query),
 	})
 	if err != nil {
 		_, _ = fmt.Fprintf(cmd.ErrOrStderr(), "Could not make request: %s\n", err)

cmd/relationtuple/get.go

@@ -4,7 +4,7 @@ import (
 	"fmt"
 	"strconv"
 
-	acl "github.com/ory/keto/proto/ory/keto/acl/v1alpha1"
+	rts "github.com/ory/keto/proto/ory/keto/relation_tuples/v1alpha2"
 
 	"github.com/ory/x/flagx"
 
@@ -43,8 +43,8 @@ func registerRelationTupleFlags(flags *pflag.FlagSet) {
 	}
 }
 
-func readQueryFromFlags(cmd *cobra.Command) (*acl.ListRelationTuplesRequest_Query, error) {
-	query := &acl.ListRelationTuplesRequest_Query{
+func readQueryFromFlags(cmd *cobra.Command) (*rts.ListRelationTuplesRequest_Query, error) {
+	query := &rts.ListRelationTuplesRequest_Query{
 		Namespace: flagx.MustGetString(cmd, FlagNamespace),
 		Object:    flagx.MustGetString(cmd, FlagObject),
 		Relation:  flagx.MustGetString(cmd, FlagRelation),
@@ -102,13 +102,13 @@ func getTuples(pageSize *int32, pageToken *string) func(cmd *cobra.Command, _ []
 		}
 		defer conn.Close()
 
-		cl := acl.NewReadServiceClient(conn)
+		cl := rts.NewReadServiceClient(conn)
 		query, err := readQueryFromFlags(cmd)
 		if err != nil {
 			return err
 		}
 
-		resp, err := cl.ListRelationTuples(cmd.Context(), &acl.ListRelationTuplesRequest{
+		resp, err := cl.ListRelationTuples(cmd.Context(), &rts.ListRelationTuplesRequest{
 			Query:     query,
 			PageSize:  *pageSize,
 			PageToken: *pageToken,

contrib/docs-code-samples/expand-api-display-access/00-create-tuples/curl.sh

@@ -19,6 +19,6 @@ files:/photos/mountains.jpg#access@(directories:/photos#access)' | \
     jq "[ .[] | { relation_tuple: . , action: \"insert\" } ]" -c | \
       curl -X PATCH --silent --fail \
         --data @- \
-        http://127.0.0.1:4467/relation-tuples
+        http://127.0.0.1:4467/admin/relation-tuples
 
 echo "Successfully created tuples"

contrib/docs-code-samples/expand-api-display-access/00-create-tuples/index.js

@@ -1,5 +1,5 @@
 import grpc from '@ory/keto-grpc-client/node_modules/@grpc/grpc-js/build/src/index.js'
-import { acl, write, writeService } from '@ory/keto-grpc-client'
+import { relationTuples, write, writeService } from '@ory/keto-grpc-client'
 
 const writeClient = new writeService.WriteServiceClient(
   '127.0.0.1:4467',
@@ -10,19 +10,19 @@ const writeRequest = new write.TransactRelationTuplesRequest()
 
 const insert = (tuple) => {
   const tupleDelta = new write.RelationTupleDelta()
-  tupleDelta.setAction(write.RelationTupleDelta.Action.INSERT)
+  tupleDelta.setAction(write.RelationTupleDelta.Action.ACTION_INSERT)
   tupleDelta.setRelationTuple(tuple)
 
   writeRequest.addRelationTupleDeltas(tupleDelta)
 }
 
 const addSimpleTuple = (namespace, object, relation, user) => {
-  const relationTuple = new acl.RelationTuple()
+  const relationTuple = new relationTuples.RelationTuple()
   relationTuple.setNamespace(namespace)
   relationTuple.setObject(object)
   relationTuple.setRelation(relation)
 
-  const sub = new acl.Subject()
+  const sub = new relationTuples.Subject()
   sub.setId(user)
   relationTuple.setSubject(sub)
 
@@ -43,17 +43,17 @@ addSimpleTuple('directories', '/photos', 'access', 'laura')
   ['files', '/photos/mountains.jpg'],
   ['directories', '/photos']
 ].forEach(([namespace, object]) => {
-  const relationTuple = new acl.RelationTuple()
+  const relationTuple = new relationTuples.RelationTuple()
   relationTuple.setNamespace(namespace)
   relationTuple.setObject(object)
   relationTuple.setRelation('access')
 
-  const subjectSet = new acl.SubjectSet()
+  const subjectSet = new relationTuples.SubjectSet()
   subjectSet.setNamespace(namespace)
   subjectSet.setObject(object)
   subjectSet.setRelation('owner')
 
-  const sub = new acl.Subject()
+  const sub = new relationTuples.Subject()
   sub.setSet(subjectSet)
   relationTuple.setSubject(sub)
 
@@ -63,17 +63,17 @@ addSimpleTuple('directories', '/photos', 'access', 'laura')
 // should be subject set rewrite
 // access on parent means access on child
 ;['/photos/beach.jpg', '/photos/mountains.jpg'].forEach((file) => {
-  const relationTuple = new acl.RelationTuple()
+  const relationTuple = new relationTuples.RelationTuple()
   relationTuple.setNamespace('files')
   relationTuple.setObject(file)
   relationTuple.setRelation('access')
 
-  const subjectSet = new acl.SubjectSet()
+  const subjectSet = new relationTuples.SubjectSet()
   subjectSet.setNamespace('directories')
   subjectSet.setObject('/photos')
   subjectSet.setRelation('access')
 
-  const sub = new acl.Subject()
+  const sub = new relationTuples.Subject()
   sub.setSet(subjectSet)
   relationTuple.setSubject(sub)