rustrunner

rustrunner is a small, fast, opinionated CLI for running structured jobs using JSON input.

It’s designed to replace fragile shell scripts with something safer, clearer, and easier to extend — whether you’re calling it from Rundeck, Ansible, Jenkins, Airflow, Cron, CI pipelines, or your local terminal.

It’s written in Rust, but the goal is clarity, not Rust-ness.

---

Why rustrunner?

If you’re dealing with:

• too many shell scripts
• copy-pasted Rundeck jobs
• broken quoting and escaping
• unclear ownership of “what runs what”

rustrunner gives you:

• explicit, versioned routes (cli/v1/...)
• structured JSON input
• validation before execution
• predictable exit codes
• clean JSON logs

One binary. One execution model. No magic.

---

What rustrunner is (and isn’t)

rustrunner is:

• a job execution runner
• a safe entrypoint for automation
• a foundation you can build on

rustrunner is not:

• a workflow engine
• a scheduler
• a replacement for CI, Rundeck, or cron

Think of it as the execution layer, not the orchestrator.

---

Built to be extended

rustrunner is intentionally boring and explicit inside.

The included actions (git, artifact, whitelist, test) are examples, not a closed system.

You are encouraged to:

• add your own actions
• define your own routes
• enforce your own policies
• tailor it to your environment

The structure is meant to be copied, extended, and owned by your team.

If you need something custom, that’s the point.

---

Basic concepts

Routes

Routes describe what should run.

"route": "cli/v1/test"

Routes are:

• explicit
• versioned
• easy to audit
• safe to evolve

---

Data

Each route receives a data object.

"data": {
  "base_dir": "/tmp/rustrunner",
  "name": "hello"
}

Validation happens inside rustrunner, not in shell scripts.

---

Installation

Build from source:

cargo build --release

Binary:

target/release/rustrunner

On Windows:

target\release\rustrunner.exe

---

Zero-Downtime Deployment (Blue-Green)

rustrunner is a single static binary, which makes zero-downtime deployment simple and reliable.

A common approach is Blue-Green style deployment using symlinks.
This allows you to upgrade the binary without interrupting running jobs.

Example (Linux)

# Upload new version
sudo cp /tmp/rustrunner-v2.1.0 /opt/rustrunner-binaries/rustrunner-v2.1.0

# Atomically switch the symlink
sudo ln -sf /opt/rustrunner-binaries/rustrunner-v2.1.0 /opt/rustrunner/rustrunner

# Optional: keep only the last 3 versions
ls -1dt /opt/rustrunner-binaries/rustrunner-v* | tail -n +4 | xargs rm -f


---

## Usage

### Recommended: use stdin

Using stdin avoids shell quoting problems and works consistently across platforms.

---

### Windows (PowerShell)

```powershell
$json = '{"route":"cli/v1/test","data":{"base_dir":"C:\\rustrunner","name":"hello"}}'
$json | .\rustrunner.exe --log-level info --stdin

Creates:

C:\rustrunner\hello\hello.txt

---

Linux / macOS

echo '{"route":"cli/v1/test","data":{"base_dir":"/tmp/rustrunner","name":"hello"}}' \
  | ./rustrunner --log-level info --stdin

Creates:

/tmp/rustrunner/hello/hello.txt

---

Inline JSON (static values only)

./rustrunner \
  --log-level info \
  --input-json '{"route":"cli/v1/test","data":{"base_dir":"/tmp/rustrunner","name":"hello"}}'

For anything dynamic, stdin or input files are recommended.

---

Logging

Logs are written to stdout in JSON format.

This makes rustrunner easy to integrate with:

• Rundeck
• CI systems
• log aggregation tools

---

Exit codes

Code	Meaning
0	Success
1	Invalid input
2	Runtime / execution failure
3	Internal error

Stable exit codes make automation predictable.

---

Example routes

Current sample routes:

• cli/v1/test — filesystem smoke test
• cli/v1/git — git-related jobs
• cli/v1/artifact — artifact handling
• cli/v1/whitelist — whitelist management

These are examples. Add, remove, or replace them as needed.

---

Philosophy

• explicit routes
• validation before execution
• no hidden behavior
• boring code on purpose

If something runs, it should be obvious why.

---

License

This project is licensed under the Apache License, Version 2.0.

You are free to:

• use it
• modify it
• redistribute it
• build on it

Attribution is appreciated, but not required.

See LICENSE for full details.