docs: add DD-064 std/net enhancements plan#129
Conversation
Greptile SummaryThis PR adds DD-064, a design document specifying
Confidence Score: 5/5Documentation-only change with no runtime code; safe to merge, with three spec clarifications recommended before implementation begins. This is a design document with no runtime code changes. The spec is thorough and has addressed the substantial issues raised in previous review rounds. The remaining findings are clarifications and editorial consistency issues rather than defects that would cause broken implementations. design-docs/dd-064-std-net-enhancements.md — the Section 4 vs Section 6 reason_code ambiguity, the Open Decision 3 annotation, and the PR 3 scope bullets are worth resolving before this doc is used as the authoritative implementation guide. Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[v0.4.12 PR Plan] --> PR1
A --> PR2
A --> PR3
A --> PR4
A --> PR5
A --> PR6
PR1[PR 1: Result consistency\nreason_code, normalize reason strings]
PR2[PR 2: Local interface introspection\nlocal_interfaces, local_addr_for]
PR3[PR 3: DNS resolver controls\ndns_lookup nameservers/strategy\ndns_lookup_many, dns_reverse]
PR4[PR 4: Address-family controls\nping, tcp_connect, reachable\nport_scan, tls_info]
PR5[PR 5: TLS check OR tcp_banner\nchoose one based on app need]
PR6[PR 6: Docs and examples\nfinal release coherence]
PR1 --> PR2
PR2 --> PR3
PR3 --> PR4
PR4 --> PR5
PR5 --> PR6
MVP[Minimum Viable Scope] --> |PR 1 + PR 2 + PR 4 + DNS nameservers|DONE[v0.4.12 release]
style PR5 fill:#ffe0b2,stroke:#e65100
style MVP fill:#e8f5e9,stroke:#388e3c
%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
A[v0.4.12 PR Plan] --> PR1
A --> PR2
A --> PR3
A --> PR4
A --> PR5
A --> PR6
PR1[PR 1: Result consistency\nreason_code, normalize reason strings]
PR2[PR 2: Local interface introspection\nlocal_interfaces, local_addr_for]
PR3[PR 3: DNS resolver controls\ndns_lookup nameservers/strategy\ndns_lookup_many, dns_reverse]
PR4[PR 4: Address-family controls\nping, tcp_connect, reachable\nport_scan, tls_info]
PR5[PR 5: TLS check OR tcp_banner\nchoose one based on app need]
PR6[PR 6: Docs and examples\nfinal release coherence]
PR1 --> PR2
PR2 --> PR3
PR3 --> PR4
PR4 --> PR5
PR5 --> PR6
MVP[Minimum Viable Scope] --> |PR 1 + PR 2 + PR 4 + DNS nameservers|DONE[v0.4.12 release]
style PR5 fill:#ffe0b2,stroke:#e65100
style MVP fill:#e8f5e9,stroke:#388e3c
Reviews (3): Last reviewed commit: "docs: tighten DD-064 std/net enhancement..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| #### `dns_lookup_many(name, record_types, opts?) -> Result<Map, String>` | ||
|
|
||
| Batch common records with shared resolver/timeout options. | ||
|
|
||
| Example: | ||
|
|
||
| ```ntnt | ||
| let records = dns_lookup_many("example.com", ["A", "AAAA", "MX", "TXT"], map { | ||
| "timeout_ms": 1000, | ||
| "strategy": "explicit", | ||
| "nameservers": ["1.1.1.1"] | ||
| }) | ||
| // Ok(map { "A": [...], "AAAA": [...], "MX": [...], "TXT": [...] }) | ||
| ``` | ||
|
|
||
| Bounds: | ||
|
|
||
| - `opts` inherits the same resolver controls as `dns_lookup()`, including `timeout_ms`, `strategy`, `nameservers`, and `allow_private` for private nameserver targets. | ||
| - Max record types: 8. | ||
| - Reject duplicate and unsupported record types. | ||
| - Preserve per-type no-answer as an empty array. | ||
| - If one record type has an operational resolver failure, the whole call returns `Err(String)`. Mixed partial failure maps are deliberately out of scope for this primitive; apps needing partial behavior can call `dns_lookup()` individually. | ||
|
|
||
| Priority: high if current DNS usage feels repetitive; otherwise defer. |
There was a problem hiding this comment.
dns_reverse() is silently excluded from Section 3's resolver controls — leaving PTR lookups with no way to use custom nameservers.
Section 3 explicitly extends dns_lookup() with custom nameservers / strategy options and states that dns_lookup_many() "inherits the same resolver controls as dns_lookup()." But dns_reverse(ip, opts?) is in the baseline function list and is never mentioned here, in PR 3's scope, or in PR 3's test cases.
An implementor reading Section 3 will extend custom-nameserver support to dns_lookup() and dns_lookup_many() but not to dns_reverse(). PTR lookups against an explicit DNS server are a common need when verifying reverse DNS on a network you control. If exclusion is intentional, document it. If it should be supported, add it to Section 3's rules and PR 3's scope.
1 participant
Summary
std/netv0.4.12 enhancements.std/net.Test Plan
git diff --check