unraid-docker-manager/.planning/phases/16-api-migration/16-02-PLAN.md

phase, plan, type, wave, depends_on, files_modified, autonomous, must_haves

phase	plan	type	wave	depends_on	files_modified	autonomous	must_haves
16-api-migration	02	execute	1		n8n-actions.json	true	truths artifacts key_links User can start a stopped container via Telegram and sees success message User can stop a running container via Telegram and sees success message User can restart a container via Telegram and sees success message Starting an already-running container shows 'already started' (not an error) Stopping an already-stopped container shows 'already stopped' (not an error) path provides contains n8n-actions.json Container lifecycle operations via Unraid GraphQL mutations graphql from to via pattern n8n-actions.json mutation nodes Unraid GraphQL API POST mutations (start, stop) mutation.*docker.*start|stop from to via pattern GraphQL Error Handler Format Start/Stop/Restart Result Code nodes ALREADY_IN_STATE mapped to statusCode 304 statusCode.*304

Migrate n8n-actions.json from Docker socket proxy to Unraid GraphQL API for container start, stop, and restart operations.

Purpose: Container lifecycle actions are the second-most-used feature. This plan replaces 4 Docker API HTTP Request nodes (1 container list + 3 actions) with GraphQL equivalents, using Container ID Registry for name-to-PrefixedID translation and GraphQL Error Handler for ALREADY_IN_STATE mapping.

Output: n8n-actions.json with all Docker API nodes replaced by Unraid GraphQL mutations, restart implemented as sequential stop+start (no native restart mutation), error handling preserving existing statusCode 304 pattern.

<execution_context> @/home/luc/.claude/get-shit-done/workflows/execute-plan.md @/home/luc/.claude/get-shit-done/templates/summary.md </execution_context>

@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/STATE.md @.planning/phases/16-api-migration/16-RESEARCH.md @.planning/phases/15-infrastructure-foundation/15-01-SUMMARY.md @.planning/phases/15-infrastructure-foundation/15-02-SUMMARY.md @n8n-actions.json @n8n-workflow.json (for Phase 15 utility node code — Container ID Registry, GraphQL Error Handler, HTTP Template) @ARCHITECTURE.md Task 1: Replace container list query and resolve with Container ID Registry n8n-actions.json Replace the container lookup flow in n8n-actions.json. Currently: - "Has Container ID?" IF node → "Get All Containers" HTTP Request → "Resolve Container ID" Code node

The current flow fetches ALL containers from Docker API, then searches by name in Code node to find the container ID. Replace with Unraid GraphQL query + Container ID Registry:

1. Replace "Get All Containers" (GET docker-socket-proxy:2375/v1.47/containers/json?all=true):

   • Change to: POST ={{ $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
   • Rename to "Query All Containers"

2. Add GraphQL Response Normalizer Code node after the HTTP Request (before Resolve Container ID). Copy normalizer logic from n8n-workflow.json utility node. This transforms GraphQL response to Docker API contract format so "Resolve Container ID" Code node works unchanged.

3. Add Container ID Registry update after normalizer — a Code node that updates the static data registry with fresh name→PrefixedID mappings. This is critical because downstream mutations need PrefixedIDs.

4. Update "Resolve Container ID" Code node: After normalization, this node already works (it searches by Names[0]). However, enhance it to also output the unraidId (PrefixedID) from the Id field, so downstream mutation nodes can use it directly. Add to the output: unraidId: matched.Id (the normalizer preserves the full PrefixedID in the Id field).

Wire: Has Container ID? (false) → Query All Containers → Normalizer → Registry Update → Resolve Container ID → Route Action Load n8n-actions.json and verify:

1. "Get All Containers" node replaced with GraphQL query
2. Normalizer Code node exists between HTTP Request and Resolve Container ID
3. Resolve Container ID outputs unraidId field
4. No "docker-socket-proxy" in any URL Container lookup uses Unraid GraphQL API with normalizer. Container ID Registry updated on every lookup. Resolve Container ID outputs unraidId (PrefixedID) for downstream mutations.

Task 2: Replace start/stop/restart HTTP nodes with GraphQL mutations n8n-actions.json Replace the 3 Docker API action nodes with Unraid GraphQL mutations:

1. Replace "Start Container" (POST docker-socket-proxy:2375/v1.47/containers/{id}/start):

   • Add a "Build Start Mutation" Code node before the HTTP Request that constructs the GraphQL mutation body:

     const data = $('Route Action').item.json;
     const unraidId = data.unraidId || data.containerId;
     return { json: { query: `mutation { docker { start(id: "${unraidId}") { id state } } }` } };
     

   • Change HTTP Request to: POST ={{ $env.UNRAID_HOST }}/graphql, body from expression ={{ JSON.stringify({query: $json.query}) }}
   • Headers: Content-Type: application/json, x-api-key: ={{ $env.UNRAID_API_KEY }}
   • Timeout: 15000ms, error handling: continueRegularOutput
   • Add GraphQL Error Handler Code node after HTTP Request (before Format Start Result). Copy error handler logic from n8n-workflow.json utility node. Maps ALREADY_IN_STATE → {statusCode: 304}, NOT_FOUND → {statusCode: 404}.
   • Wire: Route Action → Build Start Mutation → Start Container (HTTP) → Error Handler → Format Start Result

2. Replace "Stop Container" (POST docker-socket-proxy:2375/v1.47/containers/{id}/stop?t=10):

   • Same pattern as Start: Build Stop Mutation → HTTP Request → Error Handler → Format Stop Result
   • Mutation: mutation { docker { stop(id: "${unraidId}") { id state } } }
   • Timeout: 15000ms

3. Replace "Restart Container" (POST docker-socket-proxy:2375/v1.47/containers/{id}/restart?t=10): Unraid has NO native restart mutation. Implement as sequential stop + start:

   a. Build Stop-for-Restart Mutation Code node:

   const data = $('Route Action').item.json;
   const unraidId = data.unraidId || data.containerId;
   return { json: { query: `mutation { docker { stop(id: "${unraidId}") { id state } } }`, unraidId } };
   

   b. Stop For Restart HTTP Request node (same config as Stop Container) c. Handle Stop-for-Restart Result Code node:

   • Check response: if success OR statusCode 304 (already stopped) → proceed to start
   • If error → fail restart

   const response = $input.item.json;
   const prevData = $('Build Stop-for-Restart Mutation').item.json;
   if (response.statusCode && response.statusCode !== 304 && !response.data) {
     return { json: { error: true, statusCode: response.statusCode, message: 'Failed to stop container for restart' } };
   }
   return { json: { query: `mutation { docker { start(id: "${prevData.unraidId}") { id state } } }` } };
   

   d. Start After Stop HTTP Request node (same config as Start Container) e. Restart Error Handler Code node (same GraphQL Error Handler logic) f. Wire: Route Action → Build Stop-for-Restart → Stop For Restart (HTTP) → Handle Stop-for-Restart → Start After Stop (HTTP) → Restart Error Handler → Format Restart Result

   Critical: The existing "Format Restart Result" Code node checks response.statusCode === 304 which means "already running". For restart, 304 on the start step would mean the container didn't actually stop then start — it was already running. This is correct behavior for the existing Format Restart Result node.

Existing Format Start/Stop/Restart Result Code nodes remain UNCHANGED. They already check:

• response.statusCode === 304 → "already in desired state"
• !response.message && !response.error → success (Docker 204 No Content pattern)
• The GraphQL Error Handler output maps to match these exact patterns.

Rename Docker-centric HTTP Request nodes:

• "Start Container" → "Start Container" (keep name, just change URL/method)
• "Stop Container" → "Stop Container" (keep name)
• Remove old "Restart Container" single-node and replace with stop+start chain Load n8n-actions.json and verify:

1. Zero "docker-socket-proxy" references in any node URL
2. Start and Stop nodes use POST to $env.UNRAID_HOST/graphql with mutation bodies
3. Restart implemented as 2 HTTP Request nodes (stop then start) with intermediate error handling
4. GraphQL Error Handler Code nodes exist after each mutation HTTP Request
5. Format Start/Stop/Restart Result Code nodes are UNCHANGED from pre-migration
6. All connections valid
7. Push to n8n via API and verify HTTP 200 Container start/stop use single GraphQL mutations. Restart uses sequential stop+start with ALREADY_IN_STATE tolerance on stop step. Error Handler maps GraphQL errors to statusCode 304 pattern. Format Result nodes unchanged. Workflow pushed to n8n.

1. Load n8n-actions.json and confirm zero "docker-socket-proxy" references 2. Confirm start/stop mutations use correct GraphQL syntax 3. Confirm restart is 2-step (stop → start) with 304 tolerance on stop 4. Confirm GraphQL Error Handler maps ALREADY_IN_STATE to statusCode 304 5. Confirm Format Start/Stop/Restart Result Code nodes are byte-for-byte identical to pre-migration 6. Push to n8n and verify HTTP 200

<success_criteria>

• n8n-actions.json has zero Docker socket proxy references
• Start/stop operations use GraphQL mutations with Error Handler
• Restart operates as sequential stop+start with ALREADY_IN_STATE tolerance
• Format Result Code nodes unchanged (zero-change migration for output formatting)
• Container ID Registry updated on container lookup
• Workflow valid and pushed to n8n </success_criteria>

After completion, create `.planning/phases/16-api-migration/16-02-SUMMARY.md`