Skip to content

feat(timezone): runtime-registerable IANA aliases (env var + API)#464

Merged
wboayue merged 1 commit intov2-stablefrom
feat/timezone-registry-v2
Apr 25, 2026
Merged

feat(timezone): runtime-registerable IANA aliases (env var + API)#464
wboayue merged 1 commit intov2-stablefrom
feat/timezone-registry-v2

Conversation

@wboayue
Copy link
Copy Markdown
Owner

@wboayue wboayue commented Apr 25, 2026

Summary

  • Add register_timezone_alias(name, iana) and IBAPI_TIMEZONE_ALIASES env var so users can map gateway-supplied timezone strings without rebuilding the crate.
  • User-registered aliases take precedence over the built-in TIMEZONE_ALIASES table — works for both new entries and overrides.
  • Update the unsupported-timezone error message to point at both options so users discover the fix on the first hit.

Why

IB Gateway emits a free-form timezone string from the host OS locale (e.g. China Standard Time, Romance Standard Time, GB2312 mojibake). When the gateway sends a label not in our built-in table, the connection fails. Today the only fix is a new release with the alias added — slow for users and high-touch for maintainers.

Design

  • static TIMEZONE_REGISTRY: LazyLock<Mutex<HashMap<String, String>>> seeded once from the env var (mirrors the pattern at src/stubs.rs:40).
  • Lookup precedence: user registry → built-in TIMEZONE_ALIASES → mojibake heuristic → time_tz passthrough.
  • Env-var format: name=iana;name=iana with whitespace trimmed; malformed entries are warned and skipped (env-var typos should not kill connection setup).
  • Logs a debug! line on registry hit so users can verify with RUST_LOG=ibapi::common::timezone=debug that their alias is firing.

Out of scope (follow-up)

  • src/market_data/historical/common/decoders/mod.rsparse_time_zone panics on unknown names. Inherits the registry behavior, but the panic itself is a separate bug worth its own PR.

Test plan

  • cargo +1.93.0 clippy --all-targets -- -D warnings
  • cargo +1.93.0 clippy --all-targets --features sync -- -D warnings
  • cargo +1.93.0 clippy --all-features
  • cargo +1.93.0 test --features sync (180 passed)
  • cargo +1.93.0 test --features async (105 passed)
  • 10 new timezone unit tests cover registry precedence, env-var parsing (basic, malformed, whitespace, empty, empty-sides), and the public register_timezone_alias smoke path.
  • test_parse_connection_time_unknown_timezone_errors extended to assert the error message mentions register_timezone_alias and IBAPI_TIMEZONE_ALIASES.
  • Manual smoke against a live gateway with a synthetic env var.

Add `register_timezone_alias(name, iana)` and `IBAPI_TIMEZONE_ALIASES`
env var so users can map gateway-supplied timezone strings without
rebuilding. User entries take precedence over the built-in table.

Update the unsupported-timezone error to mention both options so users
discover the fix on the first hit.
@wboayue wboayue merged commit 43b3059 into v2-stable Apr 25, 2026
3 checks passed
@wboayue wboayue deleted the feat/timezone-registry-v2 branch April 25, 2026 20:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant