Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Support for array of permissions in lookup entity v2 #1691

Open
wants to merge 16 commits into
base: master
Choose a base branch
from
Open

Support for array of permissions in lookup entity v2 #1691

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
db07226
feat: add support for list of permissions in lookup-entity
Aug 14, 2024
14f612c
refactor: update variable name
Aug 14, 2024
d5b5fcd
fix: lookup test cases
tolgaOzen Aug 15, 2024
e76ab81
resolve conflicts
Aug 15, 2024
d9593b3
Merge branch 'support-for-array-of-permissions-in-lookup-entity' of g…
Aug 15, 2024
d2a5b08
fix: linked schema test case 19
Aug 15, 2024
e1c59ea
merge: latest master
ucatbas Sep 17, 2024
e3d94fd
feat: bulk-lookup-entity
ucatbas Sep 18, 2024
4694441
Merge branch 'master' into support-for-array-of-permissions-in-lookup…
ucatbas Sep 18, 2024
ccb597f
feat: create new endpoint for list of permissions in lookup entity
Sep 30, 2024
d4f9b4b
Merge branch 'master' into support-for-array-of-permissions-in-lookup…
Sep 30, 2024
2ee4d81
fix: fixed compilable error
Sep 30, 2024
59f4462
fix: fixed lookup test cases
Oct 5, 2024
a17f7ee
fix: fixed lookup api docs
Oct 6, 2024
1d48d67
fix: fixed resolve merge conflicts
Oct 6, 2024
6f1bd1b
Merge branch 'support-for-array-of-permissions-in-lookup-entity' into…
Oct 12, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
254 changes: 254 additions & 0 deletions docs/api-reference/apidocs.swagger.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -765,6 +765,124 @@
]
}
},
"/v1/tenants/{tenant_id}/permissions/lookup-entities": {
"post": {
"summary": "lookup entities",
"operationId": "permissions.lookupEntities",
"responses": {
"200": {
"description": "A successful response.",
"schema": {
"$ref": "#/definitions/PermissionsLookupEntityResponse"
}
},
"default": {
"description": "An unexpected error response.",
"schema": {
"$ref": "#/definitions/Status"
}
}
},
"parameters": [
{
"name": "tenant_id",
"description": "Identifier of the tenant, if you are not using multi-tenancy (have only one tenant) use pre-inserted tenant \u003ccode\u003et1\u003c/code\u003e for this field. Required, and must match the pattern \\“[a-zA-Z0-9-,]+\\“, max 64 bytes.",
"in": "path",
"required": true,
"type": "string"
},
{
"name": "body",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/LookupEntitiesBody"
}
}
],
"tags": [
"Permission"
],
"x-codeSamples": [
{
"label": "go",
"lang": "go",
"source": "cr, err := client.Permission.LookupEntities(context.Background(), \u0026v1.PermissionsLookupEntityRequest{\n TenantId: \"t1\",\n Metadata: \u0026v1.PermissionLookupEntityRequestMetadata{\n SnapToken: \"\",\n SchemaVersion: \"\",\n Depth: 20,\n },\n EntityType: \"document\",\n Permissions: [\"edit\"],\n Subject: \u0026v1.Subject{\n Type: \"user\",\n Id: \"1\",\n }\n PageSize: 20,\n ContinuousToken: \"\",\n})"
},
{
"label": "node",
"lang": "javascript",
"source": "client.permission.lookupEntities({\n tenantId: \"t1\",\n metadata: {\n snapToken: \"\",\n schemaVersion: \"\",\n depth: 20\n },\n entity_type: \"document\",\n permissions: [\"edit\"],\n subject: {\n type: \"user\",\n id: \"1\"\n },\n page_size: 20,\n continuous_token: \"\"\n}).then((response) =\u003e {\n console.log(response.entity_ids)\n})"
},
{
"label": "cURL",
"lang": "curl",
"source": "curl --location --request POST 'localhost:3476/v1/tenants/{tenant_id}/permissions/lookup-entities' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"metadata\":{\n \"snap_token\": \"\",\n \"schema_version\": \"\",\n \"depth\": 20\n },\n \"entity_type\": \"document\",\n \"permissions\": [\"edit\"],\n \"subject\": {\n \"type\":\"user\",\n \"id\":\"1\"\n },\n \"page_size\": 20,\n \"continuous_token\": \"\",\n}'"
}
]
}
},
"/v1/tenants/{tenant_id}/permissions/lookup-entities-stream": {
"post": {
"summary": "lookup entities stream",
"operationId": "permissions.lookupEntitiesStream",
"responses": {
"200": {
"description": "A successful response.(streaming responses)",
"schema": {
"type": "object",
"properties": {
"result": {
"$ref": "#/definitions/PermissionsLookupEntityStreamResponse"
},
"error": {
"$ref": "#/definitions/Status"
}
},
"title": "Stream result of PermissionsLookupEntityStreamResponse"
}
},
"default": {
"description": "An unexpected error response.",
"schema": {
"$ref": "#/definitions/Status"
}
}
},
"parameters": [
{
"name": "tenant_id",
"description": "Identifier of the tenant, if you are not using multi-tenancy (have only one tenant) use pre-inserted tenant \u003ccode\u003et1\u003c/code\u003e for this field. Required, and must match the pattern \\“[a-zA-Z0-9-,]+\\“, max 64 bytes.",
"in": "path",
"required": true,
"type": "string"
},
{
"name": "body",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/LookupEntitiesStreamBody"
}
}
],
"tags": [
"Permission"
],
"x-codeSamples": [
{
"label": "go",
"lang": "go",
"source": "str, err := client.Permission.LookupEntitiesStream(context.Background(), \u0026v1.PermissionsLookupEntityRequest{\n Metadata: \u0026v1.PermissionsLookupEntityRequestMetadata{\n SnapToken: \"\",\n SchemaVersion: \"\",\n Depth: 50,\n },\n EntityType: \"document\",\n Permissions: [\"view\"],\n Subject: \u0026v1.Subject{\n Type: \"user\",\n Id: \"1\",\n },\n PageSize: 20,\n ContinuousToken: \"\",\n})\n\n// handle stream response\nfor {\n res, err := str.Recv()\n\n if err == io.EOF {\n break\n }\n\n // res.EntityId, res.Permission\n}"
},
{
"label": "node",
"lang": "javascript",
"source": "const permify = require(\"@permify/permify-node\");\nconst {PermissionsLookupEntityStreamResponse} = require(\"@permify/permify-node/dist/src/grpc/generated/base/v1/service\");\n\nfunction main() {\n const client = new permify.grpc.newClient({\n endpoint: \"localhost:3478\",\n });\n\n let res = client.permission.lookupEntitiesStream({\n metadata: {\n snapToken: \"\",\n schemaVersion: \"\",\n depth: 20\n },\n entityType: \"document\",\n permissions: [\"view\"],\n subject: {\n type: \"user\",\n id: \"1\"\n },\n page_size: 20,\n continuous_token: \"\"\n });\n\n handle(res);\n}\n\nasync function handle(res: AsyncIterable\u003cPermissionsLookupEntityStreamResponse\u003e) {\n for await (const response of res) {\n // response.entityId, response.permission\n }\n}"
}
]
}
},
"/v1/tenants/{tenant_id}/permissions/lookup-entity": {
"post": {
"summary": "lookup entity",
Expand Down Expand Up @@ -2036,6 +2154,18 @@
},
"description": "EntityFilter is used to filter entities based on the type and ids."
},
"EntityIds": {
"type": "object",
"properties": {
"ids": {
"type": "array",
"items": {
"type": "string"
},
"title": "entitiy Ids"
}
}
},
"Entry": {
"type": "object",
"properties": {
Expand Down Expand Up @@ -2231,6 +2361,96 @@
},
"description": "List type with typed elements, e.g. `list\u003cexample.proto.MyMessage\u003e`."
},
"LookupEntitiesBody": {
"type": "object",
"properties": {
"metadata": {
"$ref": "#/definitions/PermissionLookupEntityRequestMetadata",
"description": "Metadata associated with this request, required."
},
"entity_type": {
"type": "string",
"description": "Type of the entity to lookup, required, must start with a letter and can include alphanumeric and underscore, max 64 bytes."
},
"permissions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Name of the permission to check, required, must start with a letter and can include alphanumeric and underscore, max 64 bytes."
},
"subject": {
"$ref": "#/definitions/Subject",
"description": "Subject for which to check the permission, required."
},
"context": {
"$ref": "#/definitions/Context",
"description": "Context associated with this request."
},
"scope": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/StringArrayValue"
},
"description": "Scope: A map that associates entity types with lists of identifiers. Each entry\nhelps filter requests by specifying which entities are relevant to the operation."
},
"page_size": {
"type": "integer",
"format": "int64",
"description": "page_size is the number of entities to be returned in the response.\nThe value should be between 1 and 100."
},
"continuous_token": {
"type": "string",
"description": "continuous_token is an optional parameter used for pagination.\nIt should be the value received in the previous response."
}
},
"description": "PermissionsLookupEntityRequest is the request message for the LookupEntities method in the Permission service."
Comment on lines +2364 to +2407
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codebase verification

Inconsistency Detected in LookupEntitiesBody Definition

The description within LookupEntitiesBody incorrectly references PermissionsLookupEntityRequest. This inconsistency can lead to confusion and should be corrected to maintain clarity in the API documentation.

  • Action Required: Update the description to use "LookupEntitiesBody" instead of "PermissionsLookupEntityRequest".

    Example:

    "description": "LookupEntitiesBody is the request message for the LookupEntities method in the Permission service."

  • Further Investigation: Review other parts of the codebase to ensure that PermissionsLookupEntityRequest is no longer in use or appropriately updated to prevent residual inconsistencies.

🔗 Analysis chain

Review of LookupEntitiesBody definition

The LookupEntitiesBody definition has been added to support the new /lookup-entities endpoint. Overall, the structure is well-defined and includes necessary fields for the lookup operation. However, there are a few points to address:

  1. The permissions field is an array, which differs from the single permission field in similar endpoints. This change allows for checking multiple permissions at once, which can be more efficient. However, ensure that this is intentional and documented clearly for API consumers.

  2. The scope field is a new addition. While it's described as a map for filtering entities, it might benefit from a more detailed explanation or examples in the documentation to clarify its usage.

  3. The description at the end of the definition refers to "PermissionsLookupEntityRequest", which is inconsistent with the actual name "LookupEntitiesBody". This should be corrected to maintain consistency.

Consider the following improvements:

  1. Update the description to use "LookupEntitiesBody" instead of "PermissionsLookupEntityRequest".
  2. Add more detailed documentation for the scope field, possibly including examples of its usage.
  3. Ensure that the API documentation clearly explains the difference between this endpoint (which accepts multiple permissions) and other similar endpoints that might only accept a single permission.

Let's verify the consistency of the LookupEntitiesBody definition:

This script will help us identify any inconsistencies in naming, verify the permissions field definition, and check the usage of the new scope field across the API specification.

🏁 Scripts executed

The following scripts were executed for the analysis:

Script:

#!/bin/bash

# Check for any inconsistencies in naming
echo "Checking for naming inconsistencies:"
grep -n "PermissionsLookupEntityRequest" docs/api-reference/apidocs.swagger.json

# Verify that the permissions field is consistently defined as an array
echo "\nChecking permissions field definition:"
grep -n '"permissions":' docs/api-reference/apidocs.swagger.json

# Check for any other definitions using the scope field
echo "\nChecking usage of scope field in other definitions:"
grep -n '"scope":' docs/api-reference/apidocs.swagger.json

Length of output: 3643

},
"LookupEntitiesStreamBody": {
"type": "object",
"properties": {
"metadata": {
"$ref": "#/definitions/PermissionLookupEntityRequestMetadata",
"description": "Metadata associated with this request, required."
},
"entity_type": {
"type": "string",
"description": "Type of the entity to lookup, required, must start with a letter and can include alphanumeric and underscore, max 64 bytes."
},
"permissions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Name of the permission to check, required, must start with a letter and can include alphanumeric and underscore, max 64 bytes."
},
"subject": {
"$ref": "#/definitions/Subject",
"description": "Subject for which to check the permission, required."
},
"context": {
"$ref": "#/definitions/Context",
"description": "Context associated with this request."
},
"scope": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/StringArrayValue"
},
"description": "Scope: A map that associates entity types with lists of identifiers. Each entry\nhelps filter requests by specifying which entities are relevant to the operation."
},
"page_size": {
"type": "integer",
"format": "int64",
"description": "page_size is the number of entities to be returned in the response.\nThe value should be between 1 and 100."
},
"continuous_token": {
"type": "string",
"description": "continuous_token is an optional parameter used for pagination.\nIt should be the value received in the previous response."
}
},
"description": "PermissionsLookupEntityRequest is the request message for the LookupEntities method in the Permission service."
},
"LookupEntityBody": {
"type": "object",
"properties": {
Expand Down Expand Up @@ -2647,6 +2867,40 @@
},
"description": "PermissionSubjectPermissionResponse is the response message for the SubjectPermission method in the Permission service."
},
"PermissionsLookupEntityResponse": {
"type": "object",
"properties": {
"entity_ids": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/EntityIds"
},
"description": "List of identifiers for entities that match the lookup."
},
"continuous_token": {
"type": "string",
"description": "continuous_token is a string that can be used to paginate and retrieve the next set of results."
}
},
"description": "PermissionLookupEntityResponse is the response message for the LookupEntity method in the Permission service."
},
"PermissionsLookupEntityStreamResponse": {
"type": "object",
"properties": {
"entity_id": {
"type": "string",
"description": "Identifier for an entity that matches the lookup."
},
"permission": {
"type": "string",
"title": "The name of the permission for which the specified entity_id has access"
},
"continuous_token": {
"type": "string",
"description": "continuous_token is a string that can be used to paginate and retrieve the next set of results."
}
}
},
"PrimitiveType": {
"type": "string",
"enum": [
Expand Down
Loading
Loading