working out the worker/execution interface
This commit is contained in:
352
docs/QUICKREF-pack-management-api.md
Normal file
352
docs/QUICKREF-pack-management-api.md
Normal file
@@ -0,0 +1,352 @@
|
||||
# Quick Reference: Pack Management API
|
||||
|
||||
**Last Updated:** 2026-02-05
|
||||
|
||||
## Overview
|
||||
|
||||
Four API endpoints for pack installation workflow:
|
||||
1. **Download** - Fetch packs from sources
|
||||
2. **Dependencies** - Analyze requirements
|
||||
3. **Build Envs** - Prepare runtimes (detection mode)
|
||||
4. **Register** - Import to database
|
||||
|
||||
All endpoints require Bearer token authentication.
|
||||
|
||||
---
|
||||
|
||||
## 1. Download Packs
|
||||
|
||||
```bash
|
||||
POST /api/v1/packs/download
|
||||
```
|
||||
|
||||
**Minimal Request:**
|
||||
```json
|
||||
{
|
||||
"packs": ["core"],
|
||||
"destination_dir": "/tmp/packs"
|
||||
}
|
||||
```
|
||||
|
||||
**Full Request:**
|
||||
```json
|
||||
{
|
||||
"packs": ["core", "github:attune-io/pack-aws@v1.0.0"],
|
||||
"destination_dir": "/tmp/packs",
|
||||
"registry_url": "https://registry.attune.io/index.json",
|
||||
"ref_spec": "main",
|
||||
"timeout": 300,
|
||||
"verify_ssl": true
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"downloaded_packs": [...],
|
||||
"failed_packs": [...],
|
||||
"total_count": 2,
|
||||
"success_count": 1,
|
||||
"failure_count": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**cURL Example:**
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/v1/packs/download \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"packs":["core"],"destination_dir":"/tmp/packs"}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Get Dependencies
|
||||
|
||||
```bash
|
||||
POST /api/v1/packs/dependencies
|
||||
```
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"pack_paths": ["/tmp/packs/core"],
|
||||
"skip_validation": false
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"dependencies": [...],
|
||||
"runtime_requirements": {...},
|
||||
"missing_dependencies": [...],
|
||||
"analyzed_packs": [...],
|
||||
"errors": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**cURL Example:**
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/v1/packs/dependencies \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"pack_paths":["/tmp/packs/core"]}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Build Environments
|
||||
|
||||
```bash
|
||||
POST /api/v1/packs/build-envs
|
||||
```
|
||||
|
||||
**Minimal Request:**
|
||||
```json
|
||||
{
|
||||
"pack_paths": ["/tmp/packs/aws"],
|
||||
"packs_base_dir": "/opt/attune/packs"
|
||||
}
|
||||
```
|
||||
|
||||
**Full Request:**
|
||||
```json
|
||||
{
|
||||
"pack_paths": ["/tmp/packs/aws"],
|
||||
"packs_base_dir": "/opt/attune/packs",
|
||||
"python_version": "3.11",
|
||||
"nodejs_version": "20",
|
||||
"skip_python": false,
|
||||
"skip_nodejs": false,
|
||||
"force_rebuild": false,
|
||||
"timeout": 600
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"built_environments": [...],
|
||||
"failed_environments": [...],
|
||||
"summary": {
|
||||
"total_packs": 1,
|
||||
"success_count": 1,
|
||||
"python_envs_built": 1,
|
||||
"nodejs_envs_built": 0
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Note:** Currently in detection mode - checks runtime availability but doesn't build full environments.
|
||||
|
||||
**cURL Example:**
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/v1/packs/build-envs \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"pack_paths":["/tmp/packs/core"],"packs_base_dir":"/opt/attune/packs"}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Register Packs (Batch)
|
||||
|
||||
```bash
|
||||
POST /api/v1/packs/register-batch
|
||||
```
|
||||
|
||||
**Minimal Request:**
|
||||
```json
|
||||
{
|
||||
"pack_paths": ["/opt/attune/packs/core"],
|
||||
"packs_base_dir": "/opt/attune/packs"
|
||||
}
|
||||
```
|
||||
|
||||
**Full Request:**
|
||||
```json
|
||||
{
|
||||
"pack_paths": ["/opt/attune/packs/core"],
|
||||
"packs_base_dir": "/opt/attune/packs",
|
||||
"skip_validation": false,
|
||||
"skip_tests": false,
|
||||
"force": false
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"registered_packs": [...],
|
||||
"failed_packs": [...],
|
||||
"summary": {
|
||||
"total_packs": 1,
|
||||
"success_count": 1,
|
||||
"failure_count": 0,
|
||||
"total_components": 46,
|
||||
"duration_ms": 1500
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**cURL Example:**
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/v1/packs/register-batch \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"pack_paths":["/opt/attune/packs/core"],"packs_base_dir":"/opt/attune/packs","skip_tests":true}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Action Wrappers
|
||||
|
||||
Execute via CLI or workflows:
|
||||
|
||||
```bash
|
||||
# Download
|
||||
attune action execute core.download_packs \
|
||||
--param packs='["core"]' \
|
||||
--param destination_dir=/tmp/packs
|
||||
|
||||
# Analyze dependencies
|
||||
attune action execute core.get_pack_dependencies \
|
||||
--param pack_paths='["/tmp/packs/core"]'
|
||||
|
||||
# Build environments
|
||||
attune action execute core.build_pack_envs \
|
||||
--param pack_paths='["/tmp/packs/core"]'
|
||||
|
||||
# Register
|
||||
attune action execute core.register_packs \
|
||||
--param pack_paths='["/opt/attune/packs/core"]' \
|
||||
--param skip_tests=true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Complete Workflow Example
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
TOKEN=$(attune auth token)
|
||||
|
||||
# 1. Download
|
||||
DOWNLOAD=$(curl -s -X POST http://localhost:8080/api/v1/packs/download \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"packs":["aws"],"destination_dir":"/tmp/packs"}')
|
||||
|
||||
PACK_PATH=$(echo "$DOWNLOAD" | jq -r '.data.downloaded_packs[0].pack_path')
|
||||
|
||||
# 2. Check dependencies
|
||||
curl -X POST http://localhost:8080/api/v1/packs/dependencies \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "{\"pack_paths\":[\"$PACK_PATH\"]}"
|
||||
|
||||
# 3. Build/check environments
|
||||
curl -X POST http://localhost:8080/api/v1/packs/build-envs \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "{\"pack_paths\":[\"$PACK_PATH\"]}"
|
||||
|
||||
# 4. Register
|
||||
curl -X POST http://localhost:8080/api/v1/packs/register-batch \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "{\"pack_paths\":[\"$PACK_PATH\"],\"skip_tests\":true}"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Parameters
|
||||
|
||||
### Source Formats (download)
|
||||
- **Registry name:** `"core"`, `"aws"`
|
||||
- **Git URL:** `"https://github.com/org/repo.git"`
|
||||
- **Git shorthand:** `"github:org/repo@tag"`
|
||||
- **Local path:** `"/path/to/pack"`
|
||||
|
||||
### Auth Token
|
||||
```bash
|
||||
# Get token via CLI
|
||||
TOKEN=$(attune auth token)
|
||||
|
||||
# Or login directly
|
||||
LOGIN=$(curl -X POST http://localhost:8080/api/v1/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"email":"user@example.com","password":"pass"}')
|
||||
TOKEN=$(echo "$LOGIN" | jq -r '.data.access_token')
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
All endpoints return 200 with per-pack results:
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"successful_items": [...],
|
||||
"failed_items": [
|
||||
{
|
||||
"pack_ref": "unknown",
|
||||
"error": "pack.yaml not found"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Check `success_count` vs `failure_count` in summary.
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Check authentication first** - Verify token works
|
||||
2. **Process downloads** - Check `downloaded_packs` array
|
||||
3. **Validate dependencies** - Ensure `missing_dependencies` is empty
|
||||
4. **Skip tests in dev** - Use `skip_tests: true` for faster iteration
|
||||
5. **Use force carefully** - Only re-register when needed
|
||||
|
||||
---
|
||||
|
||||
## Testing Quick Start
|
||||
|
||||
```bash
|
||||
# 1. Start API
|
||||
make run-api
|
||||
|
||||
# 2. Get token
|
||||
TOKEN=$(curl -s -X POST http://localhost:8080/api/v1/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"email":"test@attune.local","password":"TestPass123!"}' \
|
||||
| jq -r '.data.access_token')
|
||||
|
||||
# 3. Test endpoint
|
||||
curl -X POST http://localhost:8080/api/v1/packs/dependencies \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"pack_paths":[]}' | jq
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Docs
|
||||
|
||||
- **Full API Docs:** [api-pack-installation.md](api/api-pack-installation.md)
|
||||
- **Pack Structure:** [pack-structure.md](packs/pack-structure.md)
|
||||
- **Registry Spec:** [pack-registry-spec.md](packs/pack-registry-spec.md)
|
||||
- **CLI Guide:** [cli.md](cli/cli.md)
|
||||
Reference in New Issue
Block a user