docs(15-02): complete GraphQL utility nodes plan
This commit is contained in:
Lucas Berger
@@ -0,0 +1,138 @@
|
||||
---
|
||||
phase: 15-infrastructure-foundation
|
||||
plan: 02
|
||||
subsystem: infra
|
||||
tags: [graphql, unraid-api, response-normalization, error-handling, http-templates]
|
||||
|
||||
# Dependency graph
|
||||
requires:
|
||||
- phase: 14-unraid-api-access
|
||||
provides: Unraid GraphQL API access verification, myunraid.net cloud relay configuration
|
||||
provides:
|
||||
- GraphQL Response Normalizer utility node (Unraid to Docker API contract transformation)
|
||||
- GraphQL Error Handler utility node (error code mapping with HTTP 304 for ALREADY_IN_STATE)
|
||||
- Unraid API HTTP Template utility node (15s timeout, env var auth, copy-paste template)
|
||||
affects: [16-api-migration, 17-container-id-translation, 18-docker-proxy-removal]
|
||||
|
||||
# Tech tracking
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- GraphQL response normalization (Unraid UPPERCASE state -> Docker lowercase)
|
||||
- ALREADY_IN_STATE error code maps to HTTP 304 (matches Docker API pattern)
|
||||
- Environment variable authentication (UNRAID_HOST, UNRAID_API_KEY headers)
|
||||
- 15-second timeout for myunraid.net cloud relay latency
|
||||
- continueRegularOutput error handling for downstream Code node processing
|
||||
|
||||
key-files:
|
||||
created: []
|
||||
modified:
|
||||
- n8n-workflow.json
|
||||
|
||||
key-decisions:
|
||||
- "GraphQL normalizer keeps full Unraid PrefixedID in Id field (downstream Container ID Registry handles translation)"
|
||||
- "STOPPED->exited state mapping (Docker convention for stopped containers)"
|
||||
- "15-second HTTP timeout for cloud relay (200-500ms latency + safety margin for slow operations)"
|
||||
- "Environment variable authentication instead of n8n Header Auth credential (Phase 14 decision - more reliable)"
|
||||
- "continueRegularOutput error handling allows downstream Code node to process GraphQL errors instead of n8n catching them"
|
||||
|
||||
patterns-established:
|
||||
- "Utility nodes as standalone copy-paste templates (not connected until Phase 16 wiring)"
|
||||
- "GraphQL error checking: response.errors[] array inspection with extensions.code mapping"
|
||||
- "HTTP Template pattern: pre-configured request nodes as duplication templates"
|
||||
|
||||
# Metrics
|
||||
duration: 5min
|
||||
completed: 2026-02-09
|
||||
---
|
||||
|
||||
# Phase 15 Plan 02: GraphQL Utility Nodes Summary
|
||||
|
||||
**GraphQL Response Normalizer, Error Handler, and HTTP Template utility nodes for zero-change Unraid API migration**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** 5 minutes
|
||||
- **Started:** 2026-02-09T13:47:13Z
|
||||
- **Completed:** 2026-02-09T13:52:29Z
|
||||
- **Tasks:** 2
|
||||
- **Files modified:** 1
|
||||
|
||||
## Accomplishments
|
||||
- GraphQL Response Normalizer transforms Unraid API shape to Docker API contract (id->Id, UPPERCASE state->lowercase, names preserved)
|
||||
- GraphQL Error Handler maps ALREADY_IN_STATE to HTTP 304 equivalent, handles NOT_FOUND/FORBIDDEN/UNAUTHORIZED
|
||||
- Unraid API HTTP Template pre-configured with 15-second timeout, environment variable auth, and continueRegularOutput
|
||||
- All three utility nodes standalone (not connected) - ready for Phase 16 API migration wiring
|
||||
|
||||
## Task Commits
|
||||
|
||||
Each task was committed atomically:
|
||||
|
||||
1. **Task 1: Add GraphQL Response Normalizer utility node** - `1b4b596` (feat)
|
||||
2. **Task 2: Add GraphQL Error Handler and Unraid API HTTP Template nodes** - `e6ac219` (feat)
|
||||
|
||||
## Files Created/Modified
|
||||
- `n8n-workflow.json` - Added 3 utility nodes (GraphQL Response Normalizer, GraphQL Error Handler, Unraid API HTTP Template) at positions [200,2600], [600,2600], [1000,2600]
|
||||
|
||||
## Decisions Made
|
||||
|
||||
1. **Full Unraid PrefixedID preservation**: GraphQL normalizer copies the full 129-character Unraid ID to the Docker API `Id` field. Translation happens downstream via the Container ID Registry (Plan 01), not in the normalizer. This keeps normalization focused on API shape transformation only.
|
||||
|
||||
2. **STOPPED->exited mapping**: Unraid returns "STOPPED" state, Docker API uses "exited" for stopped containers. Normalizer maps STOPPED->exited to match Docker convention, ensuring existing workflow nodes recognize stopped containers correctly.
|
||||
|
||||
3. **ALREADY_IN_STATE = HTTP 304**: When container is already in desired state (e.g., "start" on running container), Unraid returns ALREADY_IN_STATE error code. Mapped to HTTP 304 to match Docker API pattern used in n8n-actions.json, allowing existing success/failure logic to work unchanged.
|
||||
|
||||
4. **15-second HTTP timeout**: myunraid.net cloud relay adds 200-500ms latency (Phase 14 measurement). 15 seconds provides safety margin for slow operations like container start/stop (3-5 seconds) plus relay overhead.
|
||||
|
||||
5. **continueRegularOutput error mode**: HTTP Request node configured to pass errors as regular output instead of n8n catching them. Allows downstream GraphQL Error Handler Code node to inspect response.errors[] array and map error codes appropriately.
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 3 - Blocking] Fixed Container ID Registry invalid property**
|
||||
- **Found during:** Task 2 (n8n API push validation)
|
||||
- **Issue:** Container ID Registry node (from Task 1 commit) had `notesDisplayMode: 'show'` property which is not valid for n8n API PUT requests. API returned HTTP 400 with "must NOT have additional properties" error.
|
||||
- **Fix:** Removed `notesDisplayMode` property from Container ID Registry node. This property is display-only and not part of the n8n workflow schema for API operations.
|
||||
- **Files modified:** n8n-workflow.json
|
||||
- **Verification:** Workflow successfully pushed to n8n with HTTP 200 response
|
||||
- **Committed in:** e6ac219 (Task 2 commit)
|
||||
|
||||
---
|
||||
|
||||
**Total deviations:** 1 auto-fixed (1 blocking)
|
||||
**Impact on plan:** Auto-fix necessary to push workflow to n8n. Property was UI-only metadata not required for functionality. No scope impact.
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
**n8n API validation on push**: Initial push attempts failed with HTTP 400 "must NOT have additional properties" for node 170. Root cause was `notesDisplayMode` property present on Container ID Registry node from previous task. Property is valid in n8n UI but rejected by API validation on PUT requests. Fixed by removing the property (see Deviations).
|
||||
|
||||
## User Setup Required
|
||||
|
||||
None - no external service configuration required. All utility nodes use existing environment variables (UNRAID_HOST, UNRAID_API_KEY) configured in Phase 14.
|
||||
|
||||
## Next Phase Readiness
|
||||
|
||||
**Phase 16 (API Migration) ready to begin:**
|
||||
- Three utility nodes provide complete transformation pipeline: HTTP Request -> Error Handler -> Response Normalizer -> existing workflow nodes
|
||||
- HTTP Template serves as copy-paste template for migrating each Docker API call to Unraid GraphQL
|
||||
- Error handler maps Unraid error codes to Docker HTTP status codes (304, 404, etc.)
|
||||
- Normalizer ensures zero changes required to 60+ downstream Code nodes expecting Docker API format
|
||||
- All nodes validated and pushed to n8n successfully
|
||||
|
||||
**Blockers:** None
|
||||
|
||||
**Notes:**
|
||||
- Container ID Registry node (from uncommitted Plan 01 work) was included in Task 1 commit. This node is required for Plan 02's normalizer but belongs to Plan 01. Plan 01 should be executed to complete the Container ID Registry implementation (add translation helper functions).
|
||||
- Task 2 commit accidentally included 2 extra nodes (Callback Token Encoder, Callback Token Decoder) that were not part of Plan 02. These appear to be from uncommitted work in the repository. Total nodes added: 4 instead of planned 2. The extra nodes do not affect Plan 02 functionality.
|
||||
|
||||
## Self-Check
|
||||
|
||||
**Files:** PASSED - n8n-workflow.json exists and modified
|
||||
**Commits:** PASSED - 1b4b596 (Task 1) and e6ac219 (Task 2) exist
|
||||
**Nodes:** PASSED - All 3 Plan 02 utility nodes exist in workflow
|
||||
**Node count:** DISCREPANCY - 175 nodes total (expected 173). Task 2 commit included 4 nodes instead of 2 (see Notes above).
|
||||
|
||||
---
|
||||
*Phase: 15-infrastructure-foundation*
|
||||
*Completed: 2026-02-09*
|
||||
Reference in New Issue
Block a user