Skip to content

Commit 1382073

Browse files
TMHSDigitalclaude
andcommitted
docs(library): keep the first example compilable on v0.10.0 (#226)
The first Scan snippet printed r.Internal, which v0.10.0 does not have, so go get plus copy-paste failed to compile. Drop it from the snippet and describe Takeover and Internal in prose, tagging Internal as unreleased. Also tag RatePerResolver and document it, list the NS, MX and TXT record types, note AutoRate's six-step floor before the guard applies, and cover the newer Stats fields in Accounting. Fixes #226 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent f7b0138 commit 1382073

2 files changed

Lines changed: 9 additions & 4 deletions

File tree

‎docs/_data/unreleased.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,9 @@ action:
2121
# pkg/subenum identifiers
2222
library:
2323
- AutoRate
24+
- Internal
2425
- MaxDuration
2526
- Permutations
27+
- RatePerResolver
2628
- RetryInconclusive
2729
- TakeoverProviders

‎docs/library.md‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -30,10 +30,12 @@ if err != nil {
3030
// stats still hold what was gathered.
3131
}
3232
for _, r := range results {
33-
fmt.Println(r.Name, r.Records, r.Takeover, r.Internal)
33+
fmt.Println(r.Name, r.Records, r.Takeover)
3434
}
3535
```
3636

37+
`Takeover` is a lead to check by hand: `dangling`, `provider:<name>` or `dangling:<name>` for a CNAME, or `dangling-ns` for a delegation to a name server that does not resolve. `Internal`{% include unreleased.html library="Internal" %} names the non-public scope (`private`, `loopback`, `link-local`, `cgnat`, `unspecified`) of an address a public name answers with, and is empty when every address is public.
38+
3739
Every zero value in `Config` takes the same default as the CLI, so `Config{Domain: "example.com"}` is a complete configuration that uses the bundled 5,000-word list.
3840

3941
## Run: a stream of events
@@ -81,15 +83,16 @@ The result is sorted and duplicate-free, and names that are not valid in DNS are
8183
| `Words` | `DefaultWords()` | Labels to try, or dotted paths such as `api.eu`. |
8284
| `Resolver` | `8.8.8.8:53` | Trusted server: `ip:port`, `tls://host`, or `https://host/path`. |
8385
| `ResolverPool` | none | Extra plain-UDP resolvers. Every hit is re-checked against `Resolver`. |
86+
| `RatePerResolver`{% include unreleased.html library="RatePerResolver" %} | unlimited | Queries per second to each `ResolverPool` member. `Rate` still caps the total, so the stricter limit wins. |
8487
| `Concurrency` | `100` | Workers looking up names at once. |
8588
| `Timeout` | `1s` | Bound on one lookup of one record type. |
8689
| `Attempts` | `1` | Tries per name. Only failures are retried, never NXDOMAIN. |
8790
| `Rate` | unlimited | Queries per second on the wire, counting every type, retry and probe. |
88-
| `Types` | `A`, `AAAA` | Record types. `CNAME` populates `Result.Takeover`. |
91+
| `Types` | `A`, `AAAA` | Record types: `A`, `AAAA`, `CNAME`, and on main also `NS`, `MX` and `TXT`. `CNAME` and `NS` populate `Result.Takeover`. |
8992
| `Recursive`, `Depth` | off, `1` | Enumerate again under each name found. |
9093
| `MaxQueries` | unlimited | Cap on candidate names tested. |
9194
| `MaxDuration`{% include unreleased.html library="MaxDuration" %} | unlimited | Time budget from the start of `Run`. Then no new names are tested and the rest are counted in `Stats.Skipped`, with `Stats.Expired` set. |
92-
| `AutoRate`{% include unreleased.html library="AutoRate" %} | false | When over a fifth of the last 200 lookups fail, halve the rate and keep going (a `NoticeRate` event says so), and raise it again once lookups succeed, instead of letting the reliability guard abort. `Stats.RateBackoffs` and `Stats.FinalRate` report it. |
95+
| `AutoRate`{% include unreleased.html library="AutoRate" %} | false | When over a fifth of the last 200 lookups fail, halve the rate and keep going (a `NoticeRate` event says so), and raise it again once lookups succeed. It halves up to six times and not below 5 per second; only when it can slow down no further does the reliability guard apply. `Stats.RateBackoffs` and `Stats.FinalRate` report it. |
9396
| `TakeoverProviders`{% include unreleased.html library="TakeoverProviders" %} | built-in list | Extra takeover-prone services (`{Suffix: ".example-cdn.net", Name: "example-cdn"}`) for `provider:` hints, added to the built-in list; a `Name` of `-` removes a suffix. `TakeoverProvidersOnly` uses them alone. |
9497
| `RetryInconclusive`{% include unreleased.html library="RetryInconclusive" %} | false | Once every candidate is tried, look up each name that timed out, was refused or failed once more against `Resolver`. Names it resolves are reported but not expanded by `Recursive`. `Stats.Retried` and `Stats.Recovered` count the pass; `Stats.Inconclusive` lists the names still without an answer. |
9598
| `Exclude` | none | Out-of-scope names and `*.parent` branches, never queried. |
@@ -100,7 +103,7 @@ The result is sorted and duplicate-free, and names that are not valid in DNS are
100103

101104
## Accounting
102105

103-
`Stats` puts each candidate name into exactly one outcome: `Found`, `NXDomain`, `Timeout`, `Refused`, `Other` or `WildcardFiltered`. Alongside are `QueriesSent`, `Skipped` (left untested by `MaxQueries`), `Excluded`, and the resolver-pool counters `PoolHits`, `Confirmed` and `Unconfirmed`. `Aborted` means the reliability guard stopped the scan, so the negatives mean nothing.
106+
`Stats` puts each candidate name into exactly one outcome: `Found`, `NXDomain`, `Timeout`, `Refused`, `Other` or `WildcardFiltered`. Alongside are `QueriesSent`, `Skipped` (left untested by `MaxQueries` or `MaxDuration`, with `Expired` set for the latter), `Excluded`, the result counters `Takeover` and `Internal`, and the resolver-pool counters `PoolHits`, `Confirmed` and `Unconfirmed`. `Aborted` means the reliability guard stopped the scan, so the negatives mean nothing. `Wildcard` and `WildcardFingerprint` describe a wildcard zone. `RetryInconclusive` fills `Retried`, `Recovered` and `Inconclusive` (the names still without an answer), and `AutoRate` fills `RateBackoffs` and `FinalRate`. `Total()` sums the outcomes.
104107

105108
## Testing your integration
106109

0 commit comments

Comments
 (0)