docs(15): create phase plan — 2 plans for infrastructure foundation
This commit is contained in:
Lucas Berger
@@ -0,0 +1,243 @@
|
||||
---
|
||||
phase: 15-infrastructure-foundation
|
||||
plan: 01
|
||||
type: execute
|
||||
wave: 1
|
||||
depends_on: []
|
||||
files_modified:
|
||||
- n8n-workflow.json
|
||||
autonomous: true
|
||||
|
||||
must_haves:
|
||||
truths:
|
||||
- "Container ID Registry maps container names to Unraid PrefixedID format"
|
||||
- "Callback token encoder produces 8-char tokens from PrefixedIDs"
|
||||
- "Callback token decoder resolves 8-char tokens back to PrefixedIDs"
|
||||
- "Token collisions are detected and handled"
|
||||
- "Registry and token store persist across workflow executions via static data JSON serialization"
|
||||
artifacts:
|
||||
- path: "n8n-workflow.json"
|
||||
provides: "Container ID Registry, Callback Token Encoder, Callback Token Decoder utility nodes"
|
||||
contains: "_containerIdMap"
|
||||
key_links:
|
||||
- from: "Container ID Registry node"
|
||||
to: "static data _containerIdMap"
|
||||
via: "JSON.parse/JSON.stringify pattern"
|
||||
pattern: "JSON\\.parse\\(.*_containerIdMap"
|
||||
- from: "Callback Token Encoder node"
|
||||
to: "static data _callbackTokens"
|
||||
via: "SHA-256 hash + JSON serialization"
|
||||
pattern: "crypto\\.subtle\\.digest"
|
||||
- from: "Callback Token Decoder node"
|
||||
to: "static data _callbackTokens"
|
||||
via: "JSON.parse lookup"
|
||||
pattern: "_callbackTokens"
|
||||
---
|
||||
|
||||
<objective>
|
||||
Build the Container ID Registry and Callback Token Encoding system as utility Code nodes in the main workflow.
|
||||
|
||||
Purpose: Phase 16 (API Migration) needs to translate between container names and Unraid PrefixedIDs (129-char format like `server_hash:container_hash`). The registry provides centralized ID translation, and the token system compresses PrefixedIDs to 8-char tokens for Telegram callback_data (64-byte limit). These nodes are not wired into the active flow yet -- they are standalone utilities that Phase 16 will connect.
|
||||
|
||||
Output: Three new Code nodes in n8n-workflow.json: Container ID Registry, Callback Token Encoder, Callback Token Decoder.
|
||||
</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
|
||||
@ARCHITECTURE.md
|
||||
@.planning/phases/15-infrastructure-foundation/15-RESEARCH.md
|
||||
@.planning/phases/14-unraid-api-access/14-02-SUMMARY.md
|
||||
@.planning/phases/11-update-all-callback-limits/11-01-SUMMARY.md
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 1: Add Container ID Registry utility node</name>
|
||||
<files>n8n-workflow.json</files>
|
||||
<action>
|
||||
Add a new Code node named "Container ID Registry" to n8n-workflow.json. This is a **standalone utility node** -- do NOT connect it to any existing nodes. Place it at position [200, 2400] (below the active workflow area, in an "infrastructure utilities" zone).
|
||||
|
||||
The node must implement:
|
||||
|
||||
1. **Registry initialization** using static data with JSON serialization pattern (CRITICAL: must use top-level assignment per CLAUDE.md):
|
||||
```javascript
|
||||
const registry = $getWorkflowStaticData('global');
|
||||
if (!registry._containerIdMap) {
|
||||
registry._containerIdMap = JSON.stringify({});
|
||||
}
|
||||
const containerMap = JSON.parse(registry._containerIdMap);
|
||||
```
|
||||
|
||||
2. **updateRegistry(containers)** function that:
|
||||
- Takes an array of Unraid GraphQL container objects (format: `{ id, names[], state }`)
|
||||
- Maps each container: name (from `names[0]`, strip leading `/`, lowercase) -> `{ name, unraidId: id }`
|
||||
- The Unraid `id` field IS the PrefixedID (129-char `server_hash:container_hash` format per ARCHITECTURE.md)
|
||||
- Stores timestamp: `registry._lastRefresh = Date.now()`
|
||||
- Serializes: `registry._containerIdMap = JSON.stringify(newMap)`
|
||||
- Returns the new map
|
||||
|
||||
3. **getUnraidId(containerName)** function that:
|
||||
- Strips leading `/`, lowercases input
|
||||
- Looks up in containerMap
|
||||
- If not found AND registry older than 60 seconds: throws `Container "${name}" not found. Registry may be stale - try "status" to refresh.`
|
||||
- If not found AND registry fresh: throws `Container "${name}" not found. Check spelling or run "status" to see all containers.`
|
||||
- Returns `entry.unraidId`
|
||||
|
||||
4. **getContainerByName(containerName)** function that:
|
||||
- Same lookup as getUnraidId but returns the full entry object
|
||||
- Returns `{ name, unraidId }`
|
||||
|
||||
5. **Node input/output contract:**
|
||||
- Input: `$input.item.json.containers` (array) for registry updates, OR `$input.item.json.containerName` (string) for lookups
|
||||
- Detect mode: if `containers` array exists, update registry. If `containerName` exists, do lookup.
|
||||
- Output: Updated map (for updates) or `{ containerName, unraidId }` (for lookups)
|
||||
|
||||
Node properties:
|
||||
- id: "code-container-id-registry"
|
||||
- name: "Container ID Registry"
|
||||
- type: "n8n-nodes-base.code"
|
||||
- typeVersion: 2
|
||||
- Do NOT add any connections for this node.
|
||||
- Add `notesDisplayMode: "show"` and `notes: "UTILITY: Container name <-> Unraid PrefixedID translation. Not connected - Phase 16 will wire this in."` to parameters.
|
||||
</action>
|
||||
<verify>
|
||||
Run: `python3 -c "import json; wf=json.load(open('n8n-workflow.json')); nodes={n['name']:n for n in wf['nodes']}; r=nodes.get('Container ID Registry'); print('EXISTS' if r else 'MISSING'); print('ID:', r['id'] if r else 'N/A'); print('Has _containerIdMap:', '_containerIdMap' in r['parameters'].get('jsCode','') if r else False); print('Has JSON.parse:', 'JSON.parse' in r['parameters'].get('jsCode','') if r else False); print('Has JSON.stringify:', 'JSON.stringify' in r['parameters'].get('jsCode','') if r else False)"`
|
||||
</verify>
|
||||
<done>Container ID Registry Code node exists in n8n-workflow.json with updateRegistry() and getUnraidId() functions, uses JSON serialization for static data persistence, is not connected to any other nodes.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: Add Callback Token Encoder and Decoder utility nodes</name>
|
||||
<files>n8n-workflow.json</files>
|
||||
<action>
|
||||
Add two new Code nodes to n8n-workflow.json for callback token encoding/decoding. These are **standalone utility nodes** -- do NOT connect them to any existing nodes. Place them at positions [600, 2400] and [1000, 2400].
|
||||
|
||||
**Node 1: Callback Token Encoder**
|
||||
|
||||
id: "code-callback-token-encoder"
|
||||
name: "Callback Token Encoder"
|
||||
Position: [600, 2400]
|
||||
|
||||
Implement:
|
||||
|
||||
1. **Token store initialization** using static data JSON serialization:
|
||||
```javascript
|
||||
const staticData = $getWorkflowStaticData('global');
|
||||
if (!staticData._callbackTokens) {
|
||||
staticData._callbackTokens = JSON.stringify({});
|
||||
}
|
||||
const tokenStore = JSON.parse(staticData._callbackTokens);
|
||||
```
|
||||
|
||||
2. **encodeToken(unraidId)** async function that:
|
||||
- Generates SHA-256 hash of the unraidId string using `crypto.subtle.digest('SHA-256', new TextEncoder().encode(unraidId))`
|
||||
- Takes first 8 hex characters as the token
|
||||
- **Collision detection**: if `tokenStore[token]` exists AND `tokenStore[token] !== unraidId`, try next 8 chars from the hash (offset by 8). Repeat up to 7 times (56 chars of SHA-256 = 7 non-overlapping 8-char windows). Throw if all windows collide.
|
||||
- Stores mapping: `tokenStore[token] = unraidId`
|
||||
- Persists: `staticData._callbackTokens = JSON.stringify(tokenStore)`
|
||||
- Returns the 8-char token
|
||||
|
||||
3. **Input/output contract:**
|
||||
- Input: `$input.item.json.unraidId` (string, the 129-char PrefixedID)
|
||||
- Also accepts optional `$input.item.json.action` (string) for convenience
|
||||
- Output: `{ token, unraidId, callbackData: "action:{action}:{token}" (if action provided), byteSize }`
|
||||
- Include byte size validation: if callbackData > 64 bytes, include `warning: "Callback data exceeds 64-byte limit"`
|
||||
|
||||
4. Add notes: "UTILITY: Encode Unraid PrefixedID to 8-char callback token. Not connected - Phase 16 will wire this in."
|
||||
|
||||
**Node 2: Callback Token Decoder**
|
||||
|
||||
id: "code-callback-token-decoder"
|
||||
name: "Callback Token Decoder"
|
||||
Position: [1000, 2400]
|
||||
|
||||
Implement:
|
||||
|
||||
1. **Token store read** (same JSON parse pattern):
|
||||
```javascript
|
||||
const staticData = $getWorkflowStaticData('global');
|
||||
const tokenStore = JSON.parse(staticData._callbackTokens || '{}');
|
||||
```
|
||||
|
||||
2. **decodeToken(token)** function that:
|
||||
- Looks up token in tokenStore
|
||||
- If not found: throws `Token not found: ${token}. Token store may have been cleared.`
|
||||
- Returns the full unraidId (129-char PrefixedID)
|
||||
|
||||
3. **Input/output contract:**
|
||||
- Input: `$input.item.json.token` (string, 8-char token) OR `$input.item.json.callbackData` (string like "action:start:a1b2c3d4")
|
||||
- If callbackData provided, parse it: split by `:`, extract token from last segment
|
||||
- Output: `{ token, unraidId, action (if parsed from callbackData) }`
|
||||
|
||||
4. Add notes: "UTILITY: Decode 8-char callback token to Unraid PrefixedID. Not connected - Phase 16 will wire this in."
|
||||
|
||||
**For both nodes:** Do NOT add any connections. These are standalone utilities.
|
||||
|
||||
After adding all nodes, push the updated workflow to n8n using the push recipe from CLAUDE.md.
|
||||
</action>
|
||||
<verify>
|
||||
Run: `python3 -c "
|
||||
import json
|
||||
wf = json.load(open('n8n-workflow.json'))
|
||||
nodes = {n['name']: n for n in wf['nodes']}
|
||||
enc = nodes.get('Callback Token Encoder')
|
||||
dec = nodes.get('Callback Token Decoder')
|
||||
print('Encoder:', 'EXISTS' if enc else 'MISSING')
|
||||
print('Decoder:', 'EXISTS' if dec else 'MISSING')
|
||||
if enc:
|
||||
code = enc['parameters'].get('jsCode', '')
|
||||
print('Has crypto.subtle:', 'crypto.subtle' in code)
|
||||
print('Has collision detection:', 'tokenStore[token]' in code)
|
||||
print('Has _callbackTokens:', '_callbackTokens' in code)
|
||||
if dec:
|
||||
code = dec['parameters'].get('jsCode', '')
|
||||
print('Has decodeToken:', 'decodeToken' in code)
|
||||
print('Has _callbackTokens:', '_callbackTokens' in code)
|
||||
|
||||
# Verify no connections to/from utility nodes
|
||||
conn = wf.get('connections', {})
|
||||
for name in ['Container ID Registry', 'Callback Token Encoder', 'Callback Token Decoder']:
|
||||
has_outgoing = name in conn
|
||||
has_incoming = any(
|
||||
any(any(c.get('node') == name for c in group) for group in outputs if group)
|
||||
for outputs in conn.values()
|
||||
for outputs in [list(outputs.values()) if isinstance(outputs, dict) else []]
|
||||
)
|
||||
print(f'{name} connections: outgoing={has_outgoing}')
|
||||
print('Total nodes:', len(wf['nodes']))
|
||||
"`
|
||||
</verify>
|
||||
<done>Callback Token Encoder and Decoder Code nodes exist in n8n-workflow.json. Encoder uses SHA-256 hashing with collision detection, produces 8-char tokens. Decoder resolves tokens back to PrefixedIDs. Both use JSON serialization for static data persistence. Neither node is connected to any other nodes. Workflow pushed to n8n.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<verification>
|
||||
1. Three new utility Code nodes exist in n8n-workflow.json: Container ID Registry, Callback Token Encoder, Callback Token Decoder
|
||||
2. All three nodes use `$getWorkflowStaticData('global')` with JSON.parse/JSON.stringify pattern (not deep mutation)
|
||||
3. None of the three nodes have connections to/from other nodes (standalone utilities)
|
||||
4. Container ID Registry handles: updateRegistry(containers), getUnraidId(name), getContainerByName(name)
|
||||
5. Token Encoder handles: encodeToken(unraidId) with SHA-256 + collision detection
|
||||
6. Token Decoder handles: decodeToken(token) with error handling for missing tokens
|
||||
7. Workflow JSON is valid and pushed to n8n
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- Container ID Registry node maps container names to Unraid PrefixedID format (129-char)
|
||||
- Callback token encoding produces 8-char hex tokens that fit within Telegram's 64-byte callback_data limit
|
||||
- Token collision detection prevents wrong-container scenarios
|
||||
- All static data uses JSON serialization (top-level assignment) per CLAUDE.md convention
|
||||
- Three standalone utility nodes ready for Phase 16 to wire in
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
After completion, create `.planning/phases/15-infrastructure-foundation/15-01-SUMMARY.md`
|
||||
</output>
|
||||
Reference in New Issue
Block a user