HarmenandClaude Opus 5
de955b607d
Het plan is gepromoveerd naar Actief/003-Testclient en tier A, en fase 1 is af. De uitkomst die het plan als eerste wilde weten: @evolu/nodejs 3.1.0 bevat geen client. Het pakket levert de relay plus losse bouwstenen, maar er is geen createEvoluDeps voor Node zoals @evolu/web die voor de browser heeft. De afhankelijkheden voor createEvolu worden nu samengesteld in tools/relay-client/src/evolu-node.js, uit de in-memory workers van @evolu/common; src/client.js is de publieke kant met eigenaars en blobs. Vier dingen zaten in de weg en alle vier faalden ze stil, met een instantie die het lijkt te doen tot de eerste schrijfactie: de ontbrekende installPolyfills (Node 24 mist Map.getOrInsertComputed), createEvoluDeps overslaan, de AsyncDisposableStack van initSharedWorker laten vallen, en workers zonder eigen reportDefect. Dat laatste is waarom de andere drie te vinden waren. Uitgeschreven in PLAN.md 4e. tests/test_client_lokaal.mjs schrijft daarom een blob weg en leest hem terug in plaats van alleen een instantie te maken, en heeft een wachthond: bij een defect in een worker blijft de suite anders hangen in plaats van rood te worden, en dat gebeurde bij de mutatietoets letterlijk. Beide mutaties lieten de juiste toets omvallen. Nog niet geprobeerd: praten met de relay. Daarvoor is het adres van de Umbrel nodig en dat komt van de gebruiker; het gaat niet in deze publieke repo. Suite: 405 goed, 0 fout over alle acht de toetsen. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
147 lines
9.3 KiB
Markdown
147 lines
9.3 KiB
Markdown
# Testclient - masterplan
|
|
|
|
> **App: Evolu Relay.** Status: nog niet actief. Dit is één bestand en dat is bewust: er wordt nog niet aan
|
|
> gewerkt. Bij promotie naar `Plannen/Actief/NNN-Testclient/` worden de paragrafen hieronder over de vier
|
|
> bestanden verdeeld; zie `HomeGit/Docs/Werkproces.md` §1b.
|
|
>
|
|
> Afhankelijk van: niets. De relay draait sinds 28-08-2026 en de haken die dit plan beproeft bestaan al.
|
|
|
|
## 1. Doel
|
|
|
|
Een eigen cliënt waarmee je meerdere eigenaars kunt aanmaken, ze op de relay kunt laten verbinden en er
|
|
gegevens doorheen kunt duwen, om het toegangsbeleid en de opslag te beproeven zonder Trezor Suite en zonder
|
|
hardware.
|
|
|
|
Aanleiding: Suite is vandaag de enige cliënt, en die vraagt een apparaat dat aan het toestel kan (zie
|
|
[Upstream-evolu-relay.md](../../Referenties/Upstream-evolu-relay.md) §9). Daardoor rust een deel van wat we
|
|
over deze app opschrijven op redenering in plaats van op een proef. Het scherpste voorbeeld staat in §10 van
|
|
datzelfde document: blokkeren werkt pas bij de volgende verbinding. Dat is uit de broncode afgeleid en nooit
|
|
gezien.
|
|
|
|
## 2. Afbakening
|
|
|
|
Een programma dat buiten de Umbrel draait, op de laptop, en dat via de gepubliceerde relay-poort verbindt.
|
|
Meerdere eigenaars naast elkaar, elk met een eigen sleutelmateriaal en een eigen lokale database. Eén
|
|
bedieningsvlak waarin je die eigenaars ziet en aanstuurt.
|
|
|
|
## 3. Niet-doelen
|
|
|
|
- **Geen tweede relay en geen wijziging aan de app.** Als dit plan een aanpassing in `tools/evolu-relay/`
|
|
nodig lijkt te hebben, is dat een aanwijzing dat er iets misgaat in de opzet, niet een taak. De relay
|
|
wordt beproefd zoals hij draait.
|
|
- **Geen ontcijfering van gegevens van Trezor Suite.** De cliënt maakt eigen sleutels en leest zijn eigen
|
|
gegevens. Wat Suite op de relay zet blijft onleesbaar, en dat is de belofte in het manifest. Zie
|
|
`CLAUDE.md`, "Zet geen ontcijfering in deze app", en §11 van het naslagdocument.
|
|
- **Geen onderdeel van de app store.** Dit is gereedschap in `tools/` en het gaat nooit in een image of in
|
|
een app-map mee.
|
|
- **Geen nabouw van het protocol.** Net als bij de relay geldt: `@evolu/common` doet het werk, wij roepen
|
|
het aan.
|
|
|
|
## 4. Ontwerp
|
|
|
|
### 4a. Een eigenaar is een mnemonic plus een eigen map
|
|
|
|
Evolu leidt een `AppOwner` af uit een mnemonic. Een tweede eigenaar is dus niets anders dan een tweede
|
|
mnemonic met een eigen SQLite-bestand ernaast; er is geen accountbegrip dat gedeeld moet worden. De cliënt
|
|
bewaart per eigenaar een map met de mnemonic en de database, onder een pad dat in `.gitignore` staat.
|
|
|
|
Dat sleutelmateriaal is van deze proefopstelling en heeft geen waarde buiten de relay, maar het blijft
|
|
sleutelmateriaal: het staat niet in de repo en het wordt niet in een logregel afgedrukt. Het `OwnerId` wel,
|
|
want dat is publiek en je hebt het nodig om de eigenaar op de statuspagina terug te vinden (§1b van het
|
|
naslagdocument).
|
|
|
|
### 4b. Eén bedieningsvlak voor de cliënt
|
|
|
|
**Alles wat de cliënt doet, gebeurt vanuit één scherm.** Geen losse opdrachten per eigenaar en geen tweede
|
|
terminal ernaast: je ziet de eigenaars in een lijst en bedient ze daar. Wat dat scherm kan:
|
|
|
|
| Onderdeel | Wat je ziet of doet |
|
|
|-|-|
|
|
| De lijst | per eigenaar zijn naam, zijn `OwnerId`, of hij verbonden is, wanneer er voor het laatst iets over de lijn ging, en hoeveel er geschreven is |
|
|
| Per eigenaar | aanmaken, verbinden, verbreken, een blob schrijven met een instelbare omvang, teruglezen, en weggooien |
|
|
| Het log | wat er per verbinding gebeurt, met tijdstip. Dit is waar de proeven uit §4c af te lezen zijn |
|
|
| De relay | het adres waarmee verbonden wordt, en of hij een verbinding aanneemt |
|
|
|
|
Vorm: een kleine HTTP-server in hetzelfde proces met één pagina ervoor, in de stijl van de statuspagina's
|
|
van beide apps. Geen bouwstap en geen framework; die pagina's laten zien dat dat hier genoeg is. De
|
|
opdrachtregel blijft eronder bestaan, want stap 2 van §5 heeft hem toch nodig en het is prettig om een proef
|
|
te kunnen scripten.
|
|
|
|
**Aan de server-app wordt niets gedaan.** Bevestigd door de gebruiker op 09-09-2026: die draait en
|
|
synchroniseert met Trezor Suite op de Mac. Dit plan raakt `tools/evolu-relay/` dus niet, en een bevinding
|
|
uit §4c is materiaal voor **Umbrelapp**, geen taak hier.
|
|
|
|
**Eén grens om te kennen voordat iemand er knoppen bij wil zetten:** de leerstand openzetten, blokkeren en
|
|
labelen kán deze UI niet, en dat is de poortindeling van de app en geen tekortkoming van het gereedschap.
|
|
De relay publiceert hostpoort 3852 en daar praat de cliënt mee, maar de agent-API (`GET /api/status`,
|
|
`POST /api/command`, `POST /api/label`) hangt achter `app_proxy` met de inlog van umbrelOS, en poort 8000
|
|
staat niet op de host. Dat blijft dus op de statuspagina van de app, in een tweede tabblad. Het omzeilen
|
|
daarvan zou een onbeschermde poort vragen, en dat haalt precies de bescherming weg waarvoor de poorten in
|
|
0.0.2 omgedraaid zijn (`CLAUDE.md`, "De poorten staan omgekeerd ten opzichte van wat je verwacht").
|
|
|
|
### 4c. Wat er dan te beproeven valt
|
|
|
|
Dit is de eigenlijke opbrengst, en elk punt is vandaag niet te proberen:
|
|
|
|
| Proef | Wat er hoort te gebeuren | Waar het vandaan komt |
|
|
|-|-|-|
|
|
| Onbekende eigenaar, venster dicht | HTTP 401, socket dicht, niets in de database van de relay, wel een regel in de weigerlijst | §10 van het naslagdocument, afgeleid uit de broncode |
|
|
| Diezelfde eigenaar toelaten en opnieuw verbinden | de hele geschiedenis komt alsnog binnen, want de cliënt was niets kwijt | §10, punt 3 |
|
|
| Blokkeren tijdens een lopende verbinding | de eigenaar blijft schrijven tot hij opnieuw verbindt | §10, punt 4. Open punt 10 van **Umbrelapp** |
|
|
| Venster van twee minuten, met de pagina dicht | de teller loopt in het relay-proces en sluit vanzelf | `CLAUDE.md`, "Het tijdvenster loopt in het relay-proces" |
|
|
| Eén blob boven `RELAY_MAX_WRITE_BYTES` (1 MB) | geweigerd; meerdere kleinere samen niet, want de grens is per schrijfactie | §8 van het naslagdocument |
|
|
| Twee eigenaars die tegelijk verbinden | onafhankelijk, en elk ziet alleen zijn eigen gegevens | §1b |
|
|
|
|
Wat er als bijvangst uit kan komen, en dat is de reden om de proeven echt te dóen: `owners.json` groeit hier
|
|
voor het eerst voorbij één of twee regels, en de statuspagina is nog nooit met een handvol eigenaars en een
|
|
volle weigerlijst gezien.
|
|
|
|
### 4d. Waar het staat, en wat het niet raakt
|
|
|
|
`tools/relay-client/`, met een eigen `package.json`. Niet in een app-map, want alles daar wordt bij
|
|
installatie naar het apparaat gekopieerd (`CLAUDE.md`, "Zet geen CLAUDE.md of andere werkbestanden in een
|
|
app-map"). Geen `VERSION`, geen image, geen manifest: er is niets uit te rollen, dus de versieregels van de
|
|
twee apps gelden hier niet.
|
|
|
|
## 5. Het werk in grote lijnen
|
|
|
|
1. **De cliënt-API van `@evolu/common` 8.7.0 verifiëren.** Een eigenaar uit een mnemonic, een schema met een
|
|
kolom waar een blob in past, en verbinden met een `syncUrl`. Dit staat expres eerst: van de relaykant is
|
|
alles nagetrokken, van de cliëntkant niets. Valt die API tegen, dan verandert de rest van dit plan.
|
|
2. Een kale opdrachtregel die één eigenaar maakt, verbindt en schrijft. Dat is het moment waarop bekend is
|
|
of het werkt.
|
|
3. Meerdere eigenaars naast elkaar, elk in een eigen map, met een register erbij.
|
|
4. De UI eromheen: de lijst, de knoppen per eigenaar, en de meldingen uit de verbinding.
|
|
5. De proeven uit §4c lopen, en de uitkomsten terugschrijven naar de plek waar de bewering nu staat: §10 van
|
|
het naslagdocument en open punt 10 van **Umbrelapp**.
|
|
|
|
## 6. Open punten
|
|
|
|
1. **Hoe zichtbaar is een 401 in de cliënt?** Evolu probeert opnieuw en is ontworpen om een relay te
|
|
overleven die er niet is. Als een weigering en een relay die plat ligt in de cliënt hetzelfde signaal
|
|
geven, is de eerste proef uit §4c niet af te lezen. De uitweg blijft binnen dit gereedschap: een eigen
|
|
WebSocket-poging naast Evolu, met dezelfde `OwnerId` in de URL, die de statuscode wel te zien krijgt.
|
|
Dat is een handeling van een paar regels, want de `OwnerId` staat in de URL van de verbinding (§10 van
|
|
het naslagdocument).
|
|
2. **Wat is een zinnige blob om mee te experimenteren?** Willekeurige bytes zijn genoeg voor de bytegrens,
|
|
maar niet om te zien of gegevens werkelijk heen en weer gaan. Iets met leesbare inhoud en een teller is
|
|
waarschijnlijk beter.
|
|
3. **Wordt de gegevensmap van de proef opgeruimd?** Twintig eigenaars die blijven staan is rommel, en het
|
|
is sleutelmateriaal. Waarschijnlijk een opdracht die er één weggooit en één die alles weggooit.
|
|
4. **Data per eigenaar wissen op de relay staat al open bij Umbrelapp.** Dit gereedschap maakt dat makkelijk
|
|
te beproeven maar lost het niet op; het blijft schrijven in andermans schema (§8 van het naslagdocument).
|
|
|
|
## 7. Verificatie
|
|
|
|
**Wat automatisch kan is klein en dat is eerlijk om vooraf te zeggen.** Het meeste van dit gereedschap is
|
|
netwerk en UI. Wat wél in de suite hoort:
|
|
|
|
- het register van eigenaars: aanmaken, teruglezen, een naam die al bestaat, een map die half is;
|
|
- het afleiden van een `OwnerId` uit een mnemonic, met een vaste mnemonic en een vaste verwachte uitkomst.
|
|
Dat is de toets die omvalt als de bibliotheek onder ons iets anders gaat doen;
|
|
- het lezen van de opdrachtregel.
|
|
|
|
Alles wat een relay nodig heeft is handwerk, en dat is precies het doel van dit plan: de proeven uit §4c
|
|
worden met de hand gedaan en de uitkomst wordt opgeschreven. Een groene suite zegt hier dus weinig, en de
|
|
uitslag van dit plan staat in de documenten die het corrigeert.
|