Rails

O Runlight roda dentro de um app Rails 7.2, 8.0 ou 8.1, com as tabelas no próprio banco de dados do app e o painel em /runlight.

A gem runlight traz uma engine Rails que serve o Runlight a partir do seu app, com as tabelas no próprio banco de dados do app. Ela é a gem Ruby, que dá a cada requisição a mesma resposta que a biblioteca TypeScript dá, então qualquer uma das duas consegue ler um banco de dados que a outra escreveu. Funciona com Rails 7.2, 8.0 e 8.1 no Ruby 3.2 ou mais recente, e com SQLite, Postgres, MySQL ou MariaDB.

Instalação

Adicione a gem e rode o gerador dela.

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

O gerador cria config/initializers/runlight.rb e uma migration que cria as tabelas do Runlight. Todos os nomes delas começam com rl_, para que fiquem ao lado das tabelas do próprio app. Depois de atualizar a gem, o Runlight as atualiza sozinho na primeira requisição, e bin/rails runlight:migrate faz isso na hora.

Configure

O initializer configura o único Runlight que o app compartilha.

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

As opções têm os nomes de Configuração, escritos em snake case, então sites, trust_proxy, rate_limit, mail e managed_sites funcionam todas como lá. As que ficam em routes são as do painel, como accounts: true, que permite que as pessoas entrem com o próprio e-mail e senha depois que RUNLIGHT_SECRET estiver definido, como em Contas. Um token vazio mantém o painel fechado, e nil o deixaria aberto para todo mundo. Para guardar o token nas credentials do app, leia-o ali com Rails.application.credentials.runlight_token.

Runlight::Stores.active_record guarda as tabelas no banco de dados ao qual o ApplicationRecord se conecta. Num app com vários bancos de dados, passe a classe abstrata do banco a usar, como Runlight::Stores.active_record(AnalyticsRecord), e rode a migration nesse banco.

Adicione o script

Adicione o script ao layout, logo antes de </head>.

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

Depois defina RUNLIGHT_TOKEN com uma string aleatória longa e abra /runlight/?token= seguido dessa string uma vez para entrar, como descreve Primeiros passos.

Como as requisições chegam até ele

A engine adiciona um middleware ao app. Ele responde aos caminhos em /runlight, aos links curtos em /go e a qualquer domínio de links que você adicionar nas Configurações antes que o router os veja, e passa todas as outras requisições adiante para o app. A verificação de CSRF do Rails recusaria o script de rastreamento, que não consegue enviar um token, e o Runlight verifica as próprias requisições do jeito dele, então nada vai em config/routes.rb. O middleware também registra as leituras de agentes de IA enquanto suas páginas são servidas, o que não toma tempo de mais ninguém.

Um domínio de links é um host próprio, então adicione-o a config.hosts quando o app define essa lista, ou o Rails recusa a requisição antes.

A verificação agendada

A verificação agendada envia os relatórios por email e mantém os dados organizados. Rode-a a cada poucos minutos, uma vez para o app inteiro, e não em cada processo. Com o Solid Queue, adicione-a a config/recurring.yml.

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

Com cron, ou qualquer agendador que rode um comando, use a task do rake.

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

Nos testes

O Runlight não registra nada até uma requisição chegar a ele, então testes que nunca carregam /runlight não veem diferença. Um teste do próprio painel pode chamar Runlight.configure de novo com um store próprio, como Runlight::Stores.sqlite(":memory:"), e a engine usa o novo a partir da próxima requisição.

Diferenças em relação à biblioteca TypeScript

A engine é a gem Ruby dentro do Rails, então o que o guia do Ruby lista também vale aqui. A mesma gem tem um servidor independente para rodar o Runlight num domínio próprio, com um só painel para vários sites.