JakeChampion / JakeChampion/trafficserver
[audit][tests-docs] 49 registered configuration records are documented nowhere under doc/
Nobody has claimed this yet.
- Dominant language
- C++
- Stars
- 0
- Forks
- 0
- Avg merge
- 8h 2m
- Merged PRs (30d)
- 21
Description
Severity: medium · Category: docs
Location: src/records/RecordsConfig.cc:1313
What's wrong
Comparing all RECT_CONFIG names in src/records/RecordsConfig.cc (562 unique) against every file under doc/ finds 49 registered records with zero documentation anywhere, including security-relevant proxy.config.plugin.load_elevated (RecordsConfig.cc:1313, RECA_READ_ONLY), operational knobs like proxy.config.http.per_server.connection.metric_enabled/metric_prefix, proxy.config.cache.ram_cache.compress_percent, proxy.config.hostdb.migrate_on_demand, proxy.config.http.referer_filter/referer_default_redirect/referer_format_redirect (RecordsConfig.cc:429), and the whole HTTP/3 tuning family (proxy.config.http3.header_table_size, max_field_section_size, max_settings, qpack_blocked_streams at RecordsConfig.cc:1422, num_placeholders). Users cannot discover or safely tune any of these; several (e.g. the http3 group) are for a headline v10 feature.
Evidence
src/records/RecordsConfig.cc:1313 '{RECT_CONFIG, "proxy.config.plugin.load_elevated", RECD_INT, "0", ..., RECA_READ_ONLY}'
// 'grep -r proxy.config.plugin.load_elevated doc/' returns nothing; same for 48 others
// (full list from comm(1) diff of extracted names, e.g. proxy.config.http3.qpack_blocked_streams at RecordsConfig.cc:1422).
Suggested fix
Triage the 49-record list: document the intentionally supported ones in records.yaml.en.rst, and delete truly dead registrations. Add the same doc-vs-RecordsConfig CI cross-check suggested in the defaults-drift issue to keep the sets in sync.
Filed from an automated multi-lens codebase audit. Full report: CODEBASE_AUDIT.md / audit-report.html on branch claude/codebase-audit-review-9nw7vz.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with src/records/RecordsConfig.cc, especially the entries around lines 1313 and 1422, and compare the 49-record list against records.yaml.en.rst and the other files under doc/. Triage each registration as supported or dead: supported records should be documented, dead ones removed, and the doc-vs-RecordsConfig CI cross-check added as described. Use the reported grep/comm comparison to verify that the sets stay synchronized.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cpp
- Domain
- backend, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100