A V language implementation of the Hero Baobab runner system for distributed job execution. This runner provides a Redis-based job queue system with support for various executors including tmux sessions.

Overview

The Hero Runner V is a lightweight, high-performance job execution system built in V lang. It connects to Redis for job queuing and supports multiple execution environments through configurable executors.

Features

Redis-based Job Queue: Reliable job queuing and status tracking
Multiple Executors: Support for tmux sessions, windows, and panes
Job Lifecycle Management: Complete job status tracking (dispatched → started → finished/error)
Configurable Timeouts: Per-job timeout configuration
Environment Variables: Job-specific environment variable support
Namespace Support: Multi-tenant runner organization
CLI Interface: Command-line interface with flag parsing

Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Redis Queue   │    │     Runner      │    │    Executor     │
│                 │    │                 │    │                 │
│  Job Storage    │◄──►│  Job Processor  │◄──►│ tmux.session    │
│  Status Updates │    │  Status Manager │    │ tmux.window     │
│                 │    │                 │    │ tmux.pane       │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Installation

Prerequisites

V language compiler
Redis server
Herolib dependencies

Quick Install

# Run the installation script
./scripts/install.sh

This will:

Install V language and Herolib
Set up module dependencies
Link the runner module to vmodules

Manual Installation

# Install V & Herolib
curl 'https://raw.githubusercontent.com/freeflowuniverse/herolib/refs/heads/development/install_v.sh' > /tmp/install_v.sh
bash /tmp/install_v.sh --analyzer --herolib 

# Install herolib
cd ${HOME}/code/github/freeflowuniverse/herolib
bash install_herolib.vsh

# Link runner module
mkdir -p "${HOME}/.vmodules/herocode"
ln -s "/path/to/runner_v/src" "${HOME}/.vmodules/herocode/runner"

Usage

Starting the Runner

# Start with default settings
./scripts/run.sh

# Or run directly with custom options
./cmd/runner.vsh --name my_runner --namespace production --redis_url redis://localhost:6379

Command Line Options

Usage: runner [flags]

Flags:
  -n   --name         name of the runner (default: test_runner)
  -s   --namespace    namespace of the runner (default: '')
  -r   --redis_url    redis url (default: 127.0.0.1:6379)
  -h   --help         Show help message

Creating and Dispatching Jobs

import herocode.runner
import freeflowuniverse.herolib.core.redisclient
import time

// Create a job
job := runner.new_job(runner.Job{
    caller_id: 'my_app'
    context_id: 'task_123'
    runner: 'my_runner'
    executor: 'tmux.session1.window1'
    payload: 'echo "Hello World" && sleep 5'
    timeout: 30
})!

// Connect to Redis and store the job
mut redis_conn := redisclient.new('127.0.0.1:6379')!
job.store_in_redis(mut redis_conn, 'production:')!

// Add job to runner queue
runner_queue_key := 'production:runner:my_runner'
mut queue := redis_conn.queue_get(runner_queue_key)
queue.add(job.id)!

Job Structure

Jobs contain the following fields:

pub struct Job {
pub mut:
    id            string              // Unique job identifier
    caller_id     string              // ID of the calling service
    context_id    string              // Context/session identifier
    runner        string              // Target runner name
    executor      string              // Execution environment (e.g., tmux.session1)
    payload       string              // Script/command to execute
    status        JobStatus           // Current job status
    result        string              // Job execution result
    error         string              // Error message if failed
    timeout       int                 // Timeout in seconds
    env_vars      map[string]string   // Environment variables
    created_at    time.Time           // Job creation timestamp
    updated_at    time.Time           // Last update timestamp
}

Job Status Lifecycle

dispatched → started → finished
     ↓           ↓         ↑
     └─────── error ──────┘

dispatched: Job is queued and waiting for processing
started: Job execution has begun
finished: Job completed successfully
error: Job failed during execution

Executor Types

The runner supports various executor types for different execution environments:

Tmux Executors

tmux.session_name - Execute in a tmux session
tmux.session_name.window_name - Execute in a specific window
tmux.session_name.window_name.pane_id - Execute in a specific pane

Example:

job := runner.Job{
    // ... other fields
    executor: 'tmux.dev_session.main_window.pane1'
    payload: 'npm run build && npm test'
}

Examples

Basic Runner

#!/usr/bin/env -S v run

import herocode.runner
import freeflowuniverse.herolib.core.redisclient

mut r := &runner.Runner{
    name: 'basic_runner'
    namespace: 'development'
    redis_conn: redisclient.new('127.0.0.1:6379')!
}

// Start the runner
spawn r.run()

// Keep running
for {}

Job Submission Script

See examples/test_runner_rpc.vsh for a complete example of submitting multiple jobs to a runner.

Testing

Run the test suite:

# Run all tests
v test src/

# Run specific test files
v test src/runner_test.v
v test src/job_test.v

Configuration

Environment Variables

REDIS_URL: Redis connection URL (default: 127.0.0.1:6379)
RUNNER_NAME: Default runner name
RUNNER_NAMESPACE: Default namespace

Redis Keys

The runner uses the following Redis key patterns:

Jobs: {namespace}job_{id}
Runner Queues: {namespace}runner:{runner_name}
Status Updates: Stored within job objects

Development

Project Structure

runner_v/
├── cmd/                    # Command-line applications
│   └── runner.vsh         # Main runner executable
├── src/                   # Source code
│   ├── runner.v          # Core runner implementation
│   ├── job.v             # Job structure and operations
│   ├── factory.v         # Job creation utilities
│   └── *_test.v          # Test files
├── examples/             # Usage examples
├── scripts/              # Build and deployment scripts
└── README.md            # This file

Building

# Build the runner
v -prod cmd/runner.vsh -o runner

# Run in development mode
v run cmd/runner.vsh

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Run the test suite
Submit a pull request

License

MIT License - see LICENSE file for details.

Herolib - Core utilities and libraries
Hero Baobab - Distributed actor system

Support

For issues and questions:

Open an issue on GitHub
Check the examples directory for usage patterns
Review the test files for implementation details

README.md

Hero Runner V