Tahiti Verze 3.0 Návrh komunikačního protokolu (rozšířená verze)

Project code name: Tahiti

Language: Czech

Release date of document: 2005-06-20

Status of document:

Author: Petr Pytelka

Copyright LightComp v.o.s. 2000-2004

Obsah

1. Úvod	3

1.1. Změny 2004-02-18	3

1.2. Změny 2004-07-29	3

1.3. Změny 2004-08-07	3

1.4. Změny 2004-08-20	3

1.5. Změny 2004-08-25	3

1.6. Změny 2004-08-26	3

1.7. Změny 2004-10-21	4

1.8. Změny 2005-01-18	4

1.9. Změny 2005-04-07	4

1.10. Změny 2005-04-28	4

1.11. Změny 2005-06-20	4

2. Požadavky	4

3. Popis protokolu	4

4. Type 0	5

4.1. Autorizace	5

4.2. Vzor odpovědi	6

4.3. Popis dokumentu a jeho příjem	6

4.4. Vyžádání souboru	8

4.5. Vyžádání dokumentu	8

4.6. Vyžádání konfigurace	8

4.7. Uložení dokumentu	8

4.8. Příjem objektu	10

4.9. Stav připojení	10

5. Type 1	10

6. Type 2	11

7. Testovací packet	11

8. Příklad komunikace	11

9. Implementace	12

9.1. Atributy objektů	12

10. Závěr	13

Úvod

Cílem dokumentu je návrh nového protokol pro výměnu dokumentů s archivačním systémem. Doposud užívaný protokol vznikl v roce 2000 a v současné době je již nevyhovující.

Změny 2004-02-18

Seznam změn oproti původnímu návrhu z 12/2003.

4.3. pole atributů je pojmenováno attributes

4.7. možnost přenosu objektů

7.1. platné atributy dokumentu

Změny 2004-07-29

Seznam změn oproti úpravám návrhu z 18-2-2004.

přidání metody pro změnu stavu připojení (4.8)

možnost vyžádání určitého dokumentu (4.5)

Změny 2004-08-07

Seznam změn oproti úpravám návrhu z 29-7-2004.

přidáno potvrzení přijetí dokumentu (4.6)

Změny 2004-08-20

Seznam změn oproti úpravám návrhu z 7-8-2004.

rozšíření návratové struktury při ukládání dokumentu o jeho identifikátor (4.6)

přejmenování metody updateDocument na getDocument (4.5)

zpřesnění popisů struktur a metod (4.3-4.6)

Změny 2004-08-25

Seznam změn oproti úpravám návrhu z 20-8-2004.

přidání položek do struktury Document

úpravy hodnot pushDocument

odstranění definice atributů (7.1)

Změny 2004-08-26

Seznam změn oproti úpravám návrhu z 20-8-25

nová funkce errorReceivedDocument (4.6)

nová funkce requestConfig a errorRequestConfig (4.5), nový rámec typu 2 (6.)

úpravy struktury Document – zrušení položky source, přidání origName, serverVersion

zrušení metody getDocument

Změny 2004-10-21

úprava hodnot attributu modified (možné hodnoty 0,1,2,3)

Změny 2005-01-18

úprava struktury SaveDocument, bod 4.6, přidána položka serverVersion

textové korektury (bod č. 6)

Změny 2005-04-07

testovací packet (bod č. 7)

struktura Document obsahuje novou položku modified

struktura Document.File obsahuje nové položky keys, signature

Změny 2005-04-28

přidána zpět metoda getDocument (bod č. 4.5)

Změny 2005-06-20

přidána položka type do struktury Object (bod č. 4.8)

upraveny atributy zasílaných objektů (bod č. 9.1)

Požadavky

Nový protokol by měl být postaven nad rodinou protokolů TCP/IP. Měli by existovat dvě verze protokolu: nešifrovaná a šifrovaná. Šifrování je transparentní z hlediska vyšších aplikačních vrstev, z tohoto důvodu je vhodnou možností SSL.

Požadované operace:

Autorizace

Vyžádání dokumentu jako celku

Odesílání pozměněného dokumentu - odesílají se pozměněné stránky. Před odesláním bude provedena kontrola aktuální verze dokumentu

Možnost offline uložení dokumentů na lokálním disku

Možnost zjistit dotazem nutnost aktualizace offline stažených dokumentů

Vkládání nových stránek k pozměněnému dokumentu

Cachování vyžádaných souborů

Zachování práv pouhého čtení nebo editace dokumentů

Popis protokolu

Protokol je postaven nad protokolem TCP. Přenášená data jsou uzavřena do datových rámců.

0123 4567 8901 234... END 4 bytes
MGID FRTP FRSZ ......FRDT .......FRCS

Význam jednotlivých bloků

Položka	Velikost	Význam
MGID	4	Identifikátor paketu (magic id), očekávaná hodnota 0xE1 0x87 0x05 0xA3
FRTP	4	Typ rámce, číslo určující typ
FRSZ	4	Velikost dat v rámci (počet bytů)
FRDT	Určeno FRSZ	Vlastní data rámce, jejich velikost je ve FRSZ
FRCS	4	Kontrolní součet rámce. Je použita vhodná hashovací funkce. Součástí součtu je MGID,FRTP,FRSZ,FRDT

Protokol má pouze 2 stavy – bez autorizace, s autorizací. Pro zahájení přenosu dokumentů se nejprve musí klient autorizovat k serveru (viz. bod 4.1), dále již není protokol stavový. Stav je nutno sledovat u přenášených dokumentů a souborů.

Poznámky:

Pro přenos číselných hodnot se používá formát LittleEndian (typické pro platformu x86).

Při implementaci protokolu je vhodné limitovat nastavením maximální velikost rámce FRSZ.

Type 0

Jedná se o základní typ umožňující přenos jednoho XML souboru. Ten je určen pro přenos dotazu, resp. odpovědi na dotaz. Formát souboru musí odpovídat standardu XML-RPC (viz. http://www.xmlrpc.com/spec ). Tento typ rámce slouží pro vzdálená volání. Následující popis dostupných metod je zapsán pomocí „pseudo C“ syntaxe.

Součástí každého volání je položka ticker, která slouží k jednoznačné identifikaci volání. Tato položka je vrácena současně s návratovou hodnotou funkce.

Autorizace

Prvním krokem po vytvoření spojení je autorizace klienta. Ta se provede zavoláním metody authorize.

int authorize(string ticker, string user, string password);

Parametrem metody je user – uživatelské jméno, password – heslo pro přihlášení.
Příklad převedeného volání do XML-RPC:

<?xml version="1.0"?>
<methodCall>
<methodName>authorize</methodName>
<params>
<param>
<value><string>ticker</string></value>
</param>
<param>
<value><string>user</string></value>
</param>
<param>
<value><string>password</string></value>
</param>
</params>
</methodCall>

Jako odpověď je očekáváno číslo:

0 – korektní přihlášení
1 – chybné jméno nebo heslo
2 – jiná chyba při přihlášení

Vzor odpovědi

Formát odpovědi odpovídá standardní odpovědi pro XML-RPC. Navíc vždy jako první parametr obsahuje ticker, který je shodný jako při volání.

<?xml version="1.0"?>
<methodResponse>
<params>
<param>
<value><string>ticker</string></value>
</param>
<param>
<value><i4>130</i4></value>
</param>
</params>
</methodResponse>

Popis dokumentu a jeho příjem

Dokument je popsán strukturou Document.

/* Document description */
Struct Document {
/* Unique document identifacator */
string documentId;
/* Document version. Every document
* can have more versions.
*/
string version;
/* Document version. This is identification
* of subversion on server side. Client can
* safely ignore this value and have to just
* send it back to server.
*/
string serverVersion;
/* Document type. Document type define which
* attributes are valid for document, how-to
* display document and organize in logical
* structure. Every document have to have
* valid type.
*/
string type;
/* Document modification.
* 0 – document is not modified
* 1 – document attributes are modified
*/
int modified;
/* Document attributes. Array of document
* attributes. Used attributes depens on document type
*/
array attributes {
/* Structure describes one attribute */
struct Attribute {
/* Attribute name */
string name;
/* Attribute value */
string value;
};
};
/* Array of files, pages. */
array files {
/* Structure describing one file, page */
struct File {
/* Unique file (page) identifacator */
string ident;
/* File mime-type. */
string mimeType;
/* Page importance.
* 0 – page is not important
* 1 – page is important
*/
int important;
/* Page modification.
* 0 – page is not modified
* 1 – page attributes are modified
* 2 – page data modified
* 3 – page attributes and data modified
*/
int modified;
/* Page number */
int pageNumber;
/* Page notes or comments. */
string note;
/* Original filename. */
string origName;
/* Keys for page decryption/encryption. */
string keys;
/* Page signature. */
string signature;
};
};
};

Dokument ze serveru na klienta je možno zaslat metodou pushDocument. Metoda zajistí přeposlání dokumentu, resp. popisu jeho struktury Document. Metoda nemá žádnou návratovou hodnotu. Při příjmu dokumentu klient reaguje na nastavení hodnot modified.

void pushDocument(string ticker, Document document, int state);

Parametr state určuje, zda je možno dokument odeslat zpět, zde je určen pouze k prohlížení či je možno mazat stránky (0 – dokument pouze pro čtení, 1 – dokument pro čtení a zápis).

Vyžádání souboru

Vyžádání souboru ze serveru se provede metodou requestFile. Metoda zajistí odeslání jedné stránky do klienta. Soubor je odesílán jako rámec typu 1.

void requestFile(string ticker, string fileId);

Parametr fileId je jednoznačný identifikátor souboru.

Vyžádání dokumentu

Klient může zaslat žádost o dokument pomocí metody getDocument.

int getDocument(string ticker, string docId, string version);

Parametr docId je jednoznačný identifikátor dokumentu.
Parametr version je identifikace verze, pokud je řetězec prázdný je zaslána poslední verze.
Metoda vrací 0 v případě platné žádosti. V případě chyby, neplatná žádost nebo nedostupnosti dokumentu je vrácena hodnota >0.

Vyžádaný dokument je zaslán zpět pomocí metody pushDocument.

Vyžádání konfigurace

Vyžádání konfiguračního souboru ze serveru se provede metodou requestConfig. Metoda zajistí odeslání požadovaného souboru do klienta. Soubor je odesílán jako rámec typu 2.

void requestConfig(string ticker, string fileId);

Parametr fileId je jednoznačný identifikátor souboru.

V případě chyby vyžádání souboru, tj. soubor je neplatný, neexistuje apod. může server vyslat oznámení o chybě.

void errorRequestConfig(string ticker, string fileId, int errorCode);

Parametr fileId je identifikátor souboru, který není možno vrátit.
Parametr errorCode je identifikace chyby ke které došlo.

Uložení dokumentu

Uložení dokumentu se skládá ze tří kroků. Prvním je vytvoření nové verze na straně serveru, alokace identifikátorů pro ukládané soubory, druhým uložení vlastních datových souborů a třetím potvrzení úspěšného přijetí celého dokumentu.

/* Structure with newly allocated
* identificators, new version
*/
Struct SaveDocument {
/* Document state:
* 0 – ok, 1 – lock, 2 – document not up2date, 3 – error
*/
int state;
/* Document identifacator. This is unique
* document identifacator. If new document
* is saved server have to generate this identificator.
*/
string documentId;
/* Identificator of new document version.
* Each document version have to unique combination of
* docId and version.
*/
string version;

/* Identificator of new server version.
* Server version is used by optimistic server locks.
*/
string serverVersion;
/* List of new identificators for files. */
array<string> NewFileIdents;
};

/* Function for saving document or new version of document. */
SaveDocument saveDocument(string ticker, Document document);

Parametrem funkce je struktura Document. Musí mít korektně vyplněny všechny položky. Výjimku tvoří identifikátory ukládaných souborů. V případě, kdy soubor není modifikován, tj. nebude odesílán na server, tak je vyplněn současný identifikátor, u změněného nebo nového souboru se identifikátor nevyplňuje a je to prázdný řetězec. Funkce vrací zpět identifikátory všech ukládaných souborů.

Při ukládání nového dokumentu na server je identifikátor dokumentu i jeho verze prázdný řetězec. Server vrací zpět nově vytvořený identifikátor dokumentu a jeho verzi.

Chování serveru při ukládání souborů:

Jestliže je vyžádán dokument v průběhu ukládání, tak se vrací poslední platně uložená verze.

Jestliže se klient pokouší uložit dokument paralelně s jiným je vrácena informace o uplatněném zámku. Zámek se odemkne při uložení všech souborů, pádu spojení nebo vypršení časového limitu.

Po úspěšném přijetí celého dokumentu je poslána notifikace zpět na klienta, tj. zavolána funkce:

void receivedDocument(string ticker, string documentId,
string documentVersion);

Funkce nemá žádnou návratovou hodnotu a slouží pouze pro notifikaci klienta.

V případě chyby při ukládání dokumentu je možno klienta notifikovat o této situaci pomocí errorReceivedDocument:

void errorReceivedDocument(string ticker, string documentId,
string documentVersion);

Funkce nemá žádnou návratovou hodnotu a slouží pouze pro notifikaci klienta.

Příjem objektu

Protokol umožňuje přenos obecných objektů. Přenášený typ objektu je určen položkou type. Další hodnoty definované pro daný typ objektu jsou popsány dvojicí název/hodnota. Následující struktura popisuje jeden přenášený objekt.

/* Object description /
Struct Object {
/* Object type */
string type;
/* Array of object attributes */
array attributes {
/* One attribute */
struct Attribute {
/* Attribute name */
string name;
/* Attribute value */
string value;
};
};
};

Objekt je přenesen pomocí metody pushObject.

void pushObject(ticker, Object);

Metoda zajistí přeposlání objektu, resp. jeho struktury. Metoda nemá žádnou návratovou hodnotu.

Stav připojení

Po provedení autorizace nemohou přicházet nevyžádané dokumenty na klienta, tj. nelze posílat dokumenty pomocí pushDocument. Změnit stav připojení je možno pomocí metody setState:

void setState(string ticker, int iNewState);

Povolené stavy připojení:

0 – výchozí stav neumožňující příjem dokumentů metodou pushDocument

1 – příjem dokumentů pomocí pushDocument je možný

Type 1

Typ jedna umožňuje přenos jednoho binárního souboru. Přenášený soubor je identifikován jedním identifikátorem.

FRDT=IDSZ IDDT BIDT

Význam jednotlivých bloků

Položka	Velikost	Význam
IDSZ	4	Velikost identifikátoru
IDDT	IDSZ	Data identifikátoru
BIDT	FRSZ-4-IDSZ	Binární data přenášeného souboru

Type 2

Typ 2 umožňuje přenos jednoho konfiguračního souboru. Přenášený soubor je identifikován jedním identifikátorem. Viz. popis v bodu 4.5.

FRDT=IDSZ IDDT BIDT

Význam jednotlivých bloků

Položka	Velikost	Význam
IDSZ	4	Velikost identifikátoru
IDDT	IDSZ	Data identifikátoru
BIDT	FRSZ-4-IDSZ	Binární data přenášeného souboru

Testovací packet

Pro zjištění stavu konekce a její dostupnosti existuje samostatný diagnostický packet. Tento packet by měl být druhou stranou ignorován. Jeho doručení je pro odesílatele známkou dostupnosti spojení.

0123 4 bytes
MGID

Identifikátor paketu (MGID), hodnota 0xD0 0x87 0x05 0xA3

Předpokládaná frekvence těchto packetů v případě jejich použití je v řádu desítek sekund.

Příklad komunikace

Následující tabulka popisuje příklad komunikace a popisuje stav jednotlivých proměnných:

Směr	Metoda	Popis
C → S	authorize	Autorizace k serveru
S → C	Ret authorize	Návrat výsledku autorizace
C → S	setState	Nastavení kanálu pro příjem dokumentů
S → C	pushDocument	Server zasílá dokument klientovi, ten kontroluje svou cache a vyžádá si chybějící soubory
C → S	requestFile	Vyžádání chybějícího souboru z dokumentu
S → C	Data, Type=1	Zaslání požadovaného souboru

Další příklad ukazuje komunikaci při zasílání změn zpět na server:

Směr	Metoda	Popis
C → S	updateDocument	Kontrola aktuálnosti vyžádaného dokumentu, funkce je v závislosti na nastavení volána pravidelně
S → C	Ret updateDocument	Vrácení aktuální struktury popisující dokument
C → S	saveDocument	Uložení dokumentu na server, resp. vytvoření identifikátorů pro zaslání dat. souborů
S → C	Ret saveDocument	Vrácení nových identifikátorů, které budou použity při odesílání
C → S	Data, type=1	Zaslání datového souboru na server.
S → C	receivedDocument	Notifikace klienta o příjmu celého dokumentu

Implementace

Protokol je navržen tak, aby umožňoval efektivní a rychlou implementaci. Na straně serveru je možno zapojit prioritní frontu a na tomto základě přednostně zasílat popisy dokumentů a teprve následně datové soubory.

Z hlediska Serveru je obtížnější část týkající se ukládání dokumentu a správného verzování. Klient má obtížnou implementaci příjmové části, neboť uživatel by měl soubory vidět co nejdříve ve stromu, ovšem k jejich přijetí dochází až později.

Atributy objektů

V současné době jsou definovány 2 typy objektů, které je možno přenášet do Tahiti. Jejich popis je uveden níže:

Objekt pro zobrazení URL

type: Tahiti.System.DisplayURL

význam: Objekt umožňuje předání URL do klientského systému a tím přechod na danou stránku, spuštění aplikace apod.

attributy:
URL – URL, které bude předáno systému

Objekt pro notifikaci o nové skenovací dávce

type: Tahiti.DistrIdent.DocSet.Open

význam: Objekt umožňuje stažení sady stránek k identifikaci ze serveru

attributy:
ServerName – logický název serveru odkud budou stránky staženy
DocSetId – identifikátor sady stránek

Závěr

Návrh je možno upravovat a modifikovat dle připomínek jednotlivých čtenářů. Navržené řešení by mělo být poměrně otevřené a umožňuje další případné rozšiřování.

Project: Tahiti	Date 2005-06-20, 20:02:59

Page 5/13	LightComp v.o.s.
Software Development

Tahiti - protokol 3.0

2001-04-28T15:26:03