Skip to content

docs: update keepalive defaults, add default timeout config #63

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ankurs merged 4 commits into from
Apr 8, 2026
Merged

docs: update keepalive defaults, add default timeout config #63

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b804b98
docs: update keepalive defaults and document -1 opt-out
ankurs Apr 8, 2026
74a7594
fix: clarify -1 opt-out wording per review feedback
ankurs Apr 8, 2026
db0f018
fix: clarify disable examples per review feedback
ankurs Apr 8, 2026
047b46c
docs: add GRPC_SERVER_DEFAULT_TIMEOUT_IN_SECONDS to config reference
ankurs Apr 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 6 additions & 3 deletions config-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,7 @@ cfg := config.GetColdBrewConfig()
| `GRPC_MAX_RECV_MSG_SIZE` | int | `4194304` | Maximum receive message size in bytes (default: 4MB) |
| `DISABLE_VT_PROTOBUF` | bool | `false` | Disable [vtprotobuf](https://github.com/planetscale/vtprotobuf) marshaller for gRPC. See [vtprotobuf guide](/howto/vtproto) |
| `DISABLE_PROTO_VALIDATE` | bool | `false` | Disable [protovalidate](https://github.com/bufbuild/protovalidate) interceptor. When disabled, proto validation annotations are ignored |
| `GRPC_SERVER_DEFAULT_TIMEOUT_IN_SECONDS` | int | `60` | Default timeout for incoming unary gRPC requests without a deadline. Set to `0` to disable. Does not apply to stream RPCs |

## gRPC TLS

Expand All @@ -65,9 +66,11 @@ cfg := config.GetColdBrewConfig()

| Variable | Type | Default | Description |
|----------|------|---------|-------------|
| `GRPC_SERVER_MAX_CONNECTION_IDLE_IN_SECONDS` | int | `0` | Close idle connections after this duration (0 = disabled) |
| `GRPC_SERVER_MAX_CONNECTION_AGE_IN_SECONDS` | int | `0` | Maximum connection lifetime with ±10% jitter (0 = disabled) |
| `GRPC_SERVER_MAX_CONNECTION_AGE_GRACE_IN_SECONDS` | int | `0` | Grace period after max connection age before force-closing |
| `GRPC_SERVER_MAX_CONNECTION_IDLE_IN_SECONDS` | int | `300` | Close idle connections after this duration. Set to `-1` to disable this limit |
| `GRPC_SERVER_MAX_CONNECTION_AGE_IN_SECONDS` | int | `1800` | Maximum connection lifetime with ±10% jitter. Set to `-1` to disable this limit |
| `GRPC_SERVER_MAX_CONNECTION_AGE_GRACE_IN_SECONDS` | int | `30` | Grace period after max connection age before force-closing. Set to `-1` to disable this limit |

To allow connections to remain open indefinitely, set both `GRPC_SERVER_MAX_CONNECTION_IDLE_IN_SECONDS` and `GRPC_SERVER_MAX_CONNECTION_AGE_IN_SECONDS` to `-1`.

## HTTP Gateway

Expand Down
14 changes: 6 additions & 8 deletions howto/production.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -427,19 +427,17 @@ env:

### Connection keepalive

For services behind load balancers with idle connection timeouts, configure keepalive:
ColdBrew ships sane defaults for connection keepalive (idle: 300s, age: 1800s, grace: 30s). These ensure connections rotate for balanced load distribution and timely DNS updates. Override only if your service has specific requirements:

```yaml
env:
# Close connections idle for more than 5 minutes
# Override: close idle connections after 10 minutes instead of 5
- name: GRPC_SERVER_MAX_CONNECTION_IDLE_IN_SECONDS
value: "300"
# Force connection refresh every 30 minutes (with ±10% jitter)
value: "600"
# Override: force connection refresh every hour instead of 30 minutes
# Change to "-1" to disable the connection age limit entirely (not recommended)
- name: GRPC_SERVER_MAX_CONNECTION_AGE_IN_SECONDS
value: "1800"
# Allow 30s grace period for in-flight RPCs on aged connections
- name: GRPC_SERVER_MAX_CONNECTION_AGE_GRACE_IN_SECONDS
value: "30"
value: "3600"
```

## Production checklist
Expand Down
Loading