Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Pyjoyment/Controller.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
65 changes: 64 additions & 1 deletion Pyjoyment/Plugin/DefaultHelpers.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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 ''):
Expand Down Expand Up @@ -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)
Expand Down
6 changes: 3 additions & 3 deletions Pyjoyment/Routes/Route.py
Original file line number Diff line number Diff line change
Expand Up @@ -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()
)


Expand Down
3 changes: 3 additions & 0 deletions Pyjoyment/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
8 changes: 7 additions & 1 deletion docs/guides/routing.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 <routing-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')
Expand Down
3 changes: 3 additions & 0 deletions plugins/pyjoyment/skills/async/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
3 changes: 2 additions & 1 deletion t/Pyjoyment/app.py
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand Down
115 changes: 115 additions & 0 deletions t/Pyjoyment/heartbeat_lite_app.py
Original file line number Diff line number Diff line change
@@ -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()
4 changes: 4 additions & 0 deletions t/docs/guides_routing.py
Original file line number Diff line number Diff line change
Expand Up @@ -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')
Expand Down
Loading