[TexasCoding]

Closes #300.

Four KalshiConfig fields had docstrings but were missing from the at-a-glance reference table in docs/configuration.md:

• total_timeout — wall-clock cap across all retries (Retry: cap total wall-clock budget; no per-request deadline today (~180s worst case) #193)
• ws_ping_interval — heartbeat tuning
• ws_close_timeout — clean-close grace
• allow_unknown_host — host allowlist gate (Config: unknown base_url host only warns — typo silently signs to attacker #250, v2.5)

Also tightened the URL validation prose bullet so it states the new default-reject behavior and points readers at the table row instead of repeating the description.

No code touched.

Part of the post-v2.5 audit closure (Wave W0 docs).

[claude]

Code Review — PR #304

Overview: Documentation-only PR that adds 4 missing KalshiConfig fields to the reference table in docs/configuration.md and corrects the URL validation prose to reflect the v2.5 default-reject behavior. No code is touched.

---

Accuracy ✅

All defaults have been verified against kalshi/config.py:

Field	Doc default	Code default
total_timeout	None	None ✅
ws_ping_interval	20.0	20.0 ✅
ws_close_timeout	5.0	5.0 ✅
allow_unknown_host	False	False ✅

The URL validation correction ("Unknown hosts log a warning" → "Unknown hosts are rejected by default") matches the actual code path at config.py:182 which raises rather than warns.

---

Issues

1. total_timeout is misplaced in the table (minor)

In config.py, the field declaration order is retry_max_delay → total_timeout → extra_headers. total_timeout is a sibling of the retry/timeout controls and is conceptually grouped with them. Appending it after limits puts it far from the related timeout, max_retries, and retry_max_delay rows, which could cause readers to miss it when tuning retry behavior.

Suggestion: move the total_timeout row to immediately after retry_max_delay in the table.

2. Vague opt-in wording in allow_unknown_host (minor)

Opt out via the field or KALSHI_ALLOW_UNKNOWN_HOST=1

"Opt out via the field" is ambiguous — a reader skimming the table doesn't know which value to set. Suggest:

Set `allow_unknown_host=True` or `KALSHI_ALLOW_UNKNOWN_HOST=1` to allow it.

3. Quick-reference code block not updated (informational)

The code block at the top of the doc still doesn't include the 4 new fields. This is probably intentional (it's meant as a common-case example, not exhaustive), but if someone looks there first they won't find allow_unknown_host. At a minimum, a comment like # allow_unknown_host=True for the mock-server use-case could be worth adding when targeting test infrastructure — but this is low priority.

---

Summary

The core content is correct — defaults verified, rejection behavior accurately documented. Two minor wording/ordering nits worth addressing before merge, but nothing blocking.

[TexasCoding]

Thanks @claude. Addressed both nits in 2-line follow-up:

• total_timeout moved up next to retry_max_delay so retry knobs stay grouped.
• allow_unknown_host wording made explicit ("Set allow_unknown_host=True …").

Skipping nit #3 (extending the quick-reference code block). That block is intentionally a common-case example, not exhaustive — adding a defensive allow_unknown_host=True next to it would invert its purpose. The new table row + URL-validation bullet are the canonical discovery paths.

[claude]

Claude finished @TexasCoding's task in 41s —— View job

---

Re-review — PR #304

• Read current state of docs/configuration.md
• Confirm total_timeout placement (next to retry_max_delay)
• Confirm allow_unknown_host wording is explicit
• Post final review verdict

---

Both nits from the first pass are confirmed resolved:

Nit 1 — total_timeout placement ✅
total_timeout now sits at table row 6, immediately after retry_max_delay (row 5). Retry knobs are grouped together.

Nit 2 — allow_unknown_host wording ✅
The description now reads: "Set allow_unknown_host=True or KALSHI_ALLOW_UNKNOWN_HOST=1 to allow it (mock server, proxy, alternate region)." — no ambiguity about what value to set.

Nit 3 — Quick-reference code block (intentionally skipped)
The reasoning holds: that block is a common-case example, not an exhaustive inventory. The table row and URL-validation bullet are the canonical discovery paths. No objection.

LGTM. The doc is accurate, the retry knobs stay grouped, and the host-allow opt-in is now unambiguous. Ready to merge.

[claude]

Code Review — PR #304: docs(configuration): add missing KalshiConfig fields

Overview: Documentation-only patch that adds four fields (total_timeout, ws_ping_interval, ws_close_timeout, allow_unknown_host) to the docs/configuration.md reference table, and tightens the URL-validation prose to reflect the v2.5.0 default-reject behavior for unknown hosts. No code is touched.

---

Accuracy (verified against kalshi/config.py)

All four documented defaults match the dataclass exactly:

Field	Doc says	Code says
total_timeout	None	float | None = None ✅
ws_ping_interval	20.0	float = 20.0 ✅
ws_close_timeout	5.0	float = 5.0 ✅
allow_unknown_host	False	bool = False ✅

Descriptions are also accurate. The allow_unknown_host row correctly captures both the per-instance flag and the KALSHI_ALLOW_UNKNOWN_HOST=1 env-var escape hatch.

---

Suggestions

Minor — table row ordering: ws_ping_interval and ws_close_timeout are placed after limits in the table, but in the dataclass they appear before rest_json_loads / ws_json_loads / ws_json_dumps. The pre-existing table already had those three rows in a different order than the dataclass, so this isn't a regression you introduced. If you want to fix the full ordering in a follow-up (or squash it in here), the correct dataclass order after http2 is:

limits → ws_ping_interval → ws_close_timeout → rest_json_loads → ws_json_loads → ws_json_dumps → allow_unknown_host

Up to you — the current placement is readable and not wrong.

Nit — quick-reference code block not updated: The ## Quick reference snippet at the top still shows only http2 and limits as the "advanced" options. It doesn't need to show all four new fields (they're less commonly set), but total_timeout is probably the most user-facing of the four given the retry docs link. Consider adding a comment line there if you think users will look for it. Not a blocker.

---

URL-validation prose

The rewrite from:

"Unknown hosts log a warning…"

to:

"Unknown hosts are rejected by default; opt in via allow_unknown_host… or KALSHI_ALLOW_UNKNOWN_HOST=1."

is accurate and better. The old text described the pre-v2.5 behavior; this one describes current behavior and cross-links to the table row.

---

Verdict

Accurate, minimal, and directly closes #300. The ordering note above is cosmetic and can be addressed separately. Happy to approve as-is.

[TexasCoding]

Round-2 review notes:

• Full dataclass-order alignment: cosmetic and pre-existing per the bot itself. Tracking as a separate doc polish if it ever rises in priority — not in scope for docs(configuration): reference table missing total_timeout, ws_ping_interval, ws_close_timeout, allow_unknown_host #300.
• Quick-reference code block: declined for the same reason as round 1 — that snippet is intentionally a common-case example, not exhaustive.

Merging.