From cf63ea79b698be0ed1a3a0b972e9ed119a8097e6 Mon Sep 17 00:00:00 2001 From: slinkydeveloper Date: Wed, 5 Aug 2020 17:24:51 +0200 Subject: [PATCH 1/4] JS as expression language spec Signed-off-by: Francesco Guardiani --- docs/spec/broker.md | 18 ++++++++++++++++++ docs/spec/spec.md | 7 ++++--- 2 files changed, 22 insertions(+), 3 deletions(-) diff --git a/docs/spec/broker.md b/docs/spec/broker.md index 34db7f9cb94..5538fd22779 100644 --- a/docs/spec/broker.md +++ b/docs/spec/broker.md @@ -40,10 +40,28 @@ default Broker upon creation if no Broker is specified by the user. A Trigger MAY be created before its assigned Broker exists. A Trigger SHOULD progress to Ready when its assigned Broker exists and is Ready. +#### Event filters + +Implementations of Trigger MUST support both attributes filter and expression +filter. + The attributes filter specifying a list of key-value pairs MUST be supported by Trigger. Events that pass the attributes filter MUST include context or extension attributes that match all key-value pairs exactly. +The expression filter specifying a Javascript expression MUST be supported by +Trigger. If the evaluation of the expression returns a Javascript value +coercible to the boolean `true`, then the trigger filter MUST pass the event. +Implementations MUST make the event accessible, within the expression, through +the variable `event` and its context attributes and extensions through the +Javascript dot notation `.`. For example the `id` attribute of a CloudEvent +should be accessible with `event.id`. Implementations MUST coerce CloudEvent +types to JS types. For example the value of an attribute with type `Timestamp` +should be translated to the JS type `Date`. + +If a Trigger specify both attributes and expression filters, then the event MUST +pass only and only if both filters pass the event. + ## Data Plane ### Ingress diff --git a/docs/spec/spec.md b/docs/spec/spec.md index 232e76e8e9d..a82c6264f19 100644 --- a/docs/spec/spec.md +++ b/docs/spec/spec.md @@ -243,6 +243,7 @@ retrieved from ref. ### TriggerFilter -| Field | Type | Description | Constraints | -| ---------- | ----------------- | ----------------------------------------------------------------------------------- | ----------- | -| attributes | map[string]string | A filter specifying which events match this trigger. Matches exactly on the fields. | | +| Field | Type | Description | Constraints | +| ---------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------- | +| attributes | map[string]string | A filter specifying which events match this trigger. Matches exactly on the fields. | | +| expression | string | Javascript expression used for filtering events. If not specified, the behaviour is the same as an expression always true | | From 60fca108d118f27548cb8c7f1a2907c48113d106 Mon Sep 17 00:00:00 2001 From: slinkydeveloper Date: Wed, 5 Aug 2020 18:31:27 +0200 Subject: [PATCH 2/4] Renamed expression to jsExpression Signed-off-by: Francesco Guardiani --- docs/spec/broker.md | 8 ++++---- docs/spec/spec.md | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/spec/broker.md b/docs/spec/broker.md index 5538fd22779..2f2787a0789 100644 --- a/docs/spec/broker.md +++ b/docs/spec/broker.md @@ -42,14 +42,14 @@ progress to Ready when its assigned Broker exists and is Ready. #### Event filters -Implementations of Trigger MUST support both attributes filter and expression +Implementations of Trigger MUST support both attributes filter and jsExpression filter. The attributes filter specifying a list of key-value pairs MUST be supported by Trigger. Events that pass the attributes filter MUST include context or extension attributes that match all key-value pairs exactly. -The expression filter specifying a Javascript expression MUST be supported by +The jsExpression filter specifying a Javascript expression MUST be supported by Trigger. If the evaluation of the expression returns a Javascript value coercible to the boolean `true`, then the trigger filter MUST pass the event. Implementations MUST make the event accessible, within the expression, through @@ -59,8 +59,8 @@ should be accessible with `event.id`. Implementations MUST coerce CloudEvent types to JS types. For example the value of an attribute with type `Timestamp` should be translated to the JS type `Date`. -If a Trigger specify both attributes and expression filters, then the event MUST -pass only and only if both filters pass the event. +If a Trigger specify both attributes and jsExpression filters, then the event +MUST pass only and only if both filters pass the event. ## Data Plane diff --git a/docs/spec/spec.md b/docs/spec/spec.md index a82c6264f19..8435214efec 100644 --- a/docs/spec/spec.md +++ b/docs/spec/spec.md @@ -243,7 +243,7 @@ retrieved from ref. ### TriggerFilter -| Field | Type | Description | Constraints | -| ---------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------- | -| attributes | map[string]string | A filter specifying which events match this trigger. Matches exactly on the fields. | | -| expression | string | Javascript expression used for filtering events. If not specified, the behaviour is the same as an expression always true | | +| Field | Type | Description | Constraints | +| ------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------- | +| attributes | map[string]string | A filter specifying which events match this trigger. Matches exactly on the fields. | | +| jsExpression | string | Javascript expression used for filtering events. If not specified, the behaviour is the same as an expression always true | | From 158a50cc3b573016ae55938c68e73536ae4b8e3d Mon Sep 17 00:00:00 2001 From: slinkydeveloper Date: Wed, 5 Aug 2020 18:38:47 +0200 Subject: [PATCH 3/4] Added an expression sample Signed-off-by: Francesco Guardiani --- docs/spec/broker.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/spec/broker.md b/docs/spec/broker.md index 2f2787a0789..77fda92fd44 100644 --- a/docs/spec/broker.md +++ b/docs/spec/broker.md @@ -59,6 +59,19 @@ should be accessible with `event.id`. Implementations MUST coerce CloudEvent types to JS types. For example the value of an attribute with type `Timestamp` should be translated to the JS type `Date`. +An example jsExpression is: + +```js +event.id.indexOf("francesco") != -1 && + event.time != null && + event.time.getFullYear() >= 2020 && + event.exta != null; +``` + +This expression MUST pass the event iff the event id contains the string +`francesco`, event time has a year greater or equal to 2020 and event contains +an extension named `exta`. + If a Trigger specify both attributes and jsExpression filters, then the event MUST pass only and only if both filters pass the event. From 514aa16292610ba077811c35e6997a11f32cb6ed Mon Sep 17 00:00:00 2001 From: slinkydeveloper Date: Thu, 6 Aug 2020 10:04:47 +0200 Subject: [PATCH 4/4] Added clarification about js version supported Signed-off-by: Francesco Guardiani --- docs/spec/broker.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/spec/broker.md b/docs/spec/broker.md index 77fda92fd44..ea46ad9c858 100644 --- a/docs/spec/broker.md +++ b/docs/spec/broker.md @@ -50,7 +50,11 @@ Trigger. Events that pass the attributes filter MUST include context or extension attributes that match all key-value pairs exactly. The jsExpression filter specifying a Javascript expression MUST be supported by -Trigger. If the evaluation of the expression returns a Javascript value +Trigger. Implementations MUST support evaluation of Javascript expressions +following the standard +[EcmaScript 5.1](http://www.ecma-international.org/ecma-262/5.1/), although they +MAY support [EcmaScript 6](http://www.ecma-international.org/ecma-262/6.0/) or +greater. If the evaluation of the expression returns a Javascript value coercible to the boolean `true`, then the trigger filter MUST pass the event. Implementations MUST make the event accessible, within the expression, through the variable `event` and its context attributes and extensions through the