Add keepalive support

[rlerdorf]

Add SSH keepalive support via libssh2

Closes #79 (replaces the approach, not the code)

Problem

Long-lived SSH connections can be silently dropped by firewalls or NAT
devices when idle. There was no way to configure keepalives from PHP.

PR #79 proposed a global php.ini setting using raw SO_KEEPALIVE
socket options. That approach is Linux-only, and applies to all connections.

Fix

Expose the existing libssh2 keepalive API as two new per-connection
functions:

ssh2_keepalive_config(resource $session, bool $want_reply, int $interval)

Configures how often keepalive messages are sent. $interval is the
number of seconds that can pass without any I/O before a keepalive is
sent. Use 0 (the default) to disable. $want_reply controls whether
the server is expected to respond.

ssh2_keepalive_send(resource $session): int|false

Sends a keepalive if needed. Returns the number of seconds you can wait
before calling it again, or false on error.

Example

$ssh = ssh2_connect('example.com', 22);
ssh2_auth_password($ssh, 'user', 'pass');

// Send keepalive every 30 seconds of inactivity
ssh2_keepalive_config($ssh, true, 30);

// In a long-running loop
$seconds = ssh2_keepalive_send($ssh);
sleep($seconds);

Why this approach

• Uses libssh2_keepalive_config() and libssh2_keepalive_send(),
  which work cross-platform (Linux, macOS, Windows)
• Per-connection, not a global setting
• Follows the same pattern as ssh2_set_timeout()
• Feature-detected in config.m4 via PHP_CHECK_LIBRARY

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds per-connection SSH keepalive support by exposing libssh2’s keepalive API to PHP, preventing idle SSH sessions from being silently dropped.

Changes:

• Introduces ssh2_keepalive_config() and ssh2_keepalive_send() in the extension.
• Adds a PHPT covering basic keepalive configuration/send/disable behavior.
• Feature-detects libssh2 keepalive support at configure time (PHP_SSH2_KEEPALIVE).

Reviewed changes

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

File	Description
ssh2.c	Implements and registers the new keepalive functions and their arginfo.
config.m4	Adds a configure-time check for libssh2 keepalive symbols and defines PHP_SSH2_KEEPALIVE.
tests/ssh2_keepalive.phpt	Adds a basic functional test for keepalive config/send behavior.

---

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

[Copilot]

Pull request overview

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

---

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

[Copilot]

Pull request overview

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

---

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