design-15 S3: sing-box sidecar annotation + bounded inspect enrichment#5
Merged
Conversation
Discovery now annotates each reported line with the control-plane line_uuid and declared downstream_line_uuid from the v2 sidecar (/etc/sing-box/lattice-metadata.json, LATTICE_SINGBOX_META override), joined by inbound tag; missing/corrupt/legacy-v1 sidecars degrade quietly and never fail discovery. The primary list path is also enriched per line via bounded `sb --json inspect <name>` calls (cap 64, per-call timeout, first-call-failure detection for older sb builds), filling outbound tag/type, line_id, node_uuid, and the user roster the plain list omits. Fill-only-empty in both enrichers; existing config join keeps resolving outbound server/port. Pins lattice-sdk @60c69bd (draft PR lattice-sdk#7).
The workspace checkout forced SDK main over the pseudo-version pinned for sidecar line identity, producing compile failures unrelated to the branch. Letting Go resolve go.mod keeps the tested dependency identical to the shipped one. Constraint: The sidecar branch consumes an SDK commit not yet present on SDK main Rejected: Always checkout SDK main | masks the pinned dependency and breaks coordinated prerelease work Confidence: high Scope-risk: narrow Directive: Keep agent CI aligned with go.mod unless an explicit integration matrix is introduced Tested: GOWORK=off go mod verify; go vet ./...; go test -race -cover ./...; YAML parse; git diff --check
The module-root gosec invocation surfaced a different legacy finding set even though the SDK resolution change was the only intended behavior. Restore the previously green repository-prefixed scan target. Constraint: The sidecar PR must fix SDK selection without redefining the existing gosec baseline Confidence: high Scope-risk: narrow Tested: Workflow diff review; prior successful main CI gosec evidence
Treat the Design 15 sidecar as an atomic identity document: distinguish absence from read failure, reject invalid v2 annotations as a unit, and cap aggregate inspect latency with bounded concurrency. Build CI and prerelease artifacts against the exact SDK pinned in go.mod. Constraint: Discovery must not delay the task loop beyond a short aggregate budget. Rejected: Serial per-line eight-second inspection | it can starve task polling for minutes. Confidence: high Scope-risk: moderate Reversibility: clean Directive: Keep invalid sidecars fail-closed and release builds on the declared SDK pin. Tested: go test ./...; go vet ./...; release workflow checker; targeted singboxdiscover race tests Not-tested: HK filesystem permission failure, covered by unit seams and deferred to canary
lr00rl
marked this pull request as ready for review
July 22, 2026 12:59
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
design-15 S3 agent slice:
/etc/sing-box/lattice-metadata.json(env overrideLATTICE_SINGBOX_META), joins by inbound tag, fillsLineUUID+DownstreamLineUUIDon every reportedSingBoxNode. Missing file / corrupt JSON / legacy v1 flat sidecar all degrade quietly — discovery never fails on a read-only annotation. Applies to both the primary list path and the runtime-config fallback.sb --json inspect <name>backfills outbound tag/type,line_id,node_uuid, and user roster (cap 64 calls/cycle, per-call timeout, first-call-failure detects older sb and stops). Fill-only-empty; config join still resolves outbound server/port.lattice-agentflag/env:-singbox-meta/LATTICE_SINGBOX_META; README updated.lattice-sdk@60c69bd(draft PR lattice-sdk#7).Verification
gofmt/go vetclean;go test ./...all okRefs LatticeNet/lattice#2, LatticeNet/lattice-sdk#7, LatticeNet/lattice-server#13.