OBS/Kostenpflichtige Module/RESTServer/Scripting - Versionsgeschichte

MINERVA-Rademacker: Idempotenz bei 5xx berichtigt (Schluessel wird freigegeben), Pflichtheader und Dateiantwort ergaenzt [Volltext ersetzt]

2026-09-25T09:28:33Z

Idempotenz bei 5xx berichtigt (Schluessel wird freigegeben), Pflichtheader und Dateiantwort ergaenzt [Volltext ersetzt]

← Nächstältere Version		Version vom 25. September 2026, 10:28 Uhr
Zeile 424:		Zeile 424:
	==Idempotenz - was das Skript beachten muss==		==Idempotenz - was das Skript beachten muss==

	~~Sendet ein Konsument bei~~ ''POST''/''PUT''/''PATCH''/''DELETE'' den Header		Bei ''POST''/''PUT''/''PATCH''/''DELETE'' fängt der '''Server''' doppelte
	<code>Idempotency-Key</code>~~, fängt der '''Server''' doppelte Sendungen~~ ab. Das		Sendungen über den Header <code>Idempotency-Key</code> ab. Das Skript braucht dafür
	Skript braucht dafür '''keine eigene Logik''' - keine Schlüssel-Tabelle, keine		'''keine eigene Logik''' - keine Schlüssel-Tabelle, keine Prüfung am Anfang der
	Prüfung am Anfang der Methode.		Methode.

			{{Hinweis\|Der Header ist bei diesen vier Verben '''Pflicht'''. Fehlt er, antwortet
			der Server mit '''400''' <code>IDEMPOTENCY_KEY_MISSING</code> - das Skript läuft
			dann gar nicht erst an, es muss den Fall also auch nicht behandeln.}}

	Was das Skript wissen muss:		Was das Skript wissen muss:
Zeile 435:		Zeile 439:
	\|-		\|-
	\| '''2xx''' \|\| Statuscode, Body und Header werden gespeichert. Eine Wiederholung mit demselben Schlüssel bekommt genau diese Antwort zurück, das Skript läuft nicht erneut		\| '''2xx''' \|\| Statuscode, Body und Header werden gespeichert. Eine Wiederholung mit demselben Schlüssel bekommt genau diese Antwort zurück, das Skript läuft nicht erneut
			\|-
			\| '''2xx''' mit ''SendFile''/''SendTempFile'' \|\| '''Nichts''' wird gespeichert - eine Dateiantwort liesse sich nicht wiedergeben. Der Schlüssel wird freigegeben und ist danach wieder benutzbar
	\|-		\|-
	\| '''4xx''' \|\| Der Schlüssel wird '''freigegeben'''. Der Konsument darf denselben Schlüssel nach Korrektur des Inhalts erneut verwenden		\| '''4xx''' \|\| Der Schlüssel wird '''freigegeben'''. Der Konsument darf denselben Schlüssel nach Korrektur des Inhalts erneut verwenden
	\|-		\|-
	\| '''5xx''' oder Exception \|\| Der Schlüssel ~~bleibt belegt,~~ der Fall ~~wird~~ protokolliert. ~~Eine Wiederholung wird abgelehnt, bis der Fall geklärt ist~~		\| '''5xx''' oder Exception \|\| Der Schlüssel wird ebenfalls '''freigegeben''' und der Fall protokolliert. Der Konsument darf denselben Schlüssel erneut senden
	\|}		\|}

			{{Achtung\|'''Das 5xx-Verhalten wurde am 25.08.2026 gedreht.''' Vorher blieb der
			Schlüssel nach einem Serverfehler belegt - begründet mit „niemals eine
			Doppelbuchung". Das war falsch gewichtet: der Vorgang wurde damit
			'''unwiederholbar''', der Client bekam dauerhaft 503 und hätte die erfasste Arbeit
			verwerfen müssen. Garantierter Datenverlust wiegt schwerer als ein möglicher
			Doppelsatz.

			'''Folge für die Auslegung:''' Ein schreibender Endpunkt sollte selbst
			wiederholbar sein, etwa über ein fachliches Merkmal des Clients. Wo reines
			Anhängen stattfindet (Positionen, Dateien), bleibt sonst ein Restrisiko.}}

	Daraus folgen zwei Regeln für Endpunkt-Skripte:		Daraus folgen zwei Regeln für Endpunkt-Skripte:
Zeile 619:		Zeile 636:
	Wer beim Abmelden zusätzlich fachlich etwas tun will - eine Geräteregistrierung		Wer beim Abmelden zusätzlich fachlich etwas tun will - eine Geräteregistrierung
	löschen, einen Push-Token verwerfen, den Vorgang protokollieren - nimmt einen		löschen, einen Push-Token verwerfen, den Vorgang protokollieren - nimmt einen
	'''gewöhnlichen Endpunkt''' und ~~setzt~~ dort ''~~_OBS_JWT_REVOKE~~''. Dasselbe gilt für		'''gewöhnlichen Endpunkt''' und ruft dort ''oWriter.JwtRevoke''. Dasselbe gilt für
	"auf allen Geräten abmelden", weil das eine Berechtigungsentscheidung braucht:		"auf allen Geräten abmelden", weil das eine Berechtigungsentscheidung braucht:

Rademacker am 15. September 2026 um 10:00 Uhr

2026-09-15T10:00:28Z

← Nächstältere Version		Version vom 15. September 2026, 11:00 Uhr
Zeile 136:		Zeile 136:

	Ist gar kein Körper gesendet worden, liefert jeder Leser ''false'' und		Ist gar kein Körper gesendet worden, liefert jeder Leser ''false'' und
	''HasBody()'' ist ''false''. Maximale Body-Grösse: 10 MB.		''HasBody()'' ist ''false''. Maximale Body-Grösse: 10 MB - bei einem gepackt gesendeten Körper zusätzlich das 400fache der gesendeten Grösse, siehe [[OBS/Kostenpflichtige Module/RESTServer\|REST-Server]], Abschnitt Kompression. Beide Überschreitungen beantwortet der Server mit '''413''', das Skript läuft gar nicht erst an.

	===Werte des Servers===		===Werte des Servers===
Zeile 363:		Zeile 363:

	Zusätzlich trägt jede Antwort den Header '''X-Trace-Id''' (Korrelations-ID). Dieselbe ID liegt dem Skript als ''oReader.TraceId()'' vor und erscheint in jeder Server-Fehler-Logzeile in '''RESTSRV_PROTO''' - so lässt sich ein Fehler ohne Gerätezugriff im Log wiederfinden.		Zusätzlich trägt jede Antwort den Header '''X-Trace-Id''' (Korrelations-ID). Dieselbe ID liegt dem Skript als ''oReader.TraceId()'' vor und erscheint in jeder Server-Fehler-Logzeile in '''RESTSRV_PROTO''' - so lässt sich ein Fehler ohne Gerätezugriff im Log wiederfinden.

			Setzt ein Skript den Header '''Content-Encoding''' selbst - etwa weil es einen bereits gepackten Körper ausliefert -, hält sich die Engine heraus und packt die Antwort nicht noch einmal. Ohne diesen Header entscheidet der Server selbst, ob gzip zum Einsatz kommt.

	===Beispiel: Anlegen mit 201, Location und ETag===		===Beispiel: Anlegen mit 201, Location und ETag===

Rademacker am 14. September 2026 um 08:07 Uhr

2026-09-14T08:07:39Z

← Nächstältere Version		Version vom 14. September 2026, 09:07 Uhr
Zeile 356:		Zeile 356:
	\|-		\|-
	\| <code>oWriter.HasError()</code> \|\| Steht schon eine Fehlerantwort im Writer? Für einen Verteiler, der danach noch etwas anhängen will		\| <code>oWriter.HasError()</code> \|\| Steht schon eine Fehlerantwort im Writer? Für einen Verteiler, der danach noch etwas anhängen will
			\|-
			\| <code>oWriter.SendFile(cPfad, cName, cTyp)</code> \|\| Statt eines JSON-Körpers eine '''Datei''' ausliefern. Die Datei bleibt liegen, der Download ist wiederaufsetzbar. Siehe [[OBS/Kostenpflichtige Module/RESTServer/Datei-Download\|Datei-Download]]
			\|-
			\| <code>oWriter.SendTempFile(cPfad, cName, cTyp)</code> \|\| Wie <code>SendFile</code>, aber die Datei wird nach dem Senden '''gelöscht''' und der Download ist nicht wiederaufsetzbar - für Ergebnisse, die je Abruf entstehen (CSV-Export, Report)
	\|}		\|}

Rademacker am 9. September 2026 um 12:31 Uhr

2026-09-09T12:31:08Z

Änderungen zeigen

Rademacker am 1. September 2026 um 09:10 Uhr

2026-09-01T09:10:11Z

Änderungen zeigen

Rademacker am 31. August 2026 um 05:03 Uhr

2026-08-31T05:03:18Z

← Nächstältere Version		Version vom 31. August 2026, 06:03 Uhr
Zeile 23:		Zeile 23:
	function Patch (oParams: TStrings; oBody: TJSONObject): string;		function Patch (oParams: TStrings; oBody: TJSONObject): string;

	~~Nicht implementierte Methoden liefern automatisch~~ ''405''-~~ähnliche Fehler über~~ die ~~generische~~ Skript-Antwort.		Fehlt die zur Methode passende Funktion, antwortet der Server mit '''405 Method
			Not Allowed''' (<code>METHOD_NOT_ALLOWED</code>) und nennt im Header
			<code>Allow</code> die Verben, die dieses Skript tatsächlich anbietet - die Liste
			stammt aus dem kompilierten Skript und kann deshalb nicht veralten:

			HTTP/1.1 405 Method Not Allowed
			Allow: GET, PUT

			Ein im Vertrag zugesagtes Verb braucht also seine Funktion. Fehlt sie, ist das an
			der Antwort sofort zu erkennen und '''kein''' Serverfehler.

	==Parameter==		==Parameter==
Zeile 189:		Zeile 198:
	\|-		\|-
	\| _OBS_UPLOAD_CONTENTTYPE \|\| Content-Type der Datei (Default <code>application/octet-stream</code>, wenn der Client keinen angibt)		\| _OBS_UPLOAD_CONTENTTYPE \|\| Content-Type der Datei (Default <code>application/octet-stream</code>, wenn der Client keinen angibt)
			\|-
			\| _OBS_UPLOAD_SHA256 \|\| SHA-256 der '''gespeicherten''' Datei, hex in Kleinbuchstaben. Damit lässt sich eine vom Client mitgesendete Prüfsumme vergleichen - erst dieser Vergleich macht aus ihr eine Zusicherung
	\|}		\|}

Zeile 202:		Zeile 213:
	Eine Datei pro Request. Name und Content-Type stammen aus der		Eine Datei pro Request. Name und Content-Type stammen aus der
	<code>Content-Disposition</code> der Datei-Partie (<code>filename=</code>). Der		<code>Content-Disposition</code> der Datei-Partie (<code>filename=</code>). Der
	Server speichert die erste Datei-Partie und ruft das Skript auf:		Server speichert die erste Datei-Partie und ruft das Skript auf.

			Die '''übrigen Partien''' des Formulars - alles ohne <code>filename=</code> -
			übergibt der Server als <code>_OBS_FORM_<name></code>. Der Wert ist UTF-8 und
			auf 1024 Zeichen begrenzt, der Name auf Buchstaben, Ziffern und Unterstrich
			reduziert. Zusatzangaben lassen sich damit im selben Request mitschicken, ohne sie
			an die URL zu hängen:

	<syntaxhighlight lang="pascal" line>		<syntaxhighlight lang="pascal" line>

Rademacker am 19. August 2026 um 12:00 Uhr

2026-08-19T12:00:25Z

← Nächstältere Version		Version vom 19. August 2026, 13:00 Uhr
Zeile 559:		Zeile 559:
	====Refresh-Methode====		====Refresh-Methode====

	Der Refresh läuft über '''denselben JWT-Endpunkt''' und '''dasselbe Skript'''. Liegt am JWT-Endpunkt ein ''Authorization: Bearer <token>'' vor, ruft der Server statt ''Authenticate'' die Methode '''Refresh''' auf (~~sonst~~ Login).		Der Refresh läuft über '''denselben JWT-Endpunkt''' und '''dasselbe Skript'''. Liegt am JWT-Endpunkt ein ''Authorization: Bearer <token>'' mit einem Refresh-Token vor, ruft der Server statt ''Authenticate'' die Methode '''Refresh''' auf (ohne Bearer: Login; ''DELETE'' mit Access-Token: Abmelden, ohne Skript).

	Bevor das Skript läuft, hat der Server das vorgelegte Refresh-Token verifiziert		Bevor das Skript läuft, hat der Server das vorgelegte Refresh-Token verifiziert
Zeile 602:		Zeile 602:
	// Rolle und Mandant neu lesen, nicht aus dem alten Token uebernehmen -		// Rolle und Mandant neu lesen, nicht aus dem alten Token uebernehmen -
	// sonst wirkt ein Rechteentzug erst beim naechsten Login.		// sonst wirkt ein Rechteentzug erst beim naechsten Login.

	oRes.AddPair('status' , 1);		oRes.AddPair('status' , 1);
	oRes.AddPair('_OBS_JWT_ID' , cUser);		oRes.AddPair('_OBS_JWT_ID' , cUser);
Zeile 618:		Zeile 617:
	===Abmelden (Logout)===		===Abmelden (Logout)===

	~~Das~~ Abmelden ~~ist~~ ein ~~gewöhnlicher~~ Endpunkt - '''~~nicht~~''' ~~Teil des~~		'''Für das Abmelden braucht das Skript keine Methode.''' Es läuft über ein
	~~Authentifizierungs~~-~~Skripts. Er wird mit dem Access~~-Token ~~aufgerufen~~ und setzt		''DELETE'' auf denselben JWT-Endpunkt (Access-Token im ''Authorization''-Header)
	''_OBS_JWT_REVOKE'':		und wird komplett in der Engine erledigt: die Sitzung wird gesperrt, die Antwort
			ist 204. Eine Methode ''Logout'' gibt es nicht und wird nicht aufgerufen.
			Details: [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge\|Zugänge]], Phase 4.

			Wer beim Abmelden zusätzlich fachlich etwas tun will - eine Geräteregistrierung
			löschen, einen Push-Token verwerfen, den Vorgang protokollieren - nimmt einen
			'''gewöhnlichen Endpunkt''' und setzt dort ''_OBS_JWT_REVOKE''. Dasselbe gilt für
			"auf allen Geräten abmelden", weil das eine Berechtigungsentscheidung braucht:

	<syntaxhighlight lang="pascal" line>		<syntaxhighlight lang="pascal" line>
Zeile 628:		Zeile 634:
	oRes := TJSONObject.Create();		oRes := TJSONObject.Create();
	try		try
			GeraeteRegistrierungLoeschen(oParams.Values['_OBS_JWT_SUBJECT']);

	// 'session' = diese Sitzung, 'all' = alle Sitzungen des Subjects		// 'session' = diese Sitzung, 'all' = alle Sitzungen des Subjects
	oRes.AddPair('_OBS_JWT_REVOKE' , 'session');		oRes.AddPair('_OBS_JWT_REVOKE' , 'session');
Zeile 638:		Zeile 646:
	</syntaxhighlight>		</syntaxhighlight>

	Gesperrt wird die '''ganze Sitzung''', also auch die noch nicht abgelaufenen		Gesperrt wird in beiden Wegen die '''ganze Sitzung''', also auch die noch nicht
	Access-Token vorheriger Erneuerungen. Ein wiederholter Aufruf ist unschädlich.		abgelaufenen Access-Token vorheriger Erneuerungen. Ein wiederholter Aufruf ist
	Lässt sich die Sitzung nicht sperren, überschreibt der Server die Antwort des		unschädlich. Lässt sich die Sitzung nicht sperren, überschreibt der Server die
	Skripts mit '''503''' - ein Client darf nicht glauben, er sei abgemeldet, während		Antwort des Skripts mit '''503''' - ein Client darf nicht glauben, er sei
	sein Token weiterläuft.		abgemeldet, während sein Token weiterläuft.

	==Fehlerbehandlung im Skript==		==Fehlerbehandlung im Skript==

Rademacker am 19. August 2026 um 10:14 Uhr

2026-08-19T10:14:28Z

Änderungen zeigen

Rademacker am 17. August 2026 um 08:15 Uhr

2026-08-17T08:15:19Z

Änderungen zeigen

Rademacker am 17. August 2026 um 06:51 Uhr

2026-08-17T06:51:19Z

Änderungen zeigen