Audit and validate default values across all 124 CLI flags and config model

Open
  • Is something wrong?
#13 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
30/100
Issue type
Refactor
Clarity
Clearly specified
Activity status
Stale
Tech stack
python
Domain
backend-api-design, cli, security, testing-qa

Research direction

Start by comparing docs/review/conformance/flag_contracts.json with defaults in src/tigrcorn/constants.py, src/tigrcorn/config/model.py, and src/tigrcorn/config/normalize.py; trace CLI defaults in src/tigrcorn/cli.py. Review the P1 security-sensitive values first, then record each flag’s effective default, risk, verdict, and target in an audit artifact. Done means all 124 contract rows have reviewed defaults and the proposed conformance test and help updates cover the documented acceptance criteria.

Written by the indexing model from the issue text.

Description

Background

PR #12 (946410e) fixed a bug where --app-dir defaulted to None, causing the CWD not to appear on sys.path and breaking the most basic usage pattern (tigrcorn app:app). This was not unique to --app-dir — it exposed that defaults are defined across four independent layers with no systematic validation that the effective default for each flag is correct, safe, and documented consistently.

Layer File Role
Constants src/tigrcorn/constants.py 30+ DEFAULT_* canonical values
Model src/tigrcorn/config/model.py Dataclass field defaults (sometimes None, sometimes a constant)
CLI src/tigrcorn/cli.py Argparse defaults (almost universally None by design)
Normalize src/tigrcorn/config/normalize.py Late-applied defaults during normalize_config

The existing flag_contracts.json records a "default" field per contract row but does not track whether that default has been reviewed for correctness or safety.

Goals

  1. Enumerate every default value produced by ServerConfig() and every normalization-time override.
  2. Evaluate each default against three criteria:
Criteria Question
Correctness Does the zero-config default produce expected behavior?
Safety Does the default expose unnecessary attack surface?
Consistency Is the effective default the same via CLI, config file, env var, and Python API?
  1. Set target behavior for any default that fails a criterion.
  2. Track review progress at the flag-contract level.

Scope

All 124 public flags in flag_contracts.json plus internal defaults that affect runtime behavior (e.g., quic_secret, normalization-time backfills).

P1 — Security-sensitive defaults (review first)

  • quic_secret=b"tigrcorn-quic-shared-secret" — Require explicit config or generate random secret per process
  • connect_policy="relay" — Evaluate changing to "deny"
  • early_data_policy="allow" — Evaluate changing to "deny"
  • server_header=b"tigrcorn" — Decide: keep (convention) or default off (hardening)
Default Config Path Risk Target
quic_secret=b"tigrcorn-quic-shared-secret" constants.py:37 Hardcoded public secret for QUIC retry tokens — trivially spoofable Require explicit config or generate random secret per process
connect_policy="relay" http.connect_policy HTTP CONNECT relayed with no allowlist — open relay risk Evaluate changing to "deny"
early_data_policy="allow" quic.early_data_policy 0-RTT accepted by default — replay attack surface (RFC 8470) Evaluate changing to "deny"
server_header=b"tigrcorn" proxy.server_header Reveals server technology by default Decide: keep (convention) or default off (hardening)

P2 — Correctness / surprise defaults

  • app_dir=None — Verify PR #12 fix is sufficient, contract row accurate
  • static.route defaults to "/" when mount set — Require explicit route or default to mount basename
  • worker_class auto-upgrade — Emit log warning or document in help text
  • Legacy runtime alias — Emit deprecation warning
Default Config Path Risk Target
app_dir=None app.app_dir Fixed in PR #12 with CWD fallback Verify fix is sufficient, contract row accurate
static.route defaults to "/" when mount set static.route Shadows all app routes if --static-path-route omitted Require explicit route or default to mount basename
worker_class auto-upgrade process.worker_class Silently changes "local" to "process" when workers > 1 Emit log warning or document in help text
Legacy runtime alias process.runtime --worker-class asyncio silently remaps Emit deprecation warning

P3 — Normalization-time backfill audit

Values that are None in the model but replaced in normalize_config. Config introspection before normalization shows None while runtime uses a different value.

  • http2_max_concurrent_streams — model None, normalized to 128
  • http2_max_headers_size — model None, normalized to max_header_size
  • http2_max_frame_size — model None, normalized to 16384
  • http2_initial_connection_window_size — model 65535, silently clamps to max(65535, user_value)
  • http2_initial_stream_window_size — model 65535, normalize fallback
  • http1_buffer_size — model constant, or 65_536 fallback
  • http1_keep_alive — model True, True if None path
  • websocket.max_queue — model 32, or 32 fallback
Field Model Default Normalized To
http2_max_concurrent_streams None 128
http2_max_headers_size None max_header_size
http2_max_frame_size None 16384
http2_initial_connection_window_size 65535 max(65535, user_value) — silently clamps
http2_initial_stream_window_size 65535 Normalize fallback
http1_buffer_size Constant or 65_536 fallback
http1_keep_alive True True if None path
websocket.max_queue 32 or 32 fallback

Target: Move effective defaults into model dataclass fields (eliminate None-then-backfill), or document why late resolution is necessary and add test assertions.

P4 — Flag-pair three-state documentation

These flags use _add_flag_pair creating True/False/None three-state, but help text only describes two states.

  • --access-log / --no-access-log — effective default: True
  • --date-header / --no-date-header — effective default: True
  • --use-colors / --no-use-colors — effective default: None (auto-detect)
  • --http1-keep-alive / --no-http1-keep-alive — effective default: True
  • --http2-adaptive-window / --no-http2-adaptive-window — effective default: False
  • --static-path-dir-to-file / --no-static-path-dir-to-file — effective default: True
  • --alt-svc-auto / --no-alt-svc-auto — effective default: False
Flag pair Argparse Default Effective Default
--access-log / --no-access-log None True
--date-header / --no-date-header None True
--use-colors / --no-use-colors None None (auto-detect)
--http1-keep-alive / --no-http1-keep-alive None True
--http2-adaptive-window / --no-http2-adaptive-window None False
--static-path-dir-to-file / --no-static-path-dir-to-file None True
--alt-svc-auto / --no-alt-svc-auto None False

Target: Ensure help text documents effective defaults. Add conformance test matching flag_contracts.json values.

Proposed deliverables

# Deliverable Description
1 Audit artifact One row per flag: contract_id, model_default, normalize_effective, documented_default, matches, risk_tier, verdict, target_value
2 Code changes For verdict "change": update constants.py, model.py, normalize.py, flag_contracts.json, and tests
3 Conformance test Parametrized test asserting default_config() post-normalization matches flag_contracts.json "default" per "config_path"
4 Doc updates Help text for any flag whose default changes or three-state semantics are undocumented

Acceptance criteria

  • Every flag_contracts.json row has a reviewed "default" matching post-normalization ServerConfig
  • P1 (security) defaults have explicit verdict with rationale
  • Parametrized conformance test passes green
  • No normalization-time backfill disagrees with documented default

References

  • PR #12 (946410e) — Fix CWD app import fallback and add app-load claims
  • docs/review/conformance/flag_contracts.json (124 contract rows)
  • docs/review/conformance/app_load_claims.json (CWD import claims)
  • src/tigrcorn/constants.py, src/tigrcorn/config/model.py, src/tigrcorn/config/normalize.py
Dominant language
Python
Stars
3
Forks
3
Avg merge
7h 59m
Merged PRs (30d)
8

Getting set up

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.

More from tigrbl/tigrcorn

All issues in tigrbl/tigrcorn

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.