Описание Протокола ADC, Advanced Direct Connect Protocol Опции

[Setuper]

Структурированное описание протокола Advanced Direct Connect (ADC), под управлением которого уже работают некоторые хабы.
Ссылка на оригинальное описание: http://adc.sourceforge.net/ADC.html

По мере написания, в содержании будет появляться ссылка на соответствующий пост.
Делаю тему закрытой, дабы структурировано всё описать.


1. Введение
2. История версий
3. Структура протокола

3.1. Основное
3.2. Синтаксис команд
3.3. Типы команд
3.4. Хеш-функции
3.5. Идентификация клиента

3.5.1. SID
3.5.2. PID
3.5.3. CID

4. Файлы

4.1. Имена файлов и структура
4.2. Файл-лист

5. Команды характеристики BASE

5.1. Клиент – Хаб взаимодействие
5.2. Клиент – Клиент взаимодействие
5.3. Команды

STA
SUP
SID
INF
MSG
SCH
RES
CTM
RCM
GPA
PAS
QUI
GET
GFI
SND

6. Примеры

6.1. Связь Клиент – Хаб
6.2. Связь Клиент – Клиент

7. Стандартные дополнения/расширения

7.1. TIGR - поддержка TTH (Tiger Tree Hash)
7.2. BZIP – сжатие файл-листа пи помощи библиотеки bzip2
7.3. ZLIB - сжатие связи

7.3.1. ZLIB-FULL
7.3.2. ZLIB-GET

[Setuper]

1. Введение

ADC - это протокол для клиент-серверных сетей, на подобии Neo-Modus' Direct Connect (NMDC). Целью является создание простого протокола, который не нагружает ни клиент, ни сервер, и который можно расширять. В нём исправлены некоторые неудачные решения протокола NMDC, но не все.

Рассматриваются те же самые взаимодействия: клиент-клиент и клиент-сервер. Данная документация разделена на две части; первая часть описывает структуру протокола, вторая - специфичность системы протокола для использования этой структуры. Advanced Direct Connect - это первая версия, которая будет постепенно улучшаться.

Большинство идей для протокола пришли из проекта DCTNG (Jan Vidar Krey's). Основные участники разработки: Dustin Brody, Walter Doekes, Timmo Stange, Fredrik Ullner, Fredrik Stenberg и другие. Jon Hess посодействовал как создатель протокола NMDC.

Преимущества протокола:

• SID, а также названия команд протокола, состоят из четырёх латинских символов в верхнем регистре. Протокол достаточно хорошо подходит для реализации на языке СИ. По стандарту языка СИ sizeof(char) == 1, то есть 4 символа будут занимать 4 байта, или могут быть представлены в виде четырёхбайтового целого числа. Преобразование строки в число и обратно значительно упрощает и оптимизирует работу с командами и даёт возможность хранить команду в виде объединения.

Недостатки протокола:

• Разделителями протокола являются очень распространённые символы (пробел и перенос), которые нужно заменять на \s и \n. Так как эти символы очень распространены в сообщениях, то число замен будет всегда большим, чего не было в протоколе NMDC.
• По сравнению с протоколом NMDC, в протоколе ADC есть возможность в UserCommand удалить определённое меню. Однако, по-прежнему отсутствует возможность удаления определённого меню в определённом контексте.

[Setuper]

2. История версий

Последующие версии этого документа, а также промежуточные и более старые версии могут быть получены по адресу: https://dcplusplus.svn.sourceforge.net/svnr...s/trunk/ADC.txt. Эта версия представляется к ревизии: 923.
Данная версия: 1.0, 2007-12-01 (Первый релиз)

[Setuper]

3. Структура протокола

3.1. Основное

• Все команды протокола начинаются с четырёх букв. Первая буква определяет то, как команда должна быть послана, следующие три показывают что должно быть выполнено.
  
  
• Параметры разделяются пробелами, а каждая команда заканчивается символом переноса строки (код 0x0a). Экранируются элементы: "\s" - пробел, "\n" - новая строка и "\\" - обратный слеш. Данная версия протокола резервирует все остальные экранированные символы для возможного дальнейшего использования; любые команды, содержащие неизвестные экранированные символы, должны игнорироваться.
  
  
• Все отсылаемые команды должны отправляться в кодировке UTF-8 - закодированный Юникод в С нормализации.
  
  
• Клиенты должны игнорировать неизвестные/неправильные команды. Хабы должны игнорировать неправильные команды, и должны отсылать неизвестные команды, согласно их типу (префиксу).
  
  
• Адреса клиентов должны быть определены в виде десятичных чисел, разделённых точками ("x.x.x.x") для IPv4 или в формате RFC (1884) для IPv6. Адреса хабов должны быть определены ссылкой с добавкой "adc" спереди, которая показывает специфику данного протокола ("adc://server:port/").
  
  
• Числа отсылаются как строки в соответствии со стандартом плавающей точки, в качестве разделителя между целой дробной частью используется точка "." . Целыми являются числа без дробной части и без экспоненциальной добавки. Приложения должны иметь возможность оперировать с 64-битными положительными числами и с 64-битными числами с плавающей точкой. Префиксом отрицания является знак "-".
  
  
• SID, PID, CID и короткие бинарные данные отсылаются как закодированные base32 строки. Длинные бинарные данные должны передаваться, используя файловый механизм передачи.
  
  
• Имена расширений, протокольные имена и другой текст, не входящий в сообщения пользователя, могут включать только видимые символы, которые кодируются одним байтом в кодировке UTF-8 (Юникодные символы с номера 33 до 127). ADC - регистрозависим, и требует, чтобы имена команд были только в верхнем регистре.
  
  
• Некоторые команды и функциональные зависимости требуют использования хешей. Хеш генерируется в процессе установки сессии и остаётся постоянной на протяжении всей этой сессии (SID).

[Setuper]

3.2. Синтаксис команд

Код

message               ::= message_body? eol
message_body          ::= (b_message_header | cih_message_header | de_message_header | f_message_header | u_message_header | message_header)
                          (separator positional_parameter)* (separator named_parameter)*
b_message_header      ::= 'B' command_name separator my_sid
cih_message_header    ::= ('C' | 'I' | 'H') command_name
de_message_header     ::= ('D' | 'E') command_name separator my_sid separator target_sid
f_message_header      ::= 'F' command_name separator my_sid separator (('+'|'-') feature_name)+
u_message_header      ::= 'U' command_name separator my_cid
command_name          ::= simple_alpha simple_alphanum simple_alphanum
positional_parameter  ::= parameter_value
named_parameter       ::= parameter_name parameter_value?
parameter_name        ::= simple_alpha simple_alphanum
parameter_value       ::= escaped_letter+
target_sid            ::= encoded_sid
my_sid                ::= encoded_sid
encoded_sid           ::= base32_character{4}
my_cid                ::= encoded_cid
encoded_cid           ::= base32_character+
base32_character      ::= simple_alpha | [2-7]
feature_name          ::= simple_alpha simple_alphanum{3}
escaped_letter        ::= [^ \#x0a] | escape 's' | escape 'n' | escape escape
escape                ::= '\'
simple_alpha          ::= [A-Z]
simple_alphanum       ::= [A-Z0-9]
eol                   ::= #x0a
separator             ::= ' '

[Setuper]

3.3. Типы команд

Тип команды (определяющий символ, находящийся в начале команды) определяет то, каким образом отсылать эту команду. Клиенты, как получатели, используют ограниченный набор типов для рассылки. Клиенты должны использовать типы только для того, чтобы помочь себе распарсить команду, иначе команда должна игнорироваться. Итак, определены следующие типы (префиксы) команд:

B (Broadcast)
Хаб должен отослать команду всем подключенным клиентам, включая и самого отправителя.

C (Client message)
Клиенты должны использовать эту команду только для прямого соединения по протоколу TCP.

D (Direct message)
Хаб должен отправить эту команду для пользователя с указанным sid.

E (Echo message)
Хаб должен отправить команду для пользователей с sid и my_sid.

F (Feature broadcast)
Хаб должен отослать эту команду всем клиентам, которые поддерживают(+)/не поддерживают(-) данную характеристику. Поддержка клиентом той или иной характеристики определяется из поля SU, которое содержится в команде INF, отсылаемой клиентом.

H (Hub message)
Клиенты должны использовать данный тип для отсылки команды, которая предназначена только хабу.

I (Info message)
Хабы должны использовать данный тип для отсылки команды, которая не была отослана другим клиентом.

U (UDP message)
Клиенты должны использовать эту команду только для прямого соединения по протоколу UDP.

[Setuper]

3.4. Хеш-функции

Некоторые команды используются для определяния хеш-функций. При установке каждого нового соединения по команде SUP происходит обмен хеш-функциями. При коннекте клиент передаёт серверу несколько хеш-функций посредствам параметров команды SUP. Сервер вбирает одну из них и передаёт её клиенту, поставив её до любой другой хеш-функции в команде SUP, которая отправится с сервера. Клиент и хаб должны иметь по крайней мере одну одинаковую хеш-функцию, которая будет использоваться в протоколе и в файловой идентификации.

[Setuper]

3.5. Идентификация клиента

Каждый клиент идентифицируется по трём различным идентификаторам: идентификатор сессии - Session ID (SID), личный идентификатор - Private ID (PID) и идентификатор клиента - Client ID (CID).

[Setuper]

3.5.1. SID

Идентификатор сессии даётся клиенту на сессию, в течение которой он находится на хабе. Это идентификатор уникального пользователя на хабе, который назначается при входе на хаб. SID - 20-битный код, закодированный 4-байтной base32 строкой.

[Setuper]

3.5.2. PID

Приватный идентификатор глобально идентифицирует уникальных клиентов. Он используется при коннекте для генерации CID и не виден другим клиентам. PID генерируется для того, чтобы избежать конфузов. При генерации PID (при первом запуске клиента) используется текущее время и MAC адрес сетевой карты. Хабы и клиенты не должны раскрывать приватные идентификаторы другим клиентам, так как это нарушает безопасность ADC сетей. Клиенты должны иметь один и тот же PID в течение всей сессии на хабе.

Клиент отсылает на хаб данный идентификатор в команде INF. Хаб удаляет из команды INF этот идентификатор перед тем как отослать команду INF всем пользователям хаба.

[Setuper]

3.5.3. CID

Идентификатор клиента глобально и публично идентифицирует уникальные клиенты и лежит в основе связи между клиентами. Он генерируется по PID по определённому алгоритму. Хаб должен регистрировать клиентов по CID-у. CID должен оставаться неизменным в течении сессии. Клиенты должны уметь оперировать с CID-ми переменной длины.

[Setuper]

4. Файлы

4.1. Имена файлов и структура

Имена файлов отсчитываются от относительного (вымышленного) корня в шаре пользователя. "/" - разделитель директорий; каждый файл или имя директории должно быть уникальным в регистро-независимом контексте. Все печатные символы, включая пробел, допустимы в имени файла, символы "/" и "\" экранируются символом "\". Клиенты должны использовать фильтры для имён под свои файловые системы, имена файлов, полученные от других клиентов, должны также подчиняться этим правилам. Специальные имена "." и ".." не могут содержаться в директории или имени файла; любой полученный файл-лист, содержащий эти имена должен быть проигнорирован. Все имена директорий должны оканчиваться на "/".

Расшаренные файлы идентифицируются относительно безымянного корня "/" ("/dir/subdir/filename.ext"), тогда как дополнения могут добавить имя корня. Например, "TTH/…" для TIGR дополнения используют имя корня "TTH" для идентификации файлов по их "Tiger Tree Hash". Это недопустимо для имён из безымянного корня, которые попали в шару с идентификатором по контрольной сумме.

Без корневое имя файла "files.xml" определяет полный файл-лист, в формате XML в кодировке UTF-8. Клиентам рекомендуется использовать дополнения чтобы сжимать данный файл-лист.

Дополнения могут добавлять к имени файла свои расширения, обычно это делается для того, чтобы избежать повторения имён.

Специальный тип "list" используется для просмотра списков файлов. Частичный файловый список имеет ту же структуру, что и нормальный список, но директории могут быть теговыми с атрибутом Incomplete="1", который показывает на частичность. Только директории без корневых файлов могут начинаться с символа "/". Содержимое такой директории в последствии будет послано просящему клиенту на глубину, выбранную им (это нужно для отправки только того уровня, который требуется пользователю). Атрибут "Base" для поля "FileListing" определяет к какой конкретной директории принадлежит данный файл.

[Setuper]

4.2. Файл-лист

files.xml - список файлов, предназначенных для просмотра. Этот список должен удовлетворять следующей XML схеме:

HTML

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:simpleType name="base32Binary">
<xs:restriction base="xs:string">
<xs:pattern value="[A-Za-z2-7]+"></xs:pattern>
</xs:restriction>
</xs:simpleType>

<xs:simpleType name="zeroOne">
<xs:restriction base="xs:int">
<xs:enumeration value="0"></xs:enumeration>
<xs:enumeration value="1"></xs:enumeration>
</xs:restriction>
</xs:simpleType>

<xs:complexType name="ContainerType">
<xs:sequence minOccurs="0" maxOccurs="unbounded">
<xs:choice>
<xs:element ref="Directory"></xs:element>
<xs:element ref="File"></xs:element>
<xs:any processContents="lax"></xs:any>
</xs:choice>
</xs:sequence>
</xs:complexType>

<xs:attribute name="Base" type="xs:string"></xs:attribute>
<xs:attribute name="CID" type="base32Binary"></xs:attribute>
<xs:attribute name="Generator" type="xs:string"></xs:attribute>
<xs:attribute name="Incomplete" type="zeroOne" default="0"></xs:attribute>
<xs:attribute name="Name" type="xs:string"></xs:attribute>
<xs:attribute name="Size" type="xs:int"></xs:attribute>
<xs:attribute name="Version" type="xs:int"></xs:attribute>

<xs:element name="FileListing">
<xs:complexType>
<xs:complexContent>
<xs:extension base="ContainerType">
<xs:attribute ref="CID" use="required"></xs:attribute>
<xs:attribute ref="Version" use="required"></xs:attribute>
<xs:attribute ref="Generator" use="optional"></xs:attribute>
<xs:attribute ref="Base" use="required"></xs:attribute>
<xs:anyAttribute processContents="lax"></xs:anyAttribute>
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:element>

<xs:element name="Directory">
<xs:complexType>
<xs:complexContent>
<xs:extension base="ContainerType">
<xs:attribute ref="Name" use="required"></xs:attribute>
<xs:anyAttribute processContents="lax"></xs:anyAttribute>
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:element>

<xs:element name="File">
<xs:complexType>
<xs:sequence>
<xs:any minOccurs="0" maxOccurs="unbounded"></xs:any>
</xs:sequence>
<xs:attribute ref="Name" use="required"></xs:attribute>
<xs:attribute ref="Size" use="required"></xs:attribute>
<xs:anyAttribute processContents="lax"></xs:anyAttribute>
</xs:complexType>
</xs:element>

</xs:schema>

Пример файл-листа:

HTML

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<FileListing Version="1" CID="mycid" Generator="DC++ 0.701" Base="/">
<Directory Name="share">
<Directory Name="DC++ Prerelease">
<File Name="DCPlusPlus.pdb" Size="17648640" TTH="xxx" />
<File Name="DCPlusPlus.exe" Size="946176" TTH="yyy" />
</Directory>
<File Name="ADC.txt" Size="154112" TTH="zzz" />
</Directory>
<!-- Только при использовании частичного файл-листа -->
<Directory Name="share2" Incomplete="1"/>
</FileListing>

"encoding" должен быть всегда установлен в UTF-8. Клиенты должны иметь возможность оперировать с XML фалами как с BOM (byte order mark) так и без такового.

"Version" не изменяется, если не изменяется структура файла.

"CID" - это CID клиента, который генерирует файл-лист.

"Generator" - это опция для информативной цели.

"Base" - используется в частичных файл-листах, но также должно присутствовать и в простых файл-листах.

"Incomplete" - сигнализирует о том, что в частичном файл-листе содержатся не включённые в список пункты. "1" - означает, что директория содержит не включённые в список пункты, "0" - не содержит таковых. Incomplete="0" - по умолчанию и таким образом может быть опущено.

Дополнительная информация может быть добавлена в файл расширениями/дополнениями, но не гарантировано, что эта информация будет прочитана другими клиентами.

[Setuper]

5. Команды характеристики BASE

ADC клиенты/хабы, которые поддерживают основные команды должны отсылать характеристику "BASE" на стадии PROTOCOL.

Версия данной характеристики должна быть известны как клиенту, так и серверу. Сервер постоянно проверяет тип передачи. Для каждой команды определены возможные направления её передачи.

Направления передачи определяет то, каким образом команда может быть получена/послана. Хабы и клиенты могут поддерживать в дополнениях и другие направления передачи, однако, для характеристики BASE определены следующие направления:

• F (From)
  От хаба (хаб-клиент TCP)
• T (To)
  К хабу (хаб-клиент TCP)
• C (Client)
  Между клиентами (клиент-клиент TCP)
• U (UDP Client)
  Между клиентами (клиент-клиент UDP)

Далее, в описаниях команд, первый символ, который отвечает за направление, будет опускаться.

[Setuper]

5.1. Клиент – Хаб взаимодействие

Вход на хаб имеет определённую последовательность.
Непосредственно сам вход осуществляется на стадии под названием NORMAL.

Последовательность входа на хаб (стадии):

1. PROTOCOL - отсылка поддерживаемых характеристик
2. IDENTIFY - идентификация пользователя, статические проверки
3. VERIFY - проверка пароля
4. NORMAL - нормальная операция
5. DATA - для двоичных передач

Последовательность входа на хаб:

Код

Клиент -> Хаб: HSUP ADBASE ADTIGR ...
Хаб -> Клиент: ISUP ADBASE ADTIGR ...
Хаб -> Клиент: ISID <Client-SID> ...
Хаб -> Клиент: IINF HU1 HI1 ...
Клиент -> Хаб: BINF <My-SID> ID... PD...
Хаб -> Клиент: IGPA ...
Клиент -> Хаб: HPAS ...
Хаб -> Клиент: BINF <To All Clients>
Хаб -> Клиент: BINF <Client-SID>

В отличие от NMDC протокола, в ADC протоколе первая команда следует со стороны клиента, а не со стороны хаба.

[Setuper]

5.2. Клиент – Клиент взаимодействие

Клиент - клиент соединение использует ту же самую последовательность входа, что и клиент - хаб соединение, исключая стадию VERIFY и команды GPA/PAS.
Поддержка VERIFY/GPA/PAS должны объявляться дополнениями.
Клиент, который первый отослал команду CTM/RCM, будет контролировать соединение, после достижения между клиентами стадии NORMAL.

[Setuper]

5.3. Команды
Основные команды протокола ADC

• STA
• SUP
• SID
• INF
• MSG
• SCH
• RES
• CTM
• RCM
• GPA
• PAS
• QUI
• GET
• GFI
• SND

[Setuper]

STA

Синтаксис:

Код

STA separator code separator description

Направления:

F, T, C, U


Стадии:

Все


Описание:

Параметр code имеет формат "xyy", где x - это уровень ошибки, а yy - это код ошибки. Уровень и код ошибки обрабатываются отдельно, один о тот же код может быть на разных уровнях.


Уровни:

• 0 - успешное выполнение (используется для подтверждения команд), код ошибки должен быть "00", а дополнительный флаг "FC" содержит в себе подтверждение команды FOURCC, если это необходимо;
• 1 - исправимая ошибка (ошибка, но не дисконнект);
• 2 - критическая ошибка (дисконнект).

Коды ошибок:

• 00 - основная ошибка, показ описания;
• x0 - то же самое, что и 00, но распределенное согласно грубой структуре установленной ниже;
• 10 - основная ошибка хаба;
• 11 - хаб переполнен;
• 12 - хаб отключен (не принимает новые входящие соединения);
• 20 - основная ошибка входа/доступа;
• 21 - недопустимый ник;
• 22 - ник занят;
• 23 - недопустимый пароль;
• 24 - CID занят;
• 25 - доступ запрещён, флаг "FC" - это FOURCC последней команды. Отсылается когда пользователю не разрешается выполнить конкретную команду;
• 26 - только для зарегистрированных пользователей;
• 27 - недопустимый PID;
• 30 - кик/бан/дисконнект;
• 31 - постоянный бан;
• 32 - временный бан, флаг "TL" показывает число оставшихся секунд (Также используется при кике);
• 40 - ошибка протокола;
• 41 - не поддерживаемый протокол передачи, флаг "TO" - признак, флаг "PR" - строка протокола. Клиент, отсылающий команду CTM или RCM, должен отослать эту ошибку, если нет поддержки;
• 42 - ошибка направленного соединения, флаг "TO" - признак, флаг "PR" - строка протокола. Клиент, отсылающий команду CTM или RCM, должен отослать эту ошибку, если нет соединения;
• 43 - команда INF содержит ошибки, флаг "FM" - поле команды, "FB" - ошибочное поле;
• 44 - неправильное состояние, флаг "FC" показывает последнюю FOURCC команду;
• 45 - ошибка в характеристике, флаг "FC" показывает FOURCC ошибку характеристики;
• 46 - указан неверный IP в команде INF, флаг "I4" или "I6" показывает правильный IP;
• 47 - нет одинаковых характеристик в командах SUP хаба и клиента;
• 50 - клиент-клиент / ошибка передачи файла;
• 51 - файл недоступен;
• 52 - часть файла недоступна;
• 53 - нет свободного слота;
• 54 - нет одинаковых характеристик в командах SUP связываемых клиентов.

Замечания:

Параметр "description" содержит описание ошибки, для просмотра этого описания пользователем.

Даже если код ошибки неизвестен клиенту, он должен отображать текстовое сообщение. Коды ошибок используются для того, чтобы клиенты могли использовать различные действия на различные ошибки. Большинство кодов не содержат никаких параметров и могут использоваться только с типами команд C и I.

[Setuper]

SUP

Синтаксис:

Код

SUP (separator ('AD' | 'RM') feature)+

Направления:

F, T, C


Стадии:

PROTOCOL, NORMAL


Описание:

Данная команда определяет какие характеристики будут использоваться со стороны хаба и со стороны клиента. Название характеристики должно состоять из четырёх латинских букв верхнего регистра, при этом последним символом может быть цифра, которая указывает на версию характеристики. Первые же три символа должны быть исключительно латинскими буквами в верхнем регистре, дабы избежать каких-либо конфузов между различными ПО. Все без исключения ADC клиенты должны поддерживать BASE характеристику (или какую-либо её версию). Как сервер, так и клиент могут использовать любую характеристику, указанною другой стороной в команде SUP.

Указанная команда также может использоваться для динамического добавления или удаления характеристик. Префикс AD перед характеристикой указывает на то, что характеристика добавляется, префикс RM - указывает на удаление характеристики.

Когда хаб получает данную команду на стадии входа PROTOCOL, он должен ответить клиенту такой же командой со своими характеристиками, а также назначить клиенту SID и опционально отослать командой INF информацию о себе, и далее перейти на стадию IDENTIFY.

Когда при взаимодействии клиент-клиент один из клиентов получает данную команду на стадии PROTOCOL, он должен ответит такой же командой со своими характеристиками, отправить команду INF о себе и перейти на стадию IDENTIFY.

[Setuper]

SID

Синтаксис:

Код

SID separator sid

Направления:

F


Стадии:

PROTOCOL


Описание:

Данная команда назначает SID пользователю, который входит на хаб. Хаб должен отослать эту команду после команды SUP, но до команды INF на стадии PROTOCOL. Клиент, получивший эту команду, должен отослать на хаб информацию о себе командой INF.