Changeset f889429 in Klonkt for docs/shaer-c2s-api.md

Timestamp:

08/07/2026 10:57:55 AM (5 weeks ago)

Author:

roboburr <roboburr@…>

Branches:

main

Children:

ea138c0

Parents:

31e63d1

git-author:

Robin <roboburr@…> (08/07/2026 10:57:53 AM)

git-committer:

roboburr <roboburr@…> (08/07/2026 10:57:55 AM)

Message:

Stilte kost nu niets: 304 als er niets veranderd is (shaer-n05)

Barts punt, en het legt een echte fout in mijn ontwerp bloot. De wachtende
inbox-lezing stuurde bij elke afloop van de wachttijd de VOLLEDIGE collectie
terug -- elke 25 seconden een tijdlijn over de mobiele verbinding om te zeggen
dat er niets gebeurd is. Dat is een slecht ruilmiddel voor het uitsparen van een
rondje.

Nu: 304 zonder body als de merksteen niet bewoog, de volle collectie als hij dat
wel deed. Daarmee is dit beter dan allebei de ontwerpen die op tafel lagen --
een apart seintje-endpoint kost bij nieuws twee rondjes, dit een.

DE '0'-UITZONDERING IS GEEN FRANJE. Ontbreekt ap_feed_state, dan geeft feedCursor
altijd '0' en zou een client hier eeuwig 304 krijgen en nooit meer inhoud zien.
Bij een lege merksteen gaat de collectie dus gewoon mee: trager, nooit fout.

Aan de clientkant moest de 304-tak VOOR de foutcontrole, anders telt stilte als
een storing en duwt hij de wachtlus in zijn oplopende pauze. En caps worden bij
een 304 NIET overschreven: een leeg antwoord draagt geen rechten, en die
klakkeloos overnemen zou de gated rechten terugzetten naar "alles mag". Vandaar
dat het antwoord nu expliciet changed draagt in plaats van dat de beller het uit
de cursor moet afleiden.

Suite 544/544.

File:

• docs/shaer-c2s-api.md (modified) (1 diff)

docs/shaer-c2s-api.md

@@ -96 +96 @@
 - Send neither and the route behaves exactly as it always did.
 
-The answer arrives as soon as anything the inbox would show has changed, or when
-`wait` runs out — whichever comes first. Either way it is the full, current
-collection with a fresh `shaer:cursor`. An empty-handed return is not an error:
-it means nothing happened, ask again.
+Two possible answers:
+
+| | |
+|---|---|
+| **`200`** | something changed. The full, current collection with a fresh `shaer:cursor`. |
+| **`304`** | nothing changed within `wait`. **No body.** Keep the cursor you have and ask again. |
+
+`304` is not an error — it is the normal answer to a quiet minute, and it is why
+this costs nothing while nothing happens. Sending the whole timeline back every
+`wait` seconds just to say "still nothing" would be a poor trade for saving one
+round trip.
+
+A server that has not run the feed-state migration yet cannot tell change from
+stillness, and answers `200` with the collection every time rather than `304`
+forever. Slower, never wrong.
 
 The cursor moves for **all four** sources this read merges: the timeline,