kindred/silo-mod
1
1
Fork 0
Code Issues 7 Pull Requests Actions Packages Projects Releases Wiki Activity

Centralize hardcoded timing and timeout constants #31

New Issue
Open
opened 2026-02-16 17:01:20 +00:00 by forbes · 0 comments
forbes commented 2026-02-16 17:01:20 +00:00
Owner
Copy Link

Summary

Over 15 timing and timeout constants are scattered as magic numbers across 6 different files. These values control critical behavior (network timeouts, SSE reconnection strategy, UI responsiveness) but are invisible to operators and impossible to tune without modifying source code.

This issue focuses specifically on centralizing these constants. Once #29 (YAML config) lands, these can be further externalized, but even before that they should be collected into a single, well-documented location.

Inventory of Hardcoded Timing Constants

Network Timeouts

File Line Value Purpose
silo_commands.py ~188 timeout=10 /ready endpoint HTTP timeout
silo_commands.py ~2445 timeout=90 SSE stream connection timeout
silo_commands.py ~3899 _HTTP_TIMEOUT=10 Diagnostics HTTP timeout
silo_commands.py ~3900 _DNS_TIMEOUT=5 Diagnostics DNS timeout
schema_form.py ~279 timeout=5 Schema properties fetch timeout
schema_form.py ~301 timeout=5 Part number generation timeout

SSE Reconnection Strategy

File Line Value Purpose
silo_commands.py ~2373 _MAX_RETRIES = 10 Max reconnection attempts
silo_commands.py ~2374 _BASE_DELAY = 1 Initial backoff delay (seconds)
silo_commands.py ~2375 _MAX_DELAY = 60 Maximum backoff delay (seconds)

UI Timing

File Line Value Purpose
silo_commands.py ~2565 30000 (30s) Auth status refresh interval
silo_commands.py ~2570 60000 (60s) Relative timestamp refresh
silo_commands.py ~3660 60000 (60s) Start panel refresh interval
silo_start.py ~221 300 (300ms) Search debounce on start page
silo_start.py ~226 30000 (30s) Start page periodic refresh
schema_form.py ~247 500 (500ms) Part number preview debounce
open_search.py ~56 500 (500ms) Open-search debounce
InitGui.py ~120 2500 (2.5s) Silo overlay registration delay
InitGui.py ~147 500 (500ms) Startup URL handler delay

Problems

  1. Untunable: Operators in high-latency environments cannot increase timeouts without patching source.
  2. Inconsistent: Similar operations use different timeouts (e.g. schema fetch is 5s but ready check is 10s) without documented rationale.
  3. Hard to audit: No single place to review all timing behavior.
  4. Magic numbers: Values like 2500, 30000, 60000 appear without explanation of why those specific values were chosen.

Proposed Solution

Phase 1: Centralize into a constants module

Create freecad/silo_constants.py (or a _defaults section in the future config module):

# Network timeouts (seconds)
HTTP_TIMEOUT = 10
SCHEMA_FETCH_TIMEOUT = 5
SSE_STREAM_TIMEOUT = 90
DNS_TIMEOUT = 5

# SSE reconnection
SSE_MAX_RETRIES = 10
SSE_BASE_DELAY = 1   # seconds
SSE_MAX_DELAY = 60   # seconds

# UI timing (milliseconds)
DEBOUNCE_MS = 500
SEARCH_DEBOUNCE_MS = 300
AUTH_REFRESH_MS = 30_000
TIMESTAMP_REFRESH_MS = 60_000
PANEL_REFRESH_MS = 60_000
OVERLAY_DELAY_MS = 2_500
URL_HANDLER_DELAY_MS = 500

Phase 2: Replace all magic numbers

Update all 6 files to import from the constants module instead of using inline literals.

Phase 3: Wire into YAML config (depends on #29)

Once the YAML config system exists, these constants become the defaults that can be overridden via config.

Acceptance Criteria

  • All timing/timeout values are defined in a single module
  • No magic-number timeouts remain in silo_commands.py, schema_form.py, open_search.py, silo_start.py, or InitGui.py
  • Each constant has a descriptive name and unit comment
  • Existing behavior is preserved (same default values)
  • Constants are importable by other modules without circular dependencies
## Summary Over 15 timing and timeout constants are scattered as magic numbers across 6 different files. These values control critical behavior (network timeouts, SSE reconnection strategy, UI responsiveness) but are invisible to operators and impossible to tune without modifying source code. This issue focuses specifically on centralizing these constants. Once #29 (YAML config) lands, these can be further externalized, but even before that they should be collected into a single, well-documented location. ## Inventory of Hardcoded Timing Constants ### Network Timeouts | File | Line | Value | Purpose | |---|---|---|---| | silo_commands.py | ~188 | `timeout=10` | `/ready` endpoint HTTP timeout | | silo_commands.py | ~2445 | `timeout=90` | SSE stream connection timeout | | silo_commands.py | ~3899 | `_HTTP_TIMEOUT=10` | Diagnostics HTTP timeout | | silo_commands.py | ~3900 | `_DNS_TIMEOUT=5` | Diagnostics DNS timeout | | schema_form.py | ~279 | `timeout=5` | Schema properties fetch timeout | | schema_form.py | ~301 | `timeout=5` | Part number generation timeout | ### SSE Reconnection Strategy | File | Line | Value | Purpose | |---|---|---|---| | silo_commands.py | ~2373 | `_MAX_RETRIES = 10` | Max reconnection attempts | | silo_commands.py | ~2374 | `_BASE_DELAY = 1` | Initial backoff delay (seconds) | | silo_commands.py | ~2375 | `_MAX_DELAY = 60` | Maximum backoff delay (seconds) | ### UI Timing | File | Line | Value | Purpose | |---|---|---|---| | silo_commands.py | ~2565 | `30000` (30s) | Auth status refresh interval | | silo_commands.py | ~2570 | `60000` (60s) | Relative timestamp refresh | | silo_commands.py | ~3660 | `60000` (60s) | Start panel refresh interval | | silo_start.py | ~221 | `300` (300ms) | Search debounce on start page | | silo_start.py | ~226 | `30000` (30s) | Start page periodic refresh | | schema_form.py | ~247 | `500` (500ms) | Part number preview debounce | | open_search.py | ~56 | `500` (500ms) | Open-search debounce | | InitGui.py | ~120 | `2500` (2.5s) | Silo overlay registration delay | | InitGui.py | ~147 | `500` (500ms) | Startup URL handler delay | ## Problems 1. **Untunable**: Operators in high-latency environments cannot increase timeouts without patching source. 2. **Inconsistent**: Similar operations use different timeouts (e.g. schema fetch is 5s but ready check is 10s) without documented rationale. 3. **Hard to audit**: No single place to review all timing behavior. 4. **Magic numbers**: Values like `2500`, `30000`, `60000` appear without explanation of why those specific values were chosen. ## Proposed Solution ### Phase 1: Centralize into a constants module Create `freecad/silo_constants.py` (or a `_defaults` section in the future config module): ``` # Network timeouts (seconds) HTTP_TIMEOUT = 10 SCHEMA_FETCH_TIMEOUT = 5 SSE_STREAM_TIMEOUT = 90 DNS_TIMEOUT = 5 # SSE reconnection SSE_MAX_RETRIES = 10 SSE_BASE_DELAY = 1 # seconds SSE_MAX_DELAY = 60 # seconds # UI timing (milliseconds) DEBOUNCE_MS = 500 SEARCH_DEBOUNCE_MS = 300 AUTH_REFRESH_MS = 30_000 TIMESTAMP_REFRESH_MS = 60_000 PANEL_REFRESH_MS = 60_000 OVERLAY_DELAY_MS = 2_500 URL_HANDLER_DELAY_MS = 500 ``` ### Phase 2: Replace all magic numbers Update all 6 files to import from the constants module instead of using inline literals. ### Phase 3: Wire into YAML config (depends on #29) Once the YAML config system exists, these constants become the defaults that can be overridden via config. ## Acceptance Criteria - [ ] All timing/timeout values are defined in a single module - [ ] No magic-number timeouts remain in `silo_commands.py`, `schema_form.py`, `open_search.py`, `silo_start.py`, or `InitGui.py` - [ ] Each constant has a descriptive name and unit comment - [ ] Existing behavior is preserved (same default values) - [ ] Constants are importable by other modules without circular dependencies
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
Something isn't working
 debugging
Debugging and diagnostics
 enhancement
New feature or request
 priority:high
High priority
 ui
User interface
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
forbes
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: kindred/silo-mod#31
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?