From d45f4ea5ccbcd173f76f93f35a165aea9b508f7d Mon Sep 17 00:00:00 2001
From: Exanlv <exan@landviz.nl>
Date: Mon, 9 Mar 2026 10:19:19 +0100
Subject: [PATCH] Make heartbeat acknowledgement timer configurable

---
 src/Gateway/Connection.php | 24 ++++++++++++++++++++++--
 1 file changed, 22 insertions(+), 2 deletions(-)

diff --git a/src/Gateway/Connection.php b/src/Gateway/Connection.php
index d3a66a5..957b384 100644
--- a/src/Gateway/Connection.php
+++ b/src/Gateway/Connection.php
@@ -43,7 +43,7 @@ class Connection implements ConnectionInterface
 
     private const QUERY_DATA = ['v' => self::DISCORD_VERSION];
 
-    private const HEARTBEAT_ACK_TIMEOUT = 2.5;
+    private static float $heartbeatAckTimeout = 5;
 
     private ?int $sequence = null;
 
@@ -57,6 +57,26 @@ class Connection implements ConnectionInterface
 
     private ShardInterface $shard;
 
+    /**
+     * Change how long to wait for a heartbeat acknowledgement from Discords gateway. This essentially changes how much
+     * wiggle room your websocket connection allows for.
+     *
+     * If you're not sure you need to change this value, you should probably leave it at the default. Lowering the value
+     * is not recommended, as this will decrease stability.
+     *
+     * This function should be called at the start of your application. Before a connection is established. Otherwise
+     * this change may only take effect after the first connection resume/restart.
+     */
+    public static function setHeartbeatAckTimeout(float $timeout): void
+    {
+        self::$heartbeatAckTimeout = $timeout;
+    }
+
+    public static function getHeartbeatAckTimeout(): float
+    {
+        return self::$heartbeatAckTimeout;
+    }
+
     public function __construct(
         private LoopInterface $loop,
         private string $token,
@@ -232,7 +252,7 @@ public function sendHeartbeat(): void
 
     private function expectHeartbeatAcknowledgement(): void
     {
-        $this->unacknowledgedHeartbeatTimer = $this->loop->addTimer(self::HEARTBEAT_ACK_TIMEOUT, function () {
+        $this->unacknowledgedHeartbeatTimer = $this->loop->addTimer(self::$heartbeatAckTimeout, function () {
             $this->meta->emit(MetaEvents::UNACKNOWLEDGED_HEARTBEAT, [$this, $this->logger]);
         });
     }