fix: support pinned attachment lookup arrays

2026-08-31 15:42:11 +08:00
1 parent 0da8b4f959
commit 4ba2d43710
@@ -0,0 +1,54 @@
+# Task: Diagnose attachment DNS download failure
+
+## Identity
+
+- Task ID: 20260831-diagnose-attachment-dns-7e41c9a2
+- Mode: Feature
+- Branch: main
+- Worktree: /Users/inmanx/Documents/lwltAPI
+- Base commit: 0da8b4f959032249b0e86f82db2aeff545fa7e82
+- Owner: codex
+- Status: Ready for integration
+
+## Scope
+
+- Inspect the user-supplied production control-plane log excerpt for the current internal AgentBus roster attachment failure.
+- Correlate the structured attachment milestones and stack trace with `control-plane/src/input-attachment.ts`.
+- Correct the pinned DNS `lookup` callback so it follows both Node single-address and `all: true` callback contracts.
+- Add focused regression coverage and run the full repository gates.
+
+## Intent And Constraints
+
+- Preserve accepted internal-network behavior: private, reserved, localhost, and internal DNS attachment targets remain allowed.
+- Preserve credential-free HTTPS, DNS resolution and pinning, redirect revalidation, timeout, byte limits, declared-size validation, optional SHA-256 verification, and privacy-safe diagnostics.
+- Do not log or persist attachment URLs, hostnames, IP addresses, file bytes, message text, or roster values.
+- Do not deploy, restart services, mutate Kubernetes, read secrets, access ERP, retry a live task, or send an external message.
+
+## Outcome
+
+- Confirmed from the supplied production log that the AgentBus frame was correlated correctly, one structured `.xls` attachment was accepted, metadata validation passed, and DNS resolution returned eight IPv4 addresses. The failure occurred only when the HTTPS connection consumed the selected pinned address.
+- Root cause is the custom `lookup` callback shape, not private-network rejection or DNS failure. Node invokes connection lookup with `options.all = true`; the old callback returned `(null, addressString, family)`, while that mode requires `(null, [{ address, family }])`. Node consequently raised `ERR_INVALID_IP_ADDRESS` before any HTTP response.
+- Reproduced the same failure locally with the bundled Node runtime: the request passed `{ all: true }`, the old scalar callback produced `ERR_INVALID_IP_ADDRESS`, and the stack matched the production failure boundary.
+- Added `createPinnedAttachmentLookup()`. It returns a single-element array for `all: true` and the scalar address/family pair otherwise, retaining a single previously validated address as the only connection candidate.
+- Replaced the unsafe `as never` callback cast with the typed lookup function and added regression coverage for both callback forms.
+- No internal-address blocking was restored or added. No deployment, restart, Kubernetes mutation, secret read, ERP access, live-task retry, or external message occurred.
+
+## Verification
+
+- Focused input-attachment tests: 8/8 passed, including the new Node lookup callback-shape regression.
+- `node --run check:repo`: 9/9 passed.
+- `node --run check`: passed.
+- `node --run test:control-plane`: 136/136 passed.
+- `node --run test:legacy`: 255/255 passed.
+- `node --run build`: passed.
+- `check_project_docs.py`: passed.
+- `git diff --check`: passed.
+
+## Follow-ups
+
+- The fix is not active on the server until a separately authorized image build/deployment/restart publishes the new revision.
+- After deployment, verify a real internal roster attachment reaches `agentbus.attachment_http_response` and `agentbus.attachment_download_completed`; `DEPLOYMENT_REVISION` should no longer be `unknown`.
+
+## Promotion Candidates
+
+- None. This fixes an implementation defect while preserving the already accepted `NETWORK-001` behavior and security boundaries.