Runners

Runners in FunnelStory #

What is a Runner? #

A Runner in FunnelStory is a background task processor that executes specific business logic at regular intervals. Think of it as a scheduled job that runs automatically to keep your data fresh and perform various maintenance tasks.

Key Concepts #

Runner Interface #

Every runner must implement three core methods:

type Runner interface {
    Run(context.Context, time.Time, *Options) error  // Main execution logic
    ID() string                                      // Unique identifier
    Interval() time.Duration                         // How often to run
}

How Runners Work #

  1. Registration: Runners register themselves when the application starts
  2. Scheduling: The system checks each runner’s interval to determine if it should run
  3. Execution: Runners execute concurrently in separate goroutines
  4. Locking: Database advisory locks prevent multiple instances from running simultaneously
  5. Cleanup: Runners can optionally implement cleanup logic via the Closer interface

Runner Lifecycle # 

1. Application Start
   ↓
2. Runners Register (via init() functions)
   ↓
3. Tick() Function Called
   ↓
4. Check Runner Intervals
   ↓
5. Execute Eligible Runners (concurrently)
   ↓
6. Cleanup (if Closer interface implemented)
   ↓
7. Wait for Next Tick

Key Features #

Concurrency Safety #

  • Runners execute in parallel using goroutines
  • Database advisory locks prevent conflicts
  • Thread-safe error collection

Interval Management #

  • Each runner defines its own execution interval
  • System tracks last run time per workspace
  • Runners skip execution if not enough time has passed

Error Handling #

  • Individual runner failures don’t stop other runners
  • Errors are collected and returned together
  • Graceful degradation on failures

Workspace Isolation #

  • Each workspace runs its own set of runners
  • Advisory locks are workspace-specific
  • No cross-workspace interference

Best Practices #

  • Keep runners focused: Each runner should have a single, clear purpose
  • Handle errors gracefully: Don’t let one failure crash the entire system
  • Use appropriate intervals: Balance between freshness and resource usage
  • Implement proper cleanup: Release resources when the runner is done
  • Log appropriately: Use structured logging for debugging and monitoring
  • Test thoroughly: Runners run in production, so ensure they’re reliable

Monitoring #

The system provides visibility into runner execution:

  • runnersTriggered map shows which runners executed
  • Error collection provides failure details
  • Logging captures execution details and errors

Runners are essential for keeping FunnelStory’s data fresh and performing automated tasks that enhance the user experience.