* Rework logic of filters

* Add some documentation to rspamd (about new filters logic and about protocol)

1 files changed, 82 insertions, 0 deletions

diff --git a/README.koi8.txt b/README.koi8.txt
new file mode 100644
index 000000000..fdecd4132
--- /dev/null
+++ b/README.koi8.txt
@@ -0,0 +1,82 @@
+API Rspamd.
+===========
+
+TODO.
+
+Логика работы фильтров rspamd.
+==============================
+
+1) Все фильтры регистрируются в конфиг файле в описании цепочек фильтров:
+header_filters=regexp,my_func
+где имя фильтра - это либо название c модуля, либо название перл функции
+Типы фильтров:
+* header_filters - фильтр заголовков
+* mime_filters - фильтр для каждой mime части
+* message_filters - фильтр всего сообщения целиком
+* url_filters - фильтры URL ссылок
+Свои результаты фильтры регистрируют при помощи добавления результата в метрику.
+
+2) Метрика - это символьное значение, в котором регистрируют свои результаты фильтры
+Существует метрика по умолчанию - "default", в которой регистрируют результаты фильтры,
+для которых явно не определена метрика
+Для каждой метрики существует специальная функция консолидации, которая рассчитывает коэффициенты
+результатов согласно внутренней логике соответствия символов и коэффициентов. По умолчанию такой
+функцией является простая сумма, которая настраивается особым образом в конфигурационном файле:
+
+# Блок factors
+factors {
+	# Например, "SURBL_DNS"=5.0
+	"SYMBOL_NAME" = coefficient;
+};
+Также для метрики можно зарегистрировать особую функцию, прописав в описании метрики
+metric {
+	name = "test_metric";
+	function = "some_function";
+	required_score = 20.0;
+};
+Пока поддерживаются только перловые функции.
+
+3) Результат - это пара значений: SYMBOL:FLAG, при этом, SYMBOL - это
+строчка, характеризующая результат, а FLAG - сработал данный фильтр или нет 
+(1 или 0). Результат добавляется в метрику, после чего передается функции консолидации.
+
+4) Итог - на выходе мы имеем обработанное сообщение, список метрик и их символов и результаты
+проверки.
+
+Протокол.
+=========
+
+Формат ответа:
+SPAMD/1.1 0 EX_OK 
+\       / \/
+ Версия   Код
+         ошибки
+Spam: False ; 2 / 5
+Это формат совместимости с sa-spamd (без метрик)
+
+Новый формат ответа:
+RSPAMD/1.0 0 EX_OK
+Metric: Name ; Spam_Result ; Spam_Mark / Spam_Mark_Required
+Metric: Name2 ; Spam_Result2 ; Spam_Mark2 / Spam_Mark_Required2
+
+Заголовков типа metric может быть несколько.
+Формат вывода символов:
+SYMBOL1, SYMBOL2, SYMBOL3 -- формат совместимости с sa-spamd
+Metric: SYMBOL1, SYMBOL2, SYMBOL3 -- формат rspamd
+
+Формат ответа зависит от формата запроса:
+PROCESS SPAMC/1.2
+\     / \       /
+Команда  Версия
+
+SPAMC - протокол совместимости с sa-spamd
+RSPAMC - новый протокол rspamd
+В любом из режимов работы поддерживаются следующие заголовки:
+Content-Length - длина сообщения
+Helo - HELO, полученный от клиента
+From - MAIL FROM
+IP - IP клиента
+Recipient-Number - число реципиентов
+Rcpt - реципиент
+
+Эти значения могут использоваться в фильтрах rspamd.