/ 
PAGI-FastAPI-v0.0.8
/ PAGI::FastAPI::WebSocket

NAME

PAGI::FastAPI::WebSocket - Asynchronous WebSocket connection object for PAGI::FastAPI

VERSION

Version v0.0.8

SYNOPSIS

use Future::AsyncAwait;
use PAGI::FastAPI;

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

$app->websocket('/ws/{room_id}', handler => async sub ($ws, $deps) {
    await $ws->accept;

    my $room_id = $ws->path_params->{room_id};

    try {
        while (defined(my $msg = await $ws->receive_text)) {
            await $ws->send_text("Echo to room $room_id: $msg");
        }
    }
    catch ($err) {
        # Client disconnected or transport error
    }

    await $ws->close(1000, "Done");
});

DESCRIPTION

PAGI::FastAPI::WebSocket encapsulates an incoming WebSocket handshake and provides an asynchronous, event-driven interface for exchanging text, binary, and JSON frames over PAGI application servers.

Each connection's handler runs as an independent task under Future::AsyncAwait and IO::Async. An await inside one connection's handler (in receive_text, receive_bytes, receive_json, send_text, send_bytes, send_json, accept, or close) suspends only that connection's coroutine - it never blocks the event loop, and every other connection continues to be serviced concurrently while it's pending.

METHODS

Constructor

new(%args)

Instantiates a new PAGI::FastAPI::WebSocket context instance. Normally created internally by PAGI::FastAPI during connection dispatch.

  • scope - The PAGI WebSocket connection scope hash ref.

  • receive - Asynchronous coderef yielding incoming PAGI event hashes.

  • send - Asynchronous coderef dispatching outgoing PAGI event hashes.

  • path_params - HashRef of extracted route path parameters.

  • query_params - HashRef of decoded URI query string parameters.

Attributes and Accessors

path_params()

Returns a HashRef containing path parameters extracted during route matching.

query_params()

Returns a HashRef containing query string parameters parsed from the connection URI.

scope()

Returns the underlying PAGI scope HashRef.

is_accepted()

Returns a boolean indicating whether "accept" has been executed successfully.

is_closed()

Returns a boolean indicating whether the connection has been terminated or closed.

Connection Handshake & Lifecycle

accept($subprotocol?)

await $ws->accept;
await $ws->accept('chat.v1');

Accepts the incoming WebSocket handshake. Optionally accepts a negotiated subprotocol string.

close($code?, $reason?)

await $ws->close;
await $ws->close(1000, "Normal Closure");
await $ws->close(1008, "Policy Violation");

Sends a websocket.close frame to gracefully terminate the connection. Defaults to status code 1000.

Data Frame Operations

receive_text()

my $text = await $ws->receive_text;

Suspends the current coroutine until a text frame arrives from the client, without blocking the event loop or any other connection - other requests and WebSocket connections continue to be serviced while this call is pending. Returns undef if the connection is closed or disconnected.

receive_bytes()

my $raw_bytes = await $ws->receive_bytes;

Suspends the current coroutine until a binary frame arrives from the client, without blocking the event loop or any other connection. Returns undef if closed.

receive_json()

my $data = await $ws->receive_json;

Receives a text frame and deserialises it using JSON::MaybeXS. Returns undef on disconnect.

send_text($string)

await $ws->send_text("Hello World");

Encodes and sends a UTF-8 text frame to the connected client.

send_bytes($bytes)

await $ws->send_bytes($binary_data);

Sends a raw binary frame to the connected client.

send_json($data)

await $ws->send_json({ status => 'ok', payload => $payload });

Serialises $data to JSON using JSON::MaybeXS and transmits it as a text frame.

Low-Level Event Receiver

receive()

my $event = await $ws->receive;

Yields the next raw PAGI event hash from the server stream. Updates internal state flags if a disconnect frame is encountered.

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::WebSocket

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). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0