/ 
PAGI-FastAPI-v1.0.0
/ PAGI::FastAPI::Response::SSE

NAME

PAGI::FastAPI::Response::SSE - Server-Sent Events (SSE) Streaming Response for PAGI::FastAPI

VERSION

Version v1.0.0

SYNOPSIS

use PAGI::FastAPI;

my $app = PAGI::FastAPI->new();

$app->get('/api/v1/notifications', sub ($c) {
    return $c->sse(async sub ($sse) {
        # Enable keepalive comments every 20 seconds
        await $sse->keepalive(20);

        # Replay missed messages on client reconnection
        if (my $last_id = $sse->last_event_id) {
            my @missed = get_events_since($last_id);
            for my $event (@missed) {
                await $sse->send_event(%$event);
            }
        }

        # Send a structured SSE event
        await $sse->send_event(
            event => 'notification',
            id    => 'evt-101',
            data  => { user => 'alice', status => 'online' },
        );

        # Stream plain JSON messages
        await $sse->send_json({ message => 'System operational' });

        # Close stream when done
        await $sse->close(reason => 'complete');
    });
});

DESCRIPTION

PAGI::FastAPI::Response::SSE provides first-class, non-blocking Server-Sent Events (SSE) streaming capabilities for PAGI::FastAPI applications by wrapping PAGI::SSE.

It automatically manages connection lifecycles, flow control/backpressure, heartbeats, custom headers (such as disabling Nginx buffering via X-Accel-Buffering: no), and structured event formatting (JSON auto-encoding, event IDs, retry intervals, and keepalive comments).

CONSTRUCTOR

new(%options)

Instantiates a new SSE response object. Accepts the following named parameters:

  • generator (Required)

    An async sub ($sse) reference containing the streaming loop or event emitter. Receives a PAGI::SSE instance as its sole argument.

  • headers (Optional)

    An ArrayRef of header key-value pairs (e.g., [ ['X-Custom-Header' => 'value'] ]) to return with the initial HTTP response stream. Defaults to [].

  • status (Optional)

    Integer HTTP status code for the initial handshake response. Defaults to 200.

METHODS

dispatch($scope, $receive, $send)

await $response->dispatch($scope, $receive, $send);

Executes the SSE response lifecycle against the low-level PAGI connection. This method initialises PAGI::SSE, issues the initial sse.start event with default and custom HTTP headers, runs the generator callback, and waits on $sse-run> until client disconnect or stream closure.

SEE ALSO

PAGI::SSE, PAGI::FastAPI::Context, PAGI::FastAPI

AUTHOR

Mohammad Sajid Anwar, <mohammad.anwar at yahoo.com>

REPOSITORY

https://github.com/manwar/PAGI-FastAPI

BUGS

Please report any bugs or feature requests through the web interface at https://github.com/manwar/PAGI-FastAPI/issues. I will be notified and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc PAGI::FastAPI::Response::SSE

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright (C) 2026 Mohammad Sajid Anwar.

This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License (2.0).