Rails

Runlight funciona dentro de una aplicación Rails 7.2, 8.0 u 8.1, con sus tablas en la propia base de datos de la aplicación y su panel en /runlight.

La gema runlight trae un engine de Rails que sirve Runlight desde tu aplicación, con sus tablas en la propia base de datos de la aplicación. Es la gema de Ruby, que da a cada petición la misma respuesta que da la biblioteca de TypeScript, así que cualquiera de los dos puede leer una base de datos que haya escrito el otro. Funciona con Rails 7.2, 8.0 y 8.1 sobre Ruby 3.2 o posterior, y con SQLite, Postgres, MySQL o MariaDB.

Instalación

Añade la gema y ejecuta su generador.

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

El generador escribe config/initializers/runlight.rb y una migración que crea las tablas de Runlight. Todos sus nombres empiezan por rl_, así que conviven con las de la aplicación. Después de actualizar la gema, Runlight las pone al día por sí mismo en la primera petición, y bin/rails runlight:migrate lo hace al momento.

Configúralo

El initializer configura el único Runlight que comparte la aplicación.

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", "") },
)

Las opciones tienen los nombres de Configuración, escritos en snake case, así que sites, trust_proxy, rate_limit, mail y managed_sites funcionan como allí. Las que van bajo routes son las del panel, como accounts: true, que permite a cada persona iniciar sesión con su propio correo y contraseña una vez definido RUNLIGHT_SECRET, como en Cuentas. Un token vacío mantiene cerrado el panel, y nil lo dejaría abierto a todo el mundo. Para guardar el token en las credentials de la aplicación, léelo ahí con Rails.application.credentials.runlight_token.

Runlight::Stores.active_record guarda las tablas en la base de datos a la que se conecta ApplicationRecord. En una aplicación con varias bases de datos, pasa la clase abstracta de la que quieras usar, como Runlight::Stores.active_record(AnalyticsRecord), y ejecuta la migración contra esa base de datos.

Añade el script

Añade el script al layout, justo antes de </head>.

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

Después define RUNLIGHT_TOKEN como una cadena larga y aleatoria y abre una vez /runlight/?token= seguido de esa cadena para iniciar sesión, como describe Primeros pasos.

Cómo le llegan las peticiones

El engine añade un middleware a la aplicación. Responde a las rutas bajo /runlight, a los enlaces cortos en /go y a cualquier dominio de enlaces que añadas en Ajustes antes de que el router las vea, y pasa cualquier otra petición a la aplicación. La comprobación CSRF de Rails rechazaría al tracker, que no puede enviar un token, y Runlight comprueba sus peticiones a su manera, así que no hay que poner nada en config/routes.rb. El middleware también registra los accesos de los agentes de IA mientras se sirven tus páginas, lo que no le cuesta tiempo a nadie más.

Un dominio de enlaces es un host propio, así que añádelo a config.hosts cuando la aplicación define esa lista, o Rails rechazará antes la petición.

La comprobación programada

La comprobación programada envía los informes por email y mantiene los datos en orden. Ejecútala cada pocos minutos, una vez para toda la aplicación y no en cada proceso. Con Solid Queue, añádela a config/recurring.yml.

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

Con cron, o con cualquier programador de tareas que ejecute un comando, usa la tarea rake.

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

En los tests

Runlight no registra nada hasta que le llega una petición, así que los tests que nunca cargan /runlight no notan ninguna diferencia. Un test del propio panel puede volver a llamar a Runlight.configure con un almacén propio, como Runlight::Stores.sqlite(":memory:"), y el engine usa el nuevo a partir de la siguiente petición.

En qué se diferencia de la biblioteca de TypeScript

El engine es la gema de Ruby dentro de Rails, así que lo que enumera la guía de Ruby también se aplica aquí. La misma gema tiene un servidor independiente para ejecutar Runlight en un dominio propio, con un solo panel para varios sitios.