RoboHub

This page was generated from the source of RoboHub. Edit the source, not this page.

Notifications

Short messages a person sees on the page they have open — "Saved.", "The widget
could not be added" — shown as a toast, kept for a few seconds and then gone. A
change made anywhere in the application reaches every open page of it without a
refresh, because each page follows the same live feed.

This is the application's own toast, for the person using it. Alerts that leave
the application (email, Telegram, a webhook) go through the robohub.alert
interface and its providers instead (see robohub-alert/index).

How an application uses it

Add notifications to deps and include it. It needs no host hooks; its
routes are registered on the application's router.

  • Put notification_embed() in the page body of the application's layout. It
    draws the toast and opens an EventSource on /notifications/stream. Each
    event is shown as a toast and also dispatched on the window as a rho:event
    (its detail is the event), so a page that cares about a change can reload
    its own data without knowing where the change came from. An event for another
    language than the page's (<html lang>) is not shown.
  • Push a message from a handler:
notification_push_level_locale(i18n_t(req, "toast.widget_added"), "info", 10, i18n_locale(req))
notification_push_level("Backup finished", "info", 0)   // 0 = the default 5 seconds
notification_live_event("refresh", "inventory changed")  // live only, not kept

notification_push_level_locale(message, level, timeout, locale) stores the
message with the time it expires (timeout seconds from now) and appends it to
the live feed; notification_push_level is the same for every language. The
level is info, warning or error. notification_live_event(kind, message)
appends an event to the live feed only, so it is a page-to-page message rather
than a stored notification.

widgets, inventory, scheduler, journal and the applications use it for
their toasts.

Routes

RouteWhat it does
POST /notifications/pushPushes a message (message, optional level and timeout)
GET /notifications/list, GET /api/notificationsThe active messages, newest first, as JSON
POST /notifications/dismissDismisses one message (id)
GET /notifications/renderThe active messages as HTML
GET /notifications/streamThe live feed, as Server-Sent Events

Data it keeps

In the application's workspace (<workspace>/data):

WhatWhereWhat it holds
notifications tableapp.db (or RHO_NOTIFICATIONS_DB)Each message: level, text, when it was created, when it expires, whether it was dismissed
The live feedlive.eventsOne JSON event per line (kind, message, locale), streamed to open pages

The module has no settings.

Reference

Generated from the module's manifest and sources when this site was built.

Exports — what an application may call (provides.exports, imported as robohub.notifications):

  • notification_push_level_locale
  • notification_push_level
  • notification_live_event
  • notification_live_event_locale
  • notification_embed

Routes — registered on the host application's router:

MethodPathHandler
POST/notifications/pushnotifications_push
GET/notifications/listnotifications_list
POST/notifications/dismissnotifications_dismiss
GET/notifications/rendernotifications_render
GET/api/notificationsnotifications_api_list
GET/notifications/streamnotification_events

Release history

[0.1.1] - 2026-11-08

Live notification events carry a locale, the embed filters by the page language, and the default toast text is available in English and Romanian. Alert log writes remain file-based.

[0.1.2] - 2026-11-09

The module's clock file is written under the application workspace instead of the module source tree, so running an application no longer changes a tracked file in modules/notifications. Every pushed notification is also written to the host application log.

[0.1.3] - 2026-11-12

The module declares the runtime functions it calls, and reading the outcome of a command uses its own trim rather than the including application's.

[0.1.4] - 2026-11-13

A notification's level is escaped where it becomes part of a class attribute.

[0.1.5] - 2026-11-13

The clock is read from the process (rho_now_s, rho 0.6.0) instead of from date written to a file and read back, which a request and the background loop could truncate under each other: entries dated 1970 and modes that expired at once.

[0.1.6] - 2026-11-13

An empty list has no blank notification: a run that finds no row is not read as one. Level and message are JSON strings in the API.

[0.1.7] - 2026-11-14

Trimming, URL escapes, form fields and decimals come from the toolchain (rho 0.7.0: str_trim, str_url_encode/str_url_decode, form_field, milli_*) rather than this module's own copy, the same on both backends. Needs rho 0.7.0. A form field is URL-decoded: a channel name or message with a space, an & or an accent was stored as sent (a+b%26c).

[0.1.8] - 2026-11-14

Its data is kept where app_workspace() says (rho 0.8.0) — the application's workspace, else ~/.rho/apps/<app> — so two applications started by hand no longer share this module's records. Copies of helpers the toolchain now provides (i64_to_str, str_lower, str_field, json_str_field, escape_html) are gone. Needs rho 0.8.0.

[0.2.0] - 2026-11-14

It lists what other code may use (provides.exports, imported as robohub.notifications). An application that includes it still reaches everything, and a build (rho 0.8.3) names each call to a function outside the list. The list is what the applications and modules of the ecosystem call; anything else is the module's own and may change without notice.

[0.2.1] - 2026-11-14

notification_live_event_locale is exported, and a warning toast has its own colour.