rototo 0.1.0-alpha.3

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

# SDK Loading Reference

Applications should not parse workspace files directly. They should load a
workspace source with the SDK, let rototo lint it, and resolve named variables
from the loaded workspace.

The loading API is the boundary that decides whether the app receives a valid
control plane. Resolution and refresh have their own pages.

## `Workspace::load`

```rust
use rototo::Workspace;

let workspace = Workspace::load("git+https://github.com/acme/config.git#main").await?;
```

`Workspace::load` stages the source, inspects the workspace, runs lint, and
rejects lint failures. It accepts the same source forms as the CLI.

Use this for services that load configuration once at startup.

## `Workspace::inspect`

```rust
let workspace = Workspace::inspect("examples/basic").await?;
```

`Workspace::inspect` stages and inspects a workspace without requiring a
lint-clean runtime. It is the lower-level loader for tools that need to inspect
broken workspaces, editor state, or staged diagnostics.

Most application code should use `Workspace::load`.

## Load Options

```rust
use rototo::{LoadOptions, LintMode, SourceAuth};

let options = LoadOptions::new()
    .with_lint(LintMode::Deny)
    .with_source_auth(SourceAuth::Bearer(token));

let workspace = Workspace::load_with_options(source, options).await?;
```

`LintMode::Deny` is the default. It rejects lint failures during load.

`LintMode::Skip` is available for tools that need to stage or inspect a
workspace without enforcing lint. Do not use it as the default in application
runtime paths.

## Source Options

`LoadOptions` owns `SourceOptions`. Source options control auth and staging
limits:

```rust
use rototo::{SourceAuth, SourceOptions};
use std::time::Duration;

let source_options = SourceOptions::new()
    .with_auth(SourceAuth::Bearer(token))
    .with_http_timeout(Duration::from_secs(10));
```

Use source options when you need shorter network timeouts, archive limits, or
Bearer auth for HTTPS archive sources.

## Workspace Metadata

`Workspace` exposes loaded source metadata:

```rust
let root = workspace.root();
let inspection = workspace.inspection();
let context_schema = workspace.context_schema();
let fingerprint = workspace.source_fingerprint();
let immutable = workspace.immutable_source();
let layers = workspace.source_layers();
```

These help with observability. A service can log the source fingerprint that
selected a value, and can expose whether its loaded source is immutable.

## Temporary Staging

Remote sources are staged into temporary directories owned by the workspace
handle. Keep the `Workspace` value alive for as long as the app needs to
resolve from it.

Do not retain paths into the staged root after dropping the `Workspace`.

## Context Schema

When the loaded workspace contains `schemas/context.schema.json`,
`workspace.context_schema()` returns it. Resolution validates context against
that schema by default.

See `reference-context` and `reference-sdk-resolution`.