heartbeatIntervalMs missing from ApolloServerPluginSubscriptionCallback options

[mario-jerkovic]

Issue Description

Apollo Server docs for ApolloServerPluginSubscriptionCallback mention a configurable
heartbeatIntervalMs, but the current TypeScript interface does not expose this option.
As a result, users cannot configure heartbeat behavior in a supported or type-safe way.

Docs reference:
https://github.com/apollographql/apollo-server/blob/main/docs/source/api/plugin/subscription-callback.mdx#heartbeatintervalms

HTTP-callback subscriptions are sensitive to timing and latency between the router/gateway
and the subgraph.

Without a supported way to configure the subgraph’s heartbeat interval:

• we cannot compensate for event-loop jitter or network latency
• valid subscriptions may be terminated despite healthy communication

Link to Reproduction

https://github.com/mario-jerkovic/apollo-server-subscription-callback-plugin-issue

Reproduction Steps

Run:

yarn install
yarn build

Actual tsc fails with and error

error TS2353: Object literal may only specify known properties, and 'heartbeatIntervalMs' does not exist in type 'ApolloServerPluginSubscriptionCallbackOptions'.

[bnjjj]

You're correct @mario-jerkovic this option should not be documented because it doesn't exist. If you want to specify the heartbeat interval you have to do it at the router config level as documented here cf heartbeat_interval config.

[mario-jerkovic]

You're correct @mario-jerkovic this option should not be documented because it doesn't exist. If you want to specify the heartbeat interval you have to do it at the router config level as documented here cf heartbeat_interval config.

Thanks @bnjjj for the clarification.

One follow-up question about heartbeat timing and jitter:

Since the router passes heartbeatIntervalMs to the subgraph as the expected heartbeat period, and Apollo’s callback plugin schedules heartbeats using setInterval(heartbeatIntervalMs), does the router internally apply any jitter tolerance or grace window when enforcing the heartbeat timeout?

In practice, I’m currently encountering cases where:

• the subgraph successfully sends check heartbeats, and
• the router responds to them,
  but the subscription is still terminated shortly after with an “invalid subscription ID” / timeout behavior.

So concretely:

• If a heartbeat arrives slightly after heartbeatIntervalMs due to event-loop or scheduling jitter, will the router still consider the subscription healthy?
• Or is the interval treated as a strict deadline (single late heartbeat ⇒ terminate)?

I’m asking because when both sides use the same interval value, exact-interval scheduling plus real-world jitter can cause race conditions unless the router compensates for this internally.