From 1d0842ee56bca92a170cd57afa0ed803e7f498f3 Mon Sep 17 00:00:00 2001 From: Piotr Roszatycki Date: Thu, 12 Nov 2026 16:57:34 +0100 Subject: [PATCH] Pyjoyment: the heartbeat of a stream, the helper heartbeat and the value heartbeat of the stash of a route A comment of Server-Sent Events every so many seconds, once the response is a stream of text/event-stream, or the pings of a WebSocket with heartbeat of its transaction, so that proxies and load balancers with an idle timeout of their own, and the inactivity timeout of the connection, keep a stream that waits, as for a model of language. Mojolicious leaves the comments to the application. The value heartbeat of the stash of a route, of its defaults or of a route of under before it, sets it before the first action, and is a reserved stash value. Part of #266 Co-Authored-By: Claude Opus 5.5 --- Pyjoyment/Controller.py | 2 +- Pyjoyment/Plugin/DefaultHelpers.py | 65 +++++++++++++- Pyjoyment/Routes/Route.py | 6 +- Pyjoyment/__init__.py | 3 + docs/guides/routing.rst | 8 +- plugins/pyjoyment/skills/async/SKILL.md | 3 + t/Pyjoyment/app.py | 3 +- t/Pyjoyment/heartbeat_lite_app.py | 115 ++++++++++++++++++++++++ t/docs/guides_routing.py | 4 + 9 files changed, 202 insertions(+), 7 deletions(-) create mode 100644 t/Pyjoyment/heartbeat_lite_app.py diff --git a/Pyjoyment/Controller.py b/Pyjoyment/Controller.py index 46fdb0ca..ff074828 100644 --- a/Pyjoyment/Controller.py +++ b/Pyjoyment/Controller.py @@ -953,7 +953,7 @@ def stash(self, *args: Any, **values: Any) -> Any: :meth:`Pyjoyment.Pyjoyment_App.defaults`. Some stash values have a special meaning and are reserved, the full list is currently ``action``, ``app``, ``cb``, ``controller``, ``data``, ``extends``, - ``format``, ``handler``, ``inactivity_timeout``, ``inline``, + ``format``, ``handler``, ``heartbeat``, ``inactivity_timeout``, ``inline``, ``json``, ``layout``, ``namespace``, ``path``, ``request_timeout``, ``status``, ``template``, ``text``, ``toml``, ``variant`` and ``yaml``. Note that all stash values with a ``mojo.*`` prefix are diff --git a/Pyjoyment/Plugin/DefaultHelpers.py b/Pyjoyment/Plugin/DefaultHelpers.py index 9ae2d42d..493ae0d0 100644 --- a/Pyjoyment/Plugin/DefaultHelpers.py +++ b/Pyjoyment/Plugin/DefaultHelpers.py @@ -174,6 +174,32 @@ c.flash(message='User created successfully!') c.redirect_to('show_user', id=23) +heartbeat :: + + c = c.heartbeat() + c = c.heartbeat(15) + c = c.heartbeat(60, 10) + c = c.heartbeat(None) + +Keep a stream alive while it waits, as for a model of language that is silent +for minutes, which the value ``heartbeat`` of the stash of a route sets +before its first action, so that proxies and load balancers with an idle +timeout of their own, and the inactivity timeout of the connection, keep it: +a comment ``: heartbeat`` of Server-Sent Events every ``interval`` seconds, +``20`` by default, once the response is a stream of ``text/event-stream``, or +the pings of a WebSocket, with +:meth:`Pyjo.Transaction.WebSocket.Pyjo_Transaction_WebSocket.heartbeat`, +which closes the connection of a peer that does not answer in ``timeout`` +seconds. ``None`` stops it. :: + + # A stream of events whose connection stays open while it waits + @app.routes.get('/events', {'heartbeat': 15}) + async def events(c): + c.write_sse() + async for chunk in llm.stream(c.param('q')): + c.write_sse({'text': chunk}) + c.finish() + inactivity_timeout :: c = c.inactivity_timeout(3600) @@ -625,7 +651,7 @@ def catch(err): import weakref from collections.abc import Callable -from typing import TYPE_CHECKING, Any +from typing import TYPE_CHECKING, Any, cast if TYPE_CHECKING: @@ -673,6 +699,7 @@ def register(self, app: 'Pyjoyment.object', conf: dict[str, Any] | None = None) app.helper('current_route', _current_route) app.helper('exception_format', _exception_format) app.helper('flash', _flash) + app.helper('heartbeat', _heartbeat) app.helper('inactivity_timeout', _inactivity_timeout) app.helper('is_fresh', _is_fresh) app.helper('redirect_to', _redirect_to) @@ -890,6 +917,41 @@ def _http_not_found(c: 'Controller') -> Any: return c.helpers.reply.html_not_found() +# Not in Mojolicious: the comments of Server-Sent Events that keep a stream alive, which Mojolicious leaves to the +# application, and the pings of a WebSocket +def _heartbeat(c: 'Controller', interval: float | None = 20, timeout: float | None = 20) -> 'Controller': + if (tx := c.tx) is None: + return c + if tx.is_websocket: + cast(Any, tx).heartbeat(interval, timeout) + return c + + stash = c.stash() + loop = Pyjo.IOLoop.singleton + if (old := stash.pop('pyjo.heartbeat', None)) is not None: + loop.remove(old) + if interval is None or tx.is_finished: + return c + + # Weakly, as the loop keeps the timer, and the transaction its subscribers + ref = weakref.ref(c) + + def beat(loop: Pyjo.IOLoop.object) -> None: + if (c := ref()) is None or (tx := c.tx) is None or tx.is_finished: + return + res = c.res + if res.content.is_dynamic and (res.headers.content_type or '').startswith('text/event-stream'): + c.write_sse({'comment': 'heartbeat'}) + + id = stash['pyjo.heartbeat'] = loop.recurring(interval, beat) + + def finish(tx: Any) -> None: + loop.remove(id) + + tx.on('finish', finish) + return c + + def _inactivity_timeout(c: 'Controller', timeout: float) -> 'Controller': tx: Any = c.tx if stream := Pyjo.IOLoop.stream(tx.connection or ''): @@ -1240,6 +1302,7 @@ class Helpers: current_route = Helper(_current_route) exception_format = Helper(_exception_format) flash = Helper(_flash) + heartbeat = Helper(_heartbeat) inactivity_timeout = Helper(_inactivity_timeout) is_fresh = Helper(_is_fresh) redirect_to = Helper(_redirect_to) diff --git a/Pyjoyment/Routes/Route.py b/Pyjoyment/Routes/Route.py index 25ff6f27..4a272669 100644 --- a/Pyjoyment/Routes/Route.py +++ b/Pyjoyment/Routes/Route.py @@ -55,10 +55,10 @@ # Reserved stash values # Not in Mojolicious: toml and yaml, which the renderer renders as json -# Unlike Mojolicious: the timeouts of a route, inactivity_timeout and request_timeout, are reserved too +# Unlike Mojolicious: the timeouts of a route, inactivity_timeout and request_timeout, and its heartbeat are reserved too _RESERVED = frozenset( - 'action app cb controller data extends format handler inactivity_timeout inline json layout namespace path ' - 'request_timeout status template text toml variant yaml'.split() + 'action app cb controller data extends format handler heartbeat inactivity_timeout inline json layout namespace ' + 'path request_timeout status template text toml variant yaml'.split() ) diff --git a/Pyjoyment/__init__.py b/Pyjoyment/__init__.py index 5c88aadd..bbbbf723 100644 --- a/Pyjoyment/__init__.py +++ b/Pyjoyment/__init__.py @@ -1052,6 +1052,9 @@ def _action(next: Any, c: Pyjoyment.Controller.object, action: Callable[..., Any c.helpers.inactivity_timeout(timeout) if (timeout := stash.get('request_timeout')) is not None and 'pyjo.request_timeout' not in stash: c.helpers.request_timeout(timeout) + if (interval := stash.get('heartbeat')) is not None and 'pyjo.heartbeat' not in stash: + stash['pyjo.heartbeat'] = None + c.helpers.heartbeat(interval) try: val = action(c) diff --git a/docs/guides/routing.rst b/docs/guides/routing.rst index 219c41fb..14b0b12f 100644 --- a/docs/guides/routing.rst +++ b/docs/guides/routing.rst @@ -432,13 +432,19 @@ to the end of the response, as the helper ``request_timeout`` sets it, after which the actions are cancelled and the request gets a ``504`` response. A request that waits for a model of language, which can be silent for minutes, needs both, and the routes of :ref:`under ` give them to all -the routes of a group. +the routes of a group. The value ``heartbeat`` keeps a stream alive while it +waits, for proxies and load balancers with an idle timeout of their own, as +the helper ``heartbeat`` does, with a comment of Server-Sent Events or a ping +of a WebSocket every so many seconds. .. code-block:: python # Ten minutes of silence, and two minutes to the end of the response at most r.post('/chat', {'inactivity_timeout': 600, 'request_timeout': 120}).to('chat#reply') + # A stream of events with a comment every 15 seconds + r.get('/events', {'heartbeat': 15}).to('chat#events') + # The same for every route of a group llm = r.under('/llm', {'inactivity_timeout': 600, 'request_timeout': 120}) llm.post('/complete').to('llm#complete') diff --git a/plugins/pyjoyment/skills/async/SKILL.md b/plugins/pyjoyment/skills/async/SKILL.md index b41f717c..77e04545 100644 --- a/plugins/pyjoyment/skills/async/SKILL.md +++ b/plugins/pyjoyment/skills/async/SKILL.md @@ -255,6 +255,9 @@ app.start() `get('/chat', {'inactivity_timeout': 600}, chat)`, or of a group with `under`. `request_timeout` there, or `c.request_timeout(120)`, bounds the whole response: the actions are cancelled, and the request gets `504`. + `heartbeat` there, or `c.heartbeat(15)`, writes a comment of Server-Sent + Events, or a ping of a WebSocket, while the stream waits, for a proxy with + an idle timeout of its own. ## Documentation diff --git a/t/Pyjoyment/app.py b/t/Pyjoyment/app.py index 7779e0b6..d4a1691a 100644 --- a/t/Pyjoyment/app.py +++ b/t/Pyjoyment/app.py @@ -199,9 +199,10 @@ def local(**env): ok(t.app.routes.is_reserved('yaml'), 'is reserved') ok(t.app.routes.is_reserved('toml'), 'is reserved') - # Not in Mojolicious: the timeouts of a route + # Not in Mojolicious: the timeouts of a route and its heartbeat ok(t.app.routes.is_reserved('inactivity_timeout'), 'is reserved') ok(t.app.routes.is_reserved('request_timeout'), 'is reserved') + ok(t.app.routes.is_reserved('heartbeat'), 'is reserved') with subtest('Reserved stash value (in placeholder)'): throws_ok( diff --git a/t/Pyjoyment/heartbeat_lite_app.py b/t/Pyjoyment/heartbeat_lite_app.py new file mode 100644 index 00000000..c4a20e01 --- /dev/null +++ b/t/Pyjoyment/heartbeat_lite_app.py @@ -0,0 +1,115 @@ +import os + + +os.environ['PYJO_MODE'] = 'development' + +# A short inactivity timeout of the server, which a heartbeat keeps a stream from +os.environ['PYJO_INACTIVITY_TIMEOUT'] = '0.3' + +import Pyjo.IOLoop +import Pyjo.Promise +import Pyjo.Test.Pyjo + +from Pyjo.Test import * +from Pyjo.WebSocket import WS_PING +from Pyjoyment.Lite import app, get, websocket + + +# Not in Mojolicious: the heartbeat of a stream, the comments of Server-Sent Events or the pings of a WebSocket, of the +# helper heartbeat or of the value heartbeat of the stash of a route, set before its first action + +app.log.level = 'fatal' + + +async def events(c): + c.write_sse() + await Pyjo.Promise.timer(0.5) + c.write_sse({'text': 'done'}) + c.finish() + + +get('/events', {'heartbeat': 0.1}, events) +get('/silent', events) + + +@get('/helper') +async def helper(c): + c.heartbeat(0.1) + await events(c) + + +@get('/stopped') +async def stopped(c): + c.heartbeat(0.05).heartbeat(None) + c.write_sse() + await Pyjo.Promise.timer(0.2) + c.write_sse({'text': 'done'}) + c.finish() + + +@get('/plain', {'heartbeat': 0.05}) +async def plain(c): + await Pyjo.Promise.timer(0.2) + c.render(text='plain') + + +@websocket('/ws', {'heartbeat': 0.1}) +def ws(c): + c.on('message', lambda c, msg: c.send(f'echo: {msg}')) + + +t = Pyjo.Test.Pyjo.new() +t.ua.inactivity_timeout = 10 + + +def raw(path): + # The bytes of a stream, with its comments, which the user agent leaves out of its events, until its end + async def read(): + port = t.ua.server.url().port + stream = await Pyjo.IOLoop.client_p(address='127.0.0.1', port=port) + await stream.write_p(f'GET {path} HTTP/1.1\r\nHost: 127.0.0.1\r\nConnection: close\r\n\r\n'.encode()) + data = b'' + async for chunk in stream: + data += chunk + return data.decode() + + got = [] + Pyjo.Promise.new(read()).then(got.append).wait() + return got[0] + + +with subtest('Comments of a stream of events'): + data = raw('/events') + like_ok(data, r'Content-Type: text/event-stream', 'stream') + cmp_ok(data.count(': heartbeat\r\n\r\n'), '>=', 2, 'comments while it waits') + like_ok(data, r'data: done\r\n\r\n', 'the event after them, beyond the inactivity timeout of the server') + +with subtest('Without a heartbeat'): + data = raw('/silent') + unlike_ok(data, r'heartbeat', 'no comments') + unlike_ok(data, r'data: done', 'closed by the inactivity timeout of the server') + +with subtest('Heartbeat of the helper'): + data = raw('/helper') + cmp_ok(data.count(': heartbeat'), '>=', 2, 'comments') + like_ok(data, r'data: done', 'event') + +with subtest('Stopped'): + data = raw('/stopped') + unlike_ok(data, r'heartbeat', 'no comments') + like_ok(data, r'data: done', 'event') + +with subtest('Not a stream of events'): + t.get_ok('/plain').status_is(200).content_is('plain') + +with subtest('Pings of a WebSocket'): + pings = [] + t.websocket_ok('/ws') + t.tx.on('frame', lambda ws, frame: pings.append(frame) if frame[4] == WS_PING else None) + Pyjo.Promise.timer(0.5).wait() + t.send_ok('hi').message_ok().message_is('echo: hi').finish_ok() + cmp_ok(len(pings), '>=', 2, 'pings while it waits, which keep it open beyond the inactivity timeout') + +t.close() + +done_testing() diff --git a/t/docs/guides_routing.py b/t/docs/guides_routing.py index cc705d13..ad9eb2e3 100644 --- a/t/docs/guides_routing.py +++ b/t/docs/guides_routing.py @@ -224,6 +224,10 @@ def bye(self): # Ten minutes of silence, and two minutes to the end of the response at most r.post('/chat', {'inactivity_timeout': 600, 'request_timeout': 120}).to('chat#reply') + # A stream of events with a comment every 15 seconds + r.get('/events', {'heartbeat': 15}).to('chat#events') + is_deeply_ok(endpoint(r, '/events'), {'heartbeat': 15, 'controller': 'chat', 'action': 'events'}, 'heartbeat') + # The same for every route of a group llm = r.under('/llm', {'inactivity_timeout': 600, 'request_timeout': 120}) llm.post('/complete').to('llm#complete')