Welcome to st2

Your guide to understanding the codebase.

Learning Path Overview

  • 5 levels
  • 15 learning units

1. Orchestration & APIs

Units: 3
Pipelines, workflows, public interfaces

2. Pack-Based Plugin Architecture

Units: 7
Architecture

3. Data Models and Persistence

Units: 6
Data Model

4. Actions and Runners Fundamentals

Units: 1
Patterns

5. Core Logic & Data

Units: 3
Business rules, schemas, models

6. REST API and Serialization

Units: 6
API

7. Security and Access Control

Units: 5
Security

8. Triggers and Sensors

Units: 10
Workflow

9. Interaction & Integration

Units: 3
UI components, external connectors

10. Message Queue and Service Integration

Units: 8
Integration

11. Rules, Policies, and Automation

Units: 4
Workflow

12. Workflow Engines and Execution

Units: 2
Workflow

13. Cross-Cutting Concerns

Units: 2
Auth, logging, config, testing

14. ChatOps and Action Aliases

Units: 10
API

15. Observability and Operations

Units: 14
Infrastructure

16. Edge Cases & Resilience

Units: 1
Error handling, fault tolerance

17. Additional Data Model Patterns

Units: 11
Data Model

Test Your Knowledge

Test your deep understanding of the codebase.
Progress: 0/26 answered

Question Tiers (ordered for deep understanding)

  1. Why

    • Purpose & Problem
    • Architecture

  2. Design & Patterns

    • Code

  3. Implementation

Hands-On Assignment

Duration: 45-60 minutes

Your Challenge

Build a custom runner that executes actions with retry logic and exponential backoff. Your runner should accept parameters for max retries, initial delay, and backoff multiplier, then automatically retry failed actions while respecting these constraints. This will help you understand how runners interact with the execution framework and handle action lifecycle events.

Starting Points

  1. File: contrib/runners/action_chain_runner/action_chain_runner.py:1-93

    • Study how ActionChainRunner extends the base runner class, handles action execution, and manages state transitions

  2. File: contrib/runners/action_chain_runner/action_chain_runner.py:45-70

    • Notice how the run() method is implemented and how it returns action status

  3. File: contrib/examples/config.schema.yaml:1-21

    • Examine how runner parameters are defined using JSON schema - you'll need to create a similar schema for your retry runner

  4. Directory: contrib/runners/action_chain_runner/action_chain_runner/

    • Create your new retry_runner package here, following the same structure as action_chain_runner

Success Criteria

  • Runner successfully retries failed actions up to max_retries times.
  • Delays between retries follow exponential backoff pattern (can verify via logs/timing).
  • Runner stops retrying and returns success when action succeeds before max_retries.
  • Runner returns failure status when max_retries is exhausted.
  • config.schema.yaml properly validates runner parameters.
  • Runner can be registered and invoked through st2 action execution.

Hints

  • Hint 1: Understanding the Runner base class conceptual
  • Hint 2: Action execution and status handling code location
  • Hint 3: Parameter schema definition implementation
  • Hint 4: Implementing exponential backoff implementation
  • Hint 5: Testing your runner implementation

Prerequisites

  • Python classes and inheritance
  • Action execution model
  • JSON Schema basics