quiche

Кварт - это реализация протокола транспорта QUIC и HTTP/3, как указано в IETF. Он обеспечивает API низкого уровня для обработки пакетов QUIC и состояния подключения к обработке. Заявление отвечает за предоставление ввода/вывода (например, обработку розеток), а также за циклом событий с поддержкой таймеров.

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

Кто использует заварку?

Cloudflare

Поддержка Quiche Powers CloudFlare Edge Network HTTP/3. Веб-сайт CloudFlare-quic.com может использоваться для тестирования и экспериментов.

Android

DNS Resolver Android использует заварку для реализации DNS через HTTP/3.

загрязнение

Кварт может быть интегрирован в Curl, чтобы обеспечить поддержку HTTP/3.

Nginx (неофициальный)

Кварт может быть интегрирован в Nginx с использованием неофициального патча, чтобы обеспечить поддержку HTTP/3.

Начиная

Приложения командной строки

Перед тем как погрузиться в API заварного крема, вот несколько примеров о том, как использовать инструменты, предоставляемые заварным кремом, предоставляемые в рамках ящика заварного заделка.

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

 $ Cargo Run-bin Quiche-Client-https://cloudflare-quic.com/

В то время как сервер можно запускать следующим образом:

 $ Cargo Run-bin Quiche-Server--cert Apps/src/bin/cert.crt-apps/src/bin/cert.key

(Обратите внимание, что предоставленный сертификат самоподнегивается и не должен использоваться в производстве)

Используйте флаг командной строки- --help , чтобы получить более подробное описание параметров каждого инструмента.

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

Первым шагом в установлении подключения к Quic с использованием заварного завода является создание объекта Config :

 let mut config = Quiche :: config :: new (Quiche :: protocol_version)?; config.set_application_protos (& [b "Пример Proto"]); // Дополнительная конфигурация, специфичная для приложения и использования ...

Объект Config управляет важными аспектами соединения QUIC, таких как версия QUIC, идентификаторы ALPN, управление потоком, управление перегрузками, тайм -аут холостого хода и другие свойства или функции.

Quic-это протокол транспорта общего назначения, и существует несколько свойств конфигурации, где нет разумного значения по умолчанию. Например, разрешенное количество одновременных потоков любого конкретного типа зависит от приложения, работающего над QUIC, и других конкретных проблем.

Заварные квин по умолчанию по умолчанию несколько свойств до нуля, приложения, скорее всего, должны установить их на что -то другое, чтобы удовлетворить их потребности, используя следующее:

• set_initial_max_streams_bidi()

• set_initial_max_streams_uni()

• set_initial_max_data()

• set_initial_max_stream_data_bidi_local()

• set_initial_max_stream_data_bidi_remote()

• set_initial_max_stream_data_uni()

Config также содержит конфигурацию TLS. Это может быть изменено мутаторами на существующем объекте или путем вручную построив контекст TLS и создавая конфигурацию с использованием with_boring_ssl_ctx_builder() .

Объект конфигурации может быть разделен между несколькими соединениями.

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

На стороне клиента функция утилиты connect() может использоваться для создания нового соединения, в то время как accept() предназначена для серверов:

 // client connection.let conn = Quiche :: connect (some (& server_name), & scid, local, peer, & mut config)?; // server connection.let conn = Quiche :: Accept (& scid, none, локальный, однозначный & mut config)?;

Обработка входящих пакетов

Используя метод Connection's recv() Приложение может обрабатывать входящие пакеты, которые принадлежат этому соединению из сети:

 let to = socket.local_addr (). unwrap (); loop {let (read, from) = socket.recv_from (& mut buf) .unwrap (); let recv_info = Quiche :: Recvinfo {от, to}; let reade = Match Conn.Recv (& mut buf [.. Read], recv_info) {ok (v) => v, err (e) => {// произошла ошибка, обрабатывать его.

Создание исходящих пакетов

Вместо этого исходящий пакет генерируется с использованием метода подключения send() :

 LOOP {let (write, send_info) = match conn.send (& mut out) {ok (v) => v, err (Quiche :: erry :: dod) => {// dod witch.break;}, err ( e) => {// произошла ошибка, обрабатывать его. & send_info.to) .unwrap ();}

Когда пакеты отправляются, приложение отвечает за поддержание таймера для реагирования на события подключения на основе времени. Срок годности таймера может быть получен с помощью метода timeout() подключения.

 Let Timeout = conn.Timeout ();

Приложение отвечает за предоставление реализации таймера, которая может быть специфичной для используемой операционной системы или сетевой структуры. Когда истекает таймер, следует вызвать метод соединения on_timeout() , после чего в сети могут потребоваться отправить дополнительные пакеты:

 // Срок действия тайм -аута истек, обрабатывайте его.conn.on_timeout (); // Отправить больше пакетов по мере необходимости после Timeout.loop {let (write, send_info) = match conn.send (& mut out) {ok (v) => v, Err (Quiche :: error :: dod) => {// dode workited.break;}, err (e) => {// Произошла ошибка, обработка it.break;},}; socket.send_to (& out [.. write], & send_info.to) .unwrap ();}

Темп

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

Кварт обнаруживает намеки на исходящие пакеты через поле [ at ] структуры [ SendInfo ], которая возвращается методом send() . Это поле представляет время, когда конкретный пакет должен быть отправлен в сеть.

Приложения могут использовать эти подсказки, искусственно задерживая отправку пакетов с помощью специфичных для платформы механизмов (например, опция сокета SO_TXTIME на Linux) или пользовательские методы (например, с использованием таймеров пользовательского пространства).

Отправка и получение данных потока

После некоторых туда -сюда соединение завершит рукопожатие и будет готово к отправке или получению данных о приложениях.

Данные могут быть отправлены по потоку с помощью метода stream_send() :

 Если conn.is_establed () {// Завершено рукопожатие, отправьте несколько данных на потоке 0.conn.stream_send (0, b "Hello", true)?;}

Приложение может проверить, есть ли какие -либо читаемые потоки, используя метод readable() , который возвращает итератор на все потоки, которые имеют выдающиеся данные для чтения.

Метод stream_recv() может использоваться для извлечения данных приложения из читаемого потока:

 Если conn.is_establed () {// itater over uperable streams.for stream_id in conn.readable () {// поток читается, прочитайте, пока не будет больше данных. Пока al ok ((read, fin)) = conn.stream_recv (Stream_id, & mut buf) {println! ("at {} байты на потоке {}", read, stream_id);}}}

Http/3

Модуль Quiche HTTP/3 предоставляет API высокого уровня для отправки и получения HTTP -запросов и ответов поверх протокола транспорта QUIC.

Посмотрите на каталог [Quiche/Exerples/] для более полных примеров того, как использовать API заварного крема, включая примеры того, как использовать заварку в приложениях C/C ++ (см. Ниже дополнительную информацию).

Вызов заварку из C/C ++

Кварт обнажает тонкий API C API на вершине API ржавчины, который можно использовать для более легкой интеграции пирога в приложения C/C ++ (а также на других языках, которые позволяют вызывать CAI с помощью какой -либо формы FFI). C API следует той же конструкции, что и Rust One, модуль ограничений, налагаемых самим языком C.

При запуске cargo build статическая библиотека под названием libquiche.a будет создана автоматически вместе с ржавой. Это полностью отдельно и может быть связано непосредственно с приложениями C/C ++.

Обратите внимание, что для того, чтобы включить API FFI, функция ffi должна быть включена (она отключена по умолчанию) путем передачи --features ffi на cargo .

Здание

Кич требует ржавчины 1,67 или позже, чтобы построить. Последний стабильный выпуск ржавчины может быть установлен с использованием Rustup.

После установки среды строительства ржавчины, исходный код заварного заварного заделка можно получить с помощью GIT:

 $ git клон -рекурсивный https://github.com/cloudflare/quiche

а затем построен с помощью груза:

 $ Cargo Build -примеры

груз также может быть использован для запуска тестирования:

 $ CARGO TEST

Обратите внимание, что Boringssl, который используется для реализации криптографического рукопожатия Quic, основанного на TLS, должен быть построен и связан с заварным кремом. Это делается автоматически при строительстве заварного крема с использованием груза, но требует, чтобы команда cmake была доступна в процессе сборки. В окнах вам также нужен NASM. Официальная документация Boringssl имеет более подробную информацию.

В альтернативе вы можете использовать свою собственную сборку Boringssl, настраивая каталог Boringssl с переменной среды QUICHE_BSSL_PATH :

 $ QUICHE_BSSL_PATH = "/path/to/boringssl" Cargo Build -Examples

В качестве альтернативы вы можете использовать OpenSSL/Quictls. Чтобы позволить заварному заварному крему использовать этот поставщик, функция openssl может быть добавлена ​​в список --feature . Имейте в виду, что 0-RTT не поддерживается, если используется этот поставщик.

Здание для Android

Создание заварного крема для Android (NDK версия 19 или выше, 21 рекомендуется), может быть сделано с помощью Cargo-NDK (v2.0 или более поздней версии).

Сначала необходимо установить Android NDK, используя Android Studio или напрямую, и переменная среды ANDROID_NDK_HOME должна быть установлена ​​на путь установки NDK, например:

 $ export android_ndk_home =/usr/local/share/android-ndk

Затем можно установить инструмент для ржавчины для необходимых архитектур Android:

 $ rustup Target добавить Aarch64-Linux-And-ArmV7-Linux-Androideabi I686-Linux-Android x86_64-Linux-Android

Обратите внимание, что минимальный уровень API составляет 21 для всех целевых архитектур.

Cargo-NDK (v2.0 или более позднее) также необходимо установить:

 $ cargo Установите груз-NDK

Наконец, библиотека заварка может быть построена с помощью следующей процедуры. Обратите внимание, что варианты -t <architecture> и -p <NDK version> обязательны.

 $ cargo ndk -t arm64 -v8a -p 21 -сборка

См. Build_android_ndk19.sh для получения дополнительной информации.

Здание для iOS

Чтобы построить пирог для iOS, вам нужно следующее:

• Установите инструменты командной строки XCODE. Вы можете установить их с помощью Xcode или со следующей командой:

 $ xcode-select-install

• Установите инструмент Rust для архитектуры iOS:

 $ rustup Target добавить Aarch64-Apple-IOS x86_64-Apple-IOS

• Установите cargo-lipo :

 $ Cargo Установите груз-липо

Чтобы построить Libquiche, запустите следующую команду:

 $ Cargo Lipo -Features FFI

или

 $ Cargo Lipo -Features FFI -

Сборка iOS тестируется в Xcode 10.1 и Xcode 11.2.

Строительство изображений Docker

Чтобы создать изображения Docker, просто запустите следующую команду:

 $ Make Docker-Build

Вы можете найти изображения Docker заварного заварного крема на следующих репозиториях Docker Hub:

• Cloudflare/Quiche

• Cloudflare/Quiche-qns

latest тег будет обновляться всякий раз, когда обновления мастер -филиала Quiche Master.

Cloudflare/Quiche

Предоставляет сервер и клиент, установленные в/usr/local/bin.

Cloudflare/Quiche-qns

Предоставляет скрипт для тестирования пирогального заварного крема в пределах Quic-Interop-Runner.

Авторское право

Copyright (C) 2018-2019, Cloudflare, Inc.

Смотрите копирование для лицензии.