Configuração

Esta página cobre todas as opções de runlight() e routes(), incluindo stores e sites.

import { runlight } from "@runlight/sdk";

export const rl = runlight({ store, site, /* ...options */ });
export const routes = rl.routes({ /* ...route options */ });

Esta página usa os nomes da biblioteca TypeScript. Todas as outras linguagens aceitam as mesmas opções, escritas do jeito que cada linguagem escreve nomes, como mostra a página de cada uma, do PHP ao Rust.

Stores

O Runlight guarda tudo em algumas tabelas com o prefixo rl_, criadas no primeiro uso e atualizadas no lugar. Todo store aceita uma opção prefix para usar no lugar de rl_, como wp_rl_, para que dois apps que dividem um banco de dados tenham cada um as próprias tabelas. Ele tem até 32 letras, dígitos e sublinhados e não começa com dígito, e o tables() de um store lista as tabelas dele pelo nome, para um app que esteja removendo o Runlight.

SQLite

import { sqlite } from "@runlight/sdk/sqlite";

sqlite({ path: "./data/runlight.db" });

O SQLite precisa do better-sqlite3 e serve para um único servidor, onde o arquivo pode ficar ao lado do banco de dados do seu app. Numa hospedagem serverless sem disco persistente, use Postgres. Um arquivo que o Runlight cria só pode ser lido e gravado pelo dono e pelo grupo (0660), então um job agendado que rode como outro usuário do mesmo grupo ainda consegue usá-lo.

Postgres

import { postgres } from "@runlight/sdk/postgres";

postgres({ url: process.env.DATABASE_URL });

O Postgres precisa do pg. Passe url, ou passe pool para compartilhar um pool que o seu app já tem (o Runlight nunca encerra um pool que ele não criou). Um pool precisa de pelo menos 2 conexões. Quando o Runlight cria o pool, max define as conexões dele e o padrão é 10, uma requisição espera no máximo 10 segundos por uma conexão livre (um hit do script de rastreamento tenta mais duas vezes antes de ser descartado), e statementTimeout interrompe qualquer consulta depois desse número de milissegundos, 120000 por padrão (0 desliga). Se vários processos iniciarem ao mesmo tempo, as tabelas ainda assim são criadas uma vez só. Um processo espera no máximo 30 segundos por outro que esteja criando ou atualizando as tabelas, depois disso uma requisição responde 503 com o código tables_busy, e um hit do script de rastreamento espera no máximo 10 segundos e então é descartado.

MySQL e MariaDB

import { mysql } from "@runlight/sdk/mysql";

mysql({ url: process.env.DATABASE_URL });

Este store precisa do mysql2 e funciona com MySQL 8.0.20 ou mais recente e MariaDB 11.4 ou mais recente. Passe uma URL mysql:// ou mariadb:// como url, ou passe pool para compartilhar um pool de mysql2/promise que o seu app já tem (o Runlight nunca encerra um pool que ele não criou). Um pool precisa de pelo menos 2 conexões. Quando o Runlight cria o pool, max define as conexões dele e o padrão é 10, uma requisição espera no máximo 10 segundos por uma conexão livre (um hit do script de rastreamento tenta mais duas vezes antes de ser descartado), e statementTimeout interrompe qualquer consulta depois desse número de milissegundos, 120000 por padrão (0 desliga). No MySQL esse limite vale para leituras, e no MariaDB vale para todos os comandos. Se vários processos iniciarem ao mesmo tempo, as tabelas ainda assim são criadas uma vez só. Um processo espera no máximo 30 segundos por outro que esteja criando ou atualizando as tabelas, depois disso uma requisição responde 503 com o código tables_busy, e um hit do script de rastreamento espera no máximo 10 segundos e então é descartado.

As tabelas usam utf8mb4 com a collation utf8mb4_0900_bin. O texto é comparado e ordenado por code point, mantendo maiúsculas, minúsculas e espaços no final, então todo relatório sai igual ao que sairia no SQLite ou no Postgres.

libSQL e Turso

import { libsql } from "@runlight/sdk/libsql";
import { createClient } from "@libsql/client"; // or "@libsql/client/web" on the edge

libsql({ client: createClient({ url: process.env.TURSO_URL, authToken: process.env.TURSO_TOKEN }) });

Este store precisa do @libsql/client. O Turso por HTTP funciona em qualquer lugar onde fetch funcione, incluindo Vercel Edge e Deno Deploy, e uma URL file: aponta para um arquivo SQLite local.

Cloudflare D1

import { d1 } from "@runlight/sdk/d1";

d1({ database: env.DB });

Passe o binding do D1 do ambiente do seu Worker. O D1 não tem transações interativas, então uma importação de links grava cada link separadamente; se uma falhar no meio, rodar a importação de novo pula os links já gravados.

Bun

import { bunSqlite } from "@runlight/sdk/bun";

bunSqlite({ path: "./data/runlight.db" });

Este store usa o SQLite embutido do Bun, para apps no Bun, onde o better-sqlite3 não carrega.

Opções de runlight()

Sites

Uma visita de um nome de host que nenhum site reivindica é ignorada, então uma cópia de staging do seu site não conta, a menos que você adicione o nome de host dela.

Limite de requisições

Cada processo conta as requisições ao script de rastreamento por endereço de visitante ao longo de um minuto e descarta o excesso em silêncio, para que um script não consiga inundar um site com visitas inventadas. Um visitante de verdade envia algumas requisições por minuto, bem abaixo do padrão de 120. A contagem vive na memória sob um endereço em hash e é zerada a cada minuto, então nenhum endereço é guardado. Em hospedagens que rodam muitas cópias de curta duração do seu app, como Cloudflare Workers, cada cópia conta por conta própria, então ali o limite é mais folgado.

Localização

País, região e cidade vêm dos cabeçalhos da sua hospedagem na Vercel, na Cloudflare e na Netlify, sem configuração. Em outros lugares, passe geo, uma função que transforma um endereço IP numa localização. Este exemplo a apoia num arquivo MMDB.

runlight({
  store,
  geo: async (ip) => {
    const found = reader.get(ip); // your MMDB reader
    return found ? { country: found.country?.iso_code, city: found.city?.names?.en } : null;
  },
});

O endereço é descartado depois da consulta, então só o local é guardado.

Opções de routes()

As opções accountOf e tokenMade ligam as rotas às contas do próprio servidor independente e são internas a ele.

Sem token, o painel e a API respondem 503 até você definir um, a menos que NODE_ENV seja development. Coletar visitas, o script, os links curtos, os links de compartilhamento e os links de cancelamento de inscrição nunca precisam do token.

Contas

Ative as contas para deixar várias pessoas entrarem no painel, cada uma com o próprio e-mail, senha e função, do mesmo jeito que o servidor independente faz.

export const { GET, POST, PUT, PATCH, DELETE } = rl.routes({ accounts: true });

O painel então pede que todos entrem em /runlight/login. Para criar a primeira conta, abra /runlight/setup e informe o seu RUNLIGHT_TOKEN junto com seu e-mail e senha, para que só quem roda o app consiga fazer isso. Essa conta é a do proprietário. Em desenvolvimento sem token, ou com token: null, que deixa tudo aberto, a primeira conta não precisa de token, então crie-a antes que qualquer outra pessoa consiga chegar à página.

O proprietário e os administradores convidam mais pessoas em Configurações, Pessoas, como administrador, membro ou leitor, e o convite sai por e-mail quando há um serviço de e-mail configurado. Todos podem ativar o login em duas etapas em Conta. O token continua funcionando como bearer token para scripts.

As sessões são assinadas com RUNLIGHT_SECRET, ou com o token quando ele não está definido, então mantenha-o igual entre reinicializações e deploys. As senhas são guardadas em hash com scrypt onde o runtime o tem, como Node, Bun e Deno, e com PBKDF2 em runtimes de edge como Cloudflare Workers.

Se alguém esquecer a senha, o proprietário ou um administrador pode remover a pessoa e convidá-la de novo. Se o proprietário esquecer a dele, dê uma nova à conta a partir de um script que use o seu Runlight.

import { Accounts } from "@runlight/sdk";
import { rl } from "./lib/runlight";

const accounts = new Accounts(rl.store, process.env.RUNLIGHT_SECRET ?? process.env.RUNLIGHT_TOKEN!);
const user = await accounts.setPassword("you@example.com", "a new long password", Date.now());
await accounts.disableTwoFactor(user.id);

Variáveis de ambiente