Skip to content

Commit ca70b49

Browse files
ArthurCRodriguesArthurCRodrigues
committed
docs(pipeline): add documentation for FileCheck, AssetInjection, and SetupCommands steps
Add the missing documentation files referenced in the pipeline README: - 04-file-check.md: File validation step docs - 04.1-asset-injection.md: Asset injection step docs - 04.2-setup-commands.md: Setup commands step docs These files resolve the broken links flagged by the Validate Documentation CI check.
1 parent 26daf2e commit ca70b49

3 files changed

Lines changed: 212 additions & 0 deletions

File tree

‎docs/pipeline/04-file-check.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# Step 4: File Check
2+
3+
## Purpose
4+
5+
The File Check step validates that all required files exist in the student's submission before proceeding with sandbox execution. This provides a fast-fail mechanism that gives students immediate feedback about missing files without consuming sandbox resources.
6+
7+
## How It Works
8+
9+
The step execution follows these logic gates:
10+
11+
1. **Load Configuration**: The step reads the `setup_config` for the submission's language and extracts the `required_files` list. If no required files are configured, the step immediately succeeds.
12+
13+
2. **Check Submission Files**: The `PreFlightService` compares the list of required files against the actual files present in the submission.
14+
15+
3. **Report Results**: If any required files are missing, the step fails with a descriptive error listing all missing files. Otherwise, it succeeds.
16+
17+
## Dependencies
18+
19+
| Step | What It Needs |
20+
|------|---------------|
21+
| None | This step only needs the submission files from the pipeline context |
22+
23+
## Input
24+
25+
| Source | Data |
26+
|--------|------|
27+
| Constructor | `setup_config: dict` — language-keyed setup configuration |
28+
| Pipeline | `pipeline_exec.submission` → submission files and language |
29+
30+
## Output
31+
32+
| Field | Type | Description |
33+
|-------|------|-------------|
34+
| `data` | `None` | This step does not produce data for downstream steps |
35+
| `status` | `StepStatus.SUCCESS` | All required files are present |
36+
37+
## Language-Specific Configuration
38+
39+
The `required_files` list is defined per language in the `setup_config`:
40+
41+
```json
42+
{
43+
"python": {
44+
"required_files": ["main.py"]
45+
},
46+
"java": {
47+
"required_files": ["Calculator.java"]
48+
}
49+
}
50+
```
51+
52+
Templates can also contribute required files via `template.required_files`, which are merged with the assignment-level configuration during pipeline assembly.
53+
54+
## Failure Scenarios
55+
56+
- **Missing required file** → `StepStatus.FAIL` with an error message listing all missing files.
57+
58+
## Next Step
59+
60+
After file validation, the pipeline proceeds to **[Step 3: Sandbox](03-sandbox.md)** to prepare the execution environment (if the submission requires it).
61+
62+
---
63+
64+
## Source
65+
66+
`autograder/steps/file_check_step.py` → `FileCheckStep`
67+
68+
`autograder/services/pre_flight_service.py` → `PreFlightService`

‎docs/pipeline/04.1-asset-injection.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# Step 4.1: Asset Injection
2+
3+
## Purpose
4+
5+
The Asset Injection step is responsible for injecting grader-owned static assets (datasets, test fixtures, configuration files) from external sources (e.g., S3) into the sandbox workspace. These assets are required by the grading template but are not part of the student's submission.
6+
7+
## How It Works
8+
9+
The step execution follows these logic gates:
10+
11+
1. **Check Configuration**: The step reads the `setup_config` for an `assets` list. If no assets are configured, the step immediately succeeds with no action.
12+
13+
2. **Resolve Assets**: The `AssetSourceResolver` resolves each asset entry, fetching the file content from the configured source (typically S3).
14+
15+
3. **Inject into Sandbox**: Resolved assets are injected into the sandbox container's workspace using the sandbox's `inject_assets` method.
16+
17+
## Dependencies
18+
19+
| Step | What It Needs |
20+
|------|---------------|
21+
| **Sandbox** | Requires the `SandboxContainer` to inject files into |
22+
23+
## Input
24+
25+
| Source | Data |
26+
|--------|------|
27+
| Constructor | `setup_config: dict` — setup configuration containing `assets` list |
28+
| Pipeline | `pipeline_exec.sandbox` → the active sandbox container |
29+
30+
## Output
31+
32+
| Field | Type | Description |
33+
|-------|------|-------------|
34+
| `data` | `None` | This step does not produce data for downstream steps |
35+
| `status` | `StepStatus.SUCCESS` | All assets were successfully resolved and injected |
36+
37+
## Asset Configuration
38+
39+
Assets are defined in the `setup_config` as a list of source references:
40+
41+
```json
42+
{
43+
"assets": [
44+
{ "source": "s3", "key": "datasets/test_input.csv", "target": "/tmp/test_input.csv" },
45+
{ "source": "s3", "key": "fixtures/expected_output.json", "target": "/tmp/expected.json" }
46+
]
47+
}
48+
```
49+
50+
## Failure Scenarios
51+
52+
- **No Sandbox** → `StepStatus.FAIL` if the sandbox was not created in a previous step but asset injection is required.
53+
- **Asset Resolution Error** → `StepStatus.FAIL` if an asset cannot be fetched from its source (e.g., S3 object not found, network failure).
54+
- **Injection Error** → `StepStatus.FAIL` if writing the asset into the container fails.
55+
56+
## Next Step
57+
58+
After asset injection, the pipeline proceeds to **[Step 4.2: Setup Commands](04.2-setup-commands.md)** to execute compilation or initialization scripts.
59+
60+
---
61+
62+
## Source
63+
64+
`autograder/steps/asset_injection_step.py` → `AssetInjectionStep`
65+
66+
`autograder/services/assets/resolver.py` → `AssetSourceResolver`

‎docs/pipeline/04.2-setup-commands.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Step 4.2: Setup Commands
2+
3+
## Purpose
4+
5+
The Setup Commands step executes compilation or initialization scripts inside the sandbox. This handles language-specific build steps (e.g., `javac`, `gcc`, `npm install`) that must complete successfully before grading can begin.
6+
7+
## How It Works
8+
9+
The step execution follows these logic gates:
10+
11+
1. **Load Configuration**: The step reads the `setup_config` for the submission's language and extracts the `setup_commands` list. If no commands are configured, the step immediately succeeds.
12+
13+
2. **Validate Sandbox**: The step verifies that a sandbox container exists in the pipeline context. If setup commands are defined but no sandbox is available, the step fails immediately.
14+
15+
3. **Execute Commands Sequentially**: Each command is executed in order within the sandbox via the `PreFlightService`. Execution is **stop-on-failure** — if any command returns a non-zero exit code, the step stops immediately without running remaining commands.
16+
17+
4. **Report Results**: If all commands succeed, the step succeeds. If any command fails, the step fails with details including exit code, stdout, and stderr.
18+
19+
## Dependencies
20+
21+
| Step | What It Needs |
22+
|------|---------------|
23+
| **Sandbox** | Requires the `SandboxContainer` to execute commands in |
24+
25+
## Input
26+
27+
| Source | Data |
28+
|--------|------|
29+
| Constructor | `setup_config: dict` — language-keyed setup configuration |
30+
| Pipeline | `pipeline_exec.sandbox` → the active sandbox container |
31+
| Pipeline | `pipeline_exec.submission` → submission language |
32+
33+
## Output
34+
35+
| Field | Type | Description |
36+
|-------|------|-------------|
37+
| `data` | `None` | This step does not produce data for downstream steps |
38+
| `status` | `StepStatus.SUCCESS` | All setup commands executed successfully |
39+
40+
## Language-Specific Configuration
41+
42+
Setup commands are defined per language in the `setup_config`:
43+
44+
```json
45+
{
46+
"java": {
47+
"setup_commands": ["javac Calculator.java"]
48+
},
49+
"c": {
50+
"setup_commands": ["gcc -o main main.c -lm"]
51+
},
52+
"javascript": {
53+
"setup_commands": ["npm install"]
54+
}
55+
}
56+
```
57+
58+
Templates can also contribute setup commands via `template.setup_commands`, which are merged with the assignment-level configuration during pipeline assembly.
59+
60+
## Failure Scenarios
61+
62+
- **No Sandbox** → `StepStatus.FAIL` if the sandbox was not created but setup commands are required.
63+
- **Command Failed** → `StepStatus.FAIL` with the failing command's exit code, stdout, and stderr. Remaining commands are not executed.
64+
- **Execution Error** → `StepStatus.FAIL` if the sandbox fails to respond or the connection is lost.
65+
66+
## Next Step
67+
68+
After setup commands complete, the pipeline proceeds to the grading phase starting with **[Step 5: Grade](05-grade.md)** to execute the actual test functions.
69+
70+
---
71+
72+
## Source
73+
74+
`autograder/steps/setup_commands_step.py` → `SetupCommandsStep`
75+
76+
`autograder/services/pre_flight_service.py` → `PreFlightService`
77+
78+
`autograder/services/sandbox_service.py` → `SandboxService`

0 commit comments

Comments
 (0)