2019-03-22T18:11:56.768840842
2019-04-25T21:29:14.586349670
PT4H27M40S
185
LibreOffice/6.2.3.2$Linux_X86_64 LibreOffice_project/20$Build-2

# Netzwerkprotokoll

1.3.0
92530
0
14314
21770
true
false
view2
2501
20950
0
92530
14312
114298
0
1
false
100
false
false
false
false
false
false
false
false
true
true
true
0
true
false
true
false
true
false
false
true
false
false
192011
false
false
true
true
false
false
true
true
true
true
true
false
false
de
DE
true
false
false
1
0
0
false
true
false
false
false
false
false
false
false
true
false
high-resolution
true
true
true
false
true
false
true
false
false
false
false
true
false
false
true
false
true
3934329
true
false
false
true
false
false
false
true
false
false
false
true
false
false
false
AAEAAAAQAQAABAAARkZUTWkDcA0AAyoMAAAAHEdERUYE8wkPAAMptAAAAFZPUy8yUL7s9wAA [encoded data, 303281 characters] AAAAAQAAAAEAAAAAAAAAAQAAAADURmmjAAAAAMBkEbcAAAAA1Fj0sg==
AAEAAAARAQAABAAQR0RFRoPydSYABzQoAAAFEEdQT1OnXngWAAc5OAABIJ5HU1VCNVXTdgAI [encoded data, 812199 characters] AAAAAQAIAAEABgxyAAEAAQATAAEAAAABAAgAAQAGC1AAAQABAUEAAA==
AAEAAAARAQAABAAQR0RFRoPydSYAB4EMAAAFEEdQT1OGQmKLAAeGHAABH0hHU1VCNVXTdgAI [encoded data, 840552 characters]
AAEAAAARAQAABAAQR0RFRvVN2ToAB9xYAAAE9kdQT1Mjah5qAAfhUAABKJBHU1VCzwZh5wAJ [encoded data, 878638 characters] CIcIhAiFAAEABgBJB9QH1QfWB9cH2AABAAAAAQAIAAEABgmAAAEAAQFB
AAEAAAARAQAABAAQR0RFRvVN2ToACBcEAAAE9kdQT1NBz2RdAAgb/AABKFRHU1VCzwZh5wAJ [encoded data, 900588 characters]
AAEAAAARAQAABAAQR0RFRuFh5UEAAotwAAACtEdQT1PKV4glAAKOJAAAGypHU1VCP1wkyQAC [encoded data, 309352 characters]
AAEAAAARAQAABAAQR0RFRuFh5UEAAqA0AAACtEdQT1PdcpZ2AAKi6AAAG2ZHU1VC7cbXcgAC [encoded data, 320108 characters] A8YAAgAEA1cDaAAAA3UDdwASA5kDmQAVA8UDxQAW
T1RUTwAMAIAAAwBAQ0ZGILmRse4AAFtAAAFfMUdERUZO81E/AAG6dAAAAIBHUE9TNEuxaAAB [encoded data, 183833 characters]
T1RUTwAMAIAAAwBAQ0ZGIKQZSBEAAFtMAAFr/EdERUZO81E/AAHHSAAAAIBHUE9TAsnA9QAB [encoded data, 188652 characters]
T1RUTwAMAIAAAwBAQ0ZGILmRse4AAFtAAAFfMUdERUZO81E/AAG6dAAAAIBHUE9TNEuxaAAB [encoded data, 183833 characters]
T1RUTwAMAIAAAwBAQ0ZGIKQZSBEAAFtMAAFr/EdERUZO81E/AAHHSAAAAIBHUE9TAsnA9QAB [encoded data, 188652 characters]
AAEAAAASAQAABAAgRkZUTXlD5jUABJMIAAAAHEdERUZxBHoIAASTJAAAAIZHUE9Tdb9a4gAE [encoded data, 458990 characters]
AAEAAAASAQAABAAgRkZUTXlRG3cABGWMAAAAHEdERUZxBHoIAARlqAAAAIZHUE9TelVg1AAE [encoded data, 441926 characters] BO4AAQAFBP8FAAUKBRMFHAAA
AAEAAAASAQAABAAgRkZUTXlRHTQAA/08AAAAHEdERUZxBHoKAAP9WAAAAIZHUE9TeC9YZgAD [encoded data, 402888 characters]
AAEAAAASAQAABAAgRkZUTXlRQzcABAgcAAAAHEdERUZxBHoKAAQIOAAAAIZHUE9TeWZZsAAE [encoded data, 406929 characters] AAIE7gABAAUE/wUABQoFEwUcAAA=
AAEAAAATAQAABAAwRkZUTXlFdFwABe5gAAAAHEdERUZ0NH3vAAWh5AAAAIZHUE9T1cxb3AAF [encoded data, 568563 characters] AMj/OAABAAEE3AAAAAAAAQAAAADYXfhYAAAAAMhE0M4AAAAA2KKrNQ==
AAEAAAATAQAABAAwRkZUTXAcA18ABZNkAAAAHEdERUZ0NH3vAAVG4AAAAIZHUE9TCFBVnwAF [encoded data, 534514 characters] AADYXfhYAAAAAL8bYfAAAAAA2KKpFg==
AAEAAAATAQAABAAwRkZUTXAcBK8ABakAAAAAHEdERUZ0ZH4nAAVcvAAAAIZHUE9TOAS9AAAF [encoded data, 542643 characters]
AAEAAAATAQAABAAwRkZUTXAcA90ABas0AAAAHEdERUZ0PH36AAVeoAAAAIZHUE9TFedE+AAF [encoded data, 543441 characters] AAAAAL8bYfAAAAAA2KKplA==
AAEAAAATAQAABAAwRkZUTXlFdFwABe5gAAAAHEdERUZ0NH3vAAWh5AAAAIZHUE9T1cxb3AAF [encoded data, 568563 characters] AMj/OAABAAEE3AAAAAAAAQAAAADYXfhYAAAAAMhE0M4AAAAA2KKrNQ==
AAEAAAATAQAABAAwRkZUTXAcA18ABZNkAAAAHEdERUZ0NH3vAAVG4AAAAIZHUE9TCFBVnwAF [encoded data, 534514 characters] AADYXfhYAAAAAL8bYfAAAAAA2KKpFg==
AAEAAAATAQAABAAwRkZUTXAcBK8ABakAAAAAHEdERUZ0ZH4nAAVcvAAAAIZHUE9TOAS9AAAF [encoded data, 542643 characters]
AAEAAAATAQAABAAwRkZUTXAcA90ABas0AAAAHEdERUZ0PH36AAVeoAAAAIZHUE9TFedE+AAF [encoded data, 543441 characters] AAAAAL8bYfAAAAAA2KKplA==
AAEAAAAUAQAABABARkZUTXPB9PAAAAFMAAAAHEdERUaUz47mAAABaAAAApRHUE9TVoDENQAA [encoded data, 1107497 characters]
AAEAAAATAQAABAAwRkZUTXPB9PAAAAE8AAAAHEdERUaNwIfxAAABWAAAAjhHUE9T1BxgqAAA [encoded data, 1032293 characters] KysrKysrKysrKx0A
AAEAAAARAQAABAAQR0RFRuFh5UEAAotwAAACtEdQT1PKV4glAAKOJAAAGypHU1VCP1wkyQAC [encoded data, 309352 characters]
AAEAAAARAQAABAAQR0RFRuFh5UEAAqA0AAACtEdQT1PdcpZ2AAKi6AAAG2ZHU1VC7cbXcgAC [encoded data, 320108 characters] A8YAAgAEA1cDaAAAA3UDdwASA5kDmQAVA8UDxQAW

TextureSync

# Netzwerkprotokoll

⸬ Version 1.3.0 Seite 4/11

Netzwerk-Protokoll

TextureSync

Version

1.3.0

Datum

25.04.2019

Autor

Robin Willmann

Projektmitglieder

Hendrik Schutter,

Lukas Fürderer,

Robin Willmann,

Jannik Seiler

Inhaltsverzeichnis

Inhaltsverzeichnis

1 Grundsätzliches3

1.1 Ports3

1.2 Paketformat3

2 Befehle4

2.1 Definitionen4

2.2 Ping6

2.3 Query6

2.4 Get Texture7

2.5 Get Texture File7

2.6 Get Texture Preview8

2.7 Replace Texture9

3 Fehlerhandhabung10

4 Changelog11

5 Anmerkungen11

Grundsätzliches

Es wird eine Client-Server-Architektur verwendet. Um das Netzwerkprotokoll möglichst einfach und debuggbar zu halten, bietet sich JSON über TCP an. Dieses wird in eine eigene Paketstruktur verpackt, um so auch große Binär-Daten (z.B. Texturen) über die selbe Verbindung zu übertragen.

Eine Verbindung wird immer vom Client initiiert. Nach jeder Anfrage kann der Client die Verbindung für weitere Anfragen offen halten oder diese zur Beendigung schließen.

Der Server schließt Verbindungen bei Verletzungen des Protokolls oder wenn mindestens 10 Minuten lang kein Datenaustausch mehr stattgefunden hat.

Ports

Der Server verwendet TCP-Port 10796 für eingehende Verbindungen. Es wird sowohl IPv6 als auch IPv4 akzeptiert.

Paketformat

Daten werden über TCP gesendet. Da TCP stream-based ist, wird folgende Struktur verwendet, um Pakete zu emulieren.

<Payload-Typ : 1 byte><Reseviert : 3 bytes><Payload-Länge : 4 bytes><Payload : Payload-Länge bytes>

Alle Zahlenwerte werden als Big-Endian übertragen.

Mögliche Payload-Typen sind:

Typ

Maximales Payload

0 = Error

1024 Bytes. (Siehe unten, Fehlerhandhabung für Details.)

1 = JSON

16 MiB

2 = Binary

512 MiB

Wird das maximale Payload überschritten, wird die Verbindung sofort geschlossen. Dies dient dazu, zu verhindern, dass ein Teilnehmer mehr Daten entgegen nimmt, als dieser im RAM behalten kann.

Befehle
Definitionen

Im Folgenden sind sind Datentypen für JSON definiert, welche in dem Protokoll wiederverwendet werden:

Für String, Number, Array von <..> siehe JSON-Standart.

UUID ::= <String>

UUID nach Version 4

Beispiele

"a78c59fc-4198-421a-8ba4-db232ad7b91e"

"1f010407-130f-432c-8463-6c61fdfb8c14"

"ecb109bb-d9d6-494d-9d5e-b1e44734e20d"

Format ::= "png" | "jpeg"

Dateiformat

Beispiele

"png"

"jpeg"

Resolution ::= [<Weite:Number>, <Höhe:Number>]

Die erste Nummer stellt die Weite in Pixeln dar, die Höhe in Pixeln wird durch die zweite Nummer repräsentiert.

Beispiele

[1024, 1024]

[2048, 512]

[13, 400]

Tag ::= <String>

Stellt ein Tag dar. Kann Groß- und Kleinbuchstaben beinhalten.

Hinweis: Vergleiche von Tags sind nicht Case-Sensitiv. Die Darstellung in der UI jedoch unter Umständen schon.

Beispiele

"Holz"

"mEtALL"

"Chesse Cake"

Date ::= [<Jahr:Number>, <Monat:Number>, <Tag:Number>]
Beispiele

[2019, 3, 4] für 4. März 2019

[2017, 12, 21] für 21. Dezember 2017

Hash ::= <String>

Sha256-Hash von z.B. Texturdaten oder anderen Binärdaten, in Hexadezimal-Darstellung. Kann Groß- oder Kleinbuchstaben enthalten. Dies wird genutzt, um auf diese zu verweisen.

Beispiele

"a98f43a976e5b501961635b981022ebaf98321b97055ead4d8d4de55114015e7"

"02a08f7d697a93937cc5ace273a534c2eb021ae76b7c15ba146d279d57898893"

"A6A04ADC2E6D580B8E37CE8F4784652BE6D668EC1FB340B971DD8E8A582CE6BC"

"7bdc65d8550b0A4FBC899550bbda87DAA2E780D618A66a1F7813967ECF6C0831"

Texture ::= {id: <UUID>,name: <String>,tags: <Array von <Tag>>,format : <Format>,resolution: <Resolution>,added_on: <Date>,texture_hash: <Hash>}

Stellt einen Textur-Eintrag mit Metadaten dar.

Ping

Dieser Befehl dient zum Überprüfen der Verbindung.

Client sendet nach Schema:
type = JSON

{

"ping": {}

}

Server antwortet nach Schema:

type = JSON

{

"pong": {}

}

Query
Client sendet nach Schema:

Zusammenhänge Eingaben werden als <String> in einem Array übertragen.

type = JSON

{

"query": {

"query" : <Array of <String>>

}

}

Server antwortet nach Schema:

type = JSON

<Array of <Texture>>

Get Texture
Client sendet nach Schema:

type = JSON

{

"get_texture": {

"id" : <UUID> | null,

"name" : <String> | null,

}

}

Hierbei muss entweder das Feld "id" oder das Feld "name" gesetzt werden. Andernfalls wird Fehler 400 Bad Request gesendet,

Der Server antwortet nach Schema [Textur gefunden]:

type = JSON

<Texture>

Der Server antwortet nach Schema [Textur unbekannt]:

type = JSON null

Get Texture File
Client sendet nach Schema:

type = JSON

{

"get_texture_file": {

"texture_hash" : <Hash>,

}

}

Der Server antwortet nach Schema [Textur-Datei gefunden]:

type = Binary

Textur-Datei

Der Server antwortet nach Schema [Textur-Datei unbekannt]

type = Error 404 File Not Found.

Get Texture Preview
Client sendet nach Schema:

type = JSON

{

"get_texture_preview": {

"texture_hash" : <Hash>, "desired_format" : <Format>

}

}

Das Feld "desired_format" gibt an, in welchem Dateiformat das Antwort-Previewbild sein wird.

Der Server antwortet nach Schema [Textur-Datei gefunden]:

type = Binary

Textur-Preview

Der Server antwortet nach Schema [Textur-Datei unbekannt]:

type = Error 404 File Not Found.

Replace Texture
Client sendet nach Schema:

type = JSON

{

"replace_texture": {

"old": <Texture> | null,

"new": <Texture> | null,

}

}

Diese Anfrage dient dazu alte Texturen zu löschen und neue hinzufügen. Ein Löschen und gleichzeitiges Hinzufügen, ergibt ein Update der Textur.

Falls "old" != null, wird die hier angegebene Textur gelöscht. Wird diese nicht exakt gleich vorgefunden, schlägt diese Anfrage fehl (Fehler: 409 Conflict). In diesem Fall wird "new" nicht berücksichtigt.

Falls "new" != null, wird die hier angegebene Textur zum System hinzugefügt. Sollte die angegebene "new.id" oder der angegebene "new.name" schon vorhanden sein, schlägt diese Anfrage fehl (Fehler: 409 Conflict).

Diese Semantik wurde gewählt, damit ein Update atomar ist und doppelte Anfragen zu Fehlern führen.

Hinweis: Um zu überprüfen, ob ein Name bereits vergeben ist, sollte Get Texture verwendet werden. (IDs werden sowieso zufällig generiert.)

Der Server antwortet nach Schema ["texture_hash" bekannt]:

type = JSON

true

Die Anfrage wird damit beendet.

Der Server antwortet nach Schema ["texture_hash" unbekannt]:

type = JSON

{

"get_texture_file": {

texture_hash : <Hash>,

}

}

Woraufhin der Client die Textur-Datei sendet:

type = Binary

Textur-Datei

Der Server bestätigt dies dann mit:

type = JSON

true

Fehlerhandhabung

Fehlerbeschreibungen sind nach folgendem Schema aufgebaut:

<Fehlercode in Dezimal, Ascii><Leerzeichen><Fehlertext>

Bsp:

500 Internal Server Error

Die Fehlercodes sind an HTTP-Statuscodes angelehnt.

Das Folgende ist eine Aufstellung möglicher Fehlernachrichten, auf die in teilen oben verwiesen wurde. Der Fehlertext kann von dieser Aufstellung abweichen, um genauere Informationen wiederzugeben. Ein Vergleich muss daher immer anhand der Fehlernummer durchgeführt werden.

Nummer

Text

Beschreibung

400

Bad Request.

Anfrage hat ungültiges Format. Hierzu zählen:

Fehlerhalte Semantik.

Falsches Encoding.

404

File Not Found.

Unbekannte Textur-Datei angefordert.

409

Conflict.

Name oder Id bereits vorhanden.

Oder Löschversuch fehlgeschlagen, wegen möglicher Inkonsistenz.

500

Internal Server Error.

Unerwartbare seltene Sonstige Fehler. Z.b. Festplatte nicht lesbar etc.

501

Not Implemented.

Funktionalität wurde noch nicht implementiert. Dieser Fehlercode wird nur in der Entwicklungsphase verwendet.

Changelog

Version

Änderung

0.9.0

-

0.9.1

Formulierung und Rechtschreibung

0.10.0

Füge Ping-Befehl hinzu.

0.11.0

Server darf Verbindungen schließen, Fehlerbeschreibungen festgelegt

1.0.0

Review fertig.

1.1.0

+ Fehlerhandhabung: Genauere Aufstellung in extra Abschnitt.

1.2.0

Füge "desired_format" zu Get Texture Preview hinzu.

1.3.0

Ändere Format des Datums.

Anmerkungen

Dieses Dokument wird ergänzt, falls das WK#4 (Automatische Konfiguration des Clients) umgesetzt wird.