[Design Discussion] Pre/ Post Execution Hooks for Flow Validations

[ThaminduDilshan]

Related Feature Issue

N/A

Problem Summary

Thunder flow engine currently relies on executors as the primary workers within a flow graph. Each executor is attached to a task execution node, and the flow definition (graph) explicitly wires nodes together. This works well for the core flow logic, but introduces friction for cross-cutting concerns — operations that need to run across many (or all) nodes/requests but don't belong in the per-node execution path. Some examples are;

• Input validators (format, length, encoding checks on user-supplied data)
• CAPTCHA / bot detection (must run before user input reaches any executor)
• Rate limiting / abuse prevention (per-request, per-flow, or per-node)

Following current pattern, implementing these as executors would require duplicating nodes throughout every flow definition, which is impractical. Some concerns (e.g., challenge token validation, permission validation, attribute uniqueness) are already handled through hardcoded checks in the engine or via special-purpose executors (PermissionValidator, AttributeUniquenessValidator), but there is no unified model for them.

We need a first-class abstraction that lets these cross-cutting concerns be declared once and engaged automatically at the right lifecycle points, without polluting every flow graph.

High-Level Approach

Naming note: This document uses the placeholder term "interceptor" throughout. The final name is an open question — see the naming poll at the end.

Introduce an interceptor abstraction — lightweight, focused processing units that execute at well-defined lifecycle points during flow execution. Interceptors are distinct from executors in that:

1. They are not nodes in the flow graph — they don't occupy graph positions or affect flow topology
2. They execute at lifecycle points managed by the engine, not through node traversal
3. They can be configured once at the flow level and selectively applied to specific nodes or all nodes

Lifecycle Points

Interceptors engage at specific points in the engine's execution lifecycle:

┌──────────────────────────────────────────────────────────────┐
│                     Flow Request Arrives                     │
│                                                              │
│  ┌────────────────────────────────────────────────────────┐  │
│  │         PRE_REQUEST Interceptors                       │  │
│  │  (once per incoming request, before any node runs)     │  │
│  │  Examples: rate limiter, CAPTCHA, input sanitizer,     │  │
│  │           challenge token validation                   │  │
│  └──────────────────────┬─────────────────────────────────┘  │
│                         │                                    │
│  ┌──────────────────────▼─────────────────────────────────┐  │
│  │              Node Execution Loop                       │  │
│  │                                                        │  │
│  │  For each node:                                        │  │
│  │  ┌─────────────────────────────────────────────────┐   │  │
│  │  │      PRE_NODE Interceptors                      │   │  │
│  │  │  (before each node executes)                    │   │  │
│  │  │  Examples: permission validator,                │   │  │
│  │  │    attribute uniqueness validator               │   │  │
│  │  └────────────────────┬────────────────────────────┘   │  │
│  │                       │                                │  │
│  │  ┌────────────────────▼────────────────────────────┐   │  │
│  │  │       Node Execution (current behavior)         │   │  │
│  │  └────────────────────┬────────────────────────────┘   │  │
│  │                       │                                │  │
│  │  ┌────────────────────▼────────────────────────────┐   │  │
│  │  │      POST_NODE Interceptors                     │   │  │
│  │  │  (after each node completes)                    │   │  │
│  │  │  Examples: output sanitizer                     │   │  │
│  │  └─────────────────────────────────────────────────┘   │  │
│  │                                                        │  │
│  └──────────────────────┬─────────────────────────────────┘  │
│                         │                                    │
│  ┌──────────────────────▼─────────────────────────────────┐  │
│  │         POST_REQUEST Interceptors                      │  │
│  │  (once per request, after all node processing)         │  │
│  │  Examples: response enrichment                         │  │
│  └────────────────────────────────────────────────────────┘  │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Interceptor Categories

Category	Description	Examples
Default	Always enforced by the engine. Not configurable — they run unconditionally.	Challenge token validation, sensitive data cleanup, request context validation
Configurable	Declared in the flow definition. Flow author adds, configures, and scopes them to specific nodes.	CAPTCHA, input validators, rate limiting, attribute uniqueness validation, permission validation

Default interceptors are invisible in the flow definition and enforced in engine code. Configurable interceptors are explicitly declared and can be scoped to all nodes or selected nodes.

Architecture Overview

Interface

Interceptors follow the same Execute(ctx) → result pattern as executors, but with a narrower contract:

• They receive an InterceptorContext carrying the HTTP request context, flow state, current node info, and interceptor-specific properties
• They return a pass/fail result with an optional failure reason
• They can enrich the execution context via RuntimeData
• They cannot modify the flow graph, change node routing, or tamper with authentication state

Registration and Metadata

Interceptors register with an InterceptorRegistry at startup, mirroring the executor registry pattern. Each interceptor self-describes its metadata at registration:

Metadata	Purpose	Example values
Name	Unique identifier, referenced in flow definitions	"CaptchaInterceptor", "RateLimiter"
Modes	Supported modes	PRE_REQUEST, PRE_NODE, POST_NODE, POST_REQUEST
Category	Whether the engine enforces it or the flow author configures it	DEFAULT, CONFIGURABLE
Priority	Execution order within the same mode (lower = runs first)	100 (default), 200 (configurable)

Default interceptors always run. Configurable interceptors only run when declared in the flow definition.

Scoping

Configurable interceptors declare their scope in the flow definition:

• "scope": "ALL" — runs for every node
• "scope": "SELECTED" with "applyTo": [...] — runs only for listed nodes

Nodes can opt out of globally-scoped interceptors via "skipInterceptors" in their existing properties.

{
    "id": "some_internal_node",
    "type": "TASK_EXECUTION",
    "properties": {
        "skipInterceptors": ["InputValidator"]
    },
    "executor": {
        "name": "SomeExecutor"
    },
    "onSuccess": "end"
}

Engine Integration

The engine invokes interceptors at each lifecycle point within the existing execution loop. Default interceptors always run; configurable ones run only when declared in the flow definition. Failure at any point halts execution and returns error to the client.

Execute(ctx):
    runInterceptors(PRE_REQUEST, ctx)
    
    for each node:
        runInterceptors(PRE_NODE, ctx, node)
        node.Execute(ctx)
        runInterceptors(POST_NODE, ctx, node)
    
    runInterceptors(POST_REQUEST, ctx)

Configurable interceptors are declared as a top-level interceptors array alongside nodes. They use properties for configuration (same pattern as nodes). Nodes opt out of globally-scoped interceptors via their existing properties field.

{
    "name": "Default Basic Authentication Flow",
    "handle": "default-basic-flow",
    "flowType": "AUTHENTICATION",
    "interceptors": [
        {
            "name": "CaptchaInterceptor",
            "mode": "PRE_NODE",
            "scope": "SELECTED",
            "applyTo": ["prompt_credentials"],
            "properties": {
                "provider": "recaptcha",
                "siteKey": "..."
            }
        },
        {
            "name": "RateLimiter",
            "mode": "PRE_REQUEST",
            "scope": "ALL",
            "properties": {
                "maxAttempts": 5,
                "windowSeconds": 300
            }
        }
    ],
    "nodes": [
        {
            "id": "start",
            "type": "START",
            "onSuccess": "prompt_credentials"
        },
        {
            "id": "prompt_credentials",
            "type": "PROMPT",
            "meta": { "..." : "..." },
            "prompts": [
                {
                    "inputs": [
                        {
                            "ref": "input_001",
                            "identifier": "username",
                            "type": "TEXT_INPUT",
                            "required": true
                        },
                        {
                            "ref": "input_002",
                            "identifier": "password",
                            "type": "PASSWORD_INPUT",
                            "required": true
                        }
                    ],
                    "action": {
                        "ref": "action_001",
                        "nextNode": "basic_auth"
                    }
                }
            ]
        },
        {
            "id": "basic_auth",
            "type": "TASK_EXECUTION",
            "executor": {
                "name": "BasicAuthExecutor"
            },
            "onSuccess": "authorization_check",
            "onIncomplete": "prompt_credentials"
        },
        {
            "id": "authorization_check",
            "type": "TASK_EXECUTION",
            "executor": {
                "name": "AuthorizationExecutor"
            },
            "onSuccess": "auth_assert"
        },
        {
            "id": "auth_assert",
            "type": "TASK_EXECUTION",
            "properties": {
                "skipInterceptors": ["RateLimiter"]
            },
            "executor": {
                "name": "AuthAssertExecutor"
            },
            "onSuccess": "end"
        },
        {
            "id": "end",
            "type": "END"
        }
    ]
}

Key points in this example:

• CaptchaInterceptor runs PRE_NODE, scoped only to prompt_credentials — it validates the CAPTCHA before the prompt node processes user input
• RateLimiter runs PRE_REQUEST for all requests — but auth_assert opts out via skipInterceptors in its properties
• Default interceptors (challenge token, sensitive data cleanup) run automatically without being declared here

Existing Patterns That Become Interceptors

Several existing mechanisms would be unified under this model:

Current Implementation	Interceptor Equivalent	Category	Mode
validateChallengeToken() in engine	ChallengeTokenInterceptor	Default	PRE_REQUEST
clearSensitiveInputs() in engine	SensitiveDataInterceptor	Default	POST_NODE
PermissionValidator executor	PermissionInterceptor	Configurable	PRE_NODE
AttributeUniquenessValidator executor	UniquenessInterceptor	Configurable	PRE_NODE

Security Considerations

• Interceptor ordering matters: Interceptors within the same mode execute in priority order (ascending) as declared during registration. Default interceptors register with lower priority values to ensure they always run first. For configurable interceptors with equal priority, declaration order in the flow definition is the tiebreaker.
• Default interceptors cannot be bypassed: The engine guarantees that default interceptors (like challenge token validation) always execute, regardless of flow definition configuration or node-level skipInterceptors.
• Context isolation: Interceptors have read access to the context but limited write access. They cannot modify the flow graph, change node routing, or tamper with authentication state. Only RuntimeData enrichment is permitted.
• Sensitive data in properties: Interceptor properties containing secrets (API keys) stored in flow definitions must follow the same encryption/protection patterns used for other sensitive configuration.

Impacted Areas

• Flow Engine (flowexec/engine.go) — Interceptor invocation points in the execution loop
• Flow Core (flow/core/) — InterceptorInterface, InterceptorContext, InterceptorResult definitions
• Flow Interceptor (flow/interceptor/) — NEW package with registry, init, and interceptor implementations
• Flow Definition Model (flow/mgt/model.go) — InterceptorDefinition struct and interceptors field on FlowDefinition
• Graph Builder (flow/mgt/graph_builder.go) — Parsing interceptor definitions from flow definitions
• Flow Builder UI — Visual representation and configuration of interceptors in the flow composer
• Executor Package (flow/executor/) — Migration of PermissionValidator and AttributeUniquenessValidator to flow/interceptor/

Alternatives Considered

Alternative 1: Keep validators as executors with special handling

• Pros: No new abstraction needed, works within current model
• Cons: Requires duplicating executor nodes in every flow; no clean separation of per-request vs per-node concerns; pain point grows as more validators are needed

Alternative 2: Middleware-style pipeline (wrap the entire engine)

• Pros: Familiar pattern from HTTP middleware; clean for per-request concerns
• Cons: Doesn't handle per-node scoping well; too coarse-grained for node-level validators

Alternative 3: Implicit executor chains (engine auto-inserts hidden nodes)

• Pros: Reuses existing executor infrastructure; no new interface
• Cons: Hidden graph mutations are confusing; execution history shows phantom nodes

Questions for Community Input

1. Naming — Pick the term that best communicates the intent for this abstraction:

   Candidate	Reasoning
   Guard	Implies protection/gatekeeper — strong for validation use cases, but may feel narrow if used for non-security concerns
   Interceptor	Generic, well-known in Java EE / Spring — implies catching requests in transit
   Policy	Implies declarative rules — common in authz/cloud contexts (OPA, Kubernetes)
   Filter	Familiar from Servlet Filters — implies selection/validation, but may imply data transformation
   Checkpoint	Implies a validation gate — clear for pre-execution checks, but less intuitive for post-execution

2. Mode vs Hook — For the lifecycle point field on the interceptor definition, should we use "mode" (consistent with executor definitions) or "hook" (more semantically explicit about lifecycle engagement)?

3. UX of flow builder UI, mainly how are we going to represent validators in the flow configuration UI.

[ThaminduDilshan]

Implementation Details

Package Structure

A new flow/interceptor package alongside the existing flow/executor, following the same organizational pattern:

backend/internal/flow/
├── common/              # Shared constants and models (existing)
├── core/                # Graph, node, executor interfaces (existing)
│   ├── interceptor.go   # NEW — InterceptorInterface, InterceptorContext, InterceptorResult
│   └── ...              
├── executor/            # Executor implementations and registry (existing)
├── interceptor/         # NEW — Interceptor implementations and registry
│   ├── init.go          # Initialize() — registers all interceptors
│   ├── registry.go      # InterceptorRegistry implementation
│   ├── constants.go     # Interceptor names, mode constants, priorities
│   ├── challenge_token_interceptor.go   # Default: PRE_REQUEST
│   ├── sensitive_data_interceptor.go    # Default: POST_NODE
│   ├── permission_interceptor.go        # Configurable: PRE_NODE
│   ├── uniqueness_interceptor.go        # Configurable: PRE_NODE
│   └── ...
├── flowexec/            # Engine and service (existing — adds interceptor hooks)
├── flowmeta/            # Flow metadata service (existing)
└── mgt/                 # Flow management and graph builder (existing)

Interceptor Interface

An interceptor follows a contract similar to executors — with an Execute method — but with a narrower, validation-focused context:

// InterceptorInterface defines the interface for flow interceptors.
type InterceptorInterface interface {
    // Execute runs the interceptor logic and returns a result.
    Execute(ctx *InterceptorContext) (*InterceptorResult, error)

    // Other common methods. Can decide which are required at the implementation time.
    GetName() string
    GetMode() InterceptorMode
    GetCategory() InterceptorCategory
    GetPriority() int
}

The interceptor context carries the execution state and the HTTP request context:

// InterceptorContext holds the context available to an interceptor during execution.
type InterceptorContext struct {
    // Context carries the HTTP request context (includes request metadata,
    // permissions, trace IDs, etc.)
    Context context.Context

    // Flow-level fields
    ExecutionID   string
    FlowType      common.FlowType
    AppID         string
    UserInputs    map[string]string
    RuntimeData   map[string]string
    Application   appmodel.Application

    // Node-level fields (nil for PRE_REQUEST/POST_REQUEST interceptors)
    CurrentNodeID string
    NodeType      common.NodeType

    // Interceptor-specific properties (from flow definition)
    Properties map[string]interface{}

    // Authenticated user state
    AuthenticatedUser authncm.AuthenticatedUser
    ExecutionHistory  map[string]*common.NodeExecutionRecord
}

The result is pass/fail with optional context enrichment:

// InterceptorResult holds the outcome of an interceptor execution.
type InterceptorResult struct {
    // Status indicates whether the interceptor passed or failed.
    Status InterceptorStatus // PASS or FAIL

    // FailureReason provides a human-readable reason when Status is FAIL.
    FailureReason string

    // RuntimeData allows interceptors to enrich the execution context
    // (e.g., set metadata for downstream nodes).
    RuntimeData map[string]string
}

Key constraints:

• Interceptors cannot modify the flow graph topology or change what node executes next
• Interceptors cannot tamper with authentication state
• Interceptors can enrich the execution context via RuntimeData

Registration and Metadata

Interceptors register with an InterceptorRegistry during initialization, following the same pattern as executor registration. Each interceptor self-describes its metadata at registration time — the engine uses this metadata to determine when and in what order to run each interceptor.

// InterceptorRegistryInterface defines registry operations for interceptors.
type InterceptorRegistryInterface interface {
    RegisterInterceptor(interceptor InterceptorInterface)
    GetInterceptors(mode InterceptorMode) []InterceptorInterface
    GetInterceptor(name string) (InterceptorInterface, error)
    IsRegistered(name string) bool
}

The registry groups interceptors by mode and sorts them by priority within each group. At initialization time, all interceptors register themselves with their metadata:

// Initialize registers available interceptors and returns the interceptor registry.
func Initialize(
    flowFactory core.FlowFactoryInterface,
    // ... service dependencies
) InterceptorRegistryInterface {
    reg := newInterceptorRegistry()

    // Default interceptors (always enforced, high priority)
    reg.RegisterInterceptor(newChallengeTokenInterceptor(...))
    reg.RegisterInterceptor(newSensitiveDataInterceptor(...))

    // Configurable interceptors (engaged via flow definition)
    reg.RegisterInterceptor(newPermissionInterceptor(flowFactory))
    reg.RegisterInterceptor(newUniquenessInterceptor(flowFactory, userSchemaService, userProvider))
    reg.RegisterInterceptor(newCaptchaInterceptor(...))
    reg.RegisterInterceptor(newRateLimiterInterceptor(...))

    return reg
}

Each interceptor declares its metadata through the interface methods:

Metadata	Purpose	Example values
Name	Unique identifier, referenced in flow definitions	"CaptchaInterceptor", "RateLimiter"
Modes	Supported modes	PRE_REQUEST, PRE_NODE, POST_NODE, POST_REQUEST
Category	Whether the engine enforces it or the flow author configures it	DEFAULT, CONFIGURABLE
Priority	Execution order within the same mode (lower = runs first)	100 (default), 200 (configurable)

The engine uses this metadata at runtime:

• Default interceptors always run at their declared mode, regardless of flow definition. They cannot be skipped via skipInterceptors.
• Configurable interceptors only run when declared in the flow definition's interceptors array. The flow definition provides the scope/applyTo and runtime properties.
• Within the same mode, interceptors execute in priority order (ascending). Default interceptors typically register with lower priority values so they run before configurable ones.

Interceptor Engagement Model

Per-Request Interceptors (mode: PRE_REQUEST / POST_REQUEST):

• Execute once per incoming API request, regardless of how many nodes the engine processes
• Receive the engine context (with context.Context carrying the HTTP request)
• CurrentNodeID and NodeType are empty in the interceptor context
• Suitable for rate limiting, CAPTCHA validation, response enrichment

Per-Node Interceptors (mode: PRE_NODE / POST_NODE):

• Execute before/after each individual node in the execution loop
• Receive both engine context and current node info
• Can be scoped to all nodes or selected nodes
• Suitable for permission validation, input validation

Node Scoping for Per-Node Interceptors

Configurable interceptors specify their scope in the flow definition:

• "scope": "ALL" — runs for every node in the flow
• "scope": "SELECTED" with "applyTo": [...] — runs only for the listed node IDs

Nodes can opt out of globally-scoped interceptors via their existing properties field:

{
    "id": "some_internal_node",
    "type": "TASK_EXECUTION",
    "properties": {
        "skipInterceptors": ["InputValidator"]
    },
    "executor": {
        "name": "SomeExecutor"
    },
    "onSuccess": "end"
}

Engine Integration

The interceptor execution is woven into the existing engine loop:

Execute(ctx):
    runInterceptors(PRE_REQUEST, ctx)             ← NEW
    
    for each node:
        runInterceptors(PRE_NODE, ctx, node)      ← NEW
        node.Execute(ctx)                         ← existing
        runInterceptors(POST_NODE, ctx, node)     ← NEW
    
    runInterceptors(POST_REQUEST, ctx)            ← NEW

Interceptor failure at any point halts execution and returns an appropriate error response to the client.