luckberg/unraid-docker-manager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
gsd/v1.0-unraid-api-native
unraid-docker-manager/.planning/phases/15-infrastructure-foundation/15-02-SUMMARY.md
T
Lucas Berger d25fc1b13f docs(15-02): complete GraphQL utility nodes plan
2026-02-09 08:55:01 -05:00

7.5 KiB
Raw Permalink Blame History

phase, plan, subsystem, tags, requires, provides, affects, tech-stack, key-files, key-decisions, patterns-established, duration, completed
phase plan subsystem tags requires provides affects tech-stack key-files key-decisions patterns-established duration completed
15-infrastructure-foundation 02 infra
graphql
unraid-api
response-normalization
error-handling
http-templates
phase provides
14-unraid-api-access Unraid GraphQL API access verification, myunraid.net cloud relay configuration
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)
16-api-migration
17-container-id-translation
18-docker-proxy-removal
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
created modified
n8n-workflow.json
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
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
5min 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 View Git Blame Copy Permalink