Intents

Intents are the reactive core of PrioStack applications. They enable services to respond automatically to events and changes in the system, creating event-driven architectures. When a sensor detects a specific condition, the corresponding intent executes a function to handle the situation.

How Intents Work

Intents follow a simple but powerful pattern: WHEN something happens, THEN execute a function. This reactive approach enables services to maintain system consistency, handle cleanup tasks, and implement complex workflows.

The Intent Flow

1. Sensor Activation: A sensor detects a specific condition or event
2. Intent Matching: The system finds intents that respond to this sensor
3. Function Execution: The intent's handler function is called
4. Result Processing: The function's result may trigger additional intents

Intent Configuration

Intents are defined in service YAML files under the intents section. Each intent specifies what triggers it and what action to take.

Basic Intent Structure

intents:
  - name: cleanupExpiredSessions
    whenSensor: userInactive
    toFunc: wasm:auth:cleanupSession
    primitiveIntent: cleanup
    cooldown: 5m

Intent Fields

Primitive Intents

Primitive intents define the fundamental behaviors that intents can exhibit. Each primitive intent represents a different type of system response.

Available Primitive Intents

stateMutation

Modifies internal state or data. Used for updating records, changing status, or maintaining data consistency.

- name: updateInventory
  whenSensor: productSold
  toFunc: wasm:inventory:updateStock
  primitiveIntent: stateMutation

validation

Validates data integrity or business rules. Used to ensure data quality and prevent invalid states.

- name: validateOrder
  whenSensor: orderSubmitted
  toFunc: wasm:orders:validateOrderData
  primitiveIntent: validation

workflow

Orchestrates multi-step processes. Used for complex business logic that involves multiple steps or external systems.

- name: processPayment
  whenSensor: orderPaid
  toFunc: wasm:payment:processTransaction
  primitiveIntent: workflow
  retries: 3

notification

Sends notifications or alerts. Used for informing users, triggering external systems, or logging important events.

- name: notifyShipping
  whenSensor: orderConfirmed
  toFunc: wasm:shipping:notifyWarehouse
  primitiveIntent: notification

cleanup

Performs cleanup operations. Used for removing expired data, closing connections, or freeing resources.

- name: cleanupSessions
  whenSensor: userInactive
  toFunc: wasm:auth:cleanupExpiredSessions
  primitiveIntent: cleanup
  cooldown: 1h

Sensors

Sensors are the triggers that activate intents. They represent events, conditions, or state changes in the system that services need to respond to.

Built-in Sensors

PrioStack provides several built-in sensors that cover common use cases:

Time-based Sensors

• scheduled - Triggers at specific times or intervals
• timeout - Triggers when operations exceed time limits
• expired - Triggers when data or sessions expire

Data Change Sensors

• created - Triggers when new records are created
• updated - Triggers when records are modified
• deleted - Triggers when records are removed

System State Sensors

• error - Triggers when errors occur
• threshold - Triggers when metrics exceed thresholds
• statusChange - Triggers when status values change

Custom Sensors

Services can define custom sensors by emitting events from their WASM functions. Custom sensors follow the naming pattern: serviceName:eventName.

// In a WASM function
emitSensor("order:paymentReceived");
emitSensor("inventory:stockLow");

Intent Execution

When a sensor is triggered, PrioStack finds all intents that match the sensor and executes their handler functions. Intent execution follows specific rules to ensure reliable operation.

Execution Rules

Concurrent Execution

Multiple intents can execute concurrently when triggered by the same sensor. This allows different services to respond to the same event independently.

Cooldown Periods

The cooldown field prevents intents from executing too frequently. Once an intent executes, it won't trigger again until the cooldown period expires.

- name: frequentCleanup
  whenSensor: cacheHit
  toFunc: wasm:cache:cleanupOldEntries
  primitiveIntent: cleanup
  cooldown: 10s  # Won't execute more than once every 10 seconds

Retry Logic

Failed intent executions can be automatically retried using the retries field. This ensures reliable operation even when transient failures occur.

- name: criticalNotification
  whenSensor: systemAlert
  toFunc: wasm:alerts:sendCriticalNotification
  primitiveIntent: notification
  retries: 3  # Retry up to 3 times on failure

Expiration

Intents can be configured to expire after a certain time using the expiresIn field. This prevents stale intents from executing long after they're relevant.

Intent Chaining

Intents can trigger other intents by emitting sensors from their handler functions. This creates chains of reactive behavior that can implement complex workflows.

Chaining Best Practices

• Use descriptive sensor names that indicate the outcome
• Avoid circular dependencies between intents
• Keep chains short and focused on specific workflows
• Use cooldowns to prevent cascading failures

Intent Monitoring

PrioStack provides visibility into intent execution through logging and metrics. This helps debug issues and optimize system performance.

Execution Logs

Every intent execution is logged with details about:

• Triggering sensor and data
• Execution start and end times
• Success/failure status
• Retry attempts (if any)

Performance Metrics

Intent performance is tracked through metrics like:

• Execution duration
• Success/failure rates
• Trigger frequency
• Queue depth (for high-frequency sensors)

Best Practices

Intent Design

• Single Responsibility: Each intent should do one specific thing
• Idempotent: Intents should be safe to execute multiple times
• Fast: Keep intent handlers lightweight and responsive
• Reliable: Use retries for critical operations

Sensor Naming

• Use consistent naming patterns (e.g., resource:action)
• Be specific about what changed (e.g., order:paid vs order:updated)
• Avoid generic names like change or update

Error Handling

• Always handle errors in intent functions
• Use appropriate retry counts for different failure types
• Log errors with sufficient context for debugging
• Consider circuit breakers for frequently failing intents