Protokół wymiany sentencji, wersja 1 Sieci komputerowe 2011@ MIM UW Osowski Marcin 28 kwietnia 2011 1
Streszczenie Dokument ten opisuje protokół przesyłania sentencji w modelu klientserwer. W założeniu dostarczanie sentencji ma się odbywać szybko i z minimalnym obciążeniem serwera stąd zastosowanie UDP jako protokołu transportowego. Komunikacja odbywa się bezstanowo: klient zgłasza zapotrzebowanie na cytat i otrzymuje jedno- lub wielo-pakietową odpowiedź z cytatem. 2
Spis treści 1 Opis celów protokołu 4 2 Opis założeń protokołu 4 3 Opis podstawowego nagłówka komunikatów 4 4 Opis wymienianych komunikatów 5 4.1 Klientdoserwera,STATUSSUCCESS... 6 4.2 Klientdoserwera,STATUSERR... 6 4.3 Serwerdoklienta,STATUSSUCCESS... 6 4.4 Serwerdoklienta,STATUSERR... 7 5 Podsumowanie używanych numerów 8 3
1 Opis celów protokołu Protokół umożliwia przesyłanie cytatów w modelu klient-serwer. Cytatem jest dowolny napis zakodowany w UTF-8(z pewnym górnym ograniczeniem na długość, szczegóły poniżej). Serwer nasłuchuje na porcie UDP 19019 na zapytania klientów. Każdy z klientów może zapytać serwer(czyli wysłać komunikat UDP) i na zasadach równych praw otrzymać losowo wybrany cytat. Ze względu na zapewnienie możliwości przesyłania cytatów o długości przekraczającej długość pakietu odpowiedź serwera może być jedno- lub wielo-pakietowa. Niezależnie od typu odpowiedzi klient oczekuje na kompletną odpowiedź(co w przypadku wielo-pakietowej odpowiedzi oznacza odbiór wszystkich pakietów) przez CLIENT_TIMEOUT milisekund, po czym w przypadku nie odebrania kompletu informacji uznaje zapytanie za nieudane. 2 Opis założeń protokołu 1. Protokół pracuje w warstwie aplikacji. 2. Wszystkie liczby są zapisywane jako liczby bez znaku, w sieciowym porządku oktetów. 3. Protokół jest szybki, powoduje małe obciążenie. Realizowane jest to poprzez zastosowanie UDP jako protokołu transportowego, bezstanowość oraz binarny format przesyłanych pakietów z bardzo niewielkim nagłówkiem(typowo nie przekracza on 6 bajtów długości). 4. Protokół jest do pewnego stopnia skalowalny, umożliwiając przesyłanie cytatów o rozmiarach do kilkudziesięciu MiB(zależnie od MTU sieci). Jednocześnie nie powoduje to zwiększania objętości metadanych dla cytatów krótkich(o długości rzędu 1 KiB). 5. Protokół jest przystosowany do ewentualnego rozszerzenia funkcjonalności. 6. Protokół nie definiuje żadnych metod autoryzacji lub szyfrowania. 3 Opis podstawowego nagłówka komunikatów Każdy z komunikatów wymienianych w ramach protokołu składa się z podstawowego nagłówka rozszerzonego w miarę potrzeby dodatkowymi polami. Opis pierwszych czterech bajtów wymienianych komunikatów: basic_header{ uint8_t proto_version; /********************** uint8_t packet_type; * Podstawowy nagłówek uint16_t connection_id; **********************/ 4
}; proto_version Jest liczbą bez znaku opisującą numer wersji protokołu. W założeniu serwer zgłasza błąd, jeżeli dostaje pakiet z nieznaną sobie wersją protokołu. packet_type Jest polem złożonym z czterech części: najstarszy bit najmłodszy bit 7 6 5 4 3 2 1 0 +---------------+-----------+------------+----------------+ direction_bit error_bit reserved type_details +---------------+-----------+------------+----------------+ packet_type[7] direction_bit Klient wysyłający dane do serwera ustawia ten bit na DIRECTION_REQUEST(0). Serwer wysyłający dane do klienta ustawia ten bit na DIRECTION_RESPONSE(1). packet_type[6] error_bit W przypadku sukcesu bit ten jest ustawiany na STATUS_SUCCESS(0). W przypadku błędu bit ten jest ustawiany na STATUS_ERR(1). packet_type[5..3] reserved Zarezerwowane do przyszłego wykorzystania, powinny być ustawionena0. packet_type[2..0] type_details connection_id Znaczenie zależy od ustawienia bitów direction_bit i error_bit. Szczegóły w poniższych sekcjach. Dowolny ciąg 16 bitów ułatwiający rozróżnianie sesji klienta. Znacznik ten ustanawia klient. Serwer rozróżnia zapytania na podstawie klucza(numer ip klienta, port klienta, connection id klienta). Ma to ułatwić klientowi odfiltrowanie zagubionych pakietów z poprzednich zapytań. 4 Opis wymienianych komunikatów Komunikaty występują w czterech grupach określanych przez możliwe kombinacje ustawień bitów direction_bit i error_bit. Każdy typ komunikatu ma specyficzne wartości type_details. 5
4.1 Klient do serwera, STATUS SUCCESS Zdefiniowany jest tylko jeden typ komunikatu: zapytanie o cytat. Odpowiada mu type_details = TYPE_REQUEST_QUOTE(1). Komunikat ten składa się z podstawowego nagłówka rozszerzonego o pole max_payload_length: packet_request{ uint8_t proto_version; /********************** uint8_t packet_type; * Podstawowy nagłówek uint16_t connection_id; **********************/ }; uint16_t max_payload_length; max_payload_length Określa maksymalną akceptowalną przez klienta wartość pola payload_length. Klient uznaje za błędną odpowiedź serwera nie przestrzegającą zadeklarowanego max_payload_length 4.2 Klient do serwera, STATUS ERR Komunikaty tego typu nie powinny pojawiać się w ruchu. Wysyłanie błędnych zapytań nie ma sensowej interpretacji. 4.3 Serwer do klienta, STATUS SUCCESS Dla udanej odpowiedzi serwera zdefiniowane są dwa typy komunikatów. 1. Odpowiedź jedno-pakietowa. type_details = TYPE_FOUND_QUOTE(1) Pakiet tego typu oprócz podstawowego nagłówka zawiera pole payload_length, oraztreśćcytatuwpoludata: packet_resp_single_packet{ uint8_t proto_version; /********************** uint8_t packet_type; * Podstawowy nagłówek uint16_t connection_id; **********************/ }; uint16_t payload_length; octet[payload_length] data; 2. Odpowiedź wielo-pakietowa. type_details = TYPE_FOUND_QUOTE_MULTI_PACKET(2) Pakiet tego typu zawiera zarówno podstawowy nagłówek, pola quote_position, quote_length, payload_length jak i część treści cytatu w polu data. 6
packet_resp_multi_packet{ uint8_t proto_version; /********************** uint8_t packet_type; * Podstawowy nagłówek uint16_t connection_id; **********************/ }; uint16_t quote_position; uint16_t quote_length; uint16_t payload_length; octet[payload_length] data; Opisy pól: quote_position Określa numer pakietu w obrębie jednej odpowiedzi. quote_length Określa ilość pakietów w wielo-pakietowej odpowiedzi(powinno być stałe w obrębie jednej odpowiedzi; zmianę tej liczby klient powinien uznać za błąd). payload_length data Określa długość pola data. Wypełnia całą przestrzeń pakietu poza nagłówkiem(czyli poza polami proto_version, packet_type, connection_id, payload_length oraz poza polami quote_position, quote_length, o ile występują). Przechowuje cytat(lub część cytatu w przypadku odpowiedzi wielopakietowej). Cytatem jest dowolny napis zakodowany w UTF-8. 4.4 Serwer do klienta, STATUS ERR Komunikaty informujące klienta o wystąpieniu różnego rodzaju błędów. Pakiety te składają się wyłącznie z podstawowego nagłówka. Zdefiniowane są trzy typy błędów. 1. Nieznana wersja protokołu. type_details = TYPE_ERR_PROTO_UNSUPPORTED(1) Odpowiedź serwera po otrzymaniu nieznanej wersji protokołu(proto_version!= PROTO_VERSION). 2. Nie znaleziono cytatu. type_details = TYPE_ERR_NOT_FOUND(2) Odpowiedź serwera po otrzymaniu żądania cytatu przy jednoczesnym braku cytatów w bazie. 7
3. Niezrozumiałe polecenie. type_details = TYPE_ERR_UNKNOWN_COMMAND(3) Odpowiedź serwera po otrzymaniu niezrozumiałego polecenia. 5 Podsumowanie używanych numerów PROTOVERSION=1 UDPPORT=19019 CLIENT TIMEOUT = 2000[ms] DIRECTION REQUEST = 0 DIRECTION RESPONSE = 1 STATUS SUCCESS = 0 STATUSERR=1 TYPEREQUESTQUOTE=1 TYPEFOUNDQUOTE=1 TYPEFOUNDQUOTEMULTIPACKET=2 TYPE ERR PROTO UNSUPPORTED = 1 TYPEERRNOTFOUND=2 TYPEERRUNKNOWNCOMMAND=3 8