When cause functions

One of the advantages of using a rules language like SQRL is that the actions taken by the system can easily be explained and understood.

1
2
3
4
5
CREATE RULE SimilarTextIpSpam WHERE
  rateLimited(BY TextSimhash MAX 10 EVERY MINUTE)
  WITH REASON "Used similar text (${TextSimhash}) more than ten times in a single minute.";

WHEN SimilarTextIpSpam THEN addUserToReviewQueue("spam");

The function addUserToReviewQueue does not exist in the standard library, but if you were implementing it you can access the rules that triggered the call and their reasons.

In the case above the cause may be:

1
2
3
4
5
6
{
  "firedRules": [{
    "name": "SimilarTextIpSpam",
    "reason": "Used similar text (cf112e11) more than ten times in a single minute."
  }]
}

Creating Statements with WHEN causes

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
registry.registerStatement(
  "SqrlReviewQueueStatements",
  async function addUserToReviewQueue(
    state: Execution,
    cause: WhenCause,
    queue: string
  ) {
    // Add to the queue somehow, and save the rule reason string.
  },
  {
    args: [
      AT.state,
      AT.whenCause,
      AT.any.string
    ],
    allowNull: true
  }
);

Your addUserToReviewQueue function will be provided with additional context about why it was triggered. For more information about exactly what is included see the WhenCause reference documentation.