modelcontextprotocol/experimental-ext-triggers-events
Watch
1
0
Fork
You've already forked experimental-ext-triggers-events
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add recommended TTL grant range for webhook subscriptions

Browse source 
Adds guidance that finite grants of a few minutes up to about a day cover
most deployments, framed by the asymmetric costs (refresh traffic scales as
O(1/TTL), storage and reclamation as O(TTL)), with no-expiry as the right
choice beyond a day and minutes-to-an-hour caps for short-lived subscribers.
This commit is contained in:
Peter Alexander 2026-06-15 12:41:43 +01:00
commit 6967f2ba30
No known key found for this signature in database
1 changed files with 2 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/design-sketch-proposal.md
View file

@ -365,6 +365,8 @@ Every webhook subscription has a lifetime negotiated at subscribe time: the clie
- `refreshBefore` (response) is the grant. It SHOULD be less than or equal to the suggestion — the client asked for what it can commit to refreshing, and granting longer risks the server delivering to an endpoint past the client's expected lifetime. The one sanctioned exception is a server-side floor: a server MAY clamp an impractically short suggestion up to its minimum TTL to protect itself from refresh storms. Clamping in either direction is self-announcing — the client reads the granted `refreshBefore` and schedules its refresh loop from that, so a clamped grant is not an error and there is no rejection path for TTL values.
- `refreshBefore: null` grants **no expiry**: the subscription persists until `events/unsubscribe` or server-initiated termination. A server MUST NOT return `null` unless the client suggested `ttlMs: null` — no expiry exceeds every finite suggestion. A server unwilling to grant it simply returns a finite `refreshBefore`, which the client treats like any other grant.
**Recommended grants.** For finite TTLs, grants from a few minutes up to about a day cover most deployments. The trade-off is asymmetric: the cost of a short TTL is refresh traffic, which scales as O(1/TTL) and is negligible for any reasonable value, while the cost of a long TTL is subscription storage and slower reclamation of abandoned subscriptions, which scales as O(TTL). Refreshing once a day is not a meaningful burden on clients, and beyond a day the marginal saving in refresh traffic is close to zero while the retention burden keeps growing — a server wanting to grant more than that should usually be granting no expiry and accepting the obligations below, rather than stretching a finite TTL. Servers expecting only short-lived subscribers (e.g., a coding agent following a single CI run) can reasonably cap grants at minutes to an hour; the clamp-up floor described above protects them from refresh storms.
**TTL is the server's resource-control knob.** A server that wants refresh-driven cleanup and in-memory soft state grants short TTLs. A server that grants long TTLs is choosing to hold subscription state for that long, and should hold it durably enough to honour the grant. There is no sharp boundary to defend here: a one-year TTL is, in every practical sense, unlimited, and excluding `null` from the protocol would only invite "999 years." Offering no expiry explicitly lets the spec attach the real obligations to it. A server that grants no expiry accepts that:
- the client is not expected to refresh or unsubscribe, ever — keeping the subscription alive is now the server's job, not the client's;