previa-engine 1.0.0-alpha.14

Motor de execucao de pipelines da plataforma Previa.
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

# `previa-engine`

> Rustdoc-style crate documentation.

## Crate Purpose

`previa-engine` is the core pipeline execution crate. It resolves templates, executes HTTP steps, evaluates assertions, and returns structured execution results.

## Public API

Exported functions:

- `execute_pipeline`
- `execute_pipeline_with_client`
- `execute_pipeline_with_hooks`
- `execute_pipeline_with_specs_hooks`
- `execute_pipeline_with_client_hooks`
- `render_template_value`
- `render_template_value_simple`

## Core Types

- `RuntimeSpec`
- `Pipeline`
- `PipelineStep`
- `StepAssertion`
- `StepExecutionResult`
- `StepRequest`
- `StepResponse`
- `AssertionResult`

## Execution Model

For each step:

1. Resolve templated `url`, `headers`, and `body`.
2. Apply `delay` (if configured).
3. Perform request.
4. Evaluate assertions.
5. Retry (if allowed by `retry` and assertion behavior).

`step.url` must always be an absolute URL (`http://` or `https://`).

## Template System

Supported expressions:

- `{{steps.<step_id>.<field>}}`
- `{{specs.<slug>.url.<name>}}`
- legacy: `{{url.<slug>.<name>}}` (normalized)

Helpers:

- `{{helpers.uuid}}`
- `{{helpers.email}}`
- `{{helpers.name}}`
- `{{helpers.username}}`
- `{{helpers.number 10 99}}`
- `{{helpers.date}}`
- `{{helpers.boolean}}`
- `{{helpers.cpf}}`

## Assertion Operators

Currently implemented operators:

- `equals`
- `not_equals`
- `contains`
- `exists`
- `not_exists`
- `gt`
- `lt`

## Important Behavior Notes

- `GET` and `HEAD` do not send request body.
- `delay` is expressed in milliseconds and is applied before each attempt, including retries.
- `maxAttempts = retry + 1`.
- Assertion failures can trigger retry when `retry` allows additional attempts.
- `should_cancel` callback can interrupt execution.
- Unknown templates may remain unchanged.

## Rust Example

```rust,no_run
use previa_engine::execute_pipeline_with_specs_hooks;

# async fn demo(pipeline: previa_engine::Pipeline, specs: Vec<previa_engine::RuntimeSpec>) {
let results = execute_pipeline_with_specs_hooks(
    &pipeline,
    Some("prd"),
    Some(specs.as_slice()),
    |step_id| println!("step:start={step_id}"),
    |result| println!("step:result={}", result.step_id),
    || false,
).await;

println!("steps executed: {}", results.len());
# }
```

## Module Relationship

```text
main -> runner -> engine
```

## Common Pitfalls

- Empty `pipeline.steps` in upstream callers.
- Invalid assertion fields (for example missing `body.*`).
- Assuming unsupported operators such as `gte`, `lte`, `ne`, `not_contains`.