Rails

Runlight tourne dans une application Rails 7.2, 8.0 ou 8.1, avec ses tables dans la base de données de l’application et son tableau de bord sur /runlight.

La gem runlight apporte un engine Rails qui sert Runlight depuis votre application, avec ses tables dans la base de données de l’application. C’est la gem Ruby, qui donne à chaque requête la même réponse que la bibliothèque TypeScript, donc chacune peut lire une base de données écrite par l’autre. Elle fonctionne avec Rails 7.2, 8.0 et 8.1 sur Ruby 3.2 ou plus récent, et avec SQLite, Postgres, MySQL ou MariaDB.

Installation

Ajoutez la gem et lancez son générateur.

bundle add runlight
bin/rails generate runlight:install
bin/rails db:migrate

Le générateur écrit config/initializers/runlight.rb et une migration qui crée les tables de Runlight. Leurs noms commencent tous par rl_, donc elles se rangent à côté de celles de l’application. Après une mise à jour de la gem, Runlight les met à jour tout seul à la première requête, et bin/rails runlight:migrate le fait tout de suite.

Configuration

L’initializer met en place l’unique Runlight que partage l’application.

Runlight.configure(
  store: Runlight::Stores.active_record,
  site: { name: "example.com", hostnames: ["example.com"], timezone: "Europe/London" },
  routes: { base_path: "/runlight", token: ENV.fetch("RUNLIGHT_TOKEN", "") },
)

Les options portent les noms de Configuration, écrits en snake case, donc sites, trust_proxy, rate_limit, mail et managed_sites fonctionnent tous comme là-bas. Celles sous routes concernent le tableau de bord, comme accounts: true, qui permet à chacun de se connecter avec son propre e-mail et son propre mot de passe une fois RUNLIGHT_SECRET défini, comme dans Comptes. Un jeton vide garde le tableau de bord fermé, et nil le laisserait ouvert à tout le monde. Pour garder le jeton dans les credentials de l’application, lisez-le à cet endroit avec Rails.application.credentials.runlight_token.

Runlight::Stores.active_record garde les tables dans la base de données à laquelle se connecte ApplicationRecord. Dans une application à plusieurs bases, passez la classe abstraite de celle à utiliser, comme Runlight::Stores.active_record(AnalyticsRecord), et lancez la migration sur cette base.

Ajouter le script

Ajoutez le script au layout, juste avant </head>.

<script defer src="/runlight/s.js"></script>

Définissez ensuite RUNLIGHT_TOKEN avec une longue chaîne aléatoire et ouvrez une fois /runlight/?token= suivi de cette chaîne pour vous connecter, comme l’explique Pour commencer.

Comment les requêtes l’atteignent

L’engine ajoute un middleware à l’application. Il répond aux chemins sous /runlight, aux liens courts sur /go et à tout domaine de liens que vous ajoutez dans les Réglages avant que le routeur ne les voie, et transmet toutes les autres requêtes à l’application. La vérification CSRF de Rails refuserait le traceur, qui ne peut pas envoyer de jeton, et Runlight vérifie ses requêtes à sa façon, donc rien ne va dans config/routes.rb. Le middleware enregistre aussi les requêtes des agents IA pendant que vos pages sont servies, ce qui ne prend aucun temps pour les autres visiteurs.

Un domaine de liens est un hôte à part, donc ajoutez-le à config.hosts quand l’application définit cette liste, sinon Rails refuse la requête avant tout.

La vérification planifiée

La vérification planifiée envoie les rapports par e-mail et garde les données en ordre. Lancez-la toutes les quelques minutes, une fois pour toute l’application et non dans chaque processus. Avec Solid Queue, ajoutez-la à config/recurring.yml.

production:
  runlight_check:
    command: "Runlight.instance.check"
    schedule: every 5 minutes

Avec cron, ou tout planificateur qui lance une commande, utilisez la tâche rake.

*/5 * * * * cd /var/www/app && bin/rails runlight:check

Dans les tests

Runlight n’enregistre rien tant qu’aucune requête ne l’atteint, donc les tests qui ne chargent jamais /runlight ne voient aucune différence. Un test du tableau de bord lui-même peut appeler à nouveau Runlight.configure avec son propre stockage, comme Runlight::Stores.sqlite(":memory:"), et l’engine utilise le nouveau dès la requête suivante.

Différences avec la bibliothèque TypeScript

L’engine est la gem Ruby dans Rails, donc ce que liste la page Ruby s’applique aussi ici. La même gem a un serveur autonome pour faire tourner Runlight sur son propre domaine, avec un seul tableau de bord pour plusieurs sites.