docs(16): create API migration phase plans (5 plans in 2 waves)
This commit is contained in:
Lucas Berger
@@ -0,0 +1,145 @@
|
||||
---
|
||||
phase: 16-api-migration
|
||||
plan: 04
|
||||
type: execute
|
||||
wave: 1
|
||||
depends_on: []
|
||||
files_modified: [n8n-batch-ui.json]
|
||||
autonomous: true
|
||||
|
||||
must_haves:
|
||||
truths:
|
||||
- "Batch selection keyboard displays all containers with correct names and states"
|
||||
- "Toggling container selection updates bitmap and keyboard correctly"
|
||||
- "Navigation between pages works with correct container ordering"
|
||||
- "Batch exec resolves bitmap to correct container names"
|
||||
- "Clear selection resets to empty state"
|
||||
artifacts:
|
||||
- path: "n8n-batch-ui.json"
|
||||
provides: "Batch container selection UI via Unraid GraphQL API"
|
||||
contains: "graphql"
|
||||
key_links:
|
||||
- from: "n8n-batch-ui.json HTTP Request nodes"
|
||||
to: "Unraid GraphQL API"
|
||||
via: "POST container list queries"
|
||||
pattern: "UNRAID_HOST.*graphql"
|
||||
- from: "GraphQL Response Normalizer"
|
||||
to: "Existing Code nodes (Build Batch Keyboard, Handle Toggle, etc.)"
|
||||
via: "Docker API contract format (Names, State, Image)"
|
||||
pattern: "Names.*State"
|
||||
---
|
||||
|
||||
<objective>
|
||||
Migrate n8n-batch-ui.json from Docker socket proxy to Unraid GraphQL API for all 5 container listing queries.
|
||||
|
||||
Purpose: The batch UI sub-workflow fetches the container list 5 times (once per action path: mode selection, toggle update, exec, navigation, clear). All 5 are identical GET queries to Docker API. Replace with GraphQL queries plus normalizer for Docker API contract compatibility.
|
||||
|
||||
Output: n8n-batch-ui.json with all Docker API HTTP Request nodes replaced by Unraid GraphQL queries, wired through normalizer. All existing Code nodes (bitmap encoding, keyboard building, toggle handling) unchanged.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@/home/luc/.claude/get-shit-done/workflows/execute-plan.md
|
||||
@/home/luc/.claude/get-shit-done/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/PROJECT.md
|
||||
@.planning/ROADMAP.md
|
||||
@.planning/STATE.md
|
||||
@.planning/phases/16-api-migration/16-RESEARCH.md
|
||||
@.planning/phases/15-infrastructure-foundation/15-02-SUMMARY.md
|
||||
@n8n-batch-ui.json
|
||||
@n8n-workflow.json (for Phase 15 utility node code — GraphQL Response Normalizer)
|
||||
@ARCHITECTURE.md
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 1: Replace all 5 Docker API container queries with Unraid GraphQL queries in n8n-batch-ui.json</name>
|
||||
<files>n8n-batch-ui.json</files>
|
||||
<action>
|
||||
Replace all 5 Docker API HTTP Request nodes with Unraid GraphQL query equivalents. All 5 nodes are identical GET requests to `docker-socket-proxy:2375/containers/json?all=true`. Each one:
|
||||
|
||||
**Nodes to migrate:**
|
||||
1. "Fetch Containers For Mode" — used when entering batch selection
|
||||
2. "Fetch Containers For Update" — used after toggling a container
|
||||
3. "Fetch Containers For Exec" — used when executing batch action
|
||||
4. "Fetch Containers For Nav" — used when navigating pages
|
||||
5. "Fetch Containers For Clear" — used after clearing selection
|
||||
|
||||
**For EACH of the 5 nodes, apply the same transformation:**
|
||||
|
||||
a. Change HTTP Request configuration:
|
||||
- Method: POST
|
||||
- URL: `={{ $env.UNRAID_HOST }}/graphql`
|
||||
- Body: `{"query": "query { docker { containers { id names state image } } }"}`
|
||||
- Headers: `Content-Type: application/json`, `x-api-key: ={{ $env.UNRAID_API_KEY }}`
|
||||
- Timeout: 15000ms
|
||||
- Error handling: `continueRegularOutput`
|
||||
|
||||
b. Add a **GraphQL Response Normalizer** Code node between each HTTP Request and its downstream Code node consumer. Copy normalizer logic from n8n-workflow.json's "GraphQL Response Normalizer" utility node.
|
||||
|
||||
The normalizer transforms:
|
||||
- `{data: {docker: {containers: [...]}}}` → flat array `[{Id, Names, State, Image}]`
|
||||
- State mapping: RUNNING→running, STOPPED→exited, PAUSED→paused
|
||||
|
||||
**Wiring for each of the 5 paths:**
|
||||
```
|
||||
[upstream] → HTTP Request (GraphQL) → Normalizer (Code) → [existing downstream Code node]
|
||||
```
|
||||
|
||||
Specifically:
|
||||
1. Route Batch UI Action → Fetch Containers For Mode → **Normalizer** → Build Batch Keyboard
|
||||
2. Needs Keyboard Update? (true) → Fetch Containers For Update → **Normalizer** → Rebuild Keyboard After Toggle
|
||||
3. [exec path] → Fetch Containers For Exec → **Normalizer** → Handle Exec
|
||||
4. Handle Nav → Fetch Containers For Nav → **Normalizer** → Rebuild Keyboard For Nav
|
||||
5. Handle Clear → Fetch Containers For Clear → **Normalizer** → Rebuild Keyboard After Clear
|
||||
|
||||
**All downstream Code nodes remain UNCHANGED.** They use bitmap encoding with container arrays and reference `Names[0]`, `State`, `Image` — the normalizer ensures these fields exist in the correct format.
|
||||
|
||||
**Implementation optimization:** Since all 5 normalizers do the exact same thing, consider creating them as 5 identical Code nodes (n8n sub-workflows cannot share nodes across paths — each path needs its own node instance). Keep the Code identical across all 5 to simplify future maintenance.
|
||||
|
||||
Rename HTTP Request nodes to remove Docker-specific naming:
|
||||
- "Fetch Containers For Mode" → keep name (not Docker-specific)
|
||||
- "Fetch Containers For Update" → keep name
|
||||
- "Fetch Containers For Exec" → keep name
|
||||
- "Fetch Containers For Nav" → keep name
|
||||
- "Fetch Containers For Clear" → keep name
|
||||
</action>
|
||||
<verify>
|
||||
Load n8n-batch-ui.json with python3 and verify:
|
||||
1. Zero HTTP Request nodes contain "docker-socket-proxy" in URL
|
||||
2. All 5 HTTP Request nodes use POST to `$env.UNRAID_HOST/graphql`
|
||||
3. 5 GraphQL Response Normalizer Code nodes exist (one per query path)
|
||||
4. All downstream Code nodes (Build Batch Keyboard, Handle Toggle, Handle Exec, etc.) are UNCHANGED
|
||||
5. Node count increased from 17 to 22 (5 normalizer nodes added)
|
||||
6. All connections valid
|
||||
7. Push to n8n via API and verify HTTP 200
|
||||
</verify>
|
||||
<done>
|
||||
All 5 container queries in n8n-batch-ui.json use Unraid GraphQL API. Normalizer transforms responses to Docker API contract. All bitmap encoding and keyboard building Code nodes unchanged. Workflow pushed to n8n successfully.
|
||||
</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<verification>
|
||||
1. Zero "docker-socket-proxy" references in n8n-batch-ui.json
|
||||
2. All 5 HTTP Request nodes point to `$env.UNRAID_HOST/graphql`
|
||||
3. Normalizer nodes present on all 5 query paths
|
||||
4. Downstream Code nodes byte-for-byte identical to pre-migration
|
||||
5. Push to n8n with HTTP 200
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- n8n-batch-ui.json has zero Docker socket proxy references
|
||||
- All container data flows through GraphQL Response Normalizer
|
||||
- Batch selection keyboard, toggle, exec, nav, clear all work with normalized data
|
||||
- Downstream Code nodes unchanged (zero-change migration for consumers)
|
||||
- Workflow valid and pushed to n8n
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
After completion, create `.planning/phases/16-api-migration/16-04-SUMMARY.md`
|
||||
</output>
|
||||
Reference in New Issue
Block a user