О протоколе
Килопарсек представляет из себя протокол удаленного исполнения процедур (RPC, remote procedure call) повышенной защиты, предназначенный для работы в не доверенных сетях, использующий мультиплатформенный язык Котлин, позволяющий собирать исполняемый код на платформах JVM (в частности Windows, Linux, Mac, Android), JS, и наивный код для linuxX64, linuxArm64, macosX64, MacosArm64, iosArm64, cygwin (windows) и некоторых других.
Собственный уровень шифрования и аутентификации позволяет не зависеть от используемого транспорта (на данный момент доступны реализации для Wesockets, TCP/IP, UDP). Уровень защиты не зависит от использования или не использования TLS, более того, для более эффективной работы следует использовать обычные транспорты без TLS, где это возможно, а в браузерных приложениях использовать wss://, чтобы соответствовать традиционным требованиям браузера.
Для аутентификации как клиента, так и сервера, используется алгоритм на кривых Эдвардса 25519, и для каждого соединения создаются временные уникальные ключи при помощи безопасной системы обмена ключами. Если клиент и сервер знают публичные ключи друг друга, соединение получается полностью защищенным. Ключ клиента можно использовать для его аутентификации в бизнес-логике.
Таблица поддерживаемых платформ и протоколов находится в начале файла README.
Вызовы и пуши
При вызовах в аргументах и возвращаемых значениях могут использоваться любые типы, поддерживаемые kotlinx.serialization, то есть, все обычные типы данных для Котлина, и все классы, для которых указан атрибут @Serializable или зарегистрирован явный стерилизатор. см. kotlinx.serialization.
Вызовы исполняются синхронно при помощи вызова call, вызывающая сопрограмма (coroutine) приостанавливается до исполнения вызова на удаленной стороне, с передачей возвращаемого значения или исключения. Даже если возвращаемого значения нет (Unit), исполнение возобновляется только после получения подтверждения об успешном исполнении вызова на другой стороне, или возникшем исключении.
В некоторых случаях информация об исполнении не требуется на вызывающей стороне, например, при отправке пуш-уведомлений. В этом случае обратная передача информации о вызове избыточна и может быть нежелательна. В этом случае следует использовать метод push, при использовании которого не происходит отсылки подтверждения по сети, и исполнение возобновляется почти сразу. Заметим, что с этим вызовом можно использовать только команды без возвращаемого значения, и факт успешного приема пуша на удаленной стороне не подтверждается.
Пример объявления команд и использования интерфейса с комментариями находится в файле README.
Справочные материалы
Для начала работы с библиотекой прочтите README. Там есть базовые примеры и ссылки на постоянно обновляемую техдокументацию.
Частые ситуации
- Websocket сервер и клиент описаны в README.
- Создание сервера TCP/IP
- Создание клиента TCP/IP
- Создание UDP сервера acceptUdpDevice, и UdpServer
- подключение UDP клиента connectUdpDevice
Подключение бизнес логики к разным протоколам
Серверную часть бизнес-логики следует создать один раз, создав свой класс сессии (если интерфейс имеет Стейт, или используя Unit), как в примере KiloServer.
Созданный интерфейс можно подключить к произвольному количеству серверов на разных транспортах, портах, и т.д. Важно при этом понимать,ё что когда один и тот же клиент, даже и с одинаковым ключом, подключен несколько раз по одному и тому же, или по разным транспортам, для каждого подключения создается свой экземпляр сессии.
Аналогичный подход может быть применен и с клиентскими интерфейсами, когда клиент экспортирует функции, доступные для вызова с сервера.