How k1low/runn works
Project Type & Purpose
• This is a Go-based CLI tool and library for “scenario based testing” and “workflow automation.” It serves both as a standalone CLI for running runbook YAML files (which define multi-step scenarios for web requests, gRPC calls, database queries, and even browser automation via CDP) and as a Go test helper package.
• The README and file tree reveal a rich set of “runners” (modules for HTTP, gRPC, DB, CDP, SSH, Exec, etc.) as well as various features like variable binding, loop controls, and dependency between steps. This indicates that the architecture must support executing many different kinds of operations in a unified “runbook” framework.
File Structure Analysis
• The top-level directories/files (such as “cmd”, “internal”, “docs”, “examples”, test-related files, etc.) clearly separate the CLI command implementations, internal libraries (including builtin functions and runner-specific logic), and documentation.
• The “cmd” directory contains individual CLI commands (for “new”, “list”, “run”, “rprof”, etc.) which are the entry points of the tool.
• The “internal” tree contains modules for expression evaluation (using expr-lang), built-in runner implementations (e.g., for “bind”, “dump”, “include”), and other helper functionality.
• The presence of multiple YAML files in “testdata” and “docs/designs” shows that the system is driven by configuration – the user’s runbooks that describe a series of steps.
Key Architectural Components
A. CLI/Entry Point:
• A “Command-line Interface” component (from the “cmd” folder) that processes user commands and arguments.
• This component loads runbook YAML files and passes them to the core engine.
B. Runbook Parser & Loader:
• A module that reads and parses the YAML runbooks; handles configuration elements such as “runners”, “steps”, “vars”, “labels”, “if”, “loop”, “defer”, etc.
• This processor then creates an in-memory representation of the sequence of steps.
C. Core Execution Engine:
• The central engine that “orchestrates” the execution of runbook steps, performing evaluation of expressions (using the embedded expr-lang engine) and coordinating retries, loops, conditions, etc.
• It also manages storing results into variables (for use later in other steps) and deferring cleanup steps.
D. Runners (Plugin/Strategy Layer):
• Each “runner” is a pluggable module that handles a specific type of operation. Include nodes for:
• HTTP Runner – sends HTTP requests, handles redirection, cookie management, OpenAPI validations.
• gRPC Runner – issues gRPC calls (both unary and streaming), incorporates Buf support.
• DB Runner – executes database queries and records responses.
• CDP Runner – controls the browser via the Chrome DevTools Protocol.
• SSH Runner – runs commands via SSH.
• Exec Runner – executes local commands (with options for background or live output).
• Bind, Dump, Include, and Test runners – built-in modules for binding variables, dumping outputs, including other runbooks, and performing testing assertions.
E. Expression Evaluation & Built-in Functions:
• A dedicated module (or set of libraries) that evaluates the expressions used in “if” conditions, “test” scripts, and variable interpolations.
• This component integrates the built-in functions (e.g., urlencode, compare, diff, merge) to support dynamic behavior.
F. External Services & Dependencies:
• External systems that runners interact with. For example:
• HTTP endpoints and APIs.
• gRPC servers.
• SQL/NoSQL databases.
• Remote SSH hosts.
• Browser sessions (for CDP).
Relationships & Data Flow
• The CLI then invokes the Runbook Loader to parse the YAML configuration.
• The Core Execution Engine orchestrates the steps, and for each step, the engine:
– Evaluates conditions or loops using the Expression Evaluator.
– Dispatches to the proper Runner through an abstraction or strategy interface.
– Records the response (e.g., HTTP response, query result) inside its internal “steps” variable map.
• The results (and any bound variables) are used later by subsequent steps.
• Optionally, if steps are “deferred” or “included”, then the engine queues them for later processing.
Architectural Patterns & Design Principles
• Use a layered or modular architecture where the CLI is separate from the runbook processing and execution engine.
• The runners adhere to a “plugin” or “strategy” pattern. Each runner implements a common interface to the core engine.
• The engine uses dependency injection (for example, providing custom functions to the expression engine) and supports extension with new runner types.
• Provide clear separation between configuration/input processing (the YAML runbooks) and the runtime execution and reporting components.