NAME

PAGI::Middleware::SSE::Heartbeat - SSE keepalive via comment lines

SYNOPSIS

use PAGI::Middleware::Builder;

my $app = builder {
    enable 'SSE::Heartbeat',
        interval => 15;
    $my_app;
};

DESCRIPTION

PAGI::Middleware::SSE::Heartbeat sends periodic comment lines (: keepalive) to SSE connections to prevent proxy timeouts and keep connections alive.

CONFIGURATION

• interval (default: 15)

  Seconds between heartbeat comments.

• comment (default: 'keepalive')

  The comment text to send. Will be prefixed with ': '.

• loop (optional)

  IO::Async::Loop instance for scheduling.

HOW IT WORKS

After the application sends sse.start, this middleware begins sending comment lines at the configured interval. SSE comments (lines starting with ':') are ignored by the browser's EventSource API but keep the TCP connection alive through proxies.

The middleware is mostly transparent to the application - heartbeat comments are sent automatically without any action needed from the app.

WHY HEARTBEATS

Many HTTP proxies, load balancers, and firewalls close idle connections after a timeout (commonly 30-60 seconds). For long-lived SSE streams where events may be infrequent, heartbeat comments prevent these premature disconnections.

SCOPE EXTENSIONS

• pagi.sse.heartbeat

  Hashref containing interval and comment settings.

SEE ALSO

PAGI::Middleware - Base class for middleware

PAGI::Middleware::SSE::Retry - SSE retry hints