JakeChampion / JakeChampion/trafficserver

[audit][tests-docs] 49 registered configuration records are documented nowhere under doc/

Open
#58 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

area:tests-docs audit severity:medium
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.