# HTTP C API

Заголовок `duckonet_http324.h` расширяет HTTP API дополнительными структурами и функциями. Layout существующих записей не меняется. Новые записи используют версию 1 и точный размер по контракту `dn_record`.

| Функция | Назначение |
|---|---|
| `dn_session_http_capabilities324(session, output)` | Возвращает маску возможностей: upload=1, фазовые таймауты=2, IDNA/IPv6=4. |
| `dn_request_compile_http324(session, spec, hop, options, extra, output, error)` | Компилирует запрос с прежними параметрами и дополнительной `dn_http_options324`. |
| `dn_request_upload_feed324(request, data, written)` | Принимает не больше 64 KiB. `DN_PENDING` принимает ноль байт. |
| `dn_request_upload_finish324(request, producer_status)` | Отмечает EOF (`DN_OK`) либо ошибку producer. |
| `dn_request_upload_info_copy324(request, output)` | Копирует состояние в `dn_http_upload_info324`. |
| `dn_request_upload_wait324(request, minimum_room, wait_ms, output)` | Ограниченно ждёт место и копирует состояние. |
| `dn_http_url_normalize324(input, output, capacity, required)` | Канонизирует UTF-8 HTTP URL. При малом буфере возвращает `DN_E_BUFFER_SMALL` без частичной строки; `required` содержит размер результата. |

`dn_http_options324` содержит `prefix`, `connect_timeout_ms`, `read_timeout_ms`, `upload_length`, `upload_limit_bytes`, `flags`, `reserved`. Ноль фазового таймаута отключает дополнительный предел. Флаги `DN_HTTP324_UPLOAD=1` и `DN_HTTP324_LENGTH_KNOWN=2` обозначают поток и известную длину; `reserved=0`.

`dn_http_upload_info324` содержит `prefix`, `bytes_fed`, `bytes_read`, `queued_bytes`, `maximum_queued_bytes`, `ready`, `eof`, `terminal`, `timeout_reason`. Причины: NONE=0, TOTAL=1, CONNECT=2, READ=3. Счётчики подачи не подтверждают получение сервером.

Подача не вызывает пользовательский код. Она использует прежнее владение request/session, допуск и правила закрытия. Один handle нельзя освобождать, пока другой поток выполняет над ним вызов. После EOF или ошибки дождитесь terminal outcome и завершите существующие барьеры; сами по себе `finish` и `cancel` не подтверждают освобождение ресурсов.

Общие правила тел, адресов и времени приведены в [руководстве HTTP](streaming.html).


## Настройки соединения

Для прямого управления `TransportConfig` принимает те же `network`, `tls`, `rate_limit`; передавайте его существующему механизму компиляции транспорта и создания сессии. Не нужно вручную собирать C-структуры при работе через Python.

C API предоставляет `dn_session_create_network331`, `dn_session_network_capabilities331`, `dn_response_socket_info331`. Схемы их аргументов и размеры записей находятся в публичном `duckonet_network331.h`. Записи настроек имеют префикс размера/версии и не меняют layout остальных структур и функций. Фабрика принимает неизменяемые настройки соединения вместе с прежними engine/profile/transport/cookie-параметрами; getter возможностей возвращает битовую маску, getter сокета копирует наблюдение ответа в запись вызывающего кода.

Необязательные возможности проверяются по фактически загруженному runtime. Прежние вызовы продолжают использовать прежний путь. Новая опция со старым несовместимым runtime вызывает ошибку поддержки до чтения PEM-файлов и обращения к целевому серверу; сам факт наличия Python-класса не добавляет отсутствующую возможность нативной библиотеке.

На открытом `HttpClient` свойство `capabilities.connection_options` содержит поддержанные группы `dns`, `bind`, `tcp`, `mtls`, `spki_pins`, `rate_limit`; `capabilities.socket_diagnostics` сообщает о поддержке наблюдения сокета, `capabilities.http3_socks_udp` — SOCKS5 UDP. Эти сведения не отменяют ограничений конкретной комбинации настроек, профиля, ОС и прокси. `Socks5UDPProxy.validate()` и `TransportConfig.validate()` проверяют форму своей конфигурации; они не подключаются к серверу и не подтверждают сетевую доступность.