160 lines
No EOL
4.7 KiB
Markdown
160 lines
No EOL
4.7 KiB
Markdown
# Demo Provider
|
|
|
|
**Purpose**: Reference implementation for the 4-Task Completion Framework
|
|
|
|
This provider demonstrates all requirements of the cloud provider development guide:
|
|
|
|
## Framework Completeness
|
|
|
|
### ✅ Tarea 1: Nushell Compliance
|
|
- Modern error handling with `do/complete` pattern
|
|
- No mutable state (`let mut`)
|
|
- No deprecated try-catch blocks
|
|
- Complete implementations (no stubs)
|
|
|
|
**Files**: `nulib/demo/api.nu`, `nulib/demo/servers.nu`
|
|
|
|
### ✅ Tarea 2: Test Infrastructure
|
|
- 14 unit tests (`tests/unit/test_utils.nu`)
|
|
- 37 integration tests across 3 modules:
|
|
- `tests/integration/test_api_client.nu` (13 tests)
|
|
- `tests/integration/test_server_lifecycle.nu` (12 tests)
|
|
- `tests/integration/test_pricing_cache.nu` (12 tests)
|
|
- Mock API responses (`tests/mocks/mock_api_responses.json`)
|
|
- Test orchestrator (`tests/run_demo_tests.nu`)
|
|
|
|
### ✅ Tarea 3: Runtime Templates
|
|
- `templates/demo_servers.j2` - Server provisioning
|
|
- `templates/demo_networks.j2` - Network provisioning
|
|
- `templates/demo_volumes.j2` - Volume provisioning
|
|
|
|
All templates use Jinja2 + Bash with proper error handling.
|
|
|
|
### ✅ Tarea 4: Nickel Schema Validation
|
|
- `nickel/contracts.ncl` - Type definitions
|
|
- `nickel/defaults.ncl` - Default values
|
|
- `nickel/main.ncl` - Public API
|
|
- `nickel/version.ncl` - Version tracking
|
|
|
|
All files pass `nickel typecheck`.
|
|
|
|
## Running the Framework
|
|
|
|
### Validate Completeness
|
|
|
|
```bash
|
|
cd provisioning/extensions/providers/demo
|
|
|
|
# Tarea 4: Nickel validation
|
|
nickel typecheck nickel/main.ncl
|
|
nickel typecheck nickel/contracts.ncl
|
|
nickel typecheck nickel/defaults.ncl
|
|
nickel typecheck nickel/version.ncl
|
|
nickel export nickel/main.ncl
|
|
|
|
# Tarea 1: Nushell compliance
|
|
[ $(grep -r "try {" nulib/ 2>/dev/null | wc -l) -eq 0 ] && echo "✓ No deprecated patterns"
|
|
[ $(grep -r "let mut " nulib/ 2>/dev/null | wc -l) -eq 0 ] && echo "✓ No mutable state"
|
|
|
|
# Tarea 3: Template validation
|
|
for f in templates/*.j2; do
|
|
bash -n <(sed 's/{%.*%}//' "$f" | sed 's/{{.*}}/x/g')
|
|
done && echo "✓ Templates valid"
|
|
|
|
# Tarea 2: Run all tests
|
|
nu tests/run_demo_tests.nu
|
|
```
|
|
|
|
### Expected Output
|
|
|
|
```bash
|
|
✅ ALL TESTS PASSED
|
|
Total: 51 passed, 0 failed (51 total)
|
|
Execution Time: 2s
|
|
```
|
|
|
|
## Module Organization
|
|
|
|
```bash
|
|
demo/
|
|
├── nulib/demo/
|
|
│ ├── api.nu - API client and mock operations
|
|
│ ├── servers.nu - Server management
|
|
│ └── mod.nu - Module aggregator
|
|
├── tests/
|
|
│ ├── mocks/
|
|
│ │ └── mock_api_responses.json
|
|
│ ├── unit/
|
|
│ │ └── test_utils.nu
|
|
│ ├── integration/
|
|
│ │ ├── test_api_client.nu
|
|
│ │ ├── test_server_lifecycle.nu
|
|
│ │ └── test_pricing_cache.nu
|
|
│ └── run_demo_tests.nu
|
|
├── templates/
|
|
│ ├── demo_servers.j2
|
|
│ ├── demo_networks.j2
|
|
│ └── demo_volumes.j2
|
|
├── nickel/
|
|
│ ├── contracts.ncl
|
|
│ ├── defaults.ncl
|
|
│ ├── main.ncl
|
|
│ └── version.ncl
|
|
└── README.md
|
|
```
|
|
|
|
## Nushell Guidelines Applied
|
|
|
|
- **Rule 1**: Module system with proper imports
|
|
- **Rule 2**: Function signatures with type annotations
|
|
- **Rule 3**: Return early, fail fast (precondition validation)
|
|
- **Rule 4**: Modern error handling (`do/complete` pattern)
|
|
- **Rule 5**: Atomic operations
|
|
- **Rule 12**: Structured error returns
|
|
|
|
## Nickel Guidelines Applied
|
|
|
|
- **Three-File Pattern**: contracts → defaults → main
|
|
- **Type Safety**: Full type annotations
|
|
- **Defaults**: Sensible defaults for all optional fields
|
|
- **Separation of Concerns**: Types separate from defaults
|
|
|
|
## Integration Tests
|
|
|
|
All integration tests use mock API responses from:
|
|
`tests/mocks/mock_api_responses.json`
|
|
|
|
Tests cover:
|
|
- API response structures
|
|
- Error handling (401, 404, 429)
|
|
- Server lifecycle (create, list, delete)
|
|
- Resource state management
|
|
- Pricing data validation
|
|
- Cache behavior
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Clone this provider as template for new provider
|
|
cp -r provisioning/extensions/providers/demo provisioning/extensions/providers/newprovider
|
|
|
|
# Update references
|
|
sed -i '' 's/demo/newprovider/g' provisioning/extensions/providers/newprovider/**/*.nu
|
|
sed -i '' 's/demo/newprovider/g' provisioning/extensions/providers/newprovider/**/*.j2
|
|
sed -i '' 's/demo/newprovider/g' provisioning/extensions/providers/newprovider/**/*.ncl
|
|
|
|
# Validate framework
|
|
cd provisioning/extensions/providers/newprovider
|
|
nu tests/run_newprovider_tests.nu
|
|
```
|
|
|
|
## Notes
|
|
|
|
This provider is a complete, working reference implementation. It demonstrates:
|
|
|
|
1. How to structure Nushell modules following 0.109.0+ guidelines
|
|
2. How to organize 51 mock-based tests
|
|
3. How to create runtime templates with Jinja2
|
|
4. How to validate Nickel schemas with proper typing
|
|
|
|
Use this as a starting point for implementing new cloud providers. |