Documentation
¶
Overview ¶
This package defines filtering mechanism on resources, which consists the main extension point in services.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsOutOfSync ¶
IsOutOfSync returns true when the given property is the marker out-of-sync property.
func Visit ¶
Visit performs a DFS visit on the resource and sequentially invokes the ByProperty filters on each visited property in the resource. Any visit or filtering error is returned.
func VisitWithRef ¶
func VisitWithRef(ctx context.Context, resource *prop.Resource, ref *prop.Resource, filters ...ByProperty) error
VisitWithRef performs a DFS visit on the resource and sequentially invokes the ByProperty filters on each visited property in the resource, along with the synchronized reference property. The synchronization is carried out with best effort, which means the reference property may be out of sync. Out of sync can happen when the resource has a property value that the reference resource does not have (i.e. Add) Caller need to test if
ref == nil || ref == outOfSync
to determine if the reference is out of sync. Any visit or filtering error is returned.
Types ¶
type ByProperty ¶
type ByProperty interface {
// Returns true if this filter supports the supplied attribute. The Filter method
// will only be called when this method returns true. This method is expected to be
// called at setup time.
Supports(attribute *spec.Attribute) bool
// Filter the given property with reference to the resource that contains this property. The property being filter
// is the Current property on the navigator. Any error returned shall cause the caller to abort subsequent operations.
Filter(ctx context.Context, resourceType *spec.ResourceType, nav prop.Navigator) error
// Filter the given property with reference to the resource that contains this property, another reference resource which
// potentially holds a reference property. The reference resource and property may serve as a guidance for the expected
// state of the property. The reference resource shall never be nil, whereas the reference property may be nil.
// Any error returned shall cause the caller to abort subsequent operations.
FilterRef(ctx context.Context, resourceType *spec.ResourceType, nav prop.Navigator, refNav prop.Navigator) error
}
ByProperty is responsible of filtering individual property field. It provides more granular control than a resource filter. ByProperty filters can be bridged to become a ByResource filter by calling ByPropertyToByResource.
func BCryptFilter ¶
func BCryptFilter() ByProperty
BCryptFilter returns a ByProperty filter that hashes data using the BCrypt algorithm for string or binary properties whose attribute is annotated with @BCrypt. If the property is unassigned or has the same value with the reference property, the filter does nothing. Otherwise, it will attempt to determine the cost through the "cost" annotation parameter and replace the property value with the hashed value. For binary properties specifically, the hashed value is base64 encoded before replacing the original base64 encoded bytes.
func ReadOnlyFilter ¶
func ReadOnlyFilter() ByProperty
ReadOnlyFilter returns a ByProperty filter that supports resetting and copying values for readOnly properties that was annotated with @ReadOnly. The annotation can specify two boolean parameters named "reset" and "copy". When "reset" is set to true, the filter will delete the property value; When "copy" is set to true and a reference is available, the filter will replace the property value with that of the reference. If any of these two parameters are not set, they are treated as false. The value changes in this filter generates additional event propagation.
func UUIDFilter ¶
func UUIDFilter() ByProperty
UUIDFilter returns a ByProperty filter that generates a UUID for string property that is annotated with @UUID. The generation only happens when the target property is currently unassigned. The generated value will trigger event propagation.
func ValidationFilter ¶
func ValidationFilter(database db.DB) ByProperty
ValidationFilter returns a ByProperty that performs validation on each property. The validation carried out are required check, canonical check, mutability check and uniqueness check.
The required check fails when attribute is required but property is unassigned.
The canonical check fails when @Enum is annotated with the attribute, indicating that the canonicalValues defined should be treated as the only valid values of holding property, and the property value is not among the canonicalValues.
The mutability check only fails when attribute is immutable, and the property value differs from the reference property value, if one exists. It does not check for readOnly attributes because the logic is largely handled by ReadOnlyFilter.
The uniqueness check fails when the property value already exists in the database. It formulates the query (id ne <id>) and (<path> eq <value>), where <id> is the resource id, <path> is the unique attribute path, and <value> is the property value. The database returns the number of records matching this filter. If the count is greater than 0, the check fails. Note this check only handles the uniqueness=server case.
Error is returned to caller if any of these check fails.
type ByResource ¶
type ByResource interface {
// Filter the resource and return any error. If the error returned is not nil,
// the caller should immediately abort the operation and avoid executing the
// following filters.
Filter(ctx context.Context, resource *prop.Resource) error
// Filter the resource with reference to a reference resource and return any error.
// The reference resource may serve as a guidance for the expected state of the resource.
// If the error returned is not nil, the caller should immediately abort the operation
// and avoid executing the following filters.
FilterRef(ctx context.Context, resource *prop.Resource, ref *prop.Resource) error
}
ByResource is the filter responsible of filtering a resource.
func ByPropertyToByResource ¶
func ByPropertyToByResource(filters ...ByProperty) ByResource
ByPropertyToByResource returns a ByResource that iterates each property in the resource using a DFS visitor and sequentially invoke the list of ByProperty filters on each visited property. It effectively bridges ByProperty filters to a ByResource filters.
func MetaFilter ¶
func MetaFilter() ByResource
MetaFilter returns a ByResource filter that assigns and updates the meta core attribute.
Source Files