Konfiguration

Diese Seite behandelt jede Option für runlight() und routes(), einschließlich Stores und Websites.

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

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

Diese Seite verwendet die Namen der TypeScript-Bibliothek. Jede andere Sprache nimmt dieselben Optionen, geschrieben so, wie diese Sprache Namen schreibt, wie ihre Seite zeigt, von PHP bis Rust.

Stores

Runlight bewahrt alles in einer Handvoll Tabellen mit dem Präfix rl_ auf, die bei der ersten Nutzung angelegt und an Ort und Stelle aktualisiert werden. Jeder Store nimmt eine Option prefix, die anstelle von rl_ verwendet wird, etwa wp_rl_, damit zwei Apps, die sich eine Datenbank teilen, jeweils ihre eigenen Tabellen behalten. Das Präfix besteht aus bis zu 32 Buchstaben, Ziffern und Unterstrichen und beginnt nicht mit einer Ziffer, und tables() eines Stores listet seine Tabellen mit Namen auf, für eine App, die Runlight entfernt.

SQLite

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

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

SQLite braucht better-sqlite3 und passt zu einem einzelnen Server, auf dem die Datei neben der eigenen Datenbank deiner App liegen kann. Auf einem Serverless-Host ohne dauerhafte Festplatte nimmst du Postgres. Eine Datei, die Runlight anlegt, ist nur für ihren Besitzer und ihre Gruppe les- und schreibbar (0660), damit ein geplanter Job, der als anderer Benutzer derselben Gruppe läuft, sie trotzdem nutzen kann.

Postgres

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

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

Postgres braucht pg. Übergib url, oder übergib pool, um einen Pool zu teilen, den deine App schon hat (Runlight beendet nie einen Pool, den es nicht selbst angelegt hat). Ein Pool braucht mindestens 2 Verbindungen. Wenn Runlight den Pool anlegt, legt max seine Verbindungen fest, standardmäßig 10. Eine Anfrage wartet höchstens 10 Sekunden auf eine freie (ein Tracker-Aufruf versucht es noch zweimal, bevor er aufgegeben wird), und statementTimeout stoppt jede einzelne Abfrage nach so vielen Millisekunden, standardmäßig 120000 (0 schaltet das aus). Wenn mehrere Prozesse gleichzeitig starten, werden die Tabellen trotzdem nur einmal angelegt. Ein Prozess wartet höchstens 30 Sekunden auf einen anderen, der die Tabellen anlegt oder aktualisiert. Danach antwortet eine Anfrage mit 503 und dem Code tables_busy, und ein Tracker-Aufruf wartet höchstens 10 Sekunden und wird dann verworfen.

MySQL und MariaDB

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

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

Dieser Store braucht mysql2 und funktioniert mit MySQL 8.0.20 oder neuer und MariaDB 11.4 oder neuer. Übergib eine URL mit mysql:// oder mariadb:// als url, oder übergib pool, um einen Pool aus mysql2/promise zu teilen, den deine App schon hat (Runlight beendet nie einen Pool, den es nicht selbst angelegt hat). Ein Pool braucht mindestens 2 Verbindungen. Wenn Runlight den Pool anlegt, legt max seine Verbindungen fest, standardmäßig 10. Eine Anfrage wartet höchstens 10 Sekunden auf eine freie (ein Tracker-Aufruf versucht es noch zweimal, bevor er aufgegeben wird), und statementTimeout stoppt jede einzelne Abfrage nach so vielen Millisekunden, standardmäßig 120000 (0 schaltet das aus). Unter MySQL gilt diese Grenze für Lesezugriffe, unter MariaDB für jede Anweisung. Wenn mehrere Prozesse gleichzeitig starten, werden die Tabellen trotzdem nur einmal angelegt. Ein Prozess wartet höchstens 30 Sekunden auf einen anderen, der die Tabellen anlegt oder aktualisiert. Danach antwortet eine Anfrage mit 503 und dem Code tables_busy, und ein Tracker-Aufruf wartet höchstens 10 Sekunden und wird dann verworfen.

Die Tabellen nutzen utf8mb4 mit der Kollation utf8mb4_0900_bin. Text wird nach Codepoint verglichen und sortiert, Groß- und Kleinschreibung und Leerzeichen am Ende bleiben erhalten, sodass jeder Bericht genauso aussieht wie unter SQLite oder Postgres.

libSQL und 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 }) });

Dieser Store braucht @libsql/client. Turso über HTTP funktioniert überall, wo fetch funktioniert, auch auf Vercel Edge und Deno Deploy, und eine file:-URL zeigt auf eine lokale SQLite-Datei.

Cloudflare D1

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

d1({ database: env.DB });

Übergib das D1-Binding aus der Umgebung deines Workers. D1 hat keine interaktiven Transaktionen, daher schreibt ein Link-Import jeden Link einzeln. Scheitert einer mittendrin, überspringt ein erneuter Import die schon geschriebenen Links.

Bun

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

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

Dieser Store nutzt das eingebaute SQLite von Bun, für Apps auf Bun, wo better-sqlite3 nicht lädt.

Optionen von runlight()

Websites

Ein Besuch von einem Hostnamen, den keine Website beansprucht, wird ignoriert. Eine Staging-Kopie deiner Website zählt also nicht, solange du ihren Hostnamen nicht hinzufügst.

Rate-Limit

Jeder Prozess zählt Tracker-Anfragen pro Besucheradresse über eine Minute und verwirft den Rest stillschweigend, damit ein Skript eine Website nicht mit erfundenen Besuchen fluten kann. Ein echter Besucher sendet ein paar Anfragen pro Minute, weit unter dem Standard von 120. Die Zählung liegt unter einer gehashten Adresse im Speicher und wird jede Minute geleert, es wird also nie eine Adresse aufbewahrt. Auf Hosts, die viele kurzlebige Kopien deiner App ausführen, etwa Cloudflare Workers, zählt jede Kopie für sich, dort ist die Grenze also lockerer.

Standort

Land, Region und Stadt kommen auf Vercel, Cloudflare und Netlify ohne Einrichtung aus den Headern deines Hosts. Anderswo übergibst du geo, eine Funktion, die eine IP-Adresse in einen Standort umwandelt. Dieses Beispiel stützt sich auf eine MMDB-Datei.

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

Die Adresse wird nach der Suche verworfen, nur der Ort bleibt.

Optionen von routes()

Die Optionen accountOf und tokenMade verbinden die Routen mit den eigenen Konten des eigenständigen Servers und sind intern.

Ohne Token antworten Dashboard und API mit 503, bis du eines setzt, außer wenn NODE_ENV gleich development ist. Das Erfassen von Besuchen, das Skript, Kurzlinks, Freigabelinks und Abbestell-Links brauchen das Token nie.

Konten

Schalte Konten ein, damit sich mehrere Personen im Dashboard anmelden können, jede mit eigener E-Mail, eigenem Passwort und eigener Rolle, genau wie beim eigenständigen Server.

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

Das Dashboard bittet dann alle, sich unter /runlight/login anzumelden. Um das erste Konto anzulegen, öffne /runlight/setup und gib dein RUNLIGHT_TOKEN zusammen mit deiner E-Mail und deinem Passwort ein, sodass das nur kann, wer die App betreibt. Dieses Konto ist der Eigentümer. In der Entwicklung ohne Token, oder mit token: null, was alles offen lässt, braucht das erste Konto kein Token. Leg es also an, bevor jemand anderes die Seite erreichen kann.

Der Eigentümer und die Admins laden unter Einstellungen, Personen weitere Personen ein, als Admin, Mitglied oder Betrachter, und die Einladung geht per E-Mail raus, wenn ein E-Mail-Dienst eingerichtet ist. Alle können unter Konto die Zwei-Faktor-Anmeldung einschalten. Das Token funktioniert für Skripte weiterhin als Bearer-Token.

Sitzungen werden mit RUNLIGHT_SECRET signiert, oder mit dem Token, wenn das nicht gesetzt ist. Halte es also über Neustarts und Deployments hinweg gleich. Passwörter werden mit scrypt gehasht, wo die Runtime es hat, wie Node, Bun und Deno, und mit PBKDF2 auf Edge-Runtimes wie Cloudflare Workers.

Wenn jemand sein Passwort vergisst, kann der Eigentümer oder ein Admin die Person entfernen und neu einladen. Wenn der Eigentümer seines vergisst, gib dem Konto ein neues aus einem Skript, das dein Runlight nutzt.

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);

Umgebungsvariablen