rototo 0.1.0-alpha.4

Control plane for runtime configuration of your application.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

# Variable Resolution Reference

Variable resolution is where rototo turns a named runtime configuration
request into one selected value. The app supplies context, rototo evaluates
rules, and the selected value comes from the workspace version currently loaded
by the app.

## Input

Variable resolution needs:

- a loaded, lint-clean workspace;
- a variable id;
- a JSON object context.

CLI:

```sh
rototo resolve account-config \
  --variable account-limits \
  --context account.plan=enterprise
```

SDK:

```rust
let resolution = workspace
    .resolve_variable("account-limits", &context)
    .await?;
```

## Rule Evaluation

Variable rules are evaluated in file order:

```toml
[resolve]
default = "growth"

[[resolve.rule]]
qualifier = "enterprise-account"
value = "enterprise"

[[resolve.rule]]
qualifier = "paid-account"
value = "paid"
```

Resolution follows this path:

1. Resolve the first rule's qualifier.
2. If it is true, select that rule's value and stop.
3. If it is false, continue to the next rule.
4. If no rule matches, select the default value.

The default is always the fallback. It is not evaluated as a qualifier.

## Value Selection

For primitive variables, selected values come from `[values]`.

For resource-backed variables, selected values come from
`resources/<resource-id>-objects/*.toml` and are validated against the resource
schema.

The resolution result includes both:

- `value_key`: the selected key;
- `value`: the selected JSON value.

## Shadowed Rules

If two rules use the same qualifier, the later rule can never win. Rototo
reports `rototo/variable-rule-shadowed`.

If a rule selects the same value as the default, rototo reports
`rototo/variable-rule-selects-default-value`.

These rules are warnings about operational clarity. A reader should not have to
guess whether a later rule is meaningful.

## Trace Shape

CLI `--json` returns a variable trace:

```json
{
  "resolution": {
    "id": "account-limits",
    "value_key": "enterprise",
    "value": {
      "projects": 100,
      "members": 250
    }
  },
  "default_value": "growth",
  "rules": [
    {
      "index": 0,
      "qualifier": "enterprise-account",
      "value": "enterprise",
      "matched": true
    }
  ],
  "qualifier_traces": [
    {
      "id": "enterprise-account",
      "value": true,
      "predicates": []
    }
  ]
}
```

`qualifier_traces` contains the qualifiers evaluated while resolving the
variable. Use it to explain why the selected value won.

## Context Validation

If `schemas/context.schema.json` exists, rototo validates context before
resolution. SDK callers can disable that with `ResolveOptions`, but the default
is validation on.

## Multiple Variables

`rototo resolve --variables` resolves all variables in workspace order with the
same context. The SDK free function `rototo::resolve_variables` does the same
for a local workspace root.

If any variable resolution fails, the command or API call fails. Use targeted
selectors when debugging a context that is not meant to satisfy every variable.