From 1dda2cbd755079ccd4239c90fef9a368916ca705 Mon Sep 17 00:00:00 2001 From: cn337131 <141730190+cn337131@users.noreply.github.com> Date: Wed, 4 Oct 2023 08:16:04 +0000 Subject: [PATCH 1/5] add info on operation scores --- docs/administration-guide/operation-score.md | 178 +++++++++++++++++++ 1 file changed, 178 insertions(+) diff --git a/docs/administration-guide/operation-score.md b/docs/administration-guide/operation-score.md index e69de29bb2..b97af556db 100644 --- a/docs/administration-guide/operation-score.md +++ b/docs/administration-guide/operation-score.md @@ -0,0 +1,178 @@ +# Operation Scores + +Operation Scores can be used to give an OperationChains and NamedOperations a "score" which can then be used to determine whether a particular user has the required permissions to execute a given OperationChain. + +## Using Operation Scores + +A `ScoreOperationChain` operation determines a "score" for an OperationChain. + +Below is a simple example for constructing a ScoreOperationChain, using this directed graph: + +``` mermaid +graph TD + 1(1, count=3) -- count=3 --> 2 + 1 -- count=1 --> 4 + 2(2, count=1) -- count=2 --> 3 + 2 -- count=1 --> 4(4, count=1) + 2 -- count=1 --> 5(5, count=3) + 3(3, count=2) -- count=4 --> 4 +``` + +!!! example "Example ScoreOperationChain" + + === "Java" + ``` java + final ScoreOperationChain scoreOpChain = new ScoreOperationChain.Builder() + .operationChain(new OperationChain.Builder() + .first(new GetElements()) + .then(new NamedOperation.Builder>() + .name("namedOp") + .build()) + .then(new Limit<>(3)) + .build()) + .build(); + ``` + + === "JSON" + ``` json + { + "class" : "ScoreOperationChain", + "operationChain" : { + "class" : "OperationChain", + "operations" : [ { + "class" : "GetElements" + }, { + "class" : "NamedOperation", + "operationName" : "namedOp" + }, { + "class" : "Limit", + "resultLimit" : 3, + "truncate" : true + } ] + } + } + ``` + + === "Python" + ``` python + g.ScoreOperationChain( + operation_chain=g.OperationChain( + operations=[ + g.GetElements(), + g.NamedOperation( + operation_name="namedOp" + ), + g.Limit( + result_limit=3, + truncate=True + ) + ] + ) + ) + ``` + +The key variables when using ScoreOperationChain are: + +- `opScores` - required map of operation scores. These are the operation score values. +- `authScores` - required map of operation authorisation scores. These are the maximum scores allowed for a user with a given role. +- `scoreResolver` - some operations may require a custom way of calculating an associated score, therefore an implementation of the [`ScoreResolver`](https://gchq.github.io/Gaffer/uk/gov/gchq/gaffer/store/operation/resolver/ScoreResolver.html) interface may be required. +These map the operation class to its respective score resolver. +There is a `DefaultScoreResolver` to which the custom implementation should delegate, in a manner specific to the new Operation. + +!!! example "Example OperationDeclarations.json for a NamedOperation" + + ```json + { + "operations": [ + { + "operation": "uk.gov.gchq.gaffer.operation.impl.ScoreOperationChain", + "handler": { + "class": "uk.gov.gchq.gaffer.store.operation.handler.ScoreOperationChainHandler", + "opScores": { + "uk.gov.gchq.gaffer.operation.Operation": 2, + "uk.gov.gchq.gaffer.operation.impl.generate.GenerateObjects": 0 + }, + "authScores": { + "User": 4, + "EnhancedUser": 10 + }, + "scoreResolvers": { + "uk.gov.gchq.gaffer.named.operation.NamedOperation": { + "class": "uk.gov.gchq.gaffer.store.operation.resolver.named.NamedOperationScoreResolver" + } + } + } + } + ] + } + ``` + +For more examples of ScoreOperationChain refer to the [Misc Operations page in the Reference Guide](../reference/operations-guide/misc.md#scoreoperationchain). + +## Operation Chain Limiters + +`OperationChainLimiter` is a [GraphHook](../development-guide/project-structure/components/graph.md#graph-hooks) that checks a user is authorised to execute an operation chain based on that user's maximum chain score and the configured score value for each operation in the chain. +If you wish to use the ScoreOperationChain operation and this graph hook, then both need to have the same score configuration. + +To use the `OperationChainLimiter` GraphHook then you will need to configure that GraphHook to use the a Score Resolver interface. +The ScoreOperationChainDeclaration.json declares that a NamedOperation should be resolved using a [`NamedOperationScoreResolver`](https://gchq.github.io/Gaffer/uk/gov/gchq/gaffer/store/operation/resolver/named/NamedOperationScoreResolver.html). +This will then allow you to have custom scores for each NamedOperation. + +!!! example "Example hook configuration" + + Configuration of the hook should look something like this: + + ``` json + { + "class": "uk.gov.gchq.gaffer.graph.hook.OperationChainLimiter", + "opScores": { + "uk.gov.gchq.gaffer.operation.Operation": 1, + "uk.gov.gchq.gaffer.operation.impl.add.AddElements": 2, + "uk.gov.gchq.gaffer.operation.impl.get.GetAllElements": 5, + "uk.gov.gchq.gaffer.operation.impl.generate.GenerateObjects": 0 + }, + "authScores": { + "User": 2, + "SuperUser": 5 + }, + "scoreResolvers": { + "uk.gov.gchq.gaffer.named.operation.NamedOperation": { + "class": "uk.gov.gchq.gaffer.store.operation.resolver.named.NamedOperationScoreResolver" + } + } + } + ``` + +!!! example "Example operation declarations file" + + As a result, the operation declarations file for registering the `ScoreOperationChain` operation would then look like: + + ``` json + { + "operations": [ + { + "operation": "uk.gov.gchq.gaffer.operation.impl.ScoreOperationChain", + "handler": { + "opScores": { + "uk.gov.gchq.gaffer.operation.Operation": 1, + "uk.gov.gchq.gaffer.operation.impl.add.AddElements": 2, + "uk.gov.gchq.gaffer.operation.impl.get.GetAllElements": 5, + "uk.gov.gchq.gaffer.operation.impl.generate.GenerateObjects": 0 + }, + "authScores": { + "User": 2, + "SuperUser": 5 + }, + "scoreResolvers": { + "uk.gov.gchq.gaffer.named.operation.NamedOperation": { + "class": "uk.gov.gchq.gaffer.store.operation.resolver.named.NamedOperationScoreResolver" + } + } + } + } + ] + } + ``` + +If you have the `OperationChainLimiter` GraphHook configured then this score will be used by +the hook to limit operation chains. \ No newline at end of file From e393c55bc342f00d61f44236b5fca0380b8415bd Mon Sep 17 00:00:00 2001 From: cn337131 <141730190+cn337131@users.noreply.github.com> Date: Thu, 5 Oct 2023 12:58:01 +0000 Subject: [PATCH 2/5] address comments and restructure --- docs/administration-guide/operation-score.md | 104 ++++++++++--------- 1 file changed, 56 insertions(+), 48 deletions(-) diff --git a/docs/administration-guide/operation-score.md b/docs/administration-guide/operation-score.md index b97af556db..d0ebf9b520 100644 --- a/docs/administration-guide/operation-score.md +++ b/docs/administration-guide/operation-score.md @@ -2,21 +2,49 @@ Operation Scores can be used to give an OperationChains and NamedOperations a "score" which can then be used to determine whether a particular user has the required permissions to execute a given OperationChain. +These scores work on a credit-like system where user's configured "score" is the amount they can then spend on running an Operation/OperationChain. +Users cannot spend more than their score and every time they run an Operation or OperationChain that has a configured "score" this will be 'subtracted' from their score 'credit'. + ## Using Operation Scores A `ScoreOperationChain` operation determines a "score" for an OperationChain. +To use this Operation you need to configure an `OperationsDeclarations.json`. + +To configure this file you need to set the following handlers which configure how Operation Scores are used with a graph: -Below is a simple example for constructing a ScoreOperationChain, using this directed graph: +- `opScores` - required map of operation scores. These are the operation score values. +- `authScores` - required map of operation authorisation scores. These are the maximum scores allowed for a user with a given role. +- `scoreResolver` - some operations may require a custom way of calculating an associated score, therefore an implementation of the [`ScoreResolver`](https://gchq.github.io/Gaffer/uk/gov/gchq/gaffer/store/operation/resolver/ScoreResolver.html) interface may be required. +These map the operation class to its respective score resolver. +There is a `DefaultScoreResolver` to which the custom implementation should delegate, in a manner specific to the new Operation. -``` mermaid -graph TD - 1(1, count=3) -- count=3 --> 2 - 1 -- count=1 --> 4 - 2(2, count=1) -- count=2 --> 3 - 2 -- count=1 --> 4(4, count=1) - 2 -- count=1 --> 5(5, count=3) - 3(3, count=2) -- count=4 --> 4 -``` +!!! example "Example OperationDeclarations.json for a NamedOperation" + + ```json + { + "operations": [ + { + "operation": "uk.gov.gchq.gaffer.operation.impl.ScoreOperationChain", + "handler": { + "class": "uk.gov.gchq.gaffer.store.operation.handler.ScoreOperationChainHandler", + "opScores": { + "uk.gov.gchq.gaffer.operation.Operation": 2, + "uk.gov.gchq.gaffer.operation.impl.generate.GenerateObjects": 0 + }, + "authScores": { + "User": 4, + "EnhancedUser": 10 + }, + "scoreResolvers": { + "uk.gov.gchq.gaffer.named.operation.NamedOperation": { + "class": "uk.gov.gchq.gaffer.store.operation.resolver.named.NamedOperationScoreResolver" + } + } + } + } + ] + } + ``` !!! example "Example ScoreOperationChain" @@ -71,43 +99,23 @@ graph TD ) ``` -The key variables when using ScoreOperationChain are: +For more examples of ScoreOperationChain refer to the [Misc Operations page in the Reference Guide](../reference/operations-guide/misc.md#scoreoperationchain). -- `opScores` - required map of operation scores. These are the operation score values. -- `authScores` - required map of operation authorisation scores. These are the maximum scores allowed for a user with a given role. -- `scoreResolver` - some operations may require a custom way of calculating an associated score, therefore an implementation of the [`ScoreResolver`](https://gchq.github.io/Gaffer/uk/gov/gchq/gaffer/store/operation/resolver/ScoreResolver.html) interface may be required. -These map the operation class to its respective score resolver. -There is a `DefaultScoreResolver` to which the custom implementation should delegate, in a manner specific to the new Operation. +## Score Resolver -!!! example "Example OperationDeclarations.json for a NamedOperation" +A `ScoreResolver` is used to retreive the score associated with a provided Operation. +In most cases, the [`DefaultScoreResolver`](https://gchq.github.io/gaffer-doc/v1docs/javadoc/gaffer/uk/gov/gchq/gaffer/store/operation/resolver/DefaultScoreResolver.html) is suitable. +However, some operations require specific ways of calculating their score so will require the implementation of different scoreResolver handlers. - ```json - { - "operations": [ - { - "operation": "uk.gov.gchq.gaffer.operation.impl.ScoreOperationChain", - "handler": { - "class": "uk.gov.gchq.gaffer.store.operation.handler.ScoreOperationChainHandler", - "opScores": { - "uk.gov.gchq.gaffer.operation.Operation": 2, - "uk.gov.gchq.gaffer.operation.impl.generate.GenerateObjects": 0 - }, - "authScores": { - "User": 4, - "EnhancedUser": 10 - }, - "scoreResolvers": { - "uk.gov.gchq.gaffer.named.operation.NamedOperation": { - "class": "uk.gov.gchq.gaffer.store.operation.resolver.named.NamedOperationScoreResolver" - } - } - } - } - ] - } - ``` +In the case of NamedOperations, the [`NamedOperationScoreResolver`](https://gchq.github.io/gaffer-doc/v1docs/javadoc/gaffer/uk/gov/gchq/gaffer/store/operation/resolver/named/NamedOperationScoreResolver.html) should be implemented in the OperationDeclarations.json. +This will resolve the custom Operation Score for a provided NamedOperation by looking for it in the cache. -For more examples of ScoreOperationChain refer to the [Misc Operations page in the Reference Guide](../reference/operations-guide/misc.md#scoreoperationchain). +If choosing to score your `If` Operation, then you should implement the [`IfScoreResolver`](https://gchq.github.io/gaffer-doc/v1docs/javadoc/gaffer/uk/gov/gchq/gaffer/store/operation/resolver/IfScoreResolver.html). +This will provide the score as the maximum of the operations that are used within the `If` operation, regardless of which operation is actually executed. + +The `While` Operation, if scored, will also require implementation of the specific [`WhileScoreResolver`](https://gchq.github.io/gaffer-doc/v1docs/javadoc/gaffer/uk/gov/gchq/gaffer/store/operation/resolver/WhileScoreResolver.html). +The score will be the maximum of the transform operation and the delegate operation, multiplied by the minimum of the configured number of max repeats vs the global maximum number of allowed repeats. +This is simply because the number of actual repetitions is nondeterministic, therefore a "worst"-case scenario is considered. ## Operation Chain Limiters @@ -118,9 +126,12 @@ To use the `OperationChainLimiter` GraphHook then you will need to configure tha The ScoreOperationChainDeclaration.json declares that a NamedOperation should be resolved using a [`NamedOperationScoreResolver`](https://gchq.github.io/Gaffer/uk/gov/gchq/gaffer/store/operation/resolver/named/NamedOperationScoreResolver.html). This will then allow you to have custom scores for each NamedOperation. +If you have the `OperationChainLimiter` GraphHook configured then this score will be used by +the hook to limit operation chains. + !!! example "Example hook configuration" - Configuration of the hook should look something like this: + [Configuration of the hook]((../development-guide/project-structure/components/graph.md#graph-hook)) should look something like this and should be placed in your `graphConfig.json`. ``` json { @@ -172,7 +183,4 @@ This will then allow you to have custom scores for each NamedOperation. } ] } - ``` - -If you have the `OperationChainLimiter` GraphHook configured then this score will be used by -the hook to limit operation chains. \ No newline at end of file + ``` \ No newline at end of file From 2e77bf20dcbdca4beb2f223b72b11d976fb2bd81 Mon Sep 17 00:00:00 2001 From: cn337131 <141730190+cn337131@users.noreply.github.com> Date: Thu, 5 Oct 2023 13:05:45 +0000 Subject: [PATCH 3/5] fix link --- docs/administration-guide/operation-score.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/administration-guide/operation-score.md b/docs/administration-guide/operation-score.md index d0ebf9b520..4965486f54 100644 --- a/docs/administration-guide/operation-score.md +++ b/docs/administration-guide/operation-score.md @@ -131,7 +131,7 @@ the hook to limit operation chains. !!! example "Example hook configuration" - [Configuration of the hook]((../development-guide/project-structure/components/graph.md#graph-hook)) should look something like this and should be placed in your `graphConfig.json`. + [Configuration of the hook](../development-guide/project-structure/components/graph.md#graph-configuration) should look something like this and should be placed in your `graphConfig.json`. ``` json { From d06cb33491b34a9e3e300b13d1d004776cb99647 Mon Sep 17 00:00:00 2001 From: cn337131 <141730190+cn337131@users.noreply.github.com> Date: Fri, 6 Oct 2023 09:12:43 +0000 Subject: [PATCH 4/5] remove duplicate info --- docs/administration-guide/operation-score.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/administration-guide/operation-score.md b/docs/administration-guide/operation-score.md index 4965486f54..039c770226 100644 --- a/docs/administration-guide/operation-score.md +++ b/docs/administration-guide/operation-score.md @@ -14,9 +14,7 @@ To configure this file you need to set the following handlers which configure ho - `opScores` - required map of operation scores. These are the operation score values. - `authScores` - required map of operation authorisation scores. These are the maximum scores allowed for a user with a given role. -- `scoreResolver` - some operations may require a custom way of calculating an associated score, therefore an implementation of the [`ScoreResolver`](https://gchq.github.io/Gaffer/uk/gov/gchq/gaffer/store/operation/resolver/ScoreResolver.html) interface may be required. -These map the operation class to its respective score resolver. -There is a `DefaultScoreResolver` to which the custom implementation should delegate, in a manner specific to the new Operation. +- `scoreResolver` - maps the operation class to its respective [score resolver](#score-resolver). !!! example "Example OperationDeclarations.json for a NamedOperation" @@ -103,8 +101,9 @@ For more examples of ScoreOperationChain refer to the [Misc Operations page in t ## Score Resolver -A `ScoreResolver` is used to retreive the score associated with a provided Operation. -In most cases, the [`DefaultScoreResolver`](https://gchq.github.io/gaffer-doc/v1docs/javadoc/gaffer/uk/gov/gchq/gaffer/store/operation/resolver/DefaultScoreResolver.html) is suitable. +A [`ScoreResolver`](https://gchq.github.io/Gaffer/uk/gov/gchq/gaffer/store/operation/resolver/ScoreResolver.html) is used to retreive the score associated with a provided Operation. + +In most cases, implementing the [`DefaultScoreResolver`](https://gchq.github.io/gaffer-doc/v1docs/javadoc/gaffer/uk/gov/gchq/gaffer/store/operation/resolver/DefaultScoreResolver.html) interface will be suitable. However, some operations require specific ways of calculating their score so will require the implementation of different scoreResolver handlers. In the case of NamedOperations, the [`NamedOperationScoreResolver`](https://gchq.github.io/gaffer-doc/v1docs/javadoc/gaffer/uk/gov/gchq/gaffer/store/operation/resolver/named/NamedOperationScoreResolver.html) should be implemented in the OperationDeclarations.json. From cec1bbf655210cfec4fd5f749ea3b3cc2410ed6d Mon Sep 17 00:00:00 2001 From: cn337131 <141730190+cn337131@users.noreply.github.com> Date: Fri, 6 Oct 2023 10:43:21 +0000 Subject: [PATCH 5/5] add updated links --- docs/administration-guide/operation-score.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/administration-guide/operation-score.md b/docs/administration-guide/operation-score.md index 039c770226..3317673007 100644 --- a/docs/administration-guide/operation-score.md +++ b/docs/administration-guide/operation-score.md @@ -103,16 +103,16 @@ For more examples of ScoreOperationChain refer to the [Misc Operations page in t A [`ScoreResolver`](https://gchq.github.io/Gaffer/uk/gov/gchq/gaffer/store/operation/resolver/ScoreResolver.html) is used to retreive the score associated with a provided Operation. -In most cases, implementing the [`DefaultScoreResolver`](https://gchq.github.io/gaffer-doc/v1docs/javadoc/gaffer/uk/gov/gchq/gaffer/store/operation/resolver/DefaultScoreResolver.html) interface will be suitable. +In most cases, implementing the [`DefaultScoreResolver`](https://gchq.github.io/Gaffer/uk/gov/gchq/gaffer/store/operation/resolver/DefaultScoreResolver.html) interface will be suitable. However, some operations require specific ways of calculating their score so will require the implementation of different scoreResolver handlers. -In the case of NamedOperations, the [`NamedOperationScoreResolver`](https://gchq.github.io/gaffer-doc/v1docs/javadoc/gaffer/uk/gov/gchq/gaffer/store/operation/resolver/named/NamedOperationScoreResolver.html) should be implemented in the OperationDeclarations.json. +In the case of NamedOperations, the [`NamedOperationScoreResolver`](https://gchq.github.io/Gaffer/uk/gov/gchq/gaffer/store/operation/resolver/named/NamedOperationScoreResolver.html) should be implemented in the OperationDeclarations.json. This will resolve the custom Operation Score for a provided NamedOperation by looking for it in the cache. -If choosing to score your `If` Operation, then you should implement the [`IfScoreResolver`](https://gchq.github.io/gaffer-doc/v1docs/javadoc/gaffer/uk/gov/gchq/gaffer/store/operation/resolver/IfScoreResolver.html). +If choosing to score your `If` Operation, then you should implement the [`IfScoreResolver`](https://gchq.github.io/Gaffer/uk/gov/gchq/gaffer/store/operation/resolver/IfScoreResolver.html). This will provide the score as the maximum of the operations that are used within the `If` operation, regardless of which operation is actually executed. -The `While` Operation, if scored, will also require implementation of the specific [`WhileScoreResolver`](https://gchq.github.io/gaffer-doc/v1docs/javadoc/gaffer/uk/gov/gchq/gaffer/store/operation/resolver/WhileScoreResolver.html). +The `While` Operation, if scored, will also require implementation of the specific [`WhileScoreResolver`](https://gchq.github.io/Gaffer/uk/gov/gchq/gaffer/store/operation/resolver/WhileScoreResolver.html). The score will be the maximum of the transform operation and the delegate operation, multiplied by the minimum of the configured number of max repeats vs the global maximum number of allowed repeats. This is simply because the number of actual repetitions is nondeterministic, therefore a "worst"-case scenario is considered.