docs: update keepalive defaults, add default timeout config

[ankurs]

Summary

Covers config reference and howto updates for two core changes being merged together:

Keepalive defaults (core#72)

• Updated GRPC_SERVER_MAX_CONNECTION_IDLE_IN_SECONDS default from 0 to 300
• Updated GRPC_SERVER_MAX_CONNECTION_AGE_IN_SECONDS default from 0 to 1800
• Updated GRPC_SERVER_MAX_CONNECTION_AGE_GRACE_IN_SECONDS default from 0 to 30
• Documented -1 as opt-out for infinite lifetime
• Updated production howto with sane-defaults messaging

Default timeout (core#73, interceptors#37)

• Added GRPC_SERVER_DEFAULT_TIMEOUT_IN_SECONDS (default: 60, 0 to disable) to config reference
• Applies to incoming unary gRPC requests without a deadline (including HTTP gateway path)

Test plan

• Config reference table renders correctly with new rows
• Production howto reads clearly with updated defaults

Summary by CodeRabbit

• Documentation
  • Added documentation for a new gRPC server timeout env var (default 60s; 0 disables; applies to unary RPCs)
  • Updated keepalive defaults and disable semantics (use -1 to disable; setting both idle and age to -1 keeps connections open indefinitely)
  • Clarified that ColdBrew provides default keepalive settings and updated production examples (idle/age example values changed; grace example removed)

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e3f49cb1-f24b-4361-9e46-c0671632dee1

📥 Commits

Reviewing files that changed from the base of the PR and between b804b98 and 047b46c.

📒 Files selected for processing (2)

• config-reference.md
• howto/production.md

✅ Files skipped from review due to trivial changes (1)

• howto/production.md

🚧 Files skipped from review as they are similar to previous changes (1)

• config-reference.md

---

📝 Walkthrough

Walkthrough

Added a new gRPC env var GRPC_SERVER_DEFAULT_TIMEOUT_IN_SECONDS (default 60; 0 disables; applies only to unary RPCs). Updated gRPC keepalive defaults and semantics: MAX_CONNECTION_IDLE → 300s (disable -1), MAX_CONNECTION_AGE → 1800s (disable -1), MAX_CONNECTION_AGE_GRACE → 30s (disable -1); documented that setting both idle and max age to -1 keeps connections open indefinitely. Production guidance updated with example overrides and disable instructions.

Changes

Cohort / File(s)	Summary
Config reference config-reference.md	Added GRPC_SERVER_DEFAULT_TIMEOUT_IN_SECONDS (default 60, 0 disables; unary RPCs only). Updated keepalive defaults and semantics: GRPC_SERVER_MAX_CONNECTION_IDLE_IN_SECONDS default 300 (use -1 to disable), GRPC_SERVER_MAX_CONNECTION_AGE_IN_SECONDS default 1800 (use -1 to disable), GRPC_SERVER_MAX_CONNECTION_AGE_GRACE_IN_SECONDS default 30 (use -1 to disable). Explicit note that both idle and age -1 allow indefinite connections.
Production how-to howto/production.md	Noted ColdBrew provides default keepalive settings (idle 300s, age 1800s, grace 30s). Updated example overrides: changed idle example from 300→600, age from 1800→3600, removed explicit grace example, and replaced jitter guidance with commented instruction to set GRPC_SERVER_MAX_CONNECTION_AGE_IN_SECONDS to "-1" to disable the age limit.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐇 I nibble docs beneath the moonlight,

Defaults aligned, timeouts set just right.
Sixty seconds for unary calls to start,
Keepalive tuned to steady the heart.
Hop on, connections—stay or depart! 🌱

🚥 Pre-merge checks | ✅ 3

✅ 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 accurately captures the main changes: updating keepalive defaults and adding default timeout configuration documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/keepalive-defaults

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[Copilot]

Pull request overview

Updates ColdBrew documentation to reflect new gRPC server connection keepalive defaults and documents -1 as an opt-out sentinel for disabling keepalive limits, aligning docs with the companion core change.

Changes:

• Update gRPC keepalive defaults in the configuration reference (idle 300s, age 1800s, grace 30s) and document -1 opt-out.
• Update the production guide to describe the new defaults and provide updated override examples (including a -1 disable example).

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
howto/production.md	Updates production guidance and YAML examples for keepalive defaults and overrides.
config-reference.md	Updates keepalive defaults and adds -1 sentinel documentation in the config table.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.