Opis protokołu do obsługi aukcji

Opis protokołu do obsługi aukcji Maciej Pazurkiewicz 1 maja 2009 Spis treści 1 Streszczenie 2 2 Opis celów protokołu 2 3 Opis założeń protokołu 2 4 Opis formatu komunikatów 2 4.1 Podstawowe informacje............................... 2 4.2 Typy komunikatów................................. 3 4.2.1 Typy dla komunikatów w pierwszej fazie................. 3 4.2.2 Typy dla komunikatów w drugiej fazie................... 5 4.2.3 Typy dla komunikatów dodatkowych................... 8 5 Opis wymienianych komunikatów 8 5.1 Komunikaty pierwszej fazy............................. 8 5.1.1 Komunikaty wysyłane przez potencjalnego kupującego.......... 8 5.1.2 Komunikaty wysyłane przez potencjalnego sprzedawcę.......... 8 5.2 Komunikaty drugiej fazy.............................. 9 5.2.1 Komunikaty wysyłane przez kupującego................. 9 5.2.2 Komunikaty wysyłane przez sprzedającego................ 10 5.2.3 Uwagi.................................... 10 5.3 Komunikaty dodatkowe............................... 11 6 Opis stanów 11 6.1 Uwagi ogólne.................................... 11 6.2 Opis stanów uczestnika licytacji.......................... 12 6.3 Opis stanów sprzedającego............................. 13 7 Podsumowanie używanych numerów 14 7.1 Wartości stałych msg_type dla poszczególnych typów komunikatów....... 14 7.2 Wartości stałych reason w negatywnych potwierdzeniach............. 14 1

1 Streszczenie Niniejszy dokument ma na celu opisanie protokołu komunikacyjnego służącego do obsługi aukcji internetowych. Na podstawie opisu możliwa jest jego pełna implementacja. Początkowe rozdziały stanowią krótki opis celów i założeń protokołu. Kolejne zaś są precyzyjnym opisem komunikatów wysyłanych w ramach protokołu oraz oczekiwanego zachowania jego użytkowników w reakcji na nie. 2 Opis celów protokołu Celem opisywanego protokołu jest obsługa aukcji internetowych. Jego użytkownicy mogą wystawiać na aukcję własne przedmioty oraz brać udział w aukcjach przedmiotów wystawianych przez innych użytkowników. Protokół obejmuje nie tylko samą licytację, lecz także wymianę informacji o licytowanych przedmiotach. W pierwszej fazie komunikacji przy pomocy protokołu użytkownicy mogą zadawać pytania dotyczące przedmiotów wystawionych na sprzedaż przez innych użytkowników. Ci mogą na te pytania odpowiadać. Istnieje możliwość dołączenia pliku do odpowiedzi. W drugiej fazie komunikacji potencjalni kupujący mogą zapisać się do licytacji oraz zgłaszać propozycje cen. Sprzedający powininen móc powiadomić ich o nowej cenie przedmiotu oraz o zakończeniu i wyniku aukcji. O ile pierwsza faza komunikacji jest zupełnie niezobowiązująca, w drugiej protokół powinien zapewniać: mechanizm identyfikacji stron za pomocą unikalnych kluczy mechanizm potwierdzenia odebrania komunikatów 3 Opis założeń protokołu Protokół działa w warstwie aplikacji modelu ISO OSI. Przyjętym modelem komunikacji jest peer-to-peer tzn. że odbywa się ona bez udziału centralnego serwera. W warstwie transportu protokół korzysta z UDP (w pierwszej fazie komunikacji) i TCP (w drugiej fazie). Domyślnym numerem portu (zarówno dla TCP jak i UDP) jest 10187. Użytkownik może uczestniczyć w wielu aukcjach jednocześnie, jednak każda z nich powinna być prowadzona przy użyciu innego połączenia TCP. 4 Opis formatu komunikatów 4.1 Podstawowe informacje porzadek oktetów format liczb zmiennoprzecinkowych sieciowy nie są używane 2

4.2 Typy komunikatów Niniejszy rozdział zawiera jedynie opis struktury komunikatów. Opis ich znaczenia oraz kolejności wysyłania odnaleźć można w rozdziale 5. Pierwszym polem wszystkich typów komunikatów jest msg_header typu msg_header_t. msg_header_t { uint32 msg_type; uint32 protocol_version; msg_type liczba, rozróżniająca poszczególne typy komunikatów protocol_version wersja protokołu, której używa nadawca Liczby, będące dopuszczalną wartością pola msg_type odnaleźć można w rozdziale 7.1. Zamieszczenie numeru wersji w komunikacie zapewnia jego rozszerzalność. W niniejszym dokumencie opisano wersję protokołu o numerze 1. 4.2.1 Typy dla komunikatów w pierwszej fazie Typy dla komunikatów wysyłanych przez potencjalnego kupujacego typ dla prośby o listę przedmiotów wystawionych na sprzedaż MSG_LIST_ARTICLES_T { typ dla pytania o własności przedmiotu MSG_QUESTION_T { uint32 article_number; uint32 question_number; uint32 question_size; octet[question_size] question; article_number question_number question_size question numer przedmiotu, którego dotyczy pytanie numer pytania długość pola question treść pytania typ dla przyjęcia bądź odrzucenia propozycji załączenia pliku 3

MSG_FILE_ACCEPTANCE_T { uint32 article_number; uint32 question_number; uint32 filename_size; octet[filename_size] filename; article_number question_number filename_size filename numer przedmiotu, którego dotyczy komunikat numer pytania do odpowiedzi, na które sprzedawca chciałby dołączyć plik długość pola filename nazwa pliku, który chce dołączyć sprzedawca Typy dla komunikatów wysyłanych przez potencjalnego sprzedawcę typ dla komunikatu o liczbie przedmiotów wystawionych na sprzedaż. MSG_MY_ARTICLES_T { uint32 number_of_my_articles; number_of_my_articles liczba artykułów, które sprzedający ma w swojej ofercie typ dla komunikatu z podstawowymi informacjami o przedmiocie MSG_ARTICLE_INFO_T { uint32 article_number; uint32 description_size; octet[description_size] description; article_number description_size description numer przedmiotu, którego dotyczy komunikat długość pola description treść opisu przedmiotu typ dla komunikatu, będącego odpowiedzią na zadane pytanie 4

MSG_ANSWER_T { uint32 article_number; uint32 question_number; uint32 text_size; uint32 filename_size; uint32 file_size; octet[text_size] text; octet[filename_size] filename; article_number question_number text_size filename_size file_size text filename numer przedmiotu, którego dotyczy komunikat numer pytania, na które odpowiedzią jest komunikat długość pola text długość pola filename rozmiar pliku, który chce załączyć sprzedawca treść odpowiedzi na pytanie nazwa pliku, który chce dołączyć sprzedawca typ dla komunikatów, zawierających plik MSG_FILE_T { uint32 filename_size; uint32 file_size; octet[filename_size] filename; octet[file_size] file; filename_size file_size filename file długość pola filename rozmiar załączonego pliku nazwa pliku plik Uwaga! Rozszerzenie pliku zawarte w polu filename powinno być zgodne z jego faktycznym typem. 4.2.2 Typy dla komunikatów w drugiej fazie Typy dla komunikatów wysyłanych przez potencjalnego nabywcę typ dla komunikatu, będącego zapisaniem się do licytacji 5

MSG_SIGNUP_T { uint32 article_number; uint32 com_number; article_number com_number numer przedmiotu, w którego aukcji użytkownik chce uczestniczyć numer komunikatu typ dla komunikatu, stanowiącego ofertę w licytacji MSG_BID_T { octet[auction_id_size] auction_id; octet[client_id_size] client_id; uint32 com_number; uint32 price; auction_id client_id com_number price identyfikator aukcji identyfikator klienta numer komunikatu oferowana cena typ dla potwierdzeń pozytywnych MSG_POSITIVE_CONFIRMATION_T { octet[auction_id_size] auction_id; octet[client_id_size] client_id; uint32 com_number; auction_id client_id com_number identyfikator aukcji identyfikator klienta numer komunikatu, którego dotyczy potwierdzenie 6

Typy dla komunikatów wysyłanych przez sprzedajacego typ dla komunikatu, przekazującego uczestnikowi licytacji jego identyfikator i identyfikator aukcji MSG_IDS_T { uint32 client_id_size; uint32 auction_id_size; octet[client_id_size] client_id; octet[auction_id_size] auction_id; client_id_size auction_id_size client_id auction_id rozmiar pola client_id rozmiar pola auction_id identyfikator kupującego identyfikator aukcji typ dla komunikatu, będącego ogłoszeniem nowej ceny lub końca licytacji MSG_PRICE_ANNOUNCEMENT_T { octet[auction_id_size] auction_id; uint32 com_number; uint32 price; uint8 your_offer; auction_id com_number price youroffer identyfikator aukcji numer komunikatu cena przedmiotu informacja dla odbiorcy komunikatu, czy to on złożył najwyższą ofertę typ dla potwierdzeń negatywnych MSG_NEGATIVE_CONFIRMATION_T { octet[auction_id_size] auction_id; uint32 com_number; uint8 reason; 7

auction_id com_number reason identyfikator aukcji numer komunikatu, którego dotyczy potwierdzenie przyczyna odrzucenia komunikatu 4.2.3 Typy dla komunikatów dodatkowych typ dla informacji o błędzie (np. niezgodności wersji) MSG_ERROR_T { 5 Opis wymienianych komunikatów 5.1 Komunikaty pierwszej fazy 5.1.1 Komunikaty wysyłane przez potencjalnego kupujacego Prośba o listę przedmiotów MSG_LIST_ARTICLES: MSG_LIST_ARTICLES_T Komunikat ten jest prośbą o listę przedmiotów wystawionych na sprzedaż. Oczekiwaną odpowiedzią jest komunikat MSG_MY_ARTICLES i odpowiednia liczba następujących po nim komunikatów MSG_ARTICLE_INFO. Pytanie o własności przedmiotu MSG_QUESTION: MSG_QUESTION_T Komunikat ten jest prośbą o udzielenie dodatkowych informacji o pewnym przedmiocie. Oczekiwaną odpowiedzią jest komunikat MSG_ANSWER. Zgoda na przyjęcie pliku MSG_ACCEPT_FILE: MSG_FILE_ACCEPTANCE_T Komunikat ten informuje o zgodzie na przyjęcie pliku, związanego z odpowiedzią na pytanie o własności przedmiotu. Odmowa przyjęcia pliku MSG_REJECT_FILE: MSG_FILE_ACCEPTANCE_T Komunikat ten informuje o odmowie przyjęcia pliku, związanego z odpowiedzią na pytanie o własności przedmiotu. 5.1.2 Komunikaty wysyłane przez potencjalnego sprzedawcę Informacja o liczbie przedmiotów MSG_MY_ARTICLES: MSG_MY_ARTICLES_T Komunikat ten jest odpowiedzią na pytanie o przedmioty wystawione na sprzedaż (tj. na komunikat MSG_LIST_ARTICLES). Jeśli użytkownik ma jakieś przedmioty na sprzedaż (number_of_my_articles > 0), po komunikacie tym powinno następować 8

number_of_my_articles komunikatów MSG_ARTICLE_INFO z opisami poszczególnych przedmiotów. Informacja o przedmiocie MSG_ARTICLE_INFO: MSG_ARTICLE_INFO_T Komunikat ten zawiera podstawowe informacje o przedmiocie. Odpowiedź na pytanie o własności przedmiotu MSG_ANSWER: MSG_ANSWER_T Komunikat ten zawiera tekstową odpowiedź na pytane o własności danego przedmiotu zadane przez pewnego użytkownika. Może on stanowić także, propozycję wysłania pliku, uzupełniającego informację o przedmiocie (np. zdjęcia). W tym przypadku należy oczekiwać odpowiedzi akceptującej lub odrzucającej przyjęcie pliku (odpowiednio komunikatów MSG_ACCEPT_FILE lub MSG_REJECT_FILE). Gdy sprzedawca nie chce załączyć żadnego pliku pola filename_size i file_size powinny mieć wartość 0. Plik MSG_FILE: MSG_FILE_T Komunikat ten zawiera plik, dołączony do odpowiedzi na pytanie. Musi zostać poprzedzony propozycją wysłania pliku w komunikacie MSG_ANSWER i pozytywną odpowiedzią MSG_ACCEPT_FILE. 5.2 Komunikaty drugiej fazy 5.2.1 Komunikaty wysyłane przez kupujacego Zapisanie się do licytacji MSG_SIGNUP: MSG_SIGNUP_T Komunikat ten wysyłany jest przez użytkownika, który chce wziąć udział w aukcji przedmiotu wystawianego przez innego uczestnika. Oczekiwaną odpowiedzią pozytywną jest komunikat MSG_IDS, za pomocą którego sprzedający zaprasza do licytacji i przekazuje niezbędne do uczestnictwa w niej identyfikatory. Odpowiedzią negatywną na ten komunikat jest MSG_NEGATIVE_CONFIRMATION. Licytacja MSG_BID: MSG_BID_T Komunikat ten wysyłany jest przez uczestnika aukcji, który chce zaproponować nową cenę dla danego przedmiotu. Oczekiwaną odpowiedzią pozytywną jest ogłoszenie o nowej cenie z polem your_offer ustawionym na 1. Odpowiedzią negatywną jest potwierdzenie negatywne, wskazujące na przyczynę odrzucenia propozycji (np. za niska cena). Potwierdzenie informacji o nowej cenie MSG_NEW_PRICE_CONFIRMATION: MSG_POSITIVE_CONFIRMATION_T Komunikatem tym uczestnicy aukcji potwierdzają odbiór informacji o nowej cenie przedmiotu. Wartość pola com_number powinna być taka sama jak w komunikacie, który właśnie jest potwierdzany. 9

Potwierdzenie informacji o zamknięciu licytacji MSG_AUCTION_END_CONFIRMATION: MSG_POSITIVE_CONFIRMATION_T Komunikatem tym uczestnicy aukcji potwierdzają odbiór informacji o zakończeniu aukcji. Wartość pola com_number powinna być taka sama jak w komunikacie, który właśnie jest potwierdzany. 5.2.2 Komunikaty wysyłane przez sprzedajacego Komunikat z identyfikatorem aukcji MSG_IDS: MSG_IDS_T Komunikatem tym sprzedający akceptuje udział danego użytkownika w licytacji i przesyła mu niezbędne identyfikatory. Protokół nie wymusza żadnej konkretnej postaci identyfikatorów, nie ogranicza też ich rozmiaru (rozmiar każdego z identyfikatorów przesyłany jest w niniejszym komunikacie). Jedynym wymaganiem jest ich unikalność w obrębie wszystkich aukcji danego sprzedawcy. Komunikat o nowej cenie MSG_PRICE_ANNOUNCEMENT: MSG_PRICE_ANNOUNCEMENT_T Komunikat ten służy sprzedającemu do ogłoszenia nowej ceny przedmiotu. Jest on wysyłany do wszystkich uczestników aukcji, po zaakceptowaniu podniesienia ceny. Uczestnik, którego oferta jest w tej chwili najwyższa, otrzymuje komunikat z parametrem your_offer ustawionym na 1, pozostali zaś - z ustawionym na 0. Pierwszy komunikat tego typu jest otwarciem licytacji. Sprzedający może wybrać cenę wywoławczą, ustawiając pole price na żądaną wartość. Komunikat o zakończeniu licytacji MSG_AUCTION_END: MSG_PRICE_ANNOUNCEMENT_T Komunikat ten służy sprzedającemu do ogłoszenia końca licytacji. Wszyscy informowani są o cenie, za którą sprzedany został przedmiot. Zwycięzca informowany jest dodatkowo, o tym, że jego oferta wygrała (przez pole your_offer jak wyżej). Potwierdzenie negatywne MSG_NEGATIVE_CONFIRMATION: MSG_NEGATIVE_CONFIRMATION_T Komunikat służy do negatywnej odpowiedzi na próbę zapisania się do licytacji bądź zgłoszenie nowej ceny. Wartość pola com_number powinna być taka sama jak w komunikacie, który właśnie jest negatywnie potwierdzany. Stałe, które są możliwymi wartościami pola reason, można odnaleźć w rozdziale 7. 5.2.3 Uwagi użytkownik nadający komunikatowi numer com_number musi dbać o jego unikalność pośród innych numerów nadanych przez niego jako potwierdzenie negatywne uważa się także nieotrzymanie potwierdzenia pozytywnego w pewnym określonym czasie. Czasy te mogą różnić się dla poszczególnych typów komunikatów. Minimalny czas oczekiwania (w sekundach) na potwierdzenie dla różnych komunikatów przedstawia poniższa tabela 10

MSG_SIGNUP 45 MSG_BID 30 MSG_PRICE_ANNOUNCEMENT 5 MSG_AUCTION_END 5 5.3 Komunikaty dodatkowe Komunikat o niezgodności wersji MSG_INCOMPATIBLE_VERSIONS: MSG_ERROR_T Komunikat ten służy do poinformowania innego użytkownika o niezgodności wersji protokołu. Stanowi on odpowiedź na dowolny inny komunikat. Komunikat ten nie powinien być wysyłany, gdy obie strony używają innych wersji protokołu, jednak nie stanowi to przeszkody w komunikacji. Komunikat o nieodwracalnym błędzie MSG_UNRECOVERABLE_ERROR: MSG_ERROR_T Komunikat ten służy do poinformowania użytkownika, z którym wcześniej komunikowano, o błędzie, który uniemożliwia dalszą komunikację. Po odebraniu takiego komunikatu odbiorca nie powinien spodziewać się dalszych komunikatów od nadawcy. W szczególności komunikat taki wysłany w drugiej fazie przez: wysłany przez kupującego - kończy jego udział w licytacji wysłany przez sprzedającego - kończy aukcję bez jej rozstrzygnięcia Należy pamiętać, że wiele sytuacji błędnych uniemożliwi wysłanie nawet takiego komunikatu. Rolę tego komunikatu pełni wówczas negatywne potwierdzenie poprzez przekroczenie progu czasowego (patrz 5.2.3). 6 Opis stanów Opis stanów odnosi się tylko do drugiej fazy komunikacji. 6.1 Uwagi ogólne Komunikaty pierwszej fazy mogą być przesyłane przez cały czas, w szczególności także w trakcie trwania aukcji. Można zatem np. zadawać także wtedy dodatkowe pytania własności przedmiotu, w którego licytacji bierze się udział. Nie istnieje problem pomieszania komunikatów obu faz, gdyż każda z faz korzysta z innego protokołu warstwy transportu (patrz rozdział 3). Jedynym komunikatem drugiej fazy, który może być przesłany w trakcie fazy pierwszej jest MSG_SIGNUP. Wszystkie pozostałe komunikaty powinny zostać zignorowane (tj. odbiorca nie powinien na nie odpowiadać). 11

Rysunek 1: Diagram stanów uczestnika licytacji 6.2 Opis stanów uczestnika licytacji Omówienie poszczególnych stanów: OUT_OF_AUCTION_STATE - użytkownik nie bierze udziału w aukcji; aby się do niej zapisać musi wysłać do sprzedającego komunikat MSG_SIGNUP WAIT_FOR_IDS_STATE - użytkownik podjął próbę zapisania się do aukcji; oczekuje na akceptację jego prośby i otrzymanie identyfikatorów aukcji oraz klienta (komunikat MSG_IDS) IN_AUCTION_CANT_BID_STATE - użytkownik jest uczestnikiem aukcji, jednak nie została ona jeszcze otwarta - nie można jeszcze licytować CAN_BID_STATE - aukcja jest otwarta - użytkownik może licytować WAIT_FOR_CONFIRMATION_STATE - użytkownik zgłosił propozycję nowej ceny i oczekuje na potwierdzenie jej (pozytywne lub negatywne) przez sprzedającego. Uwaga! Użytkownik może dostać komunikat MSG_PRICE_ANNOUNCEMENT z polem your_offer ustawionym na 0. Oznacza to, że inna oferta została przed tą zgłoszoną przez niego. W szczególności może być to oferta z niższą ceną, co oznacza, że użytkownik może spodziewać się jeszcze pozytywnego potwierdzenia własnej oferty. Użytkownik, będący uczestnikiem licytacji powinien zignorować (tj. nie zmienić stanu i nie odpowiadać) wszystkie nieuwzględnione w powyższym opisie komunikaty drugiej fazy, które odbierze. 12

Rysunek 2: Diagram stanów sprzedającego 6.3 Opis stanów sprzedajacego Omówienie poszczególnych stanów: AUCTION_CLOSED_STATE - aukcja nie została jeszcze otwarta lub została właśnie zamknięta. Na komunikaty drugiej fazy od użytkowników niezapisanych do aukcji sprzedający powinien odpowiedzieć negatywnym potwierdzeniem z przyczyną ustawioną na ERR_WRONG_ID. Na komunikaty drugiej fazy od użytkowników zapisanych do aukcji sprzedający powinien odpowiedzieć negatywnym potwierdzeniem z przyczyną ustawioną na ERR_AUCTION_NOT_OPENED. AUCTION_OPENED_STATE - aukcja została otwarta, uczestnicy mogą zgłaszać propozycje nowych cen; WAIT_FOR_PRICE_CONFIRMATIONS_STATE - została zgłoszona propozycja nowej ceny, sprzedający poinformował o tym uczestników; teraz oczekuje na potwierdzenia od nich wszystkich. Uwaga! W tym czasie wszystkie inne komunikaty (w tym propozycje cen) powinny być kolejkowane i rozpatrzone dopiero po odebraniu potwierdzeń. WAIT_FOR_END_CONFIRMATIONS_STATE - został ogłoszony koniec aukcji, sprzedający poinformował o tym uczestników; teraz oczekuje na potwierdzenia od nich wszystkich. Inne komunikaty powinny zostać zignorowane. W każdym stanie (uwaga! w szczególności już w trakcie trwania licytacji) sprzedający może odebrać komunikat MSG_SIGNUP. Jeśli chce przyjąć kolejnego uczestnika licatycji, powinien bezzwłocznie odpowiedzieć mu wiadomością MSG_IDS, a następnie poinformować o go rozpoczęciu aukcji (bądź aktualnej cenie) komunikatem MSG_PRICE_ANNOUNCEMENT. 13

7 Podsumowanie używanych numerów 7.1 Wartości stałych msg_type dla poszczególnych typów komunikatów MSG_LIST_ARTICLES 0 MSG_QUESTION 1 MSG_ACCEPT_FILE 2 MSG_REJECT_FILE 3 MSG_MY_ARTICLES 4 MSG_ARTICLE_INFO 5 MSG_ANSWER 6 MSG_FILE 7 MSG_SIGNUP 8 MSG_BID 9 MSG_NEW_PRICE_CONFIRMATION 10 MSG_AUCTION_END_CONFIRMATION 11 MSG_IDS 12 MSG_PRICE_ANNOUNCEMENT 13 MSG_AUCTION_END 14 MSG_NEGATIVE_CONFIRMATION 15 MSG_INCOMPATIBLE_VERSIONS 16 MSG_UNRECOVERABLE_ERROR 17 7.2 Wartości stałych reason w negatywnych potwierdzeniach ERR_NO_SUCH_ARTICLE 0 ERR_WRONG_ID 1 ERR_PRICE_TO_LOW 2 ERR_AUCTION_NOT_OPENED 3 14