engines.*ExpandEngine.expandDirectAttribute - Code Metrics - Permify/permify - Measure and Improve Code Quality continuously with Scrutinizer

engines.*ExpandEngine.expandDirectAttribute B
last analyzed 2025-06-13 13:06 UTC

↳ Parent: internal/engines/expand.go
Complexity

Conditions
Size

Total Lines	62
Code Lines	40
Duplication

Lines	0
Ratio	0 %
Importance

Changes
Metric	Value
cc	7
eloc	40
nop	1
dl	0
loc	62
rs	7.52
c	0
b	0
f	0
How to fix Long Method

package engines

import (
	"context"
	"errors"

	"google.golang.org/protobuf/types/known/anypb"

	"github.com/Permify/permify/internal/schema"
	"github.com/Permify/permify/internal/storage"
	storageContext "github.com/Permify/permify/internal/storage/context"
	"github.com/Permify/permify/pkg/database"
	base "github.com/Permify/permify/pkg/pb/base/v1"
	"github.com/Permify/permify/pkg/tuple"
)

// ExpandEngine - This comment is describing a type called ExpandEngine. The ExpandEngine type contains two fields: schemaReader,
// which is a storage.SchemaReader object, and relationshipReader, which is a storage.RelationshipReader object.
// The ExpandEngine type is used to expand permission scopes based on a given user ID and a set of permission requirements.
type ExpandEngine struct {
	// schemaReader is responsible for reading schema information
	schemaReader storage.SchemaReader
	// relationshipReader is responsible for reading relationship information
	dataReader storage.DataReader
}

// NewExpandEngine - This function creates a new instance of ExpandEngine by taking a SchemaReader and a RelationshipReader as
// parameters and returning a pointer to the created instance. The SchemaReader is used to read schema definitions, while the
// RelationshipReader is used to read relationship definitions.
func NewExpandEngine(sr storage.SchemaReader, rr storage.DataReader) *ExpandEngine {
	return &ExpandEngine{
		schemaReader: sr,
		dataReader:   rr,
	}
}

// Expand - This is the Run function of the ExpandEngine type, which takes a context, a PermissionExpandRequest,
// and returns a PermissionExpandResponse and an error.
// The function begins by starting a new OpenTelemetry span, with the name "permissions.expand.execute".
// It then checks if a snap token and schema version are included in the request. If not, it retrieves the head
// snapshot and head schema version, respectively, from the appropriate repository.
//
// Finally, the function calls the expand function of the ExpandEngine type with the context, PermissionExpandRequest,
// and false value, and returns the resulting PermissionExpandResponse and error. If there is an error, the span records
// the error and sets the status to indicate an error.
func (engine *ExpandEngine) Expand(ctx context.Context, request *base.PermissionExpandRequest) (response *base.PermissionExpandResponse, err error) {
	resp := engine.expand(ctx, request)
	if resp.Err != nil {
		return nil, resp.Err
	}
	return resp.Response, resp.Err
}

// ExpandResponse is a struct that contains the response and error returned from
// the expand function in the ExpandEngine. It is used to return the response and
// error together as a single object.
type ExpandResponse struct {
	Response *base.PermissionExpandResponse
	Err      error
}

// ExpandFunction represents a function that expands the schema and relationships
// of a request and sends the response through the provided channel.
type ExpandFunction func(ctx context.Context, expandChain chan<- ExpandResponse)

// ExpandCombiner represents a function that combines the results of multiple
// ExpandFunction calls into a single ExpandResponse.
type ExpandCombiner func(ctx context.Context, entity *base.Entity, permission string, arguments []*base.Argument, functions []ExpandFunction) ExpandResponse

// 'expand' is a method of ExpandEngine which takes a context and a PermissionExpandRequest,
// and returns an ExpandResponse. This function is the main entry point for expanding permissions.
func (engine *ExpandEngine) expand(ctx context.Context, request *base.PermissionExpandRequest) ExpandResponse {
	var fn ExpandFunction // Declare an ExpandFunction variable.

	// Read entity definition based on the entity type in the request.
	en, _, err := engine.schemaReader.ReadEntityDefinition(ctx, request.GetTenantId(), request.GetEntity().GetType(), request.GetMetadata().GetSchemaVersion())
	if err != nil {
		// If an error occurred while reading entity definition, return an ExpandResponse with the error.
		return ExpandResponse{Err: err}
	}

	var tor base.EntityDefinition_Reference
	// Get the type of reference by name in the entity definition.
	tor, _ = schema.GetTypeOfReferenceByNameInEntityDefinition(en, request.GetPermission())

	// Depending on the type of reference, execute different branches of code.
	switch tor {
	case base.EntityDefinition_REFERENCE_PERMISSION:
		// If the reference is a permission, get the permission by name from the entity definition.
		permission, err := schema.GetPermissionByNameInEntityDefinition(en, request.GetPermission())
		if err != nil {
			// If an error occurred while getting the permission, return an ExpandResponse with the error.
			return ExpandResponse{Err: err}
		}

		// Get the child of the permission.
		child := permission.GetChild()
		// If the child has a rewrite rule, use the 'expandRewrite' method.
		if child.GetRewrite() != nil {
			fn = engine.expandRewrite(ctx, request, child.GetRewrite())
		} else {
			// If the child doesn't have a rewrite rule, use the 'expandLeaf' method.
			fn = engine.expandLeaf(request, child.GetLeaf())
		}
	case base.EntityDefinition_REFERENCE_ATTRIBUTE:
		// If the reference is an attribute, use the 'expandDirectAttribute' method.
		fn = engine.expandDirectAttribute(request)
	case base.EntityDefinition_REFERENCE_RELATION:
		// If the reference is a relation, use the 'expandDirectRelation' method.
		fn = engine.expandDirectRelation(request)
	default:
		// If the reference is neither permission, attribute, nor relation, use the 'expandCall' method.
		fn = engine.expandDirectCall(request)
	}

	if fn == nil {
		// If no expand function was set, return an ExpandResponse with an error.
		return ExpandResponse{Err: errors.New(base.ErrorCode_ERROR_CODE_UNDEFINED_CHILD_KIND.String())}
	}

	// Execute the expand function with the root context.
	return expandRoot(ctx, fn)
}

// 'expandRewrite' is a method of ExpandEngine which takes a context, a PermissionExpandRequest,
// and a rewrite rule. It returns an ExpandFunction which represents the expansion of the rewrite rule.
func (engine *ExpandEngine) expandRewrite(ctx context.Context, request *base.PermissionExpandRequest, rewrite *base.Rewrite) ExpandFunction {
	// The rewrite rule can have different operations: UNION, INTERSECTION, EXCLUSION.
	// Depending on the operation type, it calls different methods.
	switch rewrite.GetRewriteOperation() {
	// If the operation is UNION, call the 'setChild' method with 'expandUnion' as the expand function.
	case *base.Rewrite_OPERATION_UNION.Enum():
		return engine.setChild(ctx, request, rewrite.GetChildren(), expandUnion)

	// If the operation is INTERSECTION, call the 'setChild' method with 'expandIntersection' as the expand function.
	case *base.Rewrite_OPERATION_INTERSECTION.Enum():
		return engine.setChild(ctx, request, rewrite.GetChildren(), expandIntersection)

	// If the operation is EXCLUSION, call the 'setChild' method with 'expandExclusion' as the expand function.
	case *base.Rewrite_OPERATION_EXCLUSION.Enum():
		return engine.setChild(ctx, request, rewrite.GetChildren(), expandExclusion)

	// If the operation is not any of the defined types, return an error.
	default:
		return expandFail(errors.New(base.ErrorCode_ERROR_CODE_UNDEFINED_CHILD_TYPE.String()))
	}
}

// 'expandLeaf' is a method of ExpandEngine which takes a PermissionExpandRequest and a leaf object.
// It returns an ExpandFunction, a function which performs the action associated with a given leaf type.
func (engine *ExpandEngine) expandLeaf(
	request *base.PermissionExpandRequest,
	leaf *base.Leaf,
) ExpandFunction {
	// The leaf object can have different types, each associated with a different expansion function.
	// Depending on the type of the leaf, different expansion functions are returned.
	switch op := leaf.GetType().(type) {

	// If the type of the leaf is TupleToUserSet, the method 'expandTupleToUserSet' is called.
	case *base.Leaf_TupleToUserSet:
		return engine.expandTupleToUserSet(request, op.TupleToUserSet)

	// If the type of the leaf is ComputedUserSet, the method 'expandComputedUserSet' is called.
	case *base.Leaf_ComputedUserSet:
		return engine.expandComputedUserSet(request, op.ComputedUserSet)

	// If the type of the leaf is ComputedAttribute, the method 'expandComputedAttribute' is called.
	case *base.Leaf_ComputedAttribute:
		return engine.expandComputedAttribute(request, op.ComputedAttribute)

	// If the type of the leaf is Call, the method 'expandCall' is called.
	case *base.Leaf_Call:
		return engine.expandCall(request, op.Call)

	// If the leaf type is none of the above, an error is returned.
	default:
		return expandFail(errors.New(base.ErrorCode_ERROR_CODE_UNDEFINED_CHILD_TYPE.String()))
	}
}

// 'setChild' is a method of the ExpandEngine struct, which aims to create and set an ExpandFunction
// for each child in the provided children array. These functions are derived from the type of child
// (either a rewrite or a leaf) and are passed to a provided 'combiner' function.
func (engine *ExpandEngine) setChild(
	ctx context.Context,
	request *base.PermissionExpandRequest,
	children []*base.Child,
	combiner ExpandCombiner,
) ExpandFunction {
	// Declare an array to hold ExpandFunctions.
	var functions []ExpandFunction

	// Iterate through each child in the provided array.
	for _, child := range children {
		// Based on the type of child, append the appropriate ExpandFunction to the functions array.
		switch child.GetType().(type) {

		// If the child is a 'rewrite' type, use the 'expandRewrite' function.
		case *base.Child_Rewrite:
			functions = append(functions, engine.expandRewrite(ctx, request, child.GetRewrite()))

		// If the child is a 'leaf' type, use the 'expandLeaf' function.
		case *base.Child_Leaf:
			functions = append(functions, engine.expandLeaf(request, child.GetLeaf()))

		// If the child type is not recognized, return an error.
		default:
			return expandFail(errors.New(base.ErrorCode_ERROR_CODE_UNDEFINED_CHILD_KIND.String()))
		}
	}

	// Return an ExpandFunction that will pass the prepared functions to the combiner when called.
	return func(ctx context.Context, resultChan chan<- ExpandResponse) {
		resultChan <- combiner(ctx, request.GetEntity(), request.GetPermission(), request.GetArguments(), functions)
	}
}

// expandDirectRelation Expands the target permission for direct subjects, i.e., those whose subject entity has the same type as the target
// entity type and whose subject relation is not an ellipsis. It queries the relationship store for relationships that
// match the target permission, and for each matching relationship, calls Expand on the corresponding subject entity
// and relation. If there are no matching relationships, it returns a leaf node of the expand tree containing the direct
// subjects. If there are matching relationships, it computes the union of the results of calling Expand on each matching
// relationship's subject entity and relation, and attaches the resulting expand nodes as children of a union node in
// the expand tree. Finally, it returns the top-level expand node.
func (engine *ExpandEngine) expandDirectRelation(request *base.PermissionExpandRequest) ExpandFunction {
	return func(ctx context.Context, expandChan chan<- ExpandResponse) {
		// Define a TupleFilter. This specifies which tuples we're interested in.
		// We want tuples that match the entity type and ID from the request, and have a specific relation.
		filter := &base.TupleFilter{
			Entity: &base.EntityFilter{
				Type: request.GetEntity().GetType(),
				Ids:  []string{request.GetEntity().GetId()},
			},
			Relation: request.GetPermission(),
		}

		// Use the filter to query for relationships in the given context.
		// NewContextualRelationships() creates a ContextualRelationships instance from tuples in the request.
		// QueryRelationships() then uses the filter to find and return matching relationships.
		cti, err := storageContext.NewContextualTuples(request.GetContext().GetTuples()...).QueryRelationships(filter, database.NewCursorPagination())
		if err != nil {
			// If an error occurred while querying, return a "denied" response and the error.
			expandChan <- expandFailResponse(err)
			return
		}

		// Query the relationships for the entity in the request.
		// TupleFilter helps in filtering out the relationships for a specific entity and a permission.
		var rit *database.TupleIterator
		rit, err = engine.dataReader.QueryRelationships(ctx, request.GetTenantId(), filter, request.GetMetadata().GetSnapToken(), database.NewCursorPagination())
		if err != nil {
			expandChan <- expandFailResponse(err)
			return
		}

		// Create a new UniqueTupleIterator from the two TupleIterators.
		// NewUniqueTupleIterator() ensures that the iterator only returns unique tuples.
		it := database.NewUniqueTupleIterator(rit, cti)

		foundedUserSets := database.NewSubjectCollection()
		foundedUsers := database.NewSubjectCollection()

		// it represents an iterator over some collection of subjects.
		for it.HasNext() {
			// Get the next tuple's subject.
			next, ok := it.GetNext()
			if !ok {
				break
			}
			subject := next.GetSubject()

			if tuple.IsDirectSubject(subject) || subject.GetRelation() == tuple.ELLIPSIS {
				foundedUsers.Add(subject)
			} else {
				foundedUserSets.Add(subject)
			}
		}

		// If there are no founded user sets, create and send an expand response.
		if len(foundedUserSets.GetSubjects()) == 0 {
			expandChan <- ExpandResponse{
				Response: &base.PermissionExpandResponse{
					Tree: &base.Expand{
						Entity:     request.GetEntity(),
						Permission: request.GetPermission(),
						Arguments:  request.GetArguments(),
						Node: &base.Expand_Leaf{
							Leaf: &base.ExpandLeaf{
								Type: &base.ExpandLeaf_Subjects{
									Subjects: &base.Subjects{
										Subjects: foundedUsers.GetSubjects(),
									},
								},
							},
						},
					},
				},
			}
			return
		}

		// Define a slice of ExpandFunction.
		var expandFunctions []ExpandFunction

		// Create an iterator for the foundedUserSets.
		si := foundedUserSets.CreateSubjectIterator()

		// Iterate over the foundedUserSets.
		for si.HasNext() {
			sub := si.GetNext()
			// For each subject, append a new function to the expandFunctions slice.
			expandFunctions = append(expandFunctions, func(ctx context.Context, resultChan chan<- ExpandResponse) {
				resultChan <- engine.expand(ctx, &base.PermissionExpandRequest{
					TenantId: request.GetTenantId(),
					Entity: &base.Entity{
						Type: sub.GetType(),
						Id:   sub.GetId(),
					},
					Permission: sub.GetRelation(),
					Metadata:   request.GetMetadata(),
					Context:    request.GetContext(),
				})
			})
		}

		// Use the expandUnion function to process the expandFunctions.
		result := expandUnion(ctx, request.GetEntity(), request.GetPermission(), request.GetArguments(), expandFunctions)

		// If an error occurred, send a failure response and return.
		if result.Err != nil {
			expandChan <- expandFailResponse(result.Err)
			return
		}

		// Get the Expand field from the response tree.
		expand := result.Response.GetTree().GetExpand()

		// Add a new child to the Expand field.
		expand.Children = append(expand.Children, &base.Expand{
			Entity:     request.GetEntity(),
			Permission: request.GetPermission(),
			Arguments:  request.GetArguments(),
			Node: &base.Expand_Leaf{
				Leaf: &base.ExpandLeaf{
					Type: &base.ExpandLeaf_Subjects{
						Subjects: &base.Subjects{
							Subjects: append(foundedUsers.GetSubjects(), foundedUserSets.GetSubjects()...),
						},
					},
				},
			},
		})

		expandChan <- result
	}
}

// expandTupleToUserSet is an ExpandFunction that retrieves relationships matching the given entity and relation filter,
// and expands each relationship into a set of users that have the corresponding tuple values. If the relationship subject
// contains an ellipsis (i.e. "..."), the function will recursively expand the computed user set for that entity. The
// exclusion parameter determines whether the resulting user set should be included or excluded from the final permission set.
// The function returns an ExpandFunction that sends the expanded user set to the provided channel.
//
// Parameters:
//   - ctx: context.Context for the request
//   - request: base.PermissionExpandRequest containing the request parameters
//   - ttu: base.TupleToUserSet containing the tuple filter and computed user set
//   - exclusion: bool indicating whether to exclude or include the resulting user set in the final permission set
//
// Returns:
//   - ExpandFunction that sends the expanded user set to the provided channel
func (engine *ExpandEngine) expandTupleToUserSet(
	request *base.PermissionExpandRequest,
	ttu *base.TupleToUserSet,
) ExpandFunction {
	return func(ctx context.Context, expandChan chan<- ExpandResponse) {
		filter := &base.TupleFilter{
			Entity: &base.EntityFilter{
				Type: request.GetEntity().GetType(),
				Ids:  []string{request.GetEntity().GetId()},
			},
			Relation: ttu.GetTupleSet().GetRelation(),
		}

		// Use the filter to query for relationships in the given context.
		// NewContextualRelationships() creates a ContextualRelationships instance from tuples in the request.
		// QueryRelationships() then uses the filter to find and return matching relationships.
		cti, err := storageContext.NewContextualTuples(request.GetContext().GetTuples()...).QueryRelationships(filter, database.NewCursorPagination())
		if err != nil {
			expandChan <- expandFailResponse(err)
			return
		}

		// Use the filter to query for relationships in the database.
		// relationshipReader.QueryRelationships() uses the filter to find and return matching relationships.
		rit, err := engine.dataReader.QueryRelationships(ctx, request.GetTenantId(), filter, request.GetMetadata().GetSnapToken(), database.NewCursorPagination())
		if err != nil {
			expandChan <- expandFailResponse(err)
			return
		}

		// Create a new UniqueTupleIterator from the two TupleIterators.
		// NewUniqueTupleIterator() ensures that the iterator only returns unique tuples.
		it := database.NewUniqueTupleIterator(rit, cti)

		var expandFunctions []ExpandFunction
		for it.HasNext() {
			// Get the next tuple's subject.
			next, ok := it.GetNext()
			if !ok {
				break
			}
			subject := next.GetSubject()

			expandFunctions = append(expandFunctions, engine.expandComputedUserSet(&base.PermissionExpandRequest{
				TenantId: request.GetTenantId(),
				Entity: &base.Entity{
					Type: subject.GetType(),
					Id:   subject.GetId(),
				},
				Permission: subject.GetRelation(),
				Metadata:   request.GetMetadata(),
				Context:    request.GetContext(),
			}, ttu.GetComputed()))
		}

		expandChan <- expandUnion(
			ctx,
			request.GetEntity(),
			ttu.GetTupleSet().GetRelation(),
			request.GetArguments(),
			expandFunctions,
		)
	}
}

// expandComputedUserSet is an ExpandFunction that expands the computed user set for the given entity and relation filter.
// The function first retrieves the set of tuples that match the filter, and then expands each tuple into a set of users based
// on the values in the computed user set. The exclusion parameter determines whether the resulting user set should be included
// or excluded from the final permission set. The function returns an ExpandFunction that sends the expanded user set to the
// provided channel.
//
// Parameters:
//   - ctx: context.Context for the request
//   - request: base.PermissionExpandRequest containing the request parameters
//   - cu: base.ComputedUserSet containing the computed user set to be expanded
//
// Returns:
//   - ExpandFunction that sends the expanded user set to the provided channel
func (engine *ExpandEngine) expandComputedUserSet(
	request *base.PermissionExpandRequest,
	cu *base.ComputedUserSet,
) ExpandFunction {
	return func(ctx context.Context, resultChan chan<- ExpandResponse) {
		resultChan <- engine.expand(ctx, &base.PermissionExpandRequest{
			TenantId: request.GetTenantId(),
			Entity: &base.Entity{
				Type: request.GetEntity().GetType(),
				Id:   request.GetEntity().GetId(),
			},
			Permission: cu.GetRelation(),
			Metadata:   request.GetMetadata(),
			Context:    request.GetContext(),
		})
	}
}

// The function 'expandDirectAttribute' is a method on the ExpandEngine struct.
// It returns an ExpandFunction which is a type alias for a function that takes a context and an expand response channel as parameters.
func (engine *ExpandEngine) expandDirectAttribute(
	request *base.PermissionExpandRequest, // the request object containing information necessary for the expansion
) ExpandFunction { // returns an ExpandFunction
	return func(ctx context.Context, expandChan chan<- ExpandResponse) { // defining the returned function

		var err error // variable to store any error occurred during the process

		// Defining a filter to get the attribute based on the entity type and ID and the permission requested.
		filter := &base.AttributeFilter{
			Entity: &base.EntityFilter{
				Type: request.GetEntity().GetType(),
				Ids:  []string{request.GetEntity().GetId()},
			},
			Attributes: []string{request.GetPermission()},
		}

		var val *base.Attribute // variable to hold the attribute value

		// Attempt to get the attribute using the defined filter.
		val, err = storageContext.NewContextualAttributes(request.GetContext().GetAttributes()...).QuerySingleAttribute(filter)
		// If there's an error in getting the attribute, send a failure response through the channel and return from the function.
		if err != nil {
			expandChan <- expandFailResponse(err)
			return
		}

		// If no attribute was found, attempt to query it directly from the data reader.
		if val == nil {
			val, err = engine.dataReader.QuerySingleAttribute(ctx, request.GetTenantId(), filter, request.GetMetadata().GetSnapToken())
			if err != nil {
				expandChan <- expandFailResponse(err)
				return
			}
		}

		// If the attribute is still nil, create a new attribute with a false value.
		if val == nil {
			val = &base.Attribute{
				Entity: &base.Entity{
					Type: request.GetEntity().GetType(),
					Id:   request.GetEntity().GetId(),
				},
				Attribute: request.GetPermission(),
			}
			val.Value, err = anypb.New(&base.BooleanValue{Data: false})
			if err != nil {
				expandChan <- expandFailResponse(err)
				return
			}
		}

		// Send an ExpandResponse containing the permission expansion response with the attribute value through the channel.
		expandChan <- ExpandResponse{
			Response: &base.PermissionExpandResponse{
				Tree: &base.Expand{
					Entity:     request.GetEntity(),
					Permission: request.GetPermission(),
					Arguments:  request.GetArguments(),
					Node: &base.Expand_Leaf{
						Leaf: &base.ExpandLeaf{
							Type: &base.ExpandLeaf_Value{
								Value: val.GetValue(),
							},
						},
					},
				},
			},
		}
	}
}

// expandCall returns an ExpandFunction for the given request and call.
// The returned function, when executed, sends the expanded permission result
// to the provided result channel.
func (engine *ExpandEngine) expandCall(
	request *base.PermissionExpandRequest,
	call *base.Call,
) ExpandFunction {
	return func(ctx context.Context, resultChan chan<- ExpandResponse) {
		resultChan <- engine.expand(ctx, &base.PermissionExpandRequest{
			TenantId: request.GetTenantId(),
			Entity: &base.Entity{
				Type: request.GetEntity().GetType(),
				Id:   request.GetEntity().GetId(),
			},
			Permission: call.GetRuleName(),
			Metadata:   request.GetMetadata(),
			Context:    request.GetContext(),
			Arguments:  call.GetArguments(),
		})
	}
}

// The function 'expandCall' is a method on the ExpandEngine struct.
// It takes a PermissionExpandRequest and a Call as parameters and returns an ExpandFunction.
func (engine *ExpandEngine) expandDirectCall(
	request *base.PermissionExpandRequest, // The request object containing information necessary for the expansion.
) ExpandFunction { // The function returns an ExpandFunction.
	return func(ctx context.Context, expandChan chan<- ExpandResponse) { // defining the returned function.

		var err error // variable to store any error occurred during the process.

		var ru *base.RuleDefinition // variable to hold the rule definition.

		// Read the rule definition based on the rule name in the call.
		ru, _, err = engine.schemaReader.ReadRuleDefinition(ctx, request.GetTenantId(), request.GetPermission(), request.GetMetadata().GetSchemaVersion())
		if err != nil {
			// If there's an error in reading the rule definition, send a failure response through the channel and return from the function.
			expandChan <- expandFailResponse(err)
			return
		}

		// Prepare the arguments map to be used in the CEL evaluation
		arguments := make(map[string]*anypb.Any)

		// Prepare a slice for attributes
		attributes := make([]string, 0)

		// For each argument in the call...
		for _, arg := range request.GetArguments() {
			switch actualArg := arg.Type.(type) { // Switch on the type of the argument.
			case *base.Argument_ComputedAttribute: // If the argument is a ComputedAttribute...
				attrName := actualArg.ComputedAttribute.GetName() // get the name of the attribute.

				// Get the empty value for the attribute type.
				emptyValue, err := getEmptyProtoValueForType(ru.GetArguments()[attrName])
				if err != nil {
					expandChan <- expandFailResponse(errors.New(base.ErrorCode_ERROR_CODE_TYPE_CONVERSATION.String()))
					return
				}

				// Set the empty value in the arguments map.
				arguments[attrName] = emptyValue

				// Append the attribute name to the attributes slice.
				attributes = append(attributes, attrName)
			default:
				// If the argument type is unknown, send a failure response and return from the function.
				expandChan <- expandFailResponse(errors.New(base.ErrorCode_ERROR_CODE_INTERNAL.String()))
				return
			}
		}

		// If there are any attributes to query...
		if len(attributes) > 0 {
			// Create an AttributeFilter for the attributes.
			filter := &base.AttributeFilter{
				Entity: &base.EntityFilter{
					Type: request.GetEntity().GetType(),
					Ids:  []string{request.GetEntity().GetId()},
				},
				Attributes: attributes,
			}

			// Query the attributes from the data reader.
			ait, err := engine.dataReader.QueryAttributes(ctx, request.GetTenantId(), filter, request.GetMetadata().GetSnapToken(), database.NewCursorPagination())
			if err != nil {
				expandChan <- expandFailResponse(err)
				return
			}

			// Query the attributes from the context.
			cta, err := storageContext.NewContextualAttributes(request.GetContext().GetAttributes()...).QueryAttributes(filter, database.NewCursorPagination())
			if err != nil {
				expandChan <- expandFailResponse(err)
				return
			}

			// Create an iterator for the unique attributes.
			it := database.NewUniqueAttributeIterator(ait, cta)

			// For each unique attribute...
			for it.HasNext() {
				// Get the next attribute and its value.
				next, ok := it.GetNext()
				if !ok {
					break
				}
				// Set the attribute's value in the arguments map.
				arguments[next.GetAttribute()] = next.GetValue()
			}
		}

		// Send an ExpandResponse containing the permission expansion response with the computed arguments through the channel.
		expandChan <- ExpandResponse{
			Response: &base.PermissionExpandResponse{
				Tree: &base.Expand{
					Entity:     request.GetEntity(),
					Permission: request.GetPermission(),
					Arguments:  request.GetArguments(),
					Node: &base.Expand_Leaf{
						Leaf: &base.ExpandLeaf{
							Type: &base.ExpandLeaf_Values{
								Values: &base.Values{
									Values: arguments,
								},
							},
						},
					},
				},
			},
		}
	}
}

// 'expandComputedAttribute' is a method on the ExpandEngine struct.
// It takes a PermissionExpandRequest and a ComputedAttribute as parameters and returns an ExpandFunction.
func (engine *ExpandEngine) expandComputedAttribute(
	request *base.PermissionExpandRequest, // The request object containing necessary information for the expansion.
	ca *base.ComputedAttribute, // The computed attribute object that has the name of the attribute to be computed.
) ExpandFunction { // The function returns an ExpandFunction.
	return func(ctx context.Context, resultChan chan<- ExpandResponse) { // defining the returned function.

		// The returned function sends the result of an expansion to the result channel.
		// The expansion is performed by calling the 'expand' method of the engine with a new PermissionExpandRequest.
		// The new request is constructed using the tenant ID, entity, computed attribute name, metadata, and context from the original request.
		resultChan <- engine.expand(ctx, &base.PermissionExpandRequest{
			TenantId: request.GetTenantId(), // Tenant ID from the original request.
			Entity: &base.Entity{
				Type: request.GetEntity().GetType(), // Entity type from the original request.
				Id:   request.GetEntity().GetId(),   // Entity ID from the original request.
			},
			Permission: ca.GetName(),          // The name of the computed attribute.
			Metadata:   request.GetMetadata(), // Metadata from the original request.
			Context:    request.GetContext(),  // Context from the original request.
		})
	}
}

// 'expandOperation' is a function that takes a context, an entity, permission string,
// a slice of arguments, slice of ExpandFunctions, and an operation of type base.ExpandTreeNode_Operation.
// It returns an ExpandResponse.
func expandOperation(
	ctx context.Context, // The context of this operation, which may carry deadlines, cancellation signals, etc.
	entity *base.Entity, // The entity on which the operation will be performed.
	permission string, // The permission string required for the operation.
	arguments []*base.Argument, // A slice of arguments required for the operation.
	functions []ExpandFunction, // A slice of functions that will be used to expand the operation.
	op base.ExpandTreeNode_Operation, // The operation to be performed.
) ExpandResponse { // The function returns an ExpandResponse.

	// Initialize an empty slice of base.Expand type.
	children := make([]*base.Expand, 0, len(functions))

	// If there are no functions, return an ExpandResponse with a base.PermissionExpandResponse.
	// This response includes an empty base.Expand with the entity, permission, arguments,
	// and an ExpandTreeNode with the given operation.
	if len(functions) == 0 {
		return ExpandResponse{
			Response: &base.PermissionExpandResponse{
				Tree: &base.Expand{
					Entity:     entity,
					Permission: permission,
					Arguments:  arguments,
					Node: &base.Expand_Expand{
						Expand: &base.ExpandTreeNode{
							Operation: op,
							Children:  children,
						},
					},
				},
			},
		}
	}

	// Create a new context that can be cancelled.
	c, cancel := context.WithCancel(ctx)
	// Defer the cancellation, so that it will be called when the function exits.
	defer func() {
		cancel()
	}()

	// Initialize an empty slice of channels which will receive ExpandResponses.
	results := make([]chan ExpandResponse, 0, len(functions))
	// For each function, create a channel and add it to the results slice.
	// Start a goroutine with the function and pass the cancelable context and the channel.
	for _, fn := range functions {
		fc := make(chan ExpandResponse, 1)
		results = append(results, fc)
		go fn(c, fc)
	}

	// For each result channel, wait for a response or for the context to be cancelled.
	for _, result := range results {
		select {
		case resp := <-result:
			// If the response contains an error, return an error response.
			if resp.Err != nil {
				return expandFailResponse(resp.Err)
			}
			// If the response does not contain an error, append the tree of the response to the children slice.
			children = append(children, resp.Response.GetTree())
		case <-ctx.Done():
			// If the context is cancelled, return an error response.
			return expandFailResponse(errors.New(base.ErrorCode_ERROR_CODE_CANCELLED.String()))
		}
	}

	// Return an ExpandResponse with a base.PermissionExpandResponse.
	// This response includes an base.Expand with the entity, permission, arguments,
	// and an ExpandTreeNode with the given operation and the children slice.
	return ExpandResponse{
		Response: &base.PermissionExpandResponse{
			Tree: &base.Expand{
				Entity:     entity,
				Permission: permission,
				Arguments:  arguments,
				Node: &base.Expand_Expand{
					Expand: &base.ExpandTreeNode{
						Operation: op,
						Children:  children,
					},
				},
			},
		},
	}
}

// expandRoot is a helper function that executes an ExpandFunction and returns the resulting ExpandResponse. The function
// creates a goroutine for the ExpandFunction to allow for cancellation and concurrent execution. If the ExpandFunction
// returns an error, the function returns an ExpandResponse with the error. If the context is cancelled before the
// ExpandFunction completes, the function returns an ExpandResponse with an error indicating that the operation was cancelled.
//
// Parameters:
//   - ctx: context.Context for the request
//   - fn: ExpandFunction to execute
//
// Returns:
//   - ExpandResponse containing the expanded user set or an error if the ExpandFunction failed
func expandRoot(ctx context.Context, fn ExpandFunction) ExpandResponse {
	res := make(chan ExpandResponse, 1)
	go fn(ctx, res)

	select {
	case result := <-res:
		if result.Err == nil {
			return result
		}
		return expandFailResponse(result.Err)
	case <-ctx.Done():
		return expandFailResponse(errors.New(base.ErrorCode_ERROR_CODE_CANCELLED.String()))
	}
}

// expandUnion is a helper function that executes multiple ExpandFunctions in parallel and returns an ExpandResponse containing
// the union of their expanded user sets. The function delegates to expandOperation with the UNION operation. If any of the
// ExpandFunctions return an error, the function returns an ExpandResponse with the error. If the context is cancelled before
// all ExpandFunctions complete, the function returns an ExpandResponse with an error indicating that the operation was cancelled.
//
// Parameters:
//   - ctx: context.Context for the request
//   - functions: slice of ExpandFunctions to execute in parallel
//
// Returns:
//   - ExpandResponse containing the union of the expanded user sets, or an error if any of the ExpandFunctions failed
func expandUnion(
	ctx context.Context,
	entity *base.Entity,
	permission string,
	arguments []*base.Argument,
	functions []ExpandFunction,
) ExpandResponse {
	return expandOperation(ctx, entity, permission, arguments, functions, base.ExpandTreeNode_OPERATION_UNION)
}

// expandIntersection is a helper function that executes multiple ExpandFunctions in parallel and returns an ExpandResponse
// containing the intersection of their expanded user sets. The function delegates to expandOperation with the INTERSECTION
// operation. If any of the ExpandFunctions return an error, the function returns an ExpandResponse with the error. If the
// context is cancelled before all ExpandFunctions complete, the function returns an ExpandResponse with an error indicating
// that the operation was cancelled.
//
// Parameters:
//   - ctx: context.Context for the request
//   - functions: slice of ExpandFunctions to execute in parallel
//
// Returns:
//   - ExpandResponse containing the intersection of the expanded user sets, or an error if any of the ExpandFunctions failed
func expandIntersection(
	ctx context.Context,
	entity *base.Entity,
	permission string,
	arguments []*base.Argument,
	functions []ExpandFunction,
) ExpandResponse {
	return expandOperation(ctx, entity, permission, arguments, functions, base.ExpandTreeNode_OPERATION_INTERSECTION)
}

// expandExclusion is a helper function that executes multiple ExpandFunctions in parallel and returns an ExpandResponse
// containing the expanded user set that results from the exclusion operation. The function delegates to expandOperation
// with the EXCLUSION operation. If any of the ExpandFunctions return an error, the function returns an ExpandResponse
// with the error. If the context is cancelled before all ExpandFunctions complete, the function returns an ExpandResponse
// with an error indicating that the operation was cancelled.
//
// Parameters:
//   - ctx: context.Context for the request
//   - target: EntityAndRelation containing the entity and its relation for which the exclusion is calculated
//   - functions: slice of ExpandFunctions to execute in parallel
//
// Returns:
//   - ExpandResponse containing the expanded user sets from the exclusion operation, or an error if any of the ExpandFunctions failed
func expandExclusion(
	ctx context.Context,
	entity *base.Entity,
	permission string,
	arguments []*base.Argument,
	functions []ExpandFunction,
) ExpandResponse {
	return expandOperation(ctx, entity, permission, arguments, functions, base.ExpandTreeNode_OPERATION_EXCLUSION)
}

// expandFail is a helper function that returns an ExpandFunction that immediately sends an ExpandResponse with the specified error
// to the provided channel. The resulting ExpandResponse contains an empty ExpandTreeNode and the specified error.
//
// Parameters:
//   - err: error to include in the resulting ExpandResponse
//
// Returns:
//   - ExpandFunction that sends an ExpandResponse with the specified error to the provided channel
func expandFail(err error) ExpandFunction {
	return func(ctx context.Context, expandChan chan<- ExpandResponse) {
		expandChan <- expandFailResponse(err)
	}
}

// expandFailResponse is a helper function that returns an ExpandResponse with the specified error and an empty ExpandTreeNode.
//
// Parameters:
//   - err: error to include in the resulting ExpandResponse
//
// Returns:
//   - ExpandResponse with the specified error and an empty ExpandTreeNode
func expandFailResponse(err error) ExpandResponse {
	return ExpandResponse{
		Response: &base.PermissionExpandResponse{
			Tree: &base.Expand{},
		},
		Err: err,
	}
}

Permify / permify

engines.*ExpandEngine.expandDirectAttribute B last analyzed 2025-06-13 13:06 UTC

Complexity

Size

Duplication

Importance

How to fix Long Method

Long Method

Duplication Side-by-Side

Filter issues like

engines.*ExpandEngine.expandDirectAttribute B
last analyzed 2025-06-13 13:06 UTC
