So, what is Rototo?

Every substantial software system eventually needs a configuration subsystem. The software provides the underlying capabilities; configuration steers those capabilities to behave in a particular way.

Some configuration is settings-style: things like database URLs and encryption keys, usually held in environment variables and fixed once the software is deployed. That's not the kind we're concerned with here. What interests us instead is the configuration that governs the system's runtime behavior: feature availability, model selection, tenant overrides, offers, retry policies, logging controls, rollout plans, and so on.

Rototo provides a control plane for this kind of runtime configuration. It rests on a simple premise: runtime configuration should be treated like code. It should live alongside the code and follow a similar release cycle, and it should be testable and contract-enforced in the same way.

To that end, Rototo models configuration as files that are versioned, reviewed, tested, and released as packages. The Rototo SDK loads these packages within the application runtime to guide the application's behavior. Configuration thus follows the same release process as code, while gaining a hot-swappable deployment mechanism.

Rototo's hello world

Let's take a simple use case: we want to vary the order amount beyond which customers get free shipping. Customers in standard tier must have at least $50 as cart total while customers in premium tier get free shipping after $25. To accomplish this, we would do two things:

Create a Rototo configuration package.
Load the configuration package and resolve free shipping threshold in our application.

Create and publish a configuration package

First, install the Rototo cli from crates.io:

cargo install rototo --version 0.1.0-alpha.6

Now, create a configuration package for the application:

# Create app-config package with a variable named free-shipping-threshold
rototo init app-config --variable free-shipping-threshold

You should see the following in app-config/ dir:

$> tree app-config
app-config
├── rototo-package.toml
├── evaluation-contexts
├── qualifiers
└── variables
    └── free-shipping-threshold.toml
├── catalogs
├── lint
6 directories, 2 files

We explain the package model in Rototo Concepts. For now, we would focus on the variable free-shipping-threshold. Replace the contents of free-shipping-threshold.toml with the following:

schema_version = 1
description = "$ threshold for free shipping."
type = "int"

[resolve]
default = 50  # by default, free shipping beyond $50.

[[resolve.rule]]
when = '(context.account.tier == "premium")'
value = 25    # for premium account tier, free shipping beyond $25.

We can now validate our configuration to ensure that we got it right:

rototo lint app-config

We can further ensure that free-shipping-threshold resolves as expected.

# default value: should give 50
rototo resolve app-config --variable free-shipping-threshold

# standard account tier: should give 50
rototo resolve app-config --variable free-shipping-threshold --context account.tier=standard

# premium account tier: should give 25
rototo resolve app-config --variable free-shipping-threshold --context account.tier=premium

Load the configuration package and resolve the threshold

Now let's read that value from an application. Install the rototo Rust SDK:

cargo add rototo@0.1.0-alpha.6 serde_json
cargo add tokio --features rt-multi-thread,macros

Save this as src/main.rs. It loads a refreshing package (one that re-reads the source in the background) and prints the free-shipping threshold for a standard and a premium account every couple of seconds:

use std::time::Duration;

use rototo::{EvaluationContext, RefreshOptions, RefreshingPackage};
use serde_json::json;

const VARIABLE_ID: &str = "free-shipping-threshold";

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let app_config = RefreshingPackage::load(
        "app-config",
        RefreshOptions::new().with_period(Duration::from_secs(1)),
    )
    .await?;

    loop {
        println!("---");
        for tier in ["standard", "premium"] {
            let context = EvaluationContext::from_json(json!({ "account": { "tier": tier } }))?;
            let resolution = app_config.resolve_variable(VARIABLE_ID, &context)?;
            println!("{tier}: {} USD", resolution.value);
        }
        tokio::time::sleep(Duration::from_secs(2)).await;
    }
}

Run it (cargo run) from the directory that holds app-config, and it prints:

---
standard: 50 USD
premium: 25 USD

Now edit free-shipping-threshold.toml, change the default to 35, and save. Because the package refreshes every second, the next tick shows:

---
standard: 50 USD
premium: 35 USD

Documentation

Public docs are available on rototo.dev. The rototo cli also ships with the same documents in markdown.

You and your agent can use the docs command in the cli:

# show available docs
rototo docs

# search for docs
rototo docs -s <search terms>

# fetch doc based on doc id prefix
rototo docs -p concepts

Rototo is designed for people and agents

Agents are now among the most important users of any development tool. Hence, Rototo is designed from ground up to work well both for people and agents.

The configuration package is simply a dir tree of files that brings battle-tested ergnomics of file organization and editing.
rototo docs to discover Rototo's capabilities and the recipes to use it.
rototo lint as the backbone for configuration validation that can be run after every edit.
rototo inspect to reason about the package structure and how everything resolves at runtime.
rototo resolve for test automation of invariants (e.g. customer X must always receive configuration Y otherwise something is wrong).
rototo lsp to provide feedback (and help) during editing.
rototo console to have the comfort of a react based UI for inspecting and editing the package.

License

Licensed under either of:

Apache License, Version 2.0
MIT license

at your option.