Merge pull request #1 from fystack/feat/allow-custom-actions

Allow custom actions

Author: anhthii

README.md

@@ -134,6 +134,87 @@ default:
 
 `Matched` is true when a specific rule (or a policy-level default) triggered. If all policies fall back to the document default, `Matched` remains false but `Effect` still reflects the decision (`ALLOW` or `DENY`).
 
+### User-defined actions (custom effects)
+
+The engine ships with two built-in effects (`ALLOW` and `DENY`) but accepts any non-empty string as an effect. `DENY` always short-circuits evaluation; every other effect is treated equally—first match wins. This lets you model domain-specific outcomes without forking or wrapping the engine:
+
+```go
+package main
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/fystack/programmable-policy-engine/policy"
+)
+
+// Define your own effects alongside the built-in ones.
+const (
+	EffectAutoApprove policy.Effect = "AUTO_APPROVE"
+	EffectFlagReview  policy.Effect = "FLAG_FOR_REVIEW"
+)
+
+func main() {
+	defaultEffect := policy.EffectDeny
+
+	doc := policy.Document{
+		DefaultEffect: &defaultEffect,
+		Policies: []policy.Policy{
+			{
+				Name: "withdrawal-approval",
+				Rules: []policy.Rule{
+					{
+						ID:        "block_large",
+						Effect:    policy.EffectDeny,
+						Condition: "ValueUSD > 50000",
+					},
+					{
+						ID:        "auto_approve_small_whitelisted",
+						Effect:    EffectAutoApprove,
+						Condition: "IsWhitelisted && ValueUSD < 5000",
+					},
+					{
+						ID:        "flag_medium",
+						Effect:    EffectFlagReview,
+						Condition: "ValueUSD >= 5000 && ValueUSD <= 50000",
+					},
+					{
+						ID:        "allow_whitelisted",
+						Effect:    policy.EffectAllow,
+						Condition: "IsWhitelisted",
+					},
+				},
+			},
+		},
+	}
+
+	engine, err := policy.CompileDocument(doc)
+	if err != nil {
+		panic(err)
+	}
+
+	input := map[string]any{
+		"ValueUSD":      3500.0,
+		"IsWhitelisted": true,
+	}
+
+	decision := engine.Evaluate(context.Background(), input)
+
+	switch decision.Effect {
+	case policy.EffectDeny:
+		fmt.Println("blocked:", decision.Message)
+	case EffectAutoApprove:
+		fmt.Println("auto-approved — no manual review needed")
+	case EffectFlagReview:
+		fmt.Println("flagged for manual review")
+	case policy.EffectAllow:
+		fmt.Println("allowed — requires standard approval")
+	}
+}
+```
+
+Because the caller defines what each effect means, you can extend the decision space (e.g., `RATE_LIMIT`, `QUARANTINE`, `NOTIFY_COMPLIANCE`) without changing the engine.
+
 ### Mapping snake_case JSON to expr fields
 
 Use the `expr` struct tag to expose snake_case JSON fields with the same name inside expressions:

policy/effect.go

@@ -10,12 +10,8 @@ const (
 	EffectDeny Effect = "DENY"
 )
 
-// IsValid returns true when the effect is one of the supported values.
-func (e Effect) IsValid() bool {
-	switch e {
-	case EffectAllow, EffectDeny:
-		return true
-	default:
-		return false
-	}
+// IsDeny returns true for the built-in deny effect.
+// Deny effects short-circuit evaluation (first deny wins).
+func (e Effect) IsDeny() bool {
+	return e == EffectDeny
 }

policy/engine.go

@@ -69,8 +69,8 @@ func CompileDocument(doc Document, opts ...EngineOption) (*Engine, error) {
 		engine.defaultEffect = *doc.DefaultEffect
 	}
 
-	if !engine.defaultEffect.IsValid() {
-		return nil, fmt.Errorf("invalid default effect %q", engine.defaultEffect)
+	if engine.defaultEffect == "" {
+		return nil, fmt.Errorf("default effect cannot be empty")
 	}
 
 	compiled := make([]*compiledPolicy, 0, len(doc.Policies))
@@ -107,8 +107,8 @@ func (e *Engine) Evaluate(_ context.Context, input any) Decision {
 		return decision
 	}
 
-	var allowDecision Decision
-	var hasAllowDecision bool
+	var matchedDecision Decision
+	var hasMatchedDecision bool
 	evaluated := 0
 
 	policyErrors := make([][]error, len(e.policies))
@@ -140,15 +140,15 @@ func (e *Engine) Evaluate(_ context.Context, input any) Decision {
 			}
 			matchDecision.ErrorMessage = cleanErrorMessage(matchDecision.Error)
 
-			if rule.rule.Effect == EffectDeny {
+			if rule.rule.Effect.IsDeny() {
 				return matchDecision
 			}
 
 			policyMatched = true
 
-			if !hasAllowDecision {
-				allowDecision = matchDecision
-				hasAllowDecision = true
+			if !hasMatchedDecision {
+				matchedDecision = matchDecision
+				hasMatchedDecision = true
 			}
 		}
 
@@ -163,19 +163,19 @@ func (e *Engine) Evaluate(_ context.Context, input any) Decision {
 			}
 			defaultDecision.ErrorMessage = cleanErrorMessage(defaultDecision.Error)
 
-			if policy.defaultEffect == EffectDeny {
+			if policy.defaultEffect.IsDeny() {
 				return defaultDecision
 			}
 
-			if !hasAllowDecision {
-				allowDecision = defaultDecision
-				hasAllowDecision = true
+			if !hasMatchedDecision {
+				matchedDecision = defaultDecision
+				hasMatchedDecision = true
 			}
 		}
 	}
 
-	if hasAllowDecision {
-		return allowDecision
+	if hasMatchedDecision {
+		return matchedDecision
 	}
 
 	decision.Evaluated = evaluated
@@ -209,8 +209,8 @@ func compilePolicy(p Policy, cfg engineConfig) (*compiledPolicy, error) {
 		hasLocalDefault = true
 	}
 
-	if hasLocalDefault && !policyDefault.IsValid() {
-		return nil, fmt.Errorf("policy %q has invalid default effect %q", p.Name, policyDefault)
+	if hasLocalDefault && policyDefault == "" {
+		return nil, fmt.Errorf("policy %q has empty default effect", p.Name)
 	}
 
 	if len(p.Rules) == 0 && !hasLocalDefault {
@@ -243,8 +243,8 @@ func compilePolicy(p Policy, cfg engineConfig) (*compiledPolicy, error) {
 
 		p.Rules[idx] = rule
 
-		if !rule.Effect.IsValid() {
-			return nil, fmt.Errorf("rule %q has invalid effect %q", rule.ID, rule.Effect)
+		if rule.Effect == "" {
+			return nil, fmt.Errorf("rule %q has empty effect", rule.ID)
 		}
 
 		if rule.Condition == "" {