feat: client refresh rate

[ALPAC-4]

Summary by CodeRabbit

• New Features

  • Added clientRefreshRate configuration (CLIENT_REFRESH_RATE env var) to control how often clients are considered for update (default: 1/3 of trusting period).
  • Worker processes now honor the clientRefreshRate to adjust client refresh behavior.

• Documentation

  • README updated with CLIENT_REFRESH_RATE description and default behavior.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

A new configurable clientRefreshRate (env: CLIENT_REFRESH_RATE) is added, read into runtime config, passed into WalletWorker instances, and used by ClientController.getClientsToUpdate to compute client update thresholds. getClient now awaits addClient when creating missing clients.

Changes

Cohort / File(s)	Summary
Docs README.md	Documented new CLIENT_REFRESH_RATE environment variable and default behavior.
Config Loader src/lib/config.ts	Read CLIENT_REFRESH_RATE from environment; expose optional clientRefreshRate?: number on Config; merge env value when present.
Client DB Controller src/db/controller/client.ts	getClient now awaits addClient to return a resolved ClientTable; getClientsToUpdate signature extended to (..., clientRefreshRate?: number) and uses it (default 0.333) to derive update thresholds instead of a fixed 0.666.
Workers (init & impl) src/workers/index.ts, src/workers/wallet.ts	WalletWorker constructor gains optional clientRefreshRate parameter; index.ts passes config.clientRefreshRate into each WalletWorker; wallet.ts forwards the value to ClientController.getClientsToUpdate.

sequenceDiagram
  autonumber
  participant Config as Config Loader
  participant Wallet as WalletWorker
  participant Controller as ClientController
  participant DB as Client DB

  rect rgb(240,248,255)
    Note over Config,Wallet: Startup / Worker init
    Config->>Wallet: provide clientRefreshRate
  end

  rect rgb(245,255,240)
    Note over Wallet,Controller: Periodic client refresh flow
    Wallet->>Controller: getClientsToUpdate(chainId, peers, clientRefreshRate)
    Controller->>DB: query clients and lastUpdated
    alt missing client
      DB-->>Controller: no client found
      Controller->>DB: addClient(...)  -- awaited
      DB-->>Controller: new client record
    end
    Controller-->>Wallet: list of clients needing update (based on clientRefreshRate)
  end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐇 A little rate hops into the stack,
Carried from env to worker's pack,
Clients wake when their turn is due,
No more hardcode—just a setting true.

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: client refresh rate' accurately summarizes the main change: introducing a new client refresh rate configuration option across the codebase.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

• 📝 Generate docstrings

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

Fix all issues with AI Agents 🤖

In @src/lib/config.ts:
- Around line 47-48: The env CLIENT_REFRESH_RATE is parsed into
envConfig.clientRefreshRate but mergeConfigs does not include that field; update
mergeConfigs to copy envConfig.clientRefreshRate into the resulting config
(respecting existing config.clientRefreshRate if present), referencing
envConfig.clientRefreshRate and the mergeConfigs function so the environment
override is applied to the final config.

🧹 Nitpick comments (1)

README.md (1)

56-56: Clarify the example value vs. default.

The example shows clientRefreshRate: 0.1, but Line 121 documents the default as 1/3 (≈0.333). This inconsistency may confuse users. Consider either using the default value in the example or adding a comment explaining why a non-default value is shown.

Suggested clarification

   "rpcRequestTimeout": 5000,
-  "clientRefreshRate": 0.1,
+  "clientRefreshRate": 0.333,  // Default: 1/3 of trusting period
   "chains": [

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Cache: Disabled due to data retention organization setting

Knowledge base: Disabled due to Reviews -> Disable Knowledge Base setting

📥 Commits

Reviewing files that changed from the base of the PR and between db86db2 and f2b9f22.

📒 Files selected for processing (5)

• README.md
• src/db/controller/client.ts
• src/lib/config.ts
• src/workers/index.ts
• src/workers/wallet.ts

🧰 Additional context used

🧬 Code graph analysis (2)

src/workers/wallet.ts (1)

src/db/controller/packet.ts (1)

• PacketFilter (800-805)

src/workers/index.ts (1)

src/lib/config.ts (1)

• config (308-308)

🔇 Additional comments (6)

src/workers/wallet.ts (2)

40-41: LGTM!

The clientRefreshRate parameter is properly added to the constructor and threaded through to the client update logic.

---

226-230: LGTM!

The clientRefreshRate is correctly passed to getClientsToUpdate, enabling configurable refresh behavior.

src/lib/config.ts (1)

319-319: LGTM!

The clientRefreshRate field is correctly added to the Config interface as an optional number.

src/db/controller/client.ts (2)

139-139: Good fix for async consistency.

Adding await ensures getClient consistently returns ClientTable rather than potentially returning Promise<ClientTable>. This improves type safety and prevents runtime issues.

---

144-145: LGTM!

The clientRefreshRate parameter is properly integrated with a sensible default of 0.333 (1/3 of the trusting period). The threshold calculation correctly applies the rate to determine when clients need updates.

Also applies to: 170-172

src/workers/index.ts (1)

140-141: LGTM!

The config.clientRefreshRate is correctly passed to the WalletWorker constructor. Note that this currently only works when set in config.json due to the missing merge logic in src/lib/config.ts (see comment on that file).

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

src/lib/config.ts (1)

47-48: Consider adding validation for numeric environment variables.

The code uses Number() to parse CLIENT_REFRESH_RATE, which returns NaN for invalid input. While this follows the existing pattern for other numeric environment variables in this file, adding validation could prevent silent failures, especially for rate values that likely need to be positive.

🔎 Example validation approach

 if (env.CLIENT_REFRESH_RATE)
-  envConfig.clientRefreshRate = Number(env.CLIENT_REFRESH_RATE)
+  const rate = Number(env.CLIENT_REFRESH_RATE)
+  if (!isNaN(rate) && rate > 0) {
+    envConfig.clientRefreshRate = rate
+  } else {
+    throw new Error('CLIENT_REFRESH_RATE must be a positive number')
+  }

Note: This same validation pattern could be applied to other numeric environment variables for consistency.

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Cache: Disabled due to data retention organization setting

Knowledge base: Disabled due to Reviews -> Disable Knowledge Base setting

📥 Commits

Reviewing files that changed from the base of the PR and between f2b9f22 and a6cf61a.

📒 Files selected for processing (1)

• src/lib/config.ts

🔇 Additional comments (2)

src/lib/config.ts (2)

282-283: Previous critical issue resolved – merge logic now present.

The merge logic for clientRefreshRate is now correctly implemented, resolving the critical issue flagged in the previous review. The implementation follows the same pattern as other optional configuration properties and ensures that environment variables are properly merged into the final config.

---

321-321: LGTM!

The type definition is correct. Marking clientRefreshRate as optional is appropriate, and the number type aligns with the usage pattern.