From 57d99279230e80c62420a24080166808235c9cae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9o=20Rebert?= Date: Mon, 18 Sep 2023 13:36:58 +0200 Subject: [PATCH 1/3] Add markdown.tmpl file for bufbuild MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Cléo Rebert --- buf.gen.yaml | 2 +- proto/buf.md | 322 ++++++++++++++++++++------------------------ proto/markdown.tmpl | 104 ++++++++++++++ 3 files changed, 249 insertions(+), 179 deletions(-) create mode 100644 proto/markdown.tmpl diff --git a/buf.gen.yaml b/buf.gen.yaml index dad0e79ae..b6ef22cdb 100644 --- a/buf.gen.yaml +++ b/buf.gen.yaml @@ -24,5 +24,5 @@ plugins: - name: doc out: proto - opt: markdown,proto/buf.md + opt: proto/markdown.tmpl,proto/buf.md strategy: all diff --git a/proto/buf.md b/proto/buf.md index 7d89debfe..53fb78388 100644 --- a/proto/buf.md +++ b/proto/buf.md @@ -10,7 +10,6 @@ - [CheckResponse](#ory-keto-opl-v1alpha1-CheckResponse) - [ParseError](#ory-keto-opl-v1alpha1-ParseError) - [SourcePosition](#ory-keto-opl-v1alpha1-SourcePosition) - - [SyntaxService](#ory-keto-opl-v1alpha1-SyntaxService) - [ory/keto/relation_tuples/v1alpha2/relation_tuples.proto](#ory_keto_relation_tuples_v1alpha2_relation_tuples-proto) @@ -22,7 +21,6 @@ - [CheckRequest](#ory-keto-relation_tuples-v1alpha2-CheckRequest) - [CheckResponse](#ory-keto-relation_tuples-v1alpha2-CheckResponse) - - [CheckService](#ory-keto-relation_tuples-v1alpha2-CheckService) - [ory/keto/relation_tuples/v1alpha2/expand_service.proto](#ory_keto_relation_tuples_v1alpha2_expand_service-proto) @@ -30,9 +28,7 @@ - [ExpandRequest](#ory-keto-relation_tuples-v1alpha2-ExpandRequest) - [ExpandResponse](#ory-keto-relation_tuples-v1alpha2-ExpandResponse) - [SubjectTree](#ory-keto-relation_tuples-v1alpha2-SubjectTree) - - [NodeType](#ory-keto-relation_tuples-v1alpha2-NodeType) - - [ExpandService](#ory-keto-relation_tuples-v1alpha2-ExpandService) - [ory/keto/relation_tuples/v1alpha2/namespaces_service.proto](#ory_keto_relation_tuples_v1alpha2_namespaces_service-proto) @@ -40,7 +36,6 @@ - [ListNamespacesRequest](#ory-keto-relation_tuples-v1alpha2-ListNamespacesRequest) - [ListNamespacesResponse](#ory-keto-relation_tuples-v1alpha2-ListNamespacesResponse) - [Namespace](#ory-keto-relation_tuples-v1alpha2-Namespace) - - [NamespacesService](#ory-keto-relation_tuples-v1alpha2-NamespacesService) - [ory/keto/relation_tuples/v1alpha2/read_service.proto](#ory_keto_relation_tuples_v1alpha2_read_service-proto) @@ -48,14 +43,12 @@ - [ListRelationTuplesRequest](#ory-keto-relation_tuples-v1alpha2-ListRelationTuplesRequest) - [ListRelationTuplesRequest.Query](#ory-keto-relation_tuples-v1alpha2-ListRelationTuplesRequest-Query) - [ListRelationTuplesResponse](#ory-keto-relation_tuples-v1alpha2-ListRelationTuplesResponse) - - [ReadService](#ory-keto-relation_tuples-v1alpha2-ReadService) - [ory/keto/relation_tuples/v1alpha2/version.proto](#ory_keto_relation_tuples_v1alpha2_version-proto) - [GetVersionRequest](#ory-keto-relation_tuples-v1alpha2-GetVersionRequest) - [GetVersionResponse](#ory-keto-relation_tuples-v1alpha2-GetVersionResponse) - - [VersionService](#ory-keto-relation_tuples-v1alpha2-VersionService) - [ory/keto/relation_tuples/v1alpha2/write_service.proto](#ory_keto_relation_tuples_v1alpha2_write_service-proto) @@ -66,9 +59,7 @@ - [RelationTupleDelta](#ory-keto-relation_tuples-v1alpha2-RelationTupleDelta) - [TransactRelationTuplesRequest](#ory-keto-relation_tuples-v1alpha2-TransactRelationTuplesRequest) - [TransactRelationTuplesResponse](#ory-keto-relation_tuples-v1alpha2-TransactRelationTuplesResponse) - - [RelationTupleDelta.Action](#ory-keto-relation_tuples-v1alpha2-RelationTupleDelta-Action) - - [WriteService](#ory-keto-relation_tuples-v1alpha2-WriteService) - [Scalar Value Types](#scalar-value-types) @@ -114,6 +105,12 @@ | line | [uint32](#uint32) | | | | column | [uint32](#uint32) | | | + + + + + + ### SyntaxService @@ -124,6 +121,8 @@ The service that checks the syntax of an OPL file. | ----------- | --------------------------------------------------- | ----------------------------------------------------- | -------------------------------- | | Check | [CheckRequest](#ory-keto-opl-v1alpha1-CheckRequest) | [CheckResponse](#ory-keto-opl-v1alpha1-CheckResponse) | Performs a syntax check request. | + +

Top

@@ -142,19 +141,18 @@ Example use cases (namespace is always required): - object only: display a list of all permissions referring to a specific object - relation only: get all groups that have members; get all directories that have content -- object & relation: display all subjects that have a specific permission +- object & relation: display all subjects that have a specific permission relation -- subject & relation: display all groups a subject belongs to; display all +- subject & relation: display all groups a subject belongs to; display all objects a subject has access to -- object & relation & subject: check whether the relation tuple already - exists +- object & relation & subject: check whether the relation tuple already exists -| Field | Type | Label | Description | -| --------- | ----------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- | -| namespace | [string](#string) | optional | The namespace this relation tuple lives in. | -| object | [string](#string) | optional | The object related by this tuple. It is an object in the namespace of the tuple. | -| relation | [string](#string) | optional | The relation between an Object and a Subject. | -| subject | [Subject](#ory-keto-relation_tuples-v1alpha2-Subject) | optional | The subject related by this tuple. A Subject either represents a concrete subject id or a `SubjectSet` that expands to more Subjects. | +| Field | Type | Label | Description | +| --------- | ----------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| namespace | [string](#string) | optional | The namespace this relation tuple lives in. | +| object | [string](#string) | optional | The object related by this tuple.
It is an object in the namespace of the tuple. | +| relation | [string](#string) | optional | The relation between an Object and a Subject. | +| subject | [Subject](#ory-keto-relation_tuples-v1alpha2-Subject) | optional | The subject related by this tuple.
A Subject either represents a concrete subject id or
a `SubjectSet` that expands to more Subjects. | @@ -162,12 +160,12 @@ Example use cases (namespace is always required): RelationTuple defines a relation between an Object and a Subject. -| Field | Type | Label | Description | -| --------- | ----------------------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------- | -| namespace | [string](#string) | | The namespace this relation tuple lives in. | -| object | [string](#string) | | The object related by this tuple. It is an object in the namespace of the tuple. | -| relation | [string](#string) | | The relation between an Object and a Subject. | -| subject | [Subject](#ory-keto-relation_tuples-v1alpha2-Subject) | | The subject related by this tuple. A Subject either represents a concrete subject id or a `SubjectSet` that expands to more Subjects. | +| Field | Type | Label | Description | +| --------- | ----------------------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| namespace | [string](#string) | | The namespace this relation tuple lives in. | +| object | [string](#string) | | The object related by this tuple.
It is an object in the namespace of the tuple. | +| relation | [string](#string) | | The relation between an Object and a Subject. | +| subject | [Subject](#ory-keto-relation_tuples-v1alpha2-Subject) | | The subject related by this tuple.
A Subject either represents a concrete subject id or
a `SubjectSet` that expands to more Subjects. | @@ -176,10 +174,10 @@ RelationTuple defines a relation between an Object and a Subject. Subject is either a concrete subject id or a `SubjectSet` expanding to more Subjects. -| Field | Type | Label | Description | -| ----- | ----------------------------------------------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------- | -| id | [string](#string) | | A concrete id of the subject. | -| set | [SubjectSet](#ory-keto-relation_tuples-v1alpha2-SubjectSet) | | A subject set that expands to more Subjects. More information are available under [concepts](../concepts/15_subjects.mdx). | +| Field | Type | Label | Description | +| ----- | ----------------------------------------------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------- | +| id | [string](#string) | | A concrete id of the subject. | +| set | [SubjectSet](#ory-keto-relation_tuples-v1alpha2-SubjectSet) | | A subject set that expands to more Subjects.
More information are available under [concepts](../concepts/15_subjects.mdx). | @@ -187,11 +185,19 @@ Subjects. SubjectSet refers to all subjects who have the same `relation` on an `object`. -| Field | Type | Label | Description | -| --------- | ----------------- | ----- | ------------------------------------------------------------------------ | -| namespace | [string](#string) | | The namespace of the object and relation referenced in this subject set. | -| object | [string](#string) | | The object related by this subject set. | -| relation | [string](#string) | | The relation between the object and the subjects. | +| Field | Type | Label | Description | +| --------- | ----------------- | ----- | --------------------------------------------------------------------------- | +| namespace | [string](#string) | | The namespace of the object and relation
referenced in this subject set. | +| object | [string](#string) | | The object related by this subject set. | +| relation | [string](#string) | | The relation between the object and the subjects. | + + + + + + + + @@ -206,49 +212,16 @@ SubjectSet refers to all subjects who have the same `relation` on an `object`. The request for a CheckService.Check RPC. Checks whether a specific subject is related to an object. -| Field | Type | Label | Description | -| --------- | ----------------- | ----- | ---------------------------------------------------- | -| namespace | [string](#string) | | **Deprecated.** The namespace to evaluate the check. | - -Note: If you use the expand-API and the check evaluates a RelationTuple -specifying a SubjectSet as subject or due to a rewrite rule in a namespace -config this check request may involve other namespaces automatically. | | object -| [string](#string) | | **Deprecated.** The related object in this check. | | -relation | [string](#string) | | **Deprecated.** The relation between the Object -and the Subject. | | subject | -[Subject](#ory-keto-relation_tuples-v1alpha2-Subject) | | **Deprecated.** The -related subject in this check. | | tuple | -[RelationTuple](#ory-keto-relation_tuples-v1alpha2-RelationTuple) | | | | latest -| [bool](#bool) | | This field is not implemented yet and has no effect. <!-- -Set this field to `true` in case your application needs to authorize depending -on up to date ACLs, also called a "content-change check". - -If set to `true` the `snaptoken` field is ignored, the check is evaluated at the -latest snapshot (globally consistent) and the response includes a snaptoken for -clients to store along with object contents that can be used for subsequent -checks of the same content version. - -Example use case: - You need to authorize a user to modify/delete some resource -and it is unacceptable that if the permission to do that had just been revoked -some seconds ago so that the change had not yet been fully replicated to all -availability zones. --> | | snaptoken | [string](#string) | | This field is -not implemented yet and has no effect. <!-- Optional. Like reads, a check is -always evaluated at a consistent snapshot no earlier than the given snaptoken. - -Leave this field blank if you want to evaluate the check based on eventually -consistent ACLs, benefiting from very low latency, but possibly slightly stale -results. - -If the specified token is too old and no longer known, the server falls back as -if no snaptoken had been specified. - -If not specified the server tries to evaluate the check on the best snapshot -version where it is very likely that ACLs had already been replicated to all -availability zones. --> | | max_depth | [int32](#int32) | | The maximum depth -to search for a relation. - -If the value is less than 1 or greater than the global max-depth then the global -max-depth will be used instead. | +| Field | Type | Label | Description | +| --------- | ----------------------------------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| namespace | [string](#string) | | **Deprecated.** The namespace to evaluate the check.

Note: If you use the expand-API and the check
evaluates a RelationTuple specifying a SubjectSet as
subject or due to a rewrite rule in a namespace config
this check request may involve other namespaces automatically. | +| object | [string](#string) | | **Deprecated.** The related object in this check. | +| relation | [string](#string) | | **Deprecated.** The relation between the Object and the Subject. | +| subject | [Subject](#ory-keto-relation_tuples-v1alpha2-Subject) | | **Deprecated.** The related subject in this check. | +| tuple | [RelationTuple](#ory-keto-relation_tuples-v1alpha2-RelationTuple) | | | +| latest | [bool](#bool) | | This field is not implemented yet and has no effect.
| +| snaptoken | [string](#string) | | This field is not implemented yet and has no effect.
| +| max_depth | [int32](#int32) | | The maximum depth to search for a relation.

If the value is less than 1 or greater than the global
max-depth then the global max-depth will be used instead. | @@ -256,21 +229,16 @@ max-depth will be used instead. | The response for a CheckService.Check rpc. -| Field | Type | Label | Description | -| ------- | ------------- | ----- | ---------------------------------------------------------------------- | -| allowed | [bool](#bool) | | Whether the specified subject (id) is related to the requested object. | +| Field | Type | Label | Description | +| --------- | ----------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| allowed | [bool](#bool) | | Whether the specified subject (id)
is related to the requested object.

It is false by default if no ACL matches. | +| snaptoken | [string](#string) | | This field is not implemented yet and has no effect.
| -It is false by default if no ACL matches. | | snaptoken | [string](#string) | | -This field is not implemented yet and has no effect. <!-- The last known -snapshot token ONLY specified if the request had not specified a snaptoken, -since this performed a "content-change request" and consistently fetched -the last known snapshot token. + -This field is not set if the request had specified a snaptoken! + -If set, clients should cache and use this token for subsequent requests to have -minimal latency, but allow slightly stale responses (only some milliseconds or -seconds). --> | + @@ -286,6 +254,8 @@ This service is part of the | ----------- | --------------------------------------------------------------- | ----------------------------------------------------------------- | -------------------------------- | | Check | [CheckRequest](#ory-keto-relation_tuples-v1alpha2-CheckRequest) | [CheckResponse](#ory-keto-relation_tuples-v1alpha2-CheckResponse) | Performs an authorization check. | + +

Top

@@ -298,28 +268,11 @@ This service is part of the The request for an ExpandService.Expand RPC. Expands the given subject set. -| Field | Type | Label | Description | -| --------- | ----------------------------------------------------- | ----- | ----------------------------------- | -| subject | [Subject](#ory-keto-relation_tuples-v1alpha2-Subject) | | The subject to expand. | -| max_depth | [int32](#int32) | | The maximum depth of tree to build. | - -If the value is less than 1 or greater than the global max-depth then the global -max-depth will be used instead. - -It is important to set this parameter to a meaningful value. Ponder how deep you -really want to display this. | | snaptoken | [string](#string) | | This field is -not implemented yet and has no effect. <!-- Optional. Like reads, a expand is -always evaluated at a consistent snapshot no earlier than the given snaptoken. - -Leave this field blank if you want to expand based on eventually consistent -ACLs, benefiting from very low latency, but possibly slightly stale results. - -If the specified token is too old and no longer known, the server falls back as -if no snaptoken had been specified. - -If not specified the server tries to build the tree on the best snapshot version -where it is very likely that ACLs had already been replicated to all -availability zones. --> | +| Field | Type | Label | Description | +| --------- | ----------------------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| subject | [Subject](#ory-keto-relation_tuples-v1alpha2-Subject) | | The subject to expand. | +| max_depth | [int32](#int32) | | The maximum depth of tree to build.

If the value is less than 1 or greater than the global
max-depth then the global max-depth will be used instead.

It is important to set this parameter to a meaningful
value. Ponder how deep you really want to display this. | +| snaptoken | [string](#string) | | This field is not implemented yet and has no effect.
| @@ -327,36 +280,38 @@ availability zones. --> | The response for a ExpandService.Expand RPC. -| Field | Type | Label | Description | -| ----- | ------------------------------------------------------------- | ----- | ---------------------------------------------------------------------------------------------------- | -| tree | [SubjectTree](#ory-keto-relation_tuples-v1alpha2-SubjectTree) | | The tree the requested subject set expands to. The requested subject set is the subject of the root. | - -This field can be nil in some circumstances. | +| Field | Type | Label | Description | +| ----- | ------------------------------------------------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | +| tree | [SubjectTree](#ory-keto-relation_tuples-v1alpha2-SubjectTree) | | The tree the requested subject set expands to.
The requested subject set is the subject of the root.

This field can be nil in some circumstances. | ### SubjectTree -| Field | Type | Label | Description | -| --------- | ----------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------- | -| node_type | [NodeType](#ory-keto-relation_tuples-v1alpha2-NodeType) | | The type of the node. | -| subject | [Subject](#ory-keto-relation_tuples-v1alpha2-Subject) | | **Deprecated.** The subject this node represents. Deprecated: More information is now available in the tuple field. | -| tuple | [RelationTuple](#ory-keto-relation_tuples-v1alpha2-RelationTuple) | | The relation tuple this node represents. | -| children | [SubjectTree](#ory-keto-relation_tuples-v1alpha2-SubjectTree) | repeated | The children of this node. | +| Field | Type | Label | Description | +| --------- | ----------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- | +| node_type | [NodeType](#ory-keto-relation_tuples-v1alpha2-NodeType) | | The type of the node. | +| subject | [Subject](#ory-keto-relation_tuples-v1alpha2-Subject) | | **Deprecated.** The subject this node represents.
Deprecated: More information is now available in the tuple field. | +| tuple | [RelationTuple](#ory-keto-relation_tuples-v1alpha2-RelationTuple) | | The relation tuple this node represents. | +| children | [SubjectTree](#ory-keto-relation_tuples-v1alpha2-SubjectTree) | repeated | The children of this node.

This is never set if `node_type` == `NODE_TYPE_LEAF`. | -This is never set if `node_type` == `NODE_TYPE_LEAF`. | + ### NodeType -| Name | Number | Description | -| ---------------------- | ------ | ---------------------------------------------------------------------------------------------------------- | -| NODE_TYPE_UNSPECIFIED | 0 | | -| NODE_TYPE_UNION | 1 | This node expands to a union of all children. | -| NODE_TYPE_EXCLUSION | 2 | Not implemented yet. | -| NODE_TYPE_INTERSECTION | 3 | Not implemented yet. | -| NODE_TYPE_LEAF | 4 | This node is a leaf and contains no children. Its subject is a `SubjectID` unless `max_depth` was reached. | +| Name | Number | Description | +| ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------- | +| NODE_TYPE_UNSPECIFIED | 0 | | +| NODE_TYPE_UNION | 1 | This node expands to a union of all children. | +| NODE_TYPE_EXCLUSION | 2 | Not implemented yet. | +| NODE_TYPE_INTERSECTION | 3 | Not implemented yet. | +| NODE_TYPE_LEAF | 4 | This node is a leaf and contains no children.
Its subject is a `SubjectID` unless `max_depth` was reached. | + + + + @@ -372,6 +327,8 @@ This service is part of the | ----------- | ----------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------ | | Expand | [ExpandRequest](#ory-keto-relation_tuples-v1alpha2-ExpandRequest) | [ExpandResponse](#ory-keto-relation_tuples-v1alpha2-ExpandResponse) | Expands the subject set into a tree of subjects. | + +

Top

@@ -400,6 +357,12 @@ Request for ReadService.ListNamespaces RPC. | ----- | ----------------- | ----- | ----------- | | name | [string](#string) | | | + + + + + + ### NamespacesService @@ -413,6 +376,8 @@ This service is part of the | -------------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ---------------- | | ListNamespaces | [ListNamespacesRequest](#ory-keto-relation_tuples-v1alpha2-ListNamespacesRequest) | [ListNamespacesResponse](#ory-keto-relation_tuples-v1alpha2-ListNamespacesResponse) | Lists Namespaces | + +

Top

@@ -426,33 +391,14 @@ This service is part of the Request for ReadService.ListRelationTuples RPC. See `ListRelationTuplesRequest_Query` for how to filter the query. -| Field | Type | Label | Description | -| ----- | ----------------------------------------------------------------------------------------------------- | ----- | ----------------------------------------------------------------------------------- | -| query | [ListRelationTuplesRequest.Query](#ory-keto-relation_tuples-v1alpha2-ListRelationTuplesRequest-Query) | | **Deprecated.** All query constraints are concatenated with a logical AND operator. | - -The RelationTuple list from ListRelationTuplesResponse is ordered from the -newest RelationTuple to the oldest. | | relation_query | -[RelationQuery](#ory-keto-relation_tuples-v1alpha2-RelationQuery) | | | | -expand_mask | [google.protobuf.FieldMask](#google-protobuf-FieldMask) | | This -field is not implemented yet and has no effect. <!-- Optional. The list of -fields to be expanded in the RelationTuple list returned in -`ListRelationTuplesResponse`. Leaving this field unspecified means all fields -are expanded. - -Available fields: "object", "relation", "subject", -"namespace", "subject.id", "subject.namespace", -"subject.object", "subject.relation" --> | | snaptoken | -[string](#string) | | This field is not implemented yet and has no effect. -<!-- Optional. The snapshot token for this read. --> | | page_size | -[int32](#int32) | | Optional. The maximum number of RelationTuples to return in -the response. - -Default: 100 | | page_token | [string](#string) | | Optional. An opaque -pagination token returned from a previous call to `ListRelationTuples` that -indicates where the page should start at. - -An empty token denotes the first page. All successive pages require the token -from the previous page. | +| Field | Type | Label | Description | +| -------------- | ----------------------------------------------------------------------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| query | [ListRelationTuplesRequest.Query](#ory-keto-relation_tuples-v1alpha2-ListRelationTuplesRequest-Query) | | **Deprecated.** All query constraints are concatenated
with a logical AND operator.

The RelationTuple list from ListRelationTuplesResponse
is ordered from the newest RelationTuple to the oldest. | +| relation_query | [RelationQuery](#ory-keto-relation_tuples-v1alpha2-RelationQuery) | | | +| expand_mask | [google.protobuf.FieldMask](#google-protobuf-FieldMask) | | This field is not implemented yet and has no effect.
| +| snaptoken | [string](#string) | | This field is not implemented yet and has no effect.
| +| page_size | [int32](#int32) | | Optional. The maximum number of
RelationTuples to return in the response.

Default: 100 | +| page_token | [string](#string) | | Optional. An opaque pagination token returned from
a previous call to `ListRelationTuples` that
indicates where the page should start at.

An empty token denotes the first page. All successive
pages require the token from the previous page. | @@ -466,12 +412,11 @@ Example use cases (namespace is always required): - object only: display a list of all permissions referring to a specific object - relation only: get all groups that have members; get all directories that have content -- object & relation: display all subjects that have a specific permission +- object & relation: display all subjects that have a specific permission relation -- subject & relation: display all groups a subject belongs to; display all +- subject & relation: display all groups a subject belongs to; display all objects a subject has access to -- object & relation & subject: check whether the relation tuple already - exists +- object & relation & subject: check whether the relation tuple already exists | Field | Type | Label | Description | | --------- | ----------------------------------------------------- | ----- | ------------------------------------ | @@ -486,10 +431,16 @@ Example use cases (namespace is always required): The response of a ReadService.ListRelationTuples RPC. -| Field | Type | Label | Description | -| --------------- | ----------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------ | -| relation_tuples | [RelationTuple](#ory-keto-relation_tuples-v1alpha2-RelationTuple) | repeated | The relationships matching the list request. | -| next_page_token | [string](#string) | | The token required to get the next page. If this is the last page, the token will be the empty string. | +| Field | Type | Label | Description | +| --------------- | ----------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------- | +| relation_tuples | [RelationTuple](#ory-keto-relation_tuples-v1alpha2-RelationTuple) | repeated | The relationships matching the list request. | +| next_page_token | [string](#string) | | The token required to get the next page.
If this is the last page, the token will be the empty string. | + + + + + + @@ -504,6 +455,8 @@ This service is part of the | ------------------ | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------ | | ListRelationTuples | [ListRelationTuplesRequest](#ory-keto-relation_tuples-v1alpha2-ListRelationTuplesRequest) | [ListRelationTuplesResponse](#ory-keto-relation_tuples-v1alpha2-ListRelationTuplesResponse) | Lists ACL relationships. | + +

Top

@@ -526,6 +479,12 @@ Response of the VersionService.GetVersion RPC. | ------- | ----------------- | ----- | -------------------------------------------- | | version | [string](#string) | | The version string of the Ory Keto instance. | + + + + + + ### VersionService @@ -540,6 +499,8 @@ This service is part of the | ----------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------- | | GetVersion | [GetVersionRequest](#ory-keto-relation_tuples-v1alpha2-GetVersionRequest) | [GetVersionResponse](#ory-keto-relation_tuples-v1alpha2-GetVersionResponse) | Returns the version of the Ory Keto instance. | + +

Top

@@ -589,9 +550,9 @@ Write-delta for a TransactRelationTuplesRequest. The request of a WriteService.TransactRelationTuples RPC. -| Field | Type | Label | Description | -| --------------------- | --------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -| relation_tuple_deltas | [RelationTupleDelta](#ory-keto-relation_tuples-v1alpha2-RelationTupleDelta) | repeated | The write delta for the relationships operated in one single transaction. Either all actions succeed or no change takes effect on error. | +| Field | Type | Label | Description | +| --------------------- | --------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| relation_tuple_deltas | [RelationTupleDelta](#ory-keto-relation_tuples-v1alpha2-RelationTupleDelta) | repeated | The write delta for the relationships operated in one single transaction.
Either all actions succeed or no change takes effect on error. | @@ -599,22 +560,25 @@ The request of a WriteService.TransactRelationTuples RPC. The response of a WriteService.TransactRelationTuples rpc. -| Field | Type | Label | Description | -| ---------- | ----------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| snaptokens | [string](#string) | repeated | This field is not implemented yet and has no effect. <!-- The list of the new latest snapshot tokens of the affected RelationTuple, with the same index as specified in the `relation_tuple_deltas` field of the TransactRelationTuplesRequest request. | +| Field | Type | Label | Description | +| ---------- | ----------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| snaptokens | [string](#string) | repeated | This field is not implemented yet and has no effect.
| -If the RelationTupleDelta_Action was DELETE the snaptoken is empty at the same -index. --> | + ### RelationTupleDelta.Action -| Name | Number | Description | -| ------------------ | ------ | ----------------------------------------------------------------------------------------------------------- | -| ACTION_UNSPECIFIED | 0 | Unspecified. The `TransactRelationTuples` RPC ignores this RelationTupleDelta if an action was unspecified. | -| ACTION_INSERT | 1 | Insertion of a new RelationTuple. It is ignored if already existing. | -| ACTION_DELETE | 2 | Deletion of the RelationTuple. It is ignored if it does not exist. | +| Name | Number | Description | +| ------------------ | ------ | ----------------------------------------------------------------------------------------------------------------- | +| ACTION_UNSPECIFIED | 0 | Unspecified.
The `TransactRelationTuples` RPC ignores this
RelationTupleDelta if an action was unspecified. | +| ACTION_INSERT | 1 | Insertion of a new RelationTuple.
It is ignored if already existing. | +| ACTION_DELETE | 2 | Deletion of the RelationTuple.
It is ignored if it does not exist. | + + + + @@ -630,6 +594,8 @@ This service is part of the | TransactRelationTuples | [TransactRelationTuplesRequest](#ory-keto-relation_tuples-v1alpha2-TransactRelationTuplesRequest) | [TransactRelationTuplesResponse](#ory-keto-relation_tuples-v1alpha2-TransactRelationTuplesResponse) | Writes one or more relationships in a single transaction. | | DeleteRelationTuples | [DeleteRelationTuplesRequest](#ory-keto-relation_tuples-v1alpha2-DeleteRelationTuplesRequest) | [DeleteRelationTuplesResponse](#ory-keto-relation_tuples-v1alpha2-DeleteRelationTuplesResponse) | Deletes relationships based on relation query | + + ## Scalar Value Types | .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby | diff --git a/proto/markdown.tmpl b/proto/markdown.tmpl new file mode 100644 index 000000000..2f707c4e2 --- /dev/null +++ b/proto/markdown.tmpl @@ -0,0 +1,104 @@ +# Protocol Documentation + + +## Table of Contents +{{range .Files}} +{{$file_name := .Name}}- [{{.Name}}](#{{.Name | anchor}}) + {{- if .Messages }} + {{range .Messages}} - [{{.LongName}}](#{{.FullName | anchor}}) + {{end}} + {{- end -}} + {{- if .Enums }} + {{range .Enums}} - [{{.LongName}}](#{{.FullName | anchor}}) + {{end}} + {{- end -}} + {{- if .Extensions }} + {{range .Extensions}} - [File-level Extensions](#{{$file_name | anchor}}-extensions) + {{end}} + {{- end -}} + {{- if .Services }} + {{range .Services}} - [{{.Name}}](#{{.FullName | anchor}}) + {{end}} + {{- end -}} +{{end}} +- [Scalar Value Types](#scalar-value-types) + +{{range .Files}} +{{$file_name := .Name}} + +

Top

+ +## {{.Name}} +{{.Description}} + +{{range .Messages}} + + +### {{.LongName}} +{{.Description}} + +{{if .HasFields}} +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +{{range .Fields -}} + | {{.Name}} | [{{.LongType}}](#{{.FullType | anchor}}) | {{.Label}} | {{if (index .Options "deprecated"|default false)}}**Deprecated.** {{end}}{{.Description | replace "\n" "
" | nobr}}{{if .DefaultValue}} Default: {{.DefaultValue}}{{end}} | +{{end}} +{{end}} + +{{if .HasExtensions}} +| Extension | Type | Base | Number | Description | +| --------- | ---- | ---- | ------ | ----------- | +{{range .Extensions -}} + | {{.Name}} | {{.LongType}} | {{.ContainingLongType}} | {{.Number}} | {{.Description | rgeplace "\n" "
" | nobr}}{{if .DefaultValue}} Default: {{.DefaultValue}}{{end}} | +{{end}} +{{end}} + +{{end}} + +{{range .Enums}} + + +### {{.LongName}} +{{.Description}} + +| Name | Number | Description | +| ---- | ------ | ----------- | +{{range .Values -}} + | {{.Name}} | {{.Number}} | {{.Description | replace "\n" "
" | nobr}} | +{{end}} + +{{end}} + +{{if .HasExtensions}} + + +### File-level Extensions +| Extension | Type | Base | Number | Description | +| --------- | ---- | ---- | ------ | ----------- | +{{range .Extensions -}} + | {{.Name}} | {{.LongType}} | {{.ContainingLongType}} | {{.Number}} | {{.Description | replace "\n" "
" | nobr}}{{if .DefaultValue}} Default: `{{.DefaultValue}}`{{end}} | +{{end}} +{{end}} + +{{range .Services}} + + +### {{.Name}} +{{.Description}} + +| Method Name | Request Type | Response Type | Description | +| ----------- | ------------ | ------------- | ------------| +{{range .Methods -}} + | {{.Name}} | [{{.RequestLongType}}](#{{.RequestFullType | anchor}}){{if .RequestStreaming}} stream{{end}} | [{{.ResponseLongType}}](#{{.ResponseFullType | anchor}}){{if .ResponseStreaming}} stream{{end}} | {{.Description | replace "\n" "
" | nobr}} | +{{end}} +{{end}} + +{{end}} + +## Scalar Value Types + +| .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby | +| ----------- | ----- | --- | ---- | ------ | -- | -- | --- | ---- | +{{range .Scalars -}} + | {{.ProtoType}} | {{.Notes}} | {{.CppType}} | {{.JavaType}} | {{.PythonType}} | {{.GoType}} | {{.CSharp}} | {{.PhpType}} | {{.RubyType}} | +{{end}} \ No newline at end of file From fef3e346e98596d8999853ccd890e9dc23eec00c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9o=20Rebert?= Date: Mon, 18 Sep 2023 14:10:16 +0200 Subject: [PATCH 2/3] fix typo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Cléo Rebert --- proto/markdown.tmpl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proto/markdown.tmpl b/proto/markdown.tmpl index 2f707c4e2..159de5f2e 100644 --- a/proto/markdown.tmpl +++ b/proto/markdown.tmpl @@ -49,7 +49,7 @@ | Extension | Type | Base | Number | Description | | --------- | ---- | ---- | ------ | ----------- | {{range .Extensions -}} - | {{.Name}} | {{.LongType}} | {{.ContainingLongType}} | {{.Number}} | {{.Description | rgeplace "\n" "
" | nobr}}{{if .DefaultValue}} Default: {{.DefaultValue}}{{end}} | + | {{.Name}} | {{.LongType}} | {{.ContainingLongType}} | {{.Number}} | {{.Description | replace "\n" "
" | nobr}}{{if .DefaultValue}} Default: {{.DefaultValue}}{{end}} | {{end}} {{end}} From 5f48f1df5ff4c68e11ceca6809f7721d90065de9 Mon Sep 17 00:00:00 2001 From: Patrik Date: Fri, 22 Sep 2023 14:27:27 +0200 Subject: [PATCH 3/3] docs: add issue reference --- proto/buf.md | 3 +++ proto/markdown.tmpl | 3 +++ 2 files changed, 6 insertions(+) diff --git a/proto/buf.md b/proto/buf.md index 53fb78388..c973b9e52 100644 --- a/proto/buf.md +++ b/proto/buf.md @@ -1,3 +1,6 @@ + + + # Protocol Documentation diff --git a/proto/markdown.tmpl b/proto/markdown.tmpl index 159de5f2e..608892b94 100644 --- a/proto/markdown.tmpl +++ b/proto/markdown.tmpl @@ -1,3 +1,6 @@ + + + # Protocol Documentation