From 5bc8a21898cc9b634bb54a18d106d8f12b5cbb2f Mon Sep 17 00:00:00 2001 From: andrea bertagnolli Date: Thu, 10 Oct 2024 09:22:44 +0200 Subject: [PATCH] docs: typed policy engine DR (#4526) * docs: typed policy engine DR * pr remark * switch scope * bind scope to context --- .../2024-10-05-typed-policy-context/README.md | 61 +++++++++++++++++++ docs/developer/decision-records/README.md | 1 + 2 files changed, 62 insertions(+) create mode 100644 docs/developer/decision-records/2024-10-05-typed-policy-context/README.md diff --git a/docs/developer/decision-records/2024-10-05-typed-policy-context/README.md b/docs/developer/decision-records/2024-10-05-typed-policy-context/README.md new file mode 100644 index 00000000000..291809c0efa --- /dev/null +++ b/docs/developer/decision-records/2024-10-05-typed-policy-context/README.md @@ -0,0 +1,61 @@ +# Typed Policy Scopes through Contexts + +## Decision + +We will bind the policy scope and the `PolicyContext` hierarchy. + +## Rationale + +At the moment implementing a new policy function for an adopter requires a "blind guess" about the content of the `PolicyContext` +object, because it's designed as an unstructured map. +Bounding the context structure to the scope will help documentation and usability of the Policy Engine. + +## Approach + +### Function interfaces + +The refactor is based on the modification of the "policy function interfaces" to add them the `PolicyContext` generic type, to permit implementations +bound to the specific type. +For every of these 3 interfaces (`AtomicConstraintFunction`, `DynamicAtomicConstraintFunction`, `RuleFunction`) will be defined a new interface with the same signature, +plus the `C extends PolicyContext` generic type, e.g.: +```java +public interface AtomicConstraintRuleFunction { + + boolean evaluate(Operator operator, Object rightValue, R rule, C context); + + ... +} +``` + +The current interface will be deprecated and it will extend the new one setting `PolicyContext` as bound class. This will permit to avoid breaking changes: +```java +@Deprecated +public interface AtomicConstraintFunction extends AtomicConstraintRuleFunction { } +``` + +After then the current interfaces will be replaced by the new one in all the signature in the policy engine spi and implementation. + +### Policy Engine + +The `PolicyEngine` will have new methods to register validators/function that accept also a `Class`. E.g.: +```java + void registerFunction(Class contextType, Class type, String key, AtomicConstraintRuleFunction function); +``` +Plus there will be a new `evaluate` method that will accept a typed context: +```java + Result evaluate(Policy policy, C context); +``` + +the registered `contextType` object will then be used to filter out validators and functions during the evaluation, the validator/function +will be used only if the registered `contextType` `isAssignableFrom` the passed `context` class. +This means that they will be used only if the type is the same or a super type of the passed context, this will permit to +achieve scope inheritance, for example please consider: +- scope `foo` associated with `FooContext` +- scope `foo.bar` associated with `FooBarContext` that extends `FooContext` + +In this case, when a `FooBarContext` object is passed to the `evaluate` function, will select also functions that were registered +on the `FooContext`. + +### Policy Contexts + +The `PolicyContexts` extensions class and the scope constants will be kept in separated `spi` modules so then they could be used by different core and extension modules. diff --git a/docs/developer/decision-records/README.md b/docs/developer/decision-records/README.md index b433c3f6ee8..edf8e2a4309 100644 --- a/docs/developer/decision-records/README.md +++ b/docs/developer/decision-records/README.md @@ -63,3 +63,4 @@ - [2024-09-24 STS Accounts API](./2024-09-24-sts-accounts-api) - [2024-09-25 Multiple Protocol Versions](./2024-09-25-multiple-protocol-versions) - [2024-10-02 Clustered data-plane](./2024-10-02-clustered-data-plane/) +- [2024-10-06 Typed Policy Scopes through Contexts](./2024-10-05-typed-policy-context)