Simple-httpd - это небольшой http сервер для Колибри ОС, позволяющий размещать файлы, создавать динамические сайты и различные сетевые ресурсы.
Для упрощения установки в репозитории находится директория bin, которая представляет из себя сервер, файл конфигурации и некоторое количество демонстрационных модулей. Файл конфигурации в этой директории рассчитан на то, что сервер будет размещён в корне раздела "/usbhd0/3/".
Дальнейшая настройка содержимого директории зависит от значений в файле httpd.ini .
Примечание: Файл должен использовать кодировку UTF-8. Другие кодировки могут привести к неправильной работе сервера.
В файле конфигурации можно выделяются 3 основных раздела:
[MAIN]
Данный раздел содержит в себе базовые элементы конфигурации, такие как:
ipIPv4 адрес, на котором будет работать сервер. Параметр обязателен для заполнения
portПорт подключения к серверу. При отсутствии параметра используется порт 80
connМаксимальное количество открытых соединений. При отсутствии параметра используется значение 10
work_dirДиректория для размещения статичных файлов сервера, является корнем для uri путей. Параметр обязателен для заполнения
mime_fileПуть до файла сопоставления mime типов. Если параметр не указан используется встроенная таблица соответствия.
modules_dirДиректория, относительно которой в разделе [MODULES] указываются модули расширения.
Примечание: В качестве modules_dir могут использоватьбся только ASCII символы.
[MODULES]
Данный раздел может содержать множество элементов, представленных в виде:
uri_path=file_name;cmdline , где
Особенности работы: каждый модуль добавляется последовательно и поиск нужного модуля также производится последовательно. Из-за этой особенности нужно учитывать расположение uri в данной секции. Для того, чтобы uri модуля сравнивался с путём в запросе раньше всех остальных он должен находится в самом конце списка, чтобы
Примечание: В качестве uri_path и cmdline может использоваться строка в UTF-8 с любыми символами, но путь к модулю всегда должен использовать только ASCII символы и не использовать символ ",". Кодировка cmdline не стандартизированна, но желательно использовать ASCII символы и проверять какую кодировку поддерживает модуль.
Сервер имеет возможность установить модуль для некоторого диапазона uri путей, для этого используется символ "*", обозначающий неопределённое количество(включая ноль) любых символов.
Например: При наличии записи /img/*=img_module.obj в секции модулей, сервер будет вызывать модуль для любых uri путей, имеющих в начале "/img/".
Также для установки модуля на все возможные uri пути необходимо прописать соответствие модуля с путём "/*".
Другие примеры:
*.lua=lua_module.obj Любой путь, имеющий в конце ".lua".
*/.*=err401.obj Любой путь, имеющий в названии директорию, начинающуюся с символа ".".
[TLS]
ВНИМАНИЕ!!! TLS шифрование на данный момент не поддерживается сервером
Данный раздел содержит необходимые данные для использования TLS сервером. Все поля обязательны для заполнения.
mbedtlsПолный путь до библиотеки MbedTLS.
ca_cerПолный путь до файла корневого сертификата.
srv_crtПолный путь до файла сертификата сервера.
srv_keyПолный путь до файла содержащего секретный ключ сервера
Если сервер находит этот раздел, то он автоматически предполагает использоваться в режиме HTTPS сервера. Переход в этот режим будет использовать TLS для получения и отправки http данных, при этом порт подключения всё равно выбирается полем port в разделе [MAIN]. Если порт не задан, то в качестве стандартного порта будет выбран порт 443.
Сервер одновременно может функционировать только в одном режиме, либо полностью использовать TLS, либо полностью не использовать. Это необходимо для предотвращения использования модулей, опирающихся на шифрование HTTPS протокола, в незащищённой среде передачи данных.
Модули сервера позволяют обрабатывать запросы и отправлять отправлять ответ, в том числе и формируемый динамически. По своей структуре, модуль является обычной динамической библиотекой, экспортирующей 3 специальные функции:
uint32_t __stdcall httpd_init(IMPORT_DATA* import, char* cmdline, char* uri_path)
Функция для инициализации ресурса(uri_path), ассоциированного с модулем .
В файле конфигурации для каждого ресурса можно добавить командную строку, передаваемую в эту функцию. Например
test3=test_unit4.obj; -database="file.sqlite"
Для большей совместимости рекомендуется обрабатывать эту командную строку в кодировке UTF-8.
При успешной инициализации функция должна вернуть ненулевое значение, если же инициализация прошла неуспешно, то должен возвращаться ноль.
Также для дальнейшей работы модуля предаётся указатель на таблицу экспортируемых сервером функций.
void __stdcall httpd_serv(CONNECT_DATA* request_data, uint32_t pdata)
Данная функция вызывается сервером при получении запроса на ресурс(uri_path) ассоциированным с модулем . Для обеспечения работы сервер передаёт в функцию уникальное значение, которое вернула функция "httpd_init" и указатель на структуру контекста запроса.
В этой функции модуль производит обработку запроса используя экспортируемые сервером функции и прямой доступ к некоторым полями структуры контекста. Эти имеющиеся возможности позволяют реализовать максимально гибкую обработку запросов, в том числе для протоколов, производных от http, например RTSP.
void __stdcall httpd_close(uint32_t pdata)
Функция вызывается сервером при завершении работы и необходима для правильности завершения обработки запросов в модулях и сохранения различных временных данных, если это необходимо. В функцию передаётся уникальное значение, возвращённое функцией "httpd_init".
Завершение работы сервера производится вызовом экспортируемой функции "close_server".
Алгоритм завершения работы модулей и самого сервера заключается в том, что сервер блокирует все новые запросы на подключение и вызывает функцию "httpd_close", для того чтобы модули завершили все открытые запросы и сохранили свои данные. После завершения всех модулей сервер полностью завершает свою работу.
Любой запрос так или иначе требует ответа со стороны модуля. Этот ответ можно отправить используя экспортируемые ядром функции, позволяющие создать экземпляр класса RESPD и через него производить отправку ответа на запрос.
Далее будут перечислены некоторые функции для данного класса. Для полного ознакомления с функциями следует ознакомиться с примерами в директории example и файлом modules_api.inc в репозитории проекта.
RESPD* __stdcall create_resp(CONNECT_DATA* session, uint32_t flags);
Функция создаёт объект RESPD, который имеет базовые настройки:
| Параметр | Значение |
|---|---|
| Статус ответа | "200" |
| Версия протокола | "HTTP/1.1" |
| Content-type | "text/html" |
Также разработчик может указать битовые флаги конфигурации ответа, например следующие:
FLAG_TRANSFER_CHUNKED
Этот флаг выбирает "chunked" тип передачи данных с сервера к клиенту, что позволяет отправлять данные неограниченной или неизвестной длины.
FLAG_RAW_STREAM
Этот флаг позволяет отправлять тело ответа небольшими пакетами, что можно использовать потоковую передачу данных поверх http протокола, например для реализации интернет радио
FLAG_NO_CACHE_CONTROL
Этот флаг указывает, что в ответе не будет дефолтного заголовка "Cache-Control"
FLAG_KEEP_ALIVE
Этот флаг указывает, что в ответе будет дефолтный заголовок "Connection: keep-alive"
void __stdcall destruct_resp(RESPD* ptr);
Функция производит удаление объекта RESPD.
void __stdcall set_http_status(RESPD* ptr, uint32_t status);
Функция производит изменение статуса ответа. Статус записывается в виде строки вида "201 " упакованной в dword(0x20313032).
void __stdcall set_http_ver(RESPD* ptr, char* version, uint32_t length);
Функция производит изменение версии, отправляемой в ответе. Версия должна иметь вид строки, например "RTSP/1.1"
uint32_t __stdcall add_http_header(RESPD* ptr, char* ptr_header, uint32_t length);
Функция производит добавление новых заголовков в виде стоки. Функция не производит проверки содержимого строки.
uint32_t __stdcall del_http_header(RESPD* ptr, char* ptr_header);
Функция производит удаление дополнительного заголовка. Память под строку никак не изменяется.
uint32_t __stdcall begin_send_resp(RESPD* ptr, uint64_t content_length);
Функция производит отправку HTTP строки статуса и заголовков для флагов FLAG_TRANSFER_CHUNKED и FLAG_RAW_STREAM.
uint32_t __stdcall send_resp(RESPD* ptr, char* content, uint32_t length);
Функция производит отправку http ответа целиком или его части для флагов FLAG_TRANSFER_CHUNKED и FLAG_RAW_STREAM .
uint32_t __stdcall finish_send_resp(RESPD* ptr);
Функция производит завершение отправки данных для флагов FLAG_TRANSFER_CHUNKED
В использовании функций добавления дополнительных заголовков и изменения версии есть особенность: строки должны существовать до момента деструктуризации объекта RESPD. Также модуль сам должен отслеживать и освобождать память под эти строки.
char* __stdcall find_uri_arg(CONNECT_DATA* session, char* key);
Функция производит поиск аргумента uri строки по его названию. Если аргумент найден, то возвращается указатель на строку с его значением, иначе ноль
char* __stdcall find_header(CONNECT_DATA* session, char* key);
Функция производит поиск http заголовка по его названию. Если аргумент найден, то возвращается указатель на строку с его значением, иначе ноль
uint32_t __stdcall read_http_body(CONNECT_DATA* session, char* buff, uint32_t len);
Функция производит чтение части содержимого http запроса в буфер и возвращает количество прочитанных байт. В случае ошибки сервер вернёт значение -1
Для получения остальной информации, такой как: метод запроса, версии протокола и фрагмент uri строки используется доступ к структуре CONNECT_DATA. Описание этой структуры есть в файле modules_api.inc репозитория.
void __stdcall FileInitFILED(FILED* buffer, char* path);
Функция производит инициализацию структуры FILED для её использования в файловых операциях.
FS_STATUS __stdcall FileInfo(char* path, void* buffer);
Функция производит чтение информации о файле в буфер по его пути и возвращает код ответа файловой системы. Если возвращён 0 - операция выполнена успешно, иначе возникла ошибка.
uint32_t __stdcall FileRead(FILED* file, void* buffer, uint32_t size);
Функция производит чтение части файла и автоматически увеличивает смещение чтение на количество прочитанных байт. По завершению чтения функция вернёт количество прочитанных байт в буфер, при ошибках чтение это значение равно нулю.
void __stdcall FileSetOffset(FILED* file, uint64_t offset);
Функция изменяет смещения чтения из файла.
uint32_t __stdcall FileReadOfName(char* path, void* buffer, uint32_t size)
Функция производит чтение файла по его названию начиная с нулевого смещения. Может использоваться для работы с небольшими файлами с различными настройками модуля. Функция возвращает количество прочитанных байт, если же возвращён 0, то вероятно произошла ошибка чтения.
Примечание: Все пути на файл или директорию должны быть в кодировке UTF-8 или совместимой с ней ASCII. Строки должны использовать Null-турминатор. Кодировки UTF-16LE, cp866, cp1251 и тд нельзя использовать.
void close_server();
Функция производит завершение работы всех модулей, и основного потока этого сервера. На время завершения работы модулей сервер блокирует все новые подключения, позволяя модулям завершить открытые соединения.
char* __stdcall Get_MIME_Type(FILED* fd);
Функция производит анализ названия файла по его структуре FILED и возвращает MIME тип, соответствующий расширению файла. Данные о MIME типах берутся из встроенной таблицы соответствий либо из дополнительно загружаемого файла.
Хоть сервер и имеет встроенную таблицу сопоставления расширения файла и MIME типа, но этого недостаточно. По этой причине у сервера есть возможность загружать внешний файл с такой таблицей. Для генерации этого файла был создан макрос для fasm, позволяющий в удобном виде создать такой файл и указать все необходимые MIME типы.
Файл с расширенными MIME типами находится в репозитории в директории "utils" в этом же файле написан сам макрос. Последовательность передаваемых параметров в макрос следующая:
При эксплуатации сервера может потребоваться возможность перенаправить запросы на какой-либо определённый файл(например на index.html) или модуль. Для данных целей к серверу был создан модуль "redirect.obj", позволяющий огранизовать перенаправление на определённые ресурсы как в пределах сервера, так и на внешние ресурсы. Для использования модуля необходимо задать модуль для всех необходимых uri путей и прописать для каждого такого uri командную строку, содержащую либо полный путь к ресурсу на этом сервере, либо полную uri ссылку. Пример использования:
/=redirect.obj, /docs/index.htm перенаправление запросов на главную страницу сервера из корня.
При работе сервера, модули могут создавать различные "системные" файлы, например логи, к которым должен быть заблокирован доступ из запросов клиентов. Для этих целей к серверу был создан модуль "block_access.obj", позволяющий задать http код статуса и короткое сообщение в теле ответа сервера. Для использования необходимо связать модуль с uri путём и задать строку параметров: код статуса ответа и, через пробел, короткое сообщение. Пример использования:
*/.*=block_access.obj, 400 access error Блокировка доступа к файлам и дерикториям начинающимся с символа "." .
Также можно не указывать текстовое сообщение, тогда сервер отправит только http статус. Если не указывать никаких параметров, то сервер будет по умолчанию отправлять код "403".