julian.kiedaischandClaude Opus 5.5
416d5fdea3
test-filius refused every ticket as from the future: its clock was 886 ms behind the dashboard's machine, with NTP still 8 ms (one ticket in 125, as a ticket carries whole seconds). F now takes a ticket signed up to 5 s ahead (TICKET_AHEAD_SECONDS); itsdangerous refuses one second, and the oracle keeps that on record. tools/live measures and accepts on a live F, with fresh projects each run: m3 (200 rooms of the largest example with pings: probe p95 37 ms), m4 (63 KB document; dragging makes an update per pointer move, 59/s), m5 (an hour through the proxy), acceptance (two browsers, 14 checks, passed three times) and clock (F's clock against ours). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
98 lines
5.5 KiB
Markdown
98 lines
5.5 KiB
Markdown
# mdg-filius
|
|
|
|
Netzwerksimulation nach [FILIUS](https://www.lernsoftware-filius.de) für den
|
|
Browser — als App „Filius" im MDG-Dashboard, gemeinsam bearbeitbar.
|
|
|
|
> Based on Filius by Dr. Stefan Freischlad and the Filius project.
|
|
>
|
|
> Dieses Projekt ist unabhängig. Es wird weder vom ursprünglichen
|
|
> Filius-Projekt (Universität Siegen) noch von `filius-project`
|
|
> (Filius on iPad) herausgegeben, betrieben oder unterstützt.
|
|
|
|
## Herkunft
|
|
|
|
Der Simulationskern ist eine Übertragung nach TypeScript aus
|
|
|
|
* [`filius-project/filius-ipad`](https://github.com/filius-project/filius-ipad)
|
|
(Swift, GPLv2 oder GPLv3) — Vorlage für Kern, `.fls`-Codec und Tests,
|
|
* [`filius1/filius`](https://gitlab.com/filius1/filius) (Java, GPLv2 oder
|
|
GPLv3) — Referenz für Dateiformat und Verhalten.
|
|
|
|
Jede übertragene Datei nennt in ihrem Kopf die Quelldatei. `CHANGES.md` führt
|
|
die Herkunft je Paket. Lizenz dieses Repos: **GPL-3.0** (`LICENSE`).
|
|
|
|
## Aufbau
|
|
|
|
| Pfad | Inhalt |
|
|
| --- | --- |
|
|
| `packages/core` | Simulationskern: Modell, Ereignis-Warteschlange, Protokolle, Anwendungen — ohne DOM, ohne Node |
|
|
| `packages/fls` | `.fls` lesen, schreiben, Unbekanntes bewahren |
|
|
| `packages/doc` | gemeinsames Dokument (Yjs): Projekt ⇄ Dokument, Schnappschuss des Kerns, Hausmeister, die Änderungen der Werkzeuge und des Geräte-Blatts (mit Javas Eingabeprüfung) |
|
|
| `packages/protocol` | die eine Nachrichtenliste zwischen Editor und Simulationsraum (`/sim`) |
|
|
| `packages/sim` | Simulationsraum (für Server F und den Web Worker) und `LocalSimHost` |
|
|
| `packages/editor` | Oberfläche im Iframe des Dashboards (React, Vite), auf einem Projekt von F (`?project=<uuid>`) oder mit einem Raum in der eigenen Seite (Entwicklung): Fläche, Palette, Werkzeuge des Entwurfs, Geräte-Blatt, Aktionsmodus (Desktops, Anwendungen, Datenaustausch), Dokumentationsmodus (Text, Gliederungsfläche, Bild exportieren, Bericht als PDF); `npm run dev -w @mdg-filius/editor` öffnet die Entwicklungsseite |
|
|
| `packages/server` | Filius-Dienst auf Server F: gemeinsame Dokumente über Hocuspocus (`/sync`), gespeichert in Postgres (Stand und Aktualisierungen, verdichtet), Hausmeister; Anmeldung mit der Eintrittskarte des Dashboards (`/__auth`, Keks, Lese- und Schreibstufe); Dienstweg des Dashboards (`/svc/*`: Projekte anlegen, löschen, einfrieren, Zugänge widerrufen); Simulationsräume auf `/sim` in `worker_threads`, einer je Projekt für alle; `/healthz`; liefert Seite und Bundle des Editors aus (`editor/` neben `main.mjs`, vorab gepackt); `npm run build -w @mdg-filius/server` bündelt ihn nach `dist/main.mjs` und den Faden der Räume nach `dist/simWorker.mjs` |
|
|
| `deploy` | Image (`Dockerfile`), ein Stack je Umgebung (`docker-compose.yml`, `*.env.example`), Eintrag für den externen OpenResty (`proxy.conf`) |
|
|
|
|
Plan und Entscheidungen: `knowledge/plans/FILIUS_WEB_PLAN.md` im Dashboard.
|
|
|
|
## Entwickeln
|
|
|
|
```bash
|
|
npm install
|
|
npm run hooks # Sprachprüfung vor jedem Commit (braucht das Dashboard drumherum)
|
|
npm run check # Typprüfung + Tests (die Server-Tests starten eine Wegwerf-Postgres in Docker, oder nehmen FILIUS_TEST_DATABASE_URL)
|
|
npm run test:browser # Tests im echten Browser (Playwright: Chromium; der Touch-Test auch in WebKit als iPad hoch und quer)
|
|
```
|
|
|
|
Server F braucht zum Start `DATABASE_URL`, `FILIUS_TICKET_SECRET` (mit dem
|
|
Dashboard geteilt, das die Karten signiert), `FILIUS_SERVICE_KEY` (der
|
|
Schlüssel des Dashboards für `/svc/*`) und `FILIUS_ORIGINS` (die Herkünfte
|
|
des Editors, durch Kommas getrennt); `FILIUS_PORT` ist 8080, wenn nicht
|
|
gesetzt. Fehlt eine davon, startet er nicht. Ohne HTTPS (Entwicklerrechner)
|
|
setzt `FILIUS_INSECURE_COOKIE=1` den Keks ohne `Secure`.
|
|
|
|
## Betrieb
|
|
|
|
Zwei Docker-Stacks auf Server F, je mit eigener Datenbank, eigenem
|
|
`FILIUS_TICKET_SECRET` und `FILIUS_SERVICE_KEY`:
|
|
|
|
| Name | Port | gehört zu |
|
|
| --- | --- | --- |
|
|
| `test-filius.hub.mdg-hamburg.de` | 8081 | `test-dashboard` |
|
|
| `filius.hub.mdg-hamburg.de` | 8080 | `dashboard` |
|
|
|
|
Im Klon auf F, je Umgebung einmal:
|
|
|
|
```bash
|
|
cp deploy/test.env.example deploy/test.env # leere Werte füllen
|
|
docker compose -f deploy/docker-compose.yml --env-file deploy/test.env up -d --build
|
|
```
|
|
|
|
(für die Produktion dasselbe mit `production`). Die Umgebungsdatei bestimmt
|
|
Stack-Namen, Volume, Image-Tag und Port; die beiden Stacks teilen nichts.
|
|
Braucht Docker Compose v2. Gesichert werden muss nur das Volume
|
|
`<stack>_db` (Befehl in `deploy/docker-compose.yml`).
|
|
|
|
`deploy/proxy.conf` ist der Eintrag für den externen OpenResty (in dessen
|
|
`conf.d`); vorher die Adresse von F für `filius-lxc.invalid` einsetzen.
|
|
`FILIUS_ORIGINS` ist jeweils der eigene Name mit `https://`.
|
|
|
|
**Die Uhr von F muss per NTP laufen** (beim LXC: die des Proxmox-Hosts).
|
|
Eine Eintrittskarte trägt ganze Sekunden; F nimmt sie bis 5 s vor seiner
|
|
Uhr. Ging F 886 ms nach, scheiterte fast jede Anmeldung.
|
|
`node tools/live/clock.mjs <adresse> <port>` misst den Versatz.
|
|
|
|
Messen und Abnehmen an einem laufenden F: `tools/live/` (`m3.ts` Last,
|
|
`m4.ts` Dokumentgröße, `m5.ts` Dauerverbindung, `acceptance.ts` zwei
|
|
Browser in einem Projekt) mit den Geheimnissen der Umgebung in
|
|
`/root/.filius-test.env`; jeder Lauf legt frische Projekte an und löscht sie.
|
|
|
|
Das Image liefert auch den Editor aus: F nimmt den Ordner `editor/` neben
|
|
`main.mjs` (anderswo `FILIUS_EDITOR_DIR`). Es läuft auf Node 24, die
|
|
Entwicklung auf Node 20; vor einem Update einmal mit
|
|
`docker compose … up --build` auf `test-filius` prüfen.
|
|
|
|
Code, Kommentare und Testnamen sind englisch; sichtbare Texte stehen hinter
|
|
i18n-Schlüsseln (Deutsch/Englisch).
|