41 Commits
Author SHA1 Message Date
sergeych 271cdd18e3 Close owned WebSocket clients after reconnects 2026-08-11 14:45:37 +04:00
sergeych 19b349143d Add disconnect lifecycle handlers 2026-08-11 14:40:50 +04:00
sergeych 7bebbf7bd7 0.7.1-SNAPSHOT: small improvements to make it more universal and easy to use 2026-05-31 00:12:35 +03:00
sergeych 2829bcfecd Merge remote-tracking branch 'origin/master'
# Conflicts:
#	build.gradle.kts
2025-12-17 10:08:54 +01:00
sergeych 7cec803174 0.7.0-SNAPSHOT: migration to kotlin 2.2.21, upgrade dependencies, IOS/MacOS compatibility for broken kotlin.time/kotlinx.datetime 2025-12-17 10:07:02 +01:00
sergeych fe4cb2ca21 readme formatting 2025-11-02 14:13:47 +01:00
sergeych 6dc246e68c readme errors fix 2025-11-02 14:12:00 +01:00
sergeych bc5b5b3b3a 0.6.12 for all platforms: upgrade kotlin & dependencies 2025-10-24 18:46:19 +02:00
sergeych bc46e11158 cosmetics 2025-09-20 05:21:36 +04:00
sergeych 40f4352a31 more info n update in readme 2025-04-30 14:28:50 +04:00
sergeych cb696f5c0f 0.6.9-snapshot: wbesock can use text frames too (good for xiaomi) 2025-04-30 14:16:07 +04:00
sergeych fe96ac69d7 removed unused stuff 2025-03-27 13:37:45 +03:00
sergeych 212f82dedd 0.6.8 for all platforms 2025-03-27 00:26:10 +03:00
sergeych 59b7310385 version bump 2025-03-27 00:08:50 +03:00
sergeych 8837e49248 0.6.6 for all platforms 2025-03-26 23:50:20 +03:00
sergeych 7e1f7ec4aa fixed bug that prevented kilo client to restart if the channel was closed while channel send operation was suspended (featurebug of channels, one of) 2025-03-16 11:52:48 +03:00
sergeych 146878629e v.0.6.6-SNAPSHOT experimental wasmJs support, newer 2025-03-08 02:13:13 +03:00
sergeych d7fb26c03b v.0.6.5-SNAPSHOT experimental wasmJs support 2025-03-07 15:16:07 +03:00
sergeych 74c8bdde71 v.0.6.3 stable 2025-03-07 03:00:58 +03:00
sergeych f22ecf493b upgrade deps 2025-02-24 09:28:03 +03:00
sergeych 2b35112566 added copyright & tradewartime licensing 2025-02-20 12:10:09 +03:00
sergeych a80820b9a8 fixed/improved readme for publications 2025-02-20 11:58:13 +03:00
sergeych c0bc0e3dfe fix some ktor deprecations 2025-02-18 11:31:21 +03:00
sergeych 2d593e4107 coroutines core version upgraded 2025-02-18 11:30:47 +03:00
sergeych c1bd6f09a9 0.6.* started:
kotlin upgrade to 2.1.0
ktor updgared to 3.1.6
less debug noise
yet no wasmJS
2025-02-18 11:24:47 +03:00
sergeych 0ff27e6de9 kotlin upgrade to 2.1.0
less debug noise
use upgraded crypto2 version
2025-02-03 17:14:29 +03:00
sergeych 59906bbd2f kotlin upgrade to 2.0.21 2024-12-26 03:25:11 +03:00
sergeych 7871dc2d3d better support for code-based exceptions 2024-12-10 10:36:57 +03:00
sergeych a0dce8e604 we don't need to install Routing in web socket server - it is not used and an conflict 2024-11-27 10:45:23 +07:00
sergeych 04ffde421d 0.5.1-SNAPSHOT: crypto2 upgraded 2024-11-26 18:57:59 +07:00
sergeych 9545ca28cf websocket client now includes transport device to use in higher order protocols 2024-11-23 11:47:56 +07:00
sergeych 4098358233 +client.localIdentity 2024-11-22 09:18:07 +07:00
sergeych f2d8330ccc multiple onConnect in sessions support 2024-11-19 18:20:53 +07:00
sergeych 1032eebbbe extending functionality for kilogin 2024-11-19 12:12:41 +07:00
sergeych 93ab8ddf91 extending functionality for kilogin 2024-09-15 12:28:40 +03:00
sergeych 6ce1b576ee version bump 2024-09-01 19:42:23 +02:00
sergeych 99e98827f7 version bump 2024-08-30 11:05:19 +02:00
sergeych 26564b6081 0.4.1: performance, incompatible keys ID (as of crypto2 upgrade), fixed tests to properly run on Macos on arm64 target 2024-08-19 18:34:11 +02:00
sergeych 9ddb1209c9 more UDP tests 2024-08-11 19:08:49 +02:00
sergeych b68232653a readme docs 2024-08-11 16:31:08 +02:00
sergeych 2e4f551e8e more docs 2024-08-11 16:28:09 +02:00
53 changed files with 1229 additions and 210 deletions

No files matched your search

+4
View File
@@ -5,6 +5,7 @@ build/
!**/src/test/**/build/ !**/src/test/**/build/
### IntelliJ IDEA ### ### IntelliJ IDEA ###
.idea
.idea/modules.xml .idea/modules.xml
.idea/jarRepositories.xml .idea/jarRepositories.xml
.idea/compiler.xml .idea/compiler.xml
@@ -43,3 +44,6 @@ out/
# More # More
.kotlin .kotlin
/.idea/workspace.xml /.idea/workspace.xml
/.gigaide/gigaide.properties
local.properties
/kotlin-js-store/yarn.lock
+8
View File
@@ -0,0 +1,8 @@
<component name="ArtifactManager">
<artifact type="jar" name="kiloparsec-js-0.4.1">
<output-path>$PROJECT_DIR$/build/libs</output-path>
<root id="archive" name="kiloparsec-js-0.4.1.jar">
<element id="module-output" name="kiloparsec.jsMain" />
</root>
</artifact>
</component>
+8
View File
@@ -0,0 +1,8 @@
<component name="ArtifactManager">
<artifact type="jar" name="kiloparsec-js-0.4.3">
<output-path>$PROJECT_DIR$/build/libs</output-path>
<root id="archive" name="kiloparsec-js-0.4.3.jar">
<element id="module-output" name="kiloparsec.jsMain" />
</root>
</artifact>
</component>
+8
View File
@@ -0,0 +1,8 @@
<component name="ArtifactManager">
<artifact type="jar" name="kiloparsec-jvm-0.4.1">
<output-path>$PROJECT_DIR$/build/libs</output-path>
<root id="archive" name="kiloparsec-jvm-0.4.1.jar">
<element id="module-output" name="kiloparsec.jvmMain" />
</root>
</artifact>
</component>
+8
View File
@@ -0,0 +1,8 @@
<component name="ArtifactManager">
<artifact type="jar" name="kiloparsec-jvm-0.4.3">
<output-path>$PROJECT_DIR$/build/libs</output-path>
<root id="archive" name="kiloparsec-jvm-0.4.3.jar">
<element id="module-output" name="kiloparsec.jvmMain" />
</root>
</artifact>
</component>
+24
View File
@@ -1,5 +1,29 @@
<component name="ProjectCodeStyleConfiguration"> <component name="ProjectCodeStyleConfiguration">
<code_scheme name="Project" version="173"> <code_scheme name="Project" version="173">
<DBN-PSQL>
<case-options enabled="true">
<option name="KEYWORD_CASE" value="lower" />
<option name="FUNCTION_CASE" value="lower" />
<option name="PARAMETER_CASE" value="lower" />
<option name="DATATYPE_CASE" value="lower" />
<option name="OBJECT_CASE" value="preserve" />
</case-options>
<formatting-settings enabled="false" />
</DBN-PSQL>
<DBN-SQL>
<case-options enabled="true">
<option name="KEYWORD_CASE" value="lower" />
<option name="FUNCTION_CASE" value="lower" />
<option name="PARAMETER_CASE" value="lower" />
<option name="DATATYPE_CASE" value="lower" />
<option name="OBJECT_CASE" value="preserve" />
</case-options>
<formatting-settings enabled="false">
<option name="STATEMENT_SPACING" value="one_line" />
<option name="CLAUSE_CHOP_DOWN" value="chop_down_if_statement_long" />
<option name="ITERATION_ELEMENTS_WRAPPING" value="chop_down_if_not_single" />
</formatting-settings>
</DBN-SQL>
<ScalaCodeStyleSettings> <ScalaCodeStyleSettings>
<option name="MULTILINE_STRING_CLOSING_QUOTES_ON_NEW_LINE" value="true" /> <option name="MULTILINE_STRING_CLOSING_QUOTES_ON_NEW_LINE" value="true" />
</ScalaCodeStyleSettings> </ScalaCodeStyleSettings>
+1 -1
View File
@@ -3,7 +3,7 @@
<component name="FrameworkDetectionExcludesConfiguration"> <component name="FrameworkDetectionExcludesConfiguration">
<file type="web" url="file://$PROJECT_DIR$" /> <file type="web" url="file://$PROJECT_DIR$" />
</component> </component>
<component name="ProjectRootManager" version="2" languageLevel="JDK_17" default="true" project-jdk-name="17 (5)" project-jdk-type="JavaSDK"> <component name="ProjectRootManager" version="2" languageLevel="JDK_21" project-jdk-name="corretto-17" project-jdk-type="JavaSDK">
<output url="file://$PROJECT_DIR$/out" /> <output url="file://$PROJECT_DIR$/out" />
</component> </component>
</project> </project>
+104 -52
View File
@@ -1,27 +1,42 @@
# Kiloparsec # Kiloparsec
__Recommended version is `0.3.3`: to keep the code compatible with current and further versions we > 0.7.0-SNAPSHOT is recommended for newer builds; due to extremely poor Kotlin time migration architecture, on Apple targets it is the only working version.
ask to upgrade to `0.3.2` at least.__ Starting from this version some pacakage names are changed for
__Recommended version is `0.6.8`: to keep the code compatible with current and further versions we
ask to upgrade to `0.4.2` at least.__ Starting from this version some package names are changed for
better clarity and fast UDP endpoints are added. better clarity and fast UDP endpoints are added.
The new generation of __PARanoid SECurity__ protocol, advanced, faster, more secure. It also allows connecting any " The new generation of __PARanoid SECurity__ protocol, advanced, faster, more secure. It also allows connecting any "
block device" transport to the same local interface. Out if the box it block device" transport to the same local interface. Out if the box it
provides the following transports: provides the following transports:
| name | JVM | JS | native | | name | JVM | JS | wasmJS | native |
|----------------|--------|----|--------| |-------------------|:----:|:---:|:-------:|:------:|
| TCP/IP server | ✓ | | 0.2.6+ | | TCP/IP server | ✓ | | | ✓ |
| TCP/IP client | ✓ | | 0.2.6+ | | TCP/IP client | ✓ | | | ✓ |
| UDP server | 0.3.2+ | | 0.3.2+ | | UDP server | ✓ | | | ✓ |
| UDP client | 0.3.2+ | | 0.3.2+ | | UDP client | ✓ | | | ✓ |
| Websock server | ✓ | | | | Websockets server | ✓ | | | |
| Websock client | ✓ | ✓ | ✓ | | Websockets client | ✓ | ✓ | ✓ | ✓ |
### Note on version compatibility ### Note on version compatibility
Protocols >= 0.3.0 are not binary compatible with previous version due to more compact binary We recommend using `0.6.12`
Since version 0.6.9 websocket protocol supports both text and binary frames; old clients are backward compatible with
mew servers, but new clients only can work with older servers only in default binary frame mode. Upgrade also your
servers to get better websocket compatibility[^1].
Version 0.5.1 could be backward incompatible due to the upgrade of the crypto2.
Protocols >= 0.3.0 are not binary compatible with the previous version due to a more compact binary
format. The format from 0.3.0 onwards is supposed to keep compatible. format. The format from 0.3.0 onwards is supposed to keep compatible.
#### ID calculation algorithm is changed since 0.4.1
We recommend to upgrade to 0.4+ ASAP as public/shared key id derivation method was changed for even higher security.
### Supported native targets ### Supported native targets
- iosArm64, iosX64 - iosArm64, iosX64
@@ -30,26 +45,35 @@ format. The format from 0.3.0 onwards is supposed to keep compatible.
### Non-native targets ### Non-native targets
- JS (browser and nodeJS) - JS (browser and Node.js)
- JVM (android, macos, windows, linx, everywhere where JRE is installed) - JVM (android, macOS, windows, linux, everywhere where JRE is installed)
## TCP/IP transport ## TCP/IP and UDP transports
It is the fastest based on async socket implementation of ktor client. It works everywhere but JS target as These are the fastest based on async socket implementation of a ktor client. They work everywhere but JS target as
there is currently no widely adopted sockets for browser javascript. there are currently no widely adopted sockets for browser JavaScript.
## Websock server While UDP is faster than TCP/IP, it is less reliable, especially with commands and return values that serialize to more
than 240 bytes approx, and has no retransmission facilities (use TCP!). UDP, though, shines when all you need is
to [push](https://code.sergeych.net/docs/kiloparsec/kiloparsec/net.sergeych.kiloparsec/-remote-interface/push.html) with
little or no data in it.
While it is much slower than pure TCP, it is still faster than any http-based transport. It uses binary frames based on ## Websockets server
While it is much slower than TCP or UDP, it is still faster than any http-based API; it uses binary frames based on
the Ktor server framework to easily integrate with web services. We recommend using it instead of a classic HTTP API as the Ktor server framework to easily integrate with web services. We recommend using it instead of a classic HTTP API as
it beats it in terms of speed and server load even with HTTP/2. it beats it in terms of speed and server load even with HTTP/2.
We recommend to create the `KiloInterface<S>` instance and connect it to the websock and tcp servers in real We recommend to create the `KiloInterface<S>` instance and connect it to the websockets and tcp servers in real
applications to get easy access from anywhere. applications to get easy access from anywhere.
## Websocket client
It is slower than TCP or UDP, but it works on literally all platforms. See the sample below.
# Usage # Usage
The library should be used as maven dependency, not as source. The library should be used as a maven dependency, not as source.
## Adding dependency ## Adding dependency
@@ -70,12 +94,12 @@ It could be, depending on your project structure, something like:
```kotlin ```kotlin
val commonMain by getting { val commonMain by getting {
dependencies { dependencies {
api("net.sergeych:kiloparsec:0.3.2") api("net.sergeych:kiloparsec:0.6.8")
} }
} }
``` ```
## Create shared interface for your server and the client ## Create a shared interface for your server and the client
It could be a multiplatform library that exports it or just a shared or copied source file declaring structures It could be a multiplatform library that exports it or just a shared or copied source file declaring structures
and functions available, like: and functions available, like:
@@ -99,7 +123,7 @@ val cmdPushClient by command<String, Unit>()
## Call it from the client: ## Call it from the client:
Remember, we need to implement client interface `cmdPushClient` in our example, so we need to provide Remember, we need to implement client interface `cmdPushClient` in our example, so we need to provide
local interace too: local interface too:
```kotlin ```kotlin
// Unit: no session on the client: // Unit: no session on the client:
@@ -126,10 +150,11 @@ assertEquals(FooArgs("bar", 117), client.call(cmdGetFoo))
``` ```
## Create ktor-based server ## Create a ktor-based server
Normally server side needs some session. It is convenient and avoid sending repeating data on each request speeding up Normally the server side needs some session. It is convenient and avoids sending repeating data on each request speeding
the protocol. With KILOPARSEC it is rather basic operation: up
the protocol. With KILOPARSEC, it is a rather basic operation:
~~~kotlin ~~~kotlin
// Our session just keeps Foo for cmd{Get|Set}Foo: // Our session just keeps Foo for cmd{Get|Set}Foo:
@@ -156,11 +181,11 @@ val ns: NettyApplicationEngine = embeddedServer(Netty, port = 8080, host = "0.0.
~~~ ~~~
## Create TCP/IP client and server ## Create a TCP / IP client and server
Using plain TCP/IP is even simpler, and it works way faster than websocket one, and is _the same Using plain TCP/IP is even simpler, and it works way faster than websocket one, and is _the same
protected as `wss://` (and `ws://`) variant above due to same kiloparsec encryption in both cases. Still, a TCP/IP protected as `wss://` (and `ws://`) the variant above due to same kiloparsec encryption in both cases. Still, a TCP/IP
client is not available in Javascript browser targets and custom TCP ports could often be blocked by firewalls. client is not available in JavaScript browser targets, and custom TCP ports could often be blocked by firewalls.
Documentation is available in samples here: Documentation is available in samples here:
@@ -168,11 +193,13 @@ Documentation is available in samples here:
- [TCP/IP client](https://code.sergeych.net/docs/kiloparsec/kiloparsec/net.sergeych.kiloparsec/-kilo-client/index.html) - [TCP/IP client](https://code.sergeych.net/docs/kiloparsec/kiloparsec/net.sergeych.kiloparsec/-kilo-client/index.html)
In short, there are two functions that implements asynchronous TCP/IP transport on all platforms buy JS: In short, there are two functions that implement asynchronous TCP/IP transport on all platforms buy JS:
- [acceptTcpDevice](https://code.sergeych.net/docs/kiloparsec/kiloparsec/net.sergeych.kiloparsec.adapter/accept-tcp-device.html?query=fun%20acceptTcpDevice(port:%20Int):%20Flow%3CInetTransportDevice%3E) to create a server - [acceptTcpDevice](https://code.sergeych.net/docs/kiloparsec/kiloparsec/net.sergeych.kiloparsec.adapter/accept-tcp-device.html?query=fun%20acceptTcpDevice(port:%20Int):%20Flow%3CInetTransportDevice%3E)
to create a server
- [connectTcpDevice](https://code.sergeych.net/docs/kiloparsec/kiloparsec/net.sergeych.kiloparsec.adapter/connect-tcp-device.html) to connect to the server - [connectTcpDevice](https://code.sergeych.net/docs/kiloparsec/kiloparsec/net.sergeych.kiloparsec.adapter/connect-tcp-device.html)
to connect to the server
## UDP client and server ## UDP client and server
@@ -186,36 +213,49 @@ Is very much straightforward, same as with TCP/IP:
#### Command size #### Command size
Each command invocation and result are packed in a separate UDP diagram using effective binary packing. Each command invocation and result are packed in a separate UDP diagram using effective binary packing.
Thus for the best results commands and results should be relatively short, best to fit into 240 bytes. While bigger datagrams are often transmitted successfully, the probability of the effective transmission drops with the size. Thus, for the best results commands and results should be relatively short, best to fit into 240 bytes. While bigger
datagrams are often transmitted successfully, the probability of the effective transmission drops with the size.
Kiloparsec UDP transport does not retransmits not delivered packets. Use TCP/IP or websocket if it is a concern. Kiloparsec UDP transport does not retransmit not delivered packets. Use TCP/IP or websocket if it is a concern.
For the best results we recommend using [push](https://code.sergeych.net/docs/kiloparsec/kiloparsec/net.sergeych.kiloparsec/-remote-interface/index.html#1558240250%2FFunctions%2F788909594) for remote interfaces with UDP. For the best results, we recommend
using [push](https://code.sergeych.net/docs/kiloparsec/kiloparsec/net.sergeych.kiloparsec/-remote-interface/index.html#1558240250%2FFunctions%2F788909594)
for remote interfaces with UDP.
#### Timeouts #### Timeouts
As Datagrams do not form protocol itself, kiloparsec issues pings when no data is circulated between parties. As Datagrams do not form protocol itself, kiloparsec issues pings when no data is circulated between parties.
When no pings are received long enough, kiloparsec connection is closed. There are `maxInactivityTimeout` in all When no pings are received long enough, the kiloparsec connection is closed. There are `maxInactivityTimeout` in all
relevant functions and constructors. relevant functions and constructors.
Client shoudl not issue pings manually. Client should not issue pings manually.
## Reusing code between servers ## Reusing code between servers
The same instance of the [KiloInterface](https://code.sergeych.net/docs/kiloparsec/kiloparsec/net.sergeych.kiloparsec/-kilo-interface/index.html?query=open%20class%20KiloInterface%3CS%3E%20:%20LocalInterface%3CKiloScope%3CS%3E%3E) could easily be reused with all instances of servers with different protocols. The same instance of
the [KiloInterface](https://code.sergeych.net/docs/kiloparsec/kiloparsec/net.sergeych.kiloparsec/-kilo-interface/index.html?query=open%20class%20KiloInterface%3CS%3E%20:%20LocalInterface%3CKiloScope%3CS%3E%3E)
could easily be reused with all instances of servers with different protocols.
This is a common proactive to create a business logic in a `KiloInterface`, then create a TCP/IP and Websocket servers passing the same instance of the logic to both. This is a common practice to create a business logic in a `KiloInterface`, then create a TCP/IP and Websocket servers
passing the same instance of the logic to both.
## Note on the server identification ## Note on the server identification
We do not recommend to rely on TLS (HTTPS://, WSS://) host identification solely, in the modern world there is We do not recommend relying on TLS (HTTPS://, WSS://) host identification solely; in the modern world there is
a high probability of attacks on unfriendly (in respect to at least some of your users) states to the SSL certificates a high probability of attacks on unfriendly (in respect to at least some of your users) states to the SSL certificates
chain, in which case the MITM and spoofing will be undetected. Check the [remoteId](https://code.sergeych.net/docs/kiloparsec/kiloparsec/net.sergeych.kiloparsec/-kilo-client/remote-id.html?query=suspend%20fun%20remoteId():%20VerifyingPublicKey?) in your client on each connection and provide the safe [serverSecretKey](https://code.sergeych.net/docs/kiloparsec/kiloparsec/net.sergeych.kiloparsec/-kilo-server/index.html) when creating a server. chain, in which case the [MITM attack] and spoofing will be undetected. Check
the [remoteId](https://code.sergeych.net/docs/kiloparsec/kiloparsec/net.sergeych.kiloparsec/-kilo-client/remote-id.html?query=suspend%20fun%20remoteId():%20VerifyingPublicKey?)
in your client on each connection and provide the
safe [serverSecretKey](https://code.sergeych.net/docs/kiloparsec/kiloparsec/net.sergeych.kiloparsec/-kilo-server/index.html)
when creating a server.
This will effectively protetcs against certificate chain spoofing in the case of the application installed from the trusted source. This will effectively protect against certificate chain spoofing in the case of the application installed from the
trusted source.
__Important note__. The web application could not be completely secured this way unless is loaded from the IP-address, as the DNS could be spoofed the same, especially when used with `Cloudflare` or other CDN that can __Important note__. The web application could not be completely secured this way unless is loaded from the IP-address,
transparently substitute the whole site. In the case of we applications we strongly recommend not to use CDN except your own where you can control actual traffic rules. as the DNS could be spoofed the same, especially when used with `Cloudflare` or other CDN that can transparently
substitute the whole site. For applications, we strongly recommend not using CDN except your own, controlled ones. You
generally can't neither detect nor repel [MITM attack] performed from _any single cloudflare 'ray'_.
## See also: ## See also:
@@ -224,37 +264,49 @@ transparently substitute the whole site. In the case of we applications we stron
# Details # Details
It is not compatible with parsec family and no more based on an Universa crypto library. To better fit It is not compatible with Parsec family and no more based on the Universa crypto library. To better fit
the modern state of threats and rate of cyber crimes, KiloParsec uses more encryption and random key exchange on each the modern state of threats and rate of cyber crimes, KiloParsec uses more encryption and random key exchange on each
and every connection (while parsec caches session keys to avoid time-consuming keys exchange). For the same reason, and every connection (while parsec caches session keys to avoid time-consuming keys exchange). For the same reason,
keys cryptography for session is shifted to use ed25519 curves which are supposed to provide agreeable strength with keys cryptography for session is shifted to use ed25519 curves, which are supposed to provide agreeable strength with
enough speed to protect every connection with a unique new keys. Also, we completely get rid of SHA2. enough speed to protect every connection with unique new keys. Also, we completely get rid of SHA2.
Kiloparsec also uses a denser binary format [bipack](https://gitea.sergeych.net/SergeychWorks/mp_bintools), no more Kiloparsec also uses a denser binary format [bipack](https://gitea.sergeych.net/SergeychWorks/mp_bintools), no more
key-values, key-values,
which reveals much less on the inner data structure, providing advanced which reveals much less on the inner data structure, providing advanced
typed RPC interfaces with kotlinx.serialization. There is also Rust typed RPC interfaces with kotlinx.serialization. There is also Rust
implementation [bipack_ru](https://gitea.sergeych.net/DiWAN/bipack_ru). implementation [bipack_ru](https://gitea.sergeych.net/DiWAN/bipack_ru).
The architecture allows connecting same functional interfaces to several various type channels at once. The architecture allows connecting the same functional interfaces to several various type channels at once.
Also, the difference from parsecs is that there are no more unencrypted layer commands available to users. Also, the difference from parsecs is that there are no more unencrypted layer commands available to users.
All RPC is performed over the encrypted connection. All RPC is performed over the encrypted connection.
# Technical description # Technical description
Kiloparsec is a dull-duplex fully async (coroutine based) Remote Procedure Call protocol with typed parameters Kiloparsec is a full-duplex fully async (coroutine-based) Remote Procedure Call protocol with typed parameters
and support for serializing exceptions (e.g. exception thrown while executing remote command will be caught and and support for serializing exceptions (e.g. exception thrown while executing remote command will be caught and
rethrown at the caller context). rethrown at the caller context).
Kiloparsec is not REST, it _has advanced session mechanisms_ and built-in authentication based on the same curve keys. Kiloparsec is not REST, it _has advanced session mechanisms_ and built-in authentication based on the same curve keys.
Integrated tools to prevent MITM attacks include also non-transferred independently generated token that is calculated Integrated tools to prevent MITM attacks include also non-transferred independently generated token that is calculated
independently on the ends and is never transferred with the network. Comparing it somehow (visually, with QR code, etc) independently on the ends and is never transferred with the network. Comparing it somehow (visually, with QR code, etc.)
could add a very robust guarantee of the connection safety and ingenuity. could add a very robust guarantee of the connection safety and ingenuity.
Kiloparsec has built-in completely asynchronous (coroutine based top-down) transport layer based on TCP (JVM only as for Kiloparsec has a built-in completely asynchronous (coroutine-based top-down) transport layer based on TCP (JVM only as
for
now) and the same async Websocket-based transport based on KTOR. Websocket client is multiplatform, though the server is now) and the same async Websocket-based transport based on KTOR. Websocket client is multiplatform, though the server is
JVM only insofar. JVM only insofar.
# Licensing # Licensing
Currently, you need to obtain a license from https://8-rays.dev or Sergey Chernov. This is a work in progress, not yet moved to the public domain;
you need to obtain a license from https://8-rays.dev or [Sergey Chernov]. For open source projects it will most be free
on some special terms.
It will be moved to open source; we also guarantee that it will be moved to open source immediately if the software
export restrictions are lifted. We do not support such practices here at 8-rays.dev.
[MITM]: https://en.wikipedia.org/wiki/Man-in-the-middle_attack
[Sergey Chernov]: https://t.me/real_sergeych
[^1]: On some new Xiaomi phones we found problems with websocket binary frames, probably in ktor; use text frames
otherwise.
+10
View File
@@ -1,4 +1,14 @@
#!/bin/bash #!/bin/bash
#
# Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
#
# You may use, distribute and modify this code under the
# terms of the private license, which you must obtain from the author
#
# To obtain the license, contact the author: https://t.me/real_sergeych or email to
# real dot sergeych at gmail.
#
set -e set -e
./gradlew dokkaHtml ./gradlew dokkaHtml
rsync -avz ./build/dokka/* code.sergeych.net:/bigstore/sergeych_pub/code/docs/kiloparsec rsync -avz ./build/dokka/* code.sergeych.net:/bigstore/sergeych_pub/code/docs/kiloparsec
+59 -16
View File
@@ -1,50 +1,80 @@
/*
* Copyright (c) 2025-2026. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
import org.jetbrains.kotlin.gradle.ExperimentalWasmDsl
plugins { plugins {
kotlin("multiplatform") version "2.0.10" kotlin("multiplatform") version "2.2.21"
id("org.jetbrains.kotlin.plugin.serialization") version "2.0.0" id("org.jetbrains.kotlin.plugin.serialization") version "2.2.21"
id("com.android.library") version "8.7.2" apply true
`maven-publish` `maven-publish`
id("org.jetbrains.dokka") version "1.9.20" id("org.jetbrains.dokka") version "1.9.20"
} }
group = "net.sergeych" group = "net.sergeych"
version = "0.3.3" version = "0.7.1-SNAPSHOT"
repositories { repositories {
mavenCentral() mavenCentral()
mavenLocal() mavenLocal()
maven("https://maven.universablockchain.com/") maven("https://maven.universablockchain.com/")
maven("https://gitea.sergeych.net/api/packages/SergeychWorks/maven") maven("https://gitea.sergeych.net/api/packages/SergeychWorks/maven")
maven("https://gitea.sergeych.net/api/packages/YoungBlood/maven")
} }
kotlin { kotlin {
jvmToolchain(21)
jvm() jvm()
js { js {
browser { browser()
}
nodejs() nodejs()
} }
linuxX64()
linuxArm64()
macosArm64() macosArm64()
macosX64()
iosX64() iosX64()
iosArm64() iosArm64()
iosSimulatorArm64() iosSimulatorArm64()
linuxX64()
linuxArm64()
macosX64()
val ktor_version = "2.3.12" mingwX64()
androidTarget()
@OptIn(ExperimentalWasmDsl::class)
wasmJs {
browser()
}
val ktor_version = "3.1.1"
sourceSets { sourceSets {
all { all {
languageSettings.optIn("kotlinx.serialization.ExperimentalSerializationApi") languageSettings.optIn("kotlinx.serialization.ExperimentalSerializationApi")
languageSettings.optIn("kotlinx.coroutines.ExperimentalCoroutinesApi") languageSettings.optIn("kotlinx.coroutines.ExperimentalCoroutinesApi")
languageSettings.optIn("kotlin.ExperimentalUnsignedTypes") languageSettings.optIn("kotlin.ExperimentalUnsignedTypes")
languageSettings.optIn("kotlin.time.ExperimentalTime")
} }
val commonMain by getting { val commonMain by getting {
dependencies { dependencies {
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3") implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.2")
implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.1") implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.9.0")
api("io.ktor:ktor-client-core:$ktor_version") api("io.ktor:ktor-client-core:$ktor_version")
api("net.sergeych:crypto2:0.4.2") api("net.sergeych:crypto2:0.9.0")
}
}
val androidMain by getting {
dependencies {
implementation("io.ktor:ktor-client-okhttp:$ktor_version")
} }
} }
val ktorSocketMain by creating { val ktorSocketMain by creating {
@@ -56,8 +86,8 @@ kotlin {
val commonTest by getting { val commonTest by getting {
dependencies { dependencies {
implementation(kotlin("test")) implementation(kotlin("test"))
implementation("org.slf4j:slf4j-simple:2.0.9") implementation("org.slf4j:slf4j-simple:2.0.17")
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.8.1") implementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.10.2")
} }
} }
val ktorSocketTest by creating { val ktorSocketTest by creating {
@@ -68,6 +98,7 @@ kotlin {
implementation("io.ktor:ktor-server-core:$ktor_version") implementation("io.ktor:ktor-server-core:$ktor_version")
implementation("io.ktor:ktor-server-core-jvm:$ktor_version") implementation("io.ktor:ktor-server-core-jvm:$ktor_version")
implementation("io.ktor:ktor-server-websockets-jvm:$ktor_version") implementation("io.ktor:ktor-server-websockets-jvm:$ktor_version")
implementation("io.ktor:ktor-server-websockets:${ktor_version}")
implementation("io.ktor:ktor-server-netty:$ktor_version") implementation("io.ktor:ktor-server-netty:$ktor_version")
api("io.ktor:ktor-client-cio:$ktor_version") api("io.ktor:ktor-client-cio:$ktor_version")
} }
@@ -76,7 +107,6 @@ kotlin {
val jvmTest by getting { val jvmTest by getting {
dependsOn(ktorSocketTest) dependsOn(ktorSocketTest)
} }
val jsMain by getting { val jsMain by getting {
dependencies { dependencies {
implementation("io.ktor:ktor-client-js:$ktor_version") implementation("io.ktor:ktor-client-js:$ktor_version")
@@ -117,6 +147,7 @@ kotlin {
dependsOn(ktorSocketTest) dependsOn(ktorSocketTest)
} }
} }
}
publishing { publishing {
val mavenToken by lazy { val mavenToken by lazy {
@@ -135,7 +166,7 @@ kotlin {
} }
} }
} }
}
tasks.dokkaHtml.configure { tasks.dokkaHtml.configure {
outputDirectory.set(buildDir.resolve("dokka")) outputDirectory.set(buildDir.resolve("dokka"))
@@ -146,3 +177,15 @@ tasks.dokkaHtml.configure {
} }
} }
android {
namespace = "net.sergeych.kiloparsec"
compileSdk = 34
defaultConfig {
minSdk = 24
}
compileOptions {
sourceCompatibility = JavaVersion.VERSION_17
targetCompatibility = JavaVersion.VERSION_17
}
}
+18
View File
@@ -1,2 +1,20 @@
#
# Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
#
# You may use, distribute and modify this code under the
# terms of the private license, which you must obtain from the author
#
# To obtain the license, contact the author: https://t.me/real_sergeych or email to
# real dot sergeych at gmail.
#
kotlin.code.style=official kotlin.code.style=official
kotlin.mpp.applyDefaultHierarchyTemplate=false kotlin.mpp.applyDefaultHierarchyTemplate=false
kotlin.daemon.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8
kotlin.native.ignoreDisabledTargets=true
org.gradle.parallel=true
org.gradle.configuration-cache=true
org.gradle.caching=true
+11 -1
View File
@@ -1,5 +1,15 @@
#
# Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
#
# You may use, distribute and modify this code under the
# terms of the private license, which you must obtain from the author
#
# To obtain the license, contact the author: https://t.me/real_sergeych or email to
# real dot sergeych at gmail.
#
distributionBase=GRADLE_USER_HOME distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.2-bin.zip distributionUrl=https\://services.gradle.org/distributions/gradle-8.14.3-bin.zip
zipStoreBase=GRADLE_USER_HOME zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists zipStorePath=wrapper/dists
Vendored
+5 -11
View File
@@ -1,19 +1,13 @@
#!/bin/sh #!/bin/sh
# #
# Copyright © 2015-2021 the original authors. # Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
# #
# Licensed under the Apache License, Version 2.0 (the "License"); # You may use, distribute and modify this code under the
# you may not use this file except in compliance with the License. # terms of the private license, which you must obtain from the author
# You may obtain a copy of the License at
# #
# https://www.apache.org/licenses/LICENSE-2.0 # To obtain the license, contact the author: https://t.me/real_sergeych or email to
# # real dot sergeych at gmail.
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# #
############################################################################## ##############################################################################
+11
View File
@@ -1,5 +1,16 @@
/*
* Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
pluginManagement { pluginManagement {
repositories { repositories {
google()
mavenCentral() mavenCentral()
gradlePluginPortal() gradlePluginPortal()
} }
@@ -1,3 +1,13 @@
/*
* Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
package net.sergeych.kiloparsec package net.sergeych.kiloparsec
import io.ktor.utils.io.* import io.ktor.utils.io.*
@@ -0,0 +1,52 @@
/*
* Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
package net.sergeych.kiloparsec
import kotlinx.coroutines.sync.Mutex
import kotlinx.coroutines.sync.withLock
/**
* Multiplatform atomically mutable value to be used in [kotlinx.coroutines],
* with suspending mutating operations, see [mutate].
*
* Actual value can be either changed in a block of [mutate] when
* new value _depends on the current value_ or with [reset].
*
* [value] getter is suspended because it waits until the mutation finishes
*/
open class AtomicAsyncValue<T>(initialValue: T) {
private var actualValue = initialValue
private val access = Mutex()
/**
* Change the value: get the current and set to the returned, all in the
* atomic suspend operation. All other mutating requests including assigning to [value]
* will be blocked and queued.
* @return result of the mutation. Note that immediate call to property [value]
* could already return modified bu some other thread value!
*/
suspend fun mutate(mutator: suspend (T) -> T): T = access.withLock {
actualValue = mutator(actualValue)
actualValue
}
/**
* Atomic get or set the value. Atomic get means if there is a [mutate] in progress
* it will wait until the mutation finishes and then return the correct result.
*/
suspend fun value() = access.withLock { actualValue }
/**
* Set the new value without checking it. Shortcut to
* ```mutate { value = newValue }```
*/
suspend fun reset(value: T) = mutate { value }
}
@@ -1,3 +1,13 @@
/*
* Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
package net.sergeych.kiloparsec package net.sergeych.kiloparsec
import kotlinx.serialization.KSerializer import kotlinx.serialization.KSerializer
@@ -5,15 +15,28 @@ import kotlinx.serialization.Serializable
import net.sergeych.bintools.toDataSource import net.sergeych.bintools.toDataSource
import net.sergeych.bipack.BipackDecoder import net.sergeych.bipack.BipackDecoder
import net.sergeych.bipack.BipackEncoder import net.sergeych.bipack.BipackEncoder
import net.sergeych.kiloparsec.Command.Companion.unpackCall
import net.sergeych.utools.unpack import net.sergeych.utools.unpack
/** /**
* Typesafe command definition. Command is a universal entity in Divan: it is used * Typesafe command definition. Command is a universal entity in kiloparsec (and also diwan): it is used
* in node-2-node protocols and client API, and most importantly in calling smart contract * in node-2-node protocols and client API, and most importantly in calling smart contract
* methods. This is essentially a Kotlin binding to typesafe serialize command calls and * methods. This is essentially a Kotlin binding to typesafe serialize command calls and
* deserialize results. * deserialize results.
*
* To create command instances, it is recommended to use [command] that returns [CommandDelegate].
*
* Use [packCall] to serialize the command call with some arguments.
*
* Note that `Command` instances themselves are not serialized, instead, the call is serialized,
* in the form of [Call], containing name and properly serialized arguments.
*
* [unpackCall] deserialized result of the [packCall] so the proper handler for the command could
* be used. Then the result of the execution could be packed with [exec] and then unpacked with
* [unpackResult].
*
*/ */
class Command<A, R>( open class Command<A, R>(
val name: String, val name: String,
val argsSerializer: KSerializer<A>, val argsSerializer: KSerializer<A>,
val resultSerializer: KSerializer<R> val resultSerializer: KSerializer<R>
@@ -21,13 +44,29 @@ class Command<A, R>(
@Serializable @Serializable
data class Call(val name: String,val serializedArgs: UByteArray) data class Call(val name: String,val serializedArgs: UByteArray)
fun packCall(args: A): UByteArray = BipackEncoder.encode( /**
Call(name, BipackEncoder.encode(argsSerializer, args).toUByteArray()) * Pack command invocation with specified arguments.
).toUByteArray() */
fun packCall(args: A): UByteArray = BipackEncoder.encode(createCall(args)).toUByteArray()
/**
* Create [Call] instance for specified args vy serializing it properly
*/
fun createCall(args: A): Call = Call(name, BipackEncoder.encode(argsSerializer, args).toUByteArray())
/**
* Unpack result, obtained by [exec].
*/
fun unpackResult(packedResult: UByteArray): R = fun unpackResult(packedResult: UByteArray): R =
unpack(resultSerializer, packedResult) unpack(resultSerializer, packedResult)
/**
* Execute a command unpacking args.
*
* @param packedArgs arguments, as provided by [packCall] in the [Call] instance
* @param handler actual code to execute the command
* @return properly serialized result to be unpacked with [unpackResult].
*/
suspend fun exec(packedArgs: UByteArray, handler: suspend (A) -> R): UByteArray = suspend fun exec(packedArgs: UByteArray, handler: suspend (A) -> R): UByteArray =
BipackEncoder.encode( BipackEncoder.encode(
resultSerializer, resultSerializer,
@@ -36,6 +75,10 @@ class Command<A, R>(
).toUByteArray() ).toUByteArray()
companion object { companion object {
/**
* Unpack command invocation instance from [packCall]. Use [exec] to deserialize arguments and
* perform command.
*/
fun unpackCall(packedCall: UByteArray): Call = BipackDecoder.decode(packedCall.toDataSource()) fun unpackCall(packedCall: UByteArray): Call = BipackDecoder.decode(packedCall.toDataSource())
} }
} }
@@ -1,3 +1,13 @@
/*
* Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
package net.sergeych.kiloparsec package net.sergeych.kiloparsec
import kotlinx.serialization.KSerializer import kotlinx.serialization.KSerializer
@@ -1,3 +1,13 @@
/*
* Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
package net.sergeych.kiloparsec package net.sergeych.kiloparsec
/** /**
@@ -0,0 +1,20 @@
/*
* Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
package net.sergeych.kiloparsec
/**
* External errors wich needs to be encoded with a specific code
* should implement this interface so it will be serialized properly.
*/
interface ExceptionWithCode {
val code: String
val message: String?
}
@@ -1,3 +1,13 @@
/*
* Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
package net.sergeych.kiloparsec package net.sergeych.kiloparsec
import kotlinx.coroutines.CancellationException import kotlinx.coroutines.CancellationException
@@ -9,6 +19,7 @@ import kotlinx.coroutines.isActive
import kotlinx.coroutines.sync.Mutex import kotlinx.coroutines.sync.Mutex
import kotlinx.coroutines.sync.withLock import kotlinx.coroutines.sync.withLock
import net.sergeych.crypto2.SigningKey import net.sergeych.crypto2.SigningKey
import net.sergeych.crypto2.VerifyingKey
import net.sergeych.crypto2.VerifyingPublicKey import net.sergeych.crypto2.VerifyingPublicKey
import net.sergeych.mp_logger.LogTag import net.sergeych.mp_logger.LogTag
import net.sergeych.mp_logger.Loggable import net.sergeych.mp_logger.Loggable
@@ -60,6 +71,14 @@ class KiloClient<S>(
@Suppress("unused") @Suppress("unused")
val connectedStateFlow = _state.asStateFlow() val connectedStateFlow = _state.asStateFlow()
/**
* The verifying, or public, key identifying client sessions. It could be used to
* restore environment on reconnection. This is what remote side, e.g. server, sees as
* [KiloScope.remoteIdentity].
*/
@Suppress("unused")
val localIdentity: VerifyingKey? = secretKey?.verifyingKey
private var deferredClient = CompletableDeferred<KiloClientConnection<S>>() private var deferredClient = CompletableDeferred<KiloClientConnection<S>>()
private val job = private val job =
@@ -72,9 +91,11 @@ class KiloClient<S>(
debug { "get device and session" } debug { "get device and session" }
val client = KiloClientConnection(localInterface, kc, secretKey) val client = KiloClientConnection(localInterface, kc, secretKey)
deferredClient.complete(client) deferredClient.complete(client)
client.run { debug { "starting client run"}
val r = runCatching { client.run {
_state.value = it _state.value = it
} } }
debug { "----------- client run finished: $r" }
resetDeferredClient() resetDeferredClient()
debug { "client run finished" } debug { "client run finished" }
} catch (_: RemoteInterface.ClosedException) { } catch (_: RemoteInterface.ClosedException) {
@@ -90,7 +111,7 @@ class KiloClient<S>(
_state.value = false _state.value = false
resetDeferredClient() resetDeferredClient()
// reconnection timeout // reconnection timeout
delay(100) delay(700)
} }
} }
@@ -141,7 +162,7 @@ class KiloClient<S>(
* a key. Connection is established either with a properly authenticated key or no key at all. * a key. Connection is established either with a properly authenticated key or no key at all.
*/ */
@Suppress("unused") @Suppress("unused")
suspend fun remoteId(): VerifyingPublicKey? = deferredClient.await().remoteId() suspend fun remoteIdentity(): VerifyingPublicKey? = deferredClient.await().remoteId()
companion object { companion object {
class Builder<S>() { class Builder<S>() {
@@ -156,8 +177,19 @@ class KiloClient<S>(
var secretIdKey: SigningKey? = null var secretIdKey: SigningKey? = null
/** /**
* Build local command implementations (remotely callable ones), exception * Build local command implementations, those callable from the server, exception
* class handlers, etc. * class handlers, and anything else [KiloInterface] allows. Usage sample:
*
* ```kotlin
* val client = KiloClient {
* connect { connectTcpDevice("localhost:$port") }
* local {
* on(cmdPing) {
* "pong! $it"
* }
* }
* }
* ```
*/ */
fun local(f: KiloInterface<S>.() -> Unit) { fun local(f: KiloInterface<S>.() -> Unit) {
interfaceBuilder = f interfaceBuilder = f
@@ -1,3 +1,13 @@
/*
* Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
package net.sergeych.kiloparsec package net.sergeych.kiloparsec
import kotlinx.coroutines.* import kotlinx.coroutines.*
@@ -36,10 +46,10 @@ class KiloClientConnection<S>(
suspend fun run(onConnectedStateChanged: ((Boolean) -> Unit)? = null) { suspend fun run(onConnectedStateChanged: ((Boolean) -> Unit)? = null) {
coroutineScope { coroutineScope {
var job: Job? = null var job: Job? = null
var connectedScope: KiloScope<S>? = null
try { try {
// in parallel: keys and connection // in parallel: keys and connection
val deferredKeyPair = async { SafeKeyExchange() } val deferredKeyPair = async { SafeKeyExchange() }
debug { "opening device" }
debug { "got a transport device $device" } debug { "got a transport device $device" }
@@ -52,10 +62,11 @@ class KiloClientConnection<S>(
debug { "transport started" } debug { "transport started" }
val pair = deferredKeyPair.await() val pair = deferredKeyPair.await()
debug { "keypair ready" } debug { "keypair ready (1)" }
val serverHe = transport.call(L0Request, Handshake(1u, pair.publicKey)) val serverHe = transport.call(L0Request, Handshake(1u, pair.publicKey))
debug { "got server HE (2)" }
val sk = pair.clientSessionKey(serverHe.publicKey) val sk = pair.clientSessionKey(serverHe.publicKey)
var params = KiloParams(false, transport, sk, session, null, this@KiloClientConnection) var params = KiloParams(false, transport, sk, session, null, this@KiloClientConnection)
@@ -80,16 +91,17 @@ class KiloClientConnection<S>(
kiloRemoteInterface.complete( kiloRemoteInterface.complete(
KiloRemoteInterface(deferredParams, clientInterface) KiloRemoteInterface(deferredParams, clientInterface)
) )
clientInterface.onConnectHandler?.invoke(params.scope) connectedScope = params.scope
clientInterface.onConnectHandlers.invokeAll(connectedScope)
onConnectedStateChanged?.invoke(true) onConnectedStateChanged?.invoke(true)
job.join() job.join()
} catch (x: CancellationException) { } catch (x: CancellationException) {
info { "client is cancelled" } info { "client is cancelled" }
} catch (x: RemoteInterface.ClosedException) { } catch (x: RemoteInterface.ClosedException) {
x.printStackTrace() debug { "connection closed/refused by remote" }
info { "connection closed by remote" }
} finally { } finally {
connectedScope?.let { clientInterface.onDisconnectHandlers.invokeAll(it) }
onConnectedStateChanged?.invoke(false) onConnectedStateChanged?.invoke(false)
job?.cancel() job?.cancel()
device.apply { runCatching { close() } } device.apply { runCatching { close() } }
@@ -105,3 +117,6 @@ class KiloClientConnection<S>(
kiloRemoteInterface.await().push(cmd, args) kiloRemoteInterface.await().push(cmd, args)
} }
} }
internal fun <S>Collection<KiloHandler<S>>.invokeAll(scope: KiloScope<S>) =
forEach { runCatching { scope.it() } }
@@ -1,5 +1,16 @@
/*
* Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
package net.sergeych.kiloparsec package net.sergeych.kiloparsec
typealias KiloHandler<S> = KiloScope<S>.()->Unit
/** /**
* The local interface to provide functions, register errors for Kiloparsec users. Use it * The local interface to provide functions, register errors for Kiloparsec users. Use it
* with [KiloClient], [KiloClientConnection], [KiloServerConnection], etc. * with [KiloClient], [KiloClientConnection], [KiloServerConnection], etc.
@@ -8,25 +19,44 @@ package net.sergeych.kiloparsec
* *
* - It registers common exceptions from [RemoteInterface] and kotlin/java `IllegalArgumentException` and * - It registers common exceptions from [RemoteInterface] and kotlin/java `IllegalArgumentException` and
* `IllegalStateException` * `IllegalStateException`
* - It provides [onConnected] handler * - It provides [onConnected] and [onDisconnected] handlers
* *
* See [KiloServer] for usage sample. * See [KiloServer] for usage sample.
*/ */
open class KiloInterface<S> : LocalInterface<KiloScope<S>>() { open class KiloInterface<S> : LocalInterface<KiloScope<S>>() {
internal var onConnectHandler: (KiloScope<S>.()->Unit) ? = null internal val onConnectHandlers = mutableListOf<KiloHandler<S>>()
internal val onDisconnectHandlers = mutableListOf<KiloHandler<S>>()
fun onConnected(f: KiloScope<S>.()->Unit) { onConnectHandler = f } /**
* Registers handler [f] for [onConnected] event, to the head or the end of a handler list.
*
* @param addFirst if true, [f] will be added to the beginning of the list of handlers
*/
fun onConnected(addFirst: Boolean = false, f: KiloScope<S>.()->Unit) {
if( addFirst ) onConnectHandlers.add(0, f) else onConnectHandlers += f
}
/**
* Registers handler [f] for [onDisconnected] event, to the head or the end of a handler list.
*
* It is called with the same connection [KiloScope] as [onConnected], after an established
* connection is closed.
*
* @param addFirst if true, [f] will be added to the beginning of the list of handlers
*/
fun onDisconnected(addFirst: Boolean = false, f: KiloScope<S>.()->Unit) {
if( addFirst ) onDisconnectHandlers.add(0, f) else onDisconnectHandlers += f
}
init { init {
registerError { RemoteInterface.UnknownCommand() } registerError { RemoteInterface.UnknownCommand(it) }
registerError { RemoteInterface.InternalError(it) } registerError { RemoteInterface.InternalError(it) }
registerError { RemoteInterface.ClosedException(it) } registerError { RemoteInterface.ClosedException(it) }
// registerError { RemoteInterface.SecurityException(it) } registerError { RemoteInterface.SecurityException(it) }
registerError { RemoteInterface.InvalidDataException(it) } registerError { RemoteInterface.InvalidDataException(it) }
registerError { RemoteInterface.RemoteException(it) } registerError { RemoteInterface.RemoteException(it) }
registerError { IllegalStateException() } registerError { IllegalStateException() }
registerError { IllegalArgumentException(it) } registerError { IllegalArgumentException(it) }
} }
} }
@@ -1,3 +1,13 @@
/*
* Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
package net.sergeych.kiloparsec package net.sergeych.kiloparsec
import kotlinx.coroutines.CompletableDeferred import kotlinx.coroutines.CompletableDeferred
@@ -1,3 +1,13 @@
/*
* Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
package net.sergeych.kiloparsec package net.sergeych.kiloparsec
import kotlinx.serialization.Serializable import kotlinx.serialization.Serializable
@@ -1,3 +1,13 @@
/*
* Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
package net.sergeych.kiloparsec package net.sergeych.kiloparsec
import kotlinx.coroutines.CompletableDeferred import kotlinx.coroutines.CompletableDeferred
@@ -1,3 +1,13 @@
/*
* Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
package net.sergeych.kiloparsec package net.sergeych.kiloparsec
import net.sergeych.crypto2.SigningKey import net.sergeych.crypto2.SigningKey
@@ -1,10 +1,19 @@
/*
* Copyright (c) 2025-2026. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
package net.sergeych.kiloparsec package net.sergeych.kiloparsec
import kotlinx.coroutines.CancellationException import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.flow.Flow import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.launch import kotlinx.coroutines.launch
import net.sergeych.crypto2.SigningKey import net.sergeych.crypto2.SigningKey
import net.sergeych.kiloparsec.adapter.InetTransportDevice
import net.sergeych.mp_logger.LogTag import net.sergeych.mp_logger.LogTag
import net.sergeych.mp_logger.debug import net.sergeych.mp_logger.debug
import net.sergeych.mp_logger.exception import net.sergeych.mp_logger.exception
@@ -103,7 +112,7 @@ private val instances = AtomicCounter()
*/ */
class KiloServer<S>( class KiloServer<S>(
private val clientInterface: KiloInterface<S>, private val clientInterface: KiloInterface<S>,
private val connections: Flow<InetTransportDevice>, private val connections: Flow<Transport.Device>,
private val serverSecretKey: SigningKey? = null, private val serverSecretKey: SigningKey? = null,
private val sessionBuilder: () -> S, private val sessionBuilder: () -> S,
) : LogTag("KS:${instances.incrementAndGet()}") { ) : LogTag("KS:${instances.incrementAndGet()}") {
@@ -1,3 +1,13 @@
/*
* Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
package net.sergeych.kiloparsec package net.sergeych.kiloparsec
import kotlinx.coroutines.CompletableDeferred import kotlinx.coroutines.CompletableDeferred
@@ -43,6 +53,7 @@ class KiloServerConnection<S>(
suspend fun run() { suspend fun run() {
val deferredParams = CompletableDeferred<KiloParams<S>>() val deferredParams = CompletableDeferred<KiloParams<S>>()
val deferredTransport = CompletableDeferred<Transport<*>>() val deferredTransport = CompletableDeferred<Transport<*>>()
var connectedScope: KiloScope<S>? = null
val l0Interface = KiloL0Interface(clientInterface, deferredParams).apply { val l0Interface = KiloL0Interface(clientInterface, deferredParams).apply {
var params: KiloParams<S>? = null var params: KiloParams<S>? = null
@@ -75,7 +86,8 @@ class KiloServerConnection<S>(
kiloRemoteInterface.complete( kiloRemoteInterface.complete(
KiloRemoteInterface(deferredParams, clientInterface) KiloRemoteInterface(deferredParams, clientInterface)
) )
clientInterface.onConnectHandler?.invoke(p.scope) connectedScope = p.scope
clientInterface.onConnectHandlers.invokeAll(connectedScope)
} }
} }
@@ -83,8 +95,12 @@ class KiloServerConnection<S>(
deferredTransport.complete(transport) deferredTransport.complete(transport)
kiloRemoteInterface.complete(KiloRemoteInterface(deferredParams,clientInterface)) kiloRemoteInterface.complete(KiloRemoteInterface(deferredParams,clientInterface))
debug { "starting the transport"} debug { "starting the transport"}
try {
transport.run() transport.run()
debug { "server transport finished" } debug { "server transport finished" }
} finally {
connectedScope?.let { clientInterface.onDisconnectHandlers.invokeAll(it) }
}
} }
companion object { companion object {
@@ -1,3 +1,13 @@
/*
* Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
package net.sergeych.kiloparsec package net.sergeych.kiloparsec
import net.sergeych.mp_logger.LogTag import net.sergeych.mp_logger.LogTag
@@ -67,14 +77,18 @@ open class LocalInterface<S> : Loggable by LogTag("LocalInterface${idCounter.inc
name: String, name: String,
packedArgs: UByteArray, packedArgs: UByteArray,
): UByteArray = ): UByteArray =
(commands[name] ?: throw RemoteInterface.UnknownCommand()) (commands[name] ?: throw RemoteInterface.UnknownCommand(name))
.invoke(scope, packedArgs) .invoke(scope, packedArgs)
private val errorByClass = mutableMapOf<KClass<*>, String>() private val errorByClass = mutableMapOf<KClass<*>, String>()
private val errorBuilder = mutableMapOf<String, (String, UByteArray?) -> Throwable>() private val errorBuilder = mutableMapOf<String, (String, UByteArray?) -> Throwable>()
fun <T : Throwable> registerError( /**
* Register exception for automatic transmission over the kiloparsec connection using its [klass]
* and possibly override code. In most cases it is simpler to use [registerError].
*/
fun <T : Throwable> registerErrorClass(
klass: KClass<T>, code: String = klass.simpleName!!, klass: KClass<T>, code: String = klass.simpleName!!,
exceptionBuilder: (String, UByteArray?) -> T, exceptionBuilder: (String, UByteArray?) -> T,
) { ) {
@@ -82,10 +96,17 @@ open class LocalInterface<S> : Loggable by LogTag("LocalInterface${idCounter.inc
errorBuilder[code] = exceptionBuilder errorBuilder[code] = exceptionBuilder
} }
/**
* Register an exception to be transmitted automatically over the kiloparsec connection.
* Example:
* ```kotlin
* localInterface.registerError { IllegalArgumentException(it) }
* ```
*/
inline fun <reified T : Throwable> registerError( inline fun <reified T : Throwable> registerError(
noinline exceptionBuilder: (String) -> T, noinline exceptionBuilder: (String) -> T,
) { ) {
registerError(T::class) { msg, _ -> exceptionBuilder(msg) } registerErrorClass(T::class) { msg, _ -> exceptionBuilder(msg) }
} }
val errorProviders = mutableListOf<LocalInterface<*>>() val errorProviders = mutableListOf<LocalInterface<*>>()
@@ -95,7 +116,8 @@ open class LocalInterface<S> : Loggable by LogTag("LocalInterface${idCounter.inc
} }
fun getErrorCode(t: Throwable): String? = fun getErrorCode(t: Throwable): String? =
errorByClass[t::class] ?: errorProviders.firstNonNull { it.getErrorCode(t) } (t as? ExceptionWithCode)?.code
?: errorByClass[t::class] ?: errorProviders.firstNonNull { it.getErrorCode(t) }
fun encodeError(forId: UInt, t: Throwable): Transport.Block.Error = fun encodeError(forId: UInt, t: Throwable): Transport.Block.Error =
if (t is RemoteInterface.ClosedException) { if (t is RemoteInterface.ClosedException) {
@@ -1,3 +1,13 @@
/*
* Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
package net.sergeych.kiloparsec package net.sergeych.kiloparsec
/** /**
@@ -40,14 +50,21 @@ interface RemoteInterface {
/** /**
* Command is not supported by the remote party * Command is not supported by the remote party
*/ */
class UnknownCommand : RemoteException("UnknownCommand") class UnknownCommand(commandName: String) : RemoteException("UnknownCommand: $commandName")
open class InternalError(code: String="0"): RemoteException("Internal error: $code") open class InternalError(code: String="0"): RemoteException("Internal error: $code")
suspend fun <R> call(cmd: Command<Unit, R>): R = call(cmd, Unit) suspend fun <R> call(cmd: Command<Unit, R>): R = call(cmd, Unit)
/** /**
* Call the remote procedure with specified args and return its result * Call the remote procedure with specified [args] and return its result of type [R]. The calling coroutine
* suspends until the request is performed on the remote side and the result value (also `Unit`) will be received.
*
* When it is not necessary to wait for the return value and/or command execution, it is recommended to
* use [push] instead.
*
* @throws RemoteException if the execution caused exception on the remote size
* @throws Exception for registered exceptions, see [LocalInterface.registerError], etc.
*/ */
suspend fun <A, R> call(cmd: Command<A, R>, args: A): R suspend fun <A, R> call(cmd: Command<A, R>, args: A): R
@@ -55,6 +72,8 @@ interface RemoteInterface {
* Push the notification without waiting for reception or processing. * Push the notification without waiting for reception or processing.
* It returns immediately after sending data to the transport (e.g., to the network). * It returns immediately after sending data to the transport (e.g., to the network).
* Use [call] if it is necessary to wait until the command will be received and processed by the remote. * Use [call] if it is necessary to wait until the command will be received and processed by the remote.
*
* Push is onlu available for commands without returned value.
*/ */
suspend fun <A> push(cmd: Command<A, Unit>, args: A) suspend fun <A> push(cmd: Command<A, Unit>, args: A)
@@ -1,3 +1,13 @@
/*
* Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
package net.sergeych.kiloparsec package net.sergeych.kiloparsec
import kotlinx.coroutines.* import kotlinx.coroutines.*
@@ -17,13 +27,12 @@ import kotlinx.serialization.encoding.Encoder
import kotlinx.serialization.serializer import kotlinx.serialization.serializer
import net.sergeych.bipack.Unsigned import net.sergeych.bipack.Unsigned
import net.sergeych.crypto2.toDump import net.sergeych.crypto2.toDump
import net.sergeych.kiloparsec.Transport.Device
import net.sergeych.mp_logger.* import net.sergeych.mp_logger.*
import net.sergeych.utools.pack import net.sergeych.utools.pack
import net.sergeych.utools.unpack import net.sergeych.utools.unpack
/** /**
* Divan channel that operates some block [Device] exporting a given [localInterface] * Kiloparsec channel that operates some block [Device] exporting a given [localInterface]
* to remote callers. [LocalInterface] allows session managing, transmitting exceptions * to remote callers. [LocalInterface] allows session managing, transmitting exceptions
* in a scure and multiplatform way and provide local command execution (typed RPC) * in a scure and multiplatform way and provide local command execution (typed RPC)
*/ */
@@ -124,7 +133,13 @@ class Transport<S>(
} }
// now we have mutex freed so we can call: // now we have mutex freed so we can call:
val r = runCatching { device.output.send(pack(b).also { debug { ">>>\n${it.toDump()}" } }) } val r = runCatching {
do {
val cr = device.output.trySend(pack(b))
if( cr.isClosed ) throw ClosedSendChannelException("can't send block: channel is closed")
delay(100)
} while(!cr.isSuccess)
}
if (!r.isSuccess) { if (!r.isSuccess) {
r.exceptionOrNull()?.let { r.exceptionOrNull()?.let {
exception { "failed to send output block" to it } exception { "failed to send output block" to it }
@@ -184,10 +199,7 @@ class Transport<S>(
while (isActive && !isClosed) { while (isActive && !isClosed) {
try { try {
device.input.receive().let { packed -> device.input.receive().let { packed ->
debug { "<<<\n${packed.toDump()}" }
val b = unpack<Block>(packed) val b = unpack<Block>(packed)
debug { "<<$ $b" }
debug { "access state: ${access.isLocked}" }
when (b) { when (b) {
is Block.Error -> access.withLock { is Block.Error -> access.withLock {
val error = localInterface.decodeError(b) val error = localInterface.decodeError(b)
@@ -198,10 +210,7 @@ class Transport<S>(
} }
is Block.Response -> access.withLock { is Block.Response -> access.withLock {
calls.remove(b.forId)?.let { calls.remove(b.forId)?.complete(b.packedResult)
debug { "activating wait handle for ${b.forId}" }
it.complete(b.packedResult)
}
?: warning { "wait handle not found for ${b.forId}" } ?: warning { "wait handle not found for ${b.forId}" }
} }
@@ -228,12 +237,10 @@ class Transport<S>(
} catch (t: Throwable) { } catch (t: Throwable) {
send(Block.Error(b.id, "UnknownError", t.message)) send(Block.Error(b.id, "UnknownError", t.message))
} }
.also { debug { "command executed: ${b.name}" } }
} }
} }
debug { "=---------------------------------------------" }
} }
debug { "input step performed closed=$isClosed active=$isActive" } // debug { "input step performed closed=$isClosed active=$isActive" }
} catch (_: ClosedSendChannelException) { } catch (_: ClosedSendChannelException) {
info { "closed send channel" } info { "closed send channel" }
isClosed = true isClosed = true
@@ -243,7 +250,7 @@ class Transport<S>(
} catch (cce: LocalInterface.BreakConnectionException) { } catch (cce: LocalInterface.BreakConnectionException) {
info { "closing connection by local request ($cce)" } info { "closing connection by local request ($cce)" }
device.close() device.close()
} catch (t: RemoteInterface.ClosedException) { } catch (_: RemoteInterface.ClosedException) {
// it is ok: we just exit the coroutine normally // it is ok: we just exit the coroutine normally
// and mark we're closing // and mark we're closing
isClosed = true isClosed = true
@@ -269,7 +276,7 @@ class Transport<S>(
} }
debug { "no more active: $isActive / ${calls.size}" } debug { "no more active: $isActive / ${calls.size}" }
} }
info { "exiting transport loop" } debug { "exiting transport loop" }
} }
private suspend fun send(block: Block) { private suspend fun send(block: Block) {
@@ -1,3 +1,13 @@
/*
* Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
package net.sergeych.kiloparsec.adapter package net.sergeych.kiloparsec.adapter
import kotlinx.coroutines.channels.Channel import kotlinx.coroutines.channels.Channel
@@ -1,3 +1,13 @@
/*
* Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
package net.sergeych.kiloparsec.adapter package net.sergeych.kiloparsec.adapter
/** /**
@@ -1,3 +1,13 @@
/*
* Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
package net.sergeych.kiloparsec.adapter package net.sergeych.kiloparsec.adapter
import kotlinx.coroutines.channels.Channel import kotlinx.coroutines.channels.Channel
@@ -1,3 +1,13 @@
/*
* Copyright (c) 2025-2026. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
package net.sergeych.kiloparsec.adapter package net.sergeych.kiloparsec.adapter
import io.ktor.client.* import io.ktor.client.*
@@ -10,43 +20,71 @@ import kotlinx.coroutines.channels.Channel
import kotlinx.coroutines.channels.ClosedReceiveChannelException import kotlinx.coroutines.channels.ClosedReceiveChannelException
import kotlinx.coroutines.channels.ClosedSendChannelException import kotlinx.coroutines.channels.ClosedSendChannelException
import kotlinx.coroutines.launch import kotlinx.coroutines.launch
import kotlinx.io.IOException
import net.sergeych.crypto2.SigningKey import net.sergeych.crypto2.SigningKey
import net.sergeych.kiloparsec.KiloClient import net.sergeych.kiloparsec.*
import net.sergeych.kiloparsec.KiloConnectionData import net.sergeych.mp_logger.*
import net.sergeych.kiloparsec.KiloInterface import net.sergeych.mp_tools.decodeBase64Compact
import net.sergeych.kiloparsec.RemoteInterface import net.sergeych.mp_tools.encodeToBase64Compact
import net.sergeych.mp_logger.LogTag
import net.sergeych.mp_logger.exception
import net.sergeych.mp_logger.info
import net.sergeych.mp_logger.warning
import net.sergeych.mp_tools.globalLaunch import net.sergeych.mp_tools.globalLaunch
import net.sergeych.tools.AtomicCounter import net.sergeych.tools.AtomicCounter
private val counter = AtomicCounter() private val counter = AtomicCounter()
/**
* Shortcut to create websocket client. Use [websocketTransportDevice] with [KiloClient]
* for fine-grained control.
*/
fun <S> websocketClient( fun <S> websocketClient(
path: String, path: String,
clientInterface: KiloInterface<S> = KiloInterface(), clientInterface: KiloInterface<S> = KiloInterface(),
client: HttpClient = HttpClient { install(WebSockets) },
secretKey: SigningKey? = null, secretKey: SigningKey? = null,
useTextFrames: Boolean = false,
sessionMaker: () -> S = { sessionMaker: () -> S = {
@Suppress("UNCHECKED_CAST") @Suppress("UNCHECKED_CAST")
Unit as S Unit as S
}, },
): KiloClient<S> { ): KiloClient<S> {
return KiloClient(clientInterface, secretKey) {
KiloConnectionData(websocketTransportDevice(path, useTextFrames), sessionMaker())
}
}
/**
* Create kilopaarsec transport over websocket (ws or wss).
* @param path websocket path (must start with ws:// or wss:// and contain a path part)
* @param client optional caller-owned client. When omitted, a client with the
* [WebSockets] plugin is created for this device and closed with it.
*/
fun websocketTransportDevice(
path: String,
useTextFrames: Boolean = false,
client: HttpClient? = null,
): Transport.Device {
val ownsClient = client == null
val actualClient = client ?: HttpClient { install(WebSockets) }
val log = LogTag("WSTD")
var u = Url(path) var u = Url(path)
if (u.encodedPath.length <= 1) log.debug { "Creating websocket transport device at $u" }
if (u.encodedPath.length <= 1) {
log.debug {"Correcting path as up = ${u.encodedPath}" }
u = URLBuilder(u).apply { u = URLBuilder(u).apply {
encodedPath = "/kp" encodedPath = "/kp"
}.build() }.build()
}
log.debug { "Url to process is $u" }
return KiloClient(clientInterface, secretKey) {
val input = Channel<UByteArray>() val input = Channel<UByteArray>()
val output = Channel<UByteArray>() val output = Channel<UByteArray>()
val closeHandle = CompletableDeferred<Boolean>() val closeHandle = CompletableDeferred<Boolean>()
val readyHandle = CompletableDeferred<Unit>()
globalLaunch { globalLaunch {
val log = LogTag("KC:${counter.incrementAndGet()}") val log = LogTag("KC:${counter.incrementAndGet()}")
client.webSocket({ try {
actualClient.webSocket({
url.protocol = u.protocol url.protocol = u.protocol
url.host = u.host url.host = u.host
url.port = u.port url.port = u.port
@@ -57,18 +95,23 @@ fun <S> websocketClient(
log.info { "connected to the server" } log.info { "connected to the server" }
// println("SENDING!!!") // println("SENDING!!!")
// send("Helluva") // send("Helluva")
readyHandle.complete(Unit)
launch { launch {
try { try {
for (block in output) { for (block in output) {
if (useTextFrames)
send(
Frame.Text(block.asByteArray().encodeToBase64Compact())
)
else
send(block.toByteArray()) send(block.toByteArray())
} }
log.info { "input is closed, closing the websocket" } log.info { "input is closed, closing the websocket" }
if (closeHandle.isActive) closeHandle.complete(true) if (closeHandle.isActive) closeHandle.complete(true)
} catch (_: ClosedSendChannelException) { } catch (_: ClosedSendChannelException) {
log.info { "send channel closed" } log.info { "send channel closed" }
} } catch (_: CancellationException) {
catch(_: CancellationException) {} } catch (t: Throwable) {
catch(t: Throwable) {
log.info { "unexpected exception in websock sender: ${t.stackTraceToString()}" } log.info { "unexpected exception in websock sender: ${t.stackTraceToString()}" }
closeHandle.completeExceptionally(t) closeHandle.completeExceptionally(t)
} }
@@ -77,10 +120,10 @@ fun <S> websocketClient(
launch { launch {
try { try {
for (f in incoming) { for (f in incoming) {
if (f is Frame.Binary) { when (f) {
input.send(f.readBytes().toUByteArray()) is Frame.Binary -> input.send(f.readBytes().toUByteArray())
} else { is Frame.Text -> input.send(f.readText().decodeBase64Compact().toUByteArray())
log.warning { "ignoring unexpected frame of type ${f.frameType}" } else -> log.warning { "ignoring unexpected frame of type ${f.frameType}" }
} }
} }
if (closeHandle.isActive) closeHandle.complete(true) if (closeHandle.isActive) closeHandle.complete(true)
@@ -98,17 +141,28 @@ fun <S> websocketClient(
log.warning { "Client is closing with error" } log.warning { "Client is closing with error" }
throw RemoteInterface.ClosedException() throw RemoteInterface.ClosedException()
} }
output.close() runCatching { output.close() }
input.close() runCatching { input.close() }
runCatching { close() }
}
} catch (x: IOException) {
if ("refused" in x.toString()) log.debug { "connection refused" }
else log.warning { "unexpected IO error $x" }
runCatching { output.close() }
runCatching { input.close() }
} finally {
if (ownsClient) actualClient.close()
} }
log.info { "closing connection" } log.info { "closing connection" }
} }
val device = ProxyDevice(input, output) { // Wait for connection be established or failed
val device = ProxyDevice(input, output, doClose = {
// we need to explicitly close the coroutine job, or it can hang for a long time // we need to explicitly close the coroutine job, or it can hang for a long time
// leaking resources. // leaking resources.
runCatching { output.close() }
runCatching { input.close() }
closeHandle.complete(true) closeHandle.complete(true)
// job.cancel() // job.cancel()
} })
KiloConnectionData(device, sessionMaker()) return device
}
} }
@@ -1,3 +1,13 @@
/*
* Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
package net.sergeych.kiloparsec package net.sergeych.kiloparsec
import kotlinx.serialization.Serializable import kotlinx.serialization.Serializable
@@ -1,3 +1,13 @@
/*
* Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
package net.sergeych.kiloparsec package net.sergeych.kiloparsec
import kotlinx.coroutines.sync.Mutex import kotlinx.coroutines.sync.Mutex
+10
View File
@@ -1,3 +1,13 @@
/*
* Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
import kotlinx.coroutines.test.runTest import kotlinx.coroutines.test.runTest
import net.sergeych.crypto2.IllegalSignatureException import net.sergeych.crypto2.IllegalSignatureException
import net.sergeych.crypto2.SealedBox import net.sergeych.crypto2.SealedBox
+11 -1
View File
@@ -1,5 +1,14 @@
/*
* Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
import kotlinx.coroutines.test.runTest import kotlinx.coroutines.test.runTest
import kotlinx.datetime.Instant
import net.sergeych.bipack.BipackEncoder import net.sergeych.bipack.BipackEncoder
import net.sergeych.crypto2.initCrypto import net.sergeych.crypto2.initCrypto
import net.sergeych.kiloparsec.KiloParams import net.sergeych.kiloparsec.KiloParams
@@ -11,6 +20,7 @@ import kotlin.test.Test
import kotlin.test.assertContentEquals import kotlin.test.assertContentEquals
import kotlin.test.assertEquals import kotlin.test.assertEquals
import kotlin.time.Duration.Companion.microseconds import kotlin.time.Duration.Companion.microseconds
import kotlin.time.Instant
class PackTest { class PackTest {
inline fun <reified T>check(x: T?) { inline fun <reified T>check(x: T?) {
+10
View File
@@ -1,3 +1,13 @@
/*
* Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
class ToolsTest { class ToolsTest {
// @Test // @Test
// fun testRemoceCmd() { // fun testRemoceCmd() {
+47 -1
View File
@@ -1,3 +1,13 @@
/*
* Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
import kotlinx.coroutines.* import kotlinx.coroutines.*
import kotlinx.coroutines.channels.Channel import kotlinx.coroutines.channels.Channel
import kotlinx.coroutines.channels.ReceiveChannel import kotlinx.coroutines.channels.ReceiveChannel
@@ -66,7 +76,8 @@ class TransportTest {
"p2: $it" "p2: $it"
} }
on(cmdSlow) { on(cmdSlow) {
delay(100) // the problem: runTest() breaks delays so it is not enough
for( i in 0..10000) delay(1)
"done" "done"
} }
} }
@@ -159,6 +170,41 @@ class TransportTest {
d2.close() d2.close()
} }
@Test
fun testDisconnectedHandlers() = runTest {
initCrypto()
val cmdPing by command<String, String>()
val (d1, d2) = createTestDevice()
val serverDisconnected = CompletableDeferred<String>()
val clientDisconnected = CompletableDeferred<String>()
val serverInterface = KiloInterface<String>().apply {
onDisconnected {
serverDisconnected.complete(session)
}
on(cmdPing) {
"pong! [$it]"
}
}
launch { KiloServerConnection(serverInterface, d1, "server session").run() }
val clientInterface = KiloInterface<String>().apply {
onDisconnected {
clientDisconnected.complete(session)
}
}
val client = KiloClientConnection(clientInterface, d2, "client session")
launch { client.run() }
assertEquals("pong! [hello]", client.call(cmdPing, "hello"))
d1.close()
d2.close()
assertEquals("server session", withTimeout(1000) { serverDisconnected.await() })
assertEquals("client session", withTimeout(1000) { clientDisconnected.await() })
}
class TestException(text: String) : Exception(text) class TestException(text: String) : Exception(text)
@Test @Test
+10
View File
@@ -1,3 +1,13 @@
/*
* Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
import kotlin.test.fail import kotlin.test.fail
inline fun <reified T: Throwable>assertThrows(f: ()->Unit): T { inline fun <reified T: Throwable>assertThrows(f: ()->Unit): T {
@@ -1,3 +1,13 @@
/*
* Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
package net.sergeych.kiloparsec.adapter package net.sergeych.kiloparsec.adapter
import io.ktor.server.application.* import io.ktor.server.application.*
@@ -10,25 +20,44 @@ import kotlinx.coroutines.channels.ClosedReceiveChannelException
import kotlinx.coroutines.isActive import kotlinx.coroutines.isActive
import kotlinx.coroutines.launch import kotlinx.coroutines.launch
import net.sergeych.crypto2.SigningKey import net.sergeych.crypto2.SigningKey
import net.sergeych.crypto2.toDump
import net.sergeych.kiloparsec.KiloInterface import net.sergeych.kiloparsec.KiloInterface
import net.sergeych.kiloparsec.KiloServerConnection import net.sergeych.kiloparsec.KiloServerConnection
import net.sergeych.kiloparsec.RemoteInterface import net.sergeych.kiloparsec.RemoteInterface
import net.sergeych.mp_logger.* import net.sergeych.mp_logger.*
import net.sergeych.mp_tools.decodeBase64Compact
import net.sergeych.mp_tools.encodeToBase64Compact
import net.sergeych.tools.AtomicCounter import net.sergeych.tools.AtomicCounter
import java.time.Duration import kotlin.time.Duration.Companion.seconds
/**
* Create a ktor-based websocket server.
* This call install Routing and WebSockets with proper configuration.
*
* The course of action is:
*
* - create LocalInterface and populate it with functionality
* - call this method with localInterface
* - optionally, connect the same interface with TCP or UDP providers on supported platforms,
* in which case it might be useful to hae session creating function [createSession] separate.
*
* _Note_: [KiloInterface] as for now does not contain session creation in it as we suggest
* session could be transport specific.
*
* @param localInterface where the actual work is performed.
* @param path default http path to the websocket.
* @param serverKey optional key to authenticate the connection. If the client specify expected
* server key it should match of connection will not be established.
* @param createSession function to create a server session.
*/
fun <S> Application.setupWebsocketServer( fun <S> Application.setupWebsocketServer(
localInterface: KiloInterface<S>, localInterface: KiloInterface<S>,
path: String = "/kp", path: String = "/kp",
serverKey: SigningKey? = null, serverKey: SigningKey? = null,
createSession: () -> S, createSession: () -> S,
) { ) {
install(Routing)
install(WebSockets) { install(WebSockets) {
pingPeriod = Duration.ofSeconds(15) pingPeriod = 60.seconds //Duration.ofSeconds(15)
timeout = Duration.ofSeconds(15) timeout = 45.seconds
maxFrameSize = Long.MAX_VALUE maxFrameSize = Long.MAX_VALUE
masking = false masking = false
} }
@@ -39,13 +68,18 @@ fun <S> Application.setupWebsocketServer(
log.debug { "opening the connection" } log.debug { "opening the connection" }
val input = Channel<UByteArray>(256) val input = Channel<UByteArray>(256)
val output = Channel<UByteArray>(256) val output = Channel<UByteArray>(256)
var useBinary: Boolean? = null
launch { launch {
log.debug { "starting output pump" } log.debug { "starting output pump" }
while (isActive) { while (isActive) {
try { try {
send(output.receive().toByteArray()) val block = output.receive()
} if (useBinary == false)
catch(_: ClosedReceiveChannelException) { send(block.asByteArray().encodeToBase64Compact())
else
send(block.toByteArray())
} catch (_: ClosedReceiveChannelException) {
log.debug { "closing output pump as output channel is closed" } log.debug { "closing output pump as output channel is closed" }
break break
} }
@@ -64,12 +98,28 @@ fun <S> Application.setupWebsocketServer(
} }
log.debug { "KSC started, looking for incoming frames" } log.debug { "KSC started, looking for incoming frames" }
for (f in incoming) { for (f in incoming) {
log.debug { "incoming frame: ${f.frameType}" }
if (f is Frame.Binary)
try { try {
input.send(f.readBytes().toUByteArray().also { when (f) {
log.debug { "in frame\n${it.toDump()}" } is Frame.Binary -> {
}) if (useBinary == null) {
log.debug { "Setting binary frame mode ------------------------------------" }
useBinary = true
}
input.send(f.readBytes().toUByteArray())
}
is Frame.Text -> {
if (useBinary == null) {
log.debug { "Setting text frame mode -----------------------------------" }
useBinary = false
}
input.send(f.readText().decodeBase64Compact().asUByteArray())
}
else -> {
log.warning { "unexpected frame type ${f.frameType}, ignoring" }
}
}
} catch (_: RemoteInterface.ClosedException) { } catch (_: RemoteInterface.ClosedException) {
log.warning { "caught local closed exception (strange!), closing" } log.warning { "caught local closed exception (strange!), closing" }
break break
@@ -80,8 +130,6 @@ fun <S> Application.setupWebsocketServer(
log.exception { "unexpected exception, server connection will close" to t } log.exception { "unexpected exception, server connection will close" to t }
break break
} }
else
log.warning { "unknown frame type ${f.frameType}, ignoring" }
} }
log.debug { "closing the server" } log.debug { "closing the server" }
close() close()
@@ -1,15 +1,30 @@
/*
* Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
package net.sergeych.kiloparsec package net.sergeych.kiloparsec
import assertThrows import assertThrows
import io.ktor.server.engine.* import io.ktor.server.engine.*
import io.ktor.server.netty.* import io.ktor.server.netty.*
import kotlinx.coroutines.delay
import kotlinx.coroutines.launch import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.test.runTest import kotlinx.coroutines.test.runTest
import net.sergeych.crypto2.SigningSecretKey
import net.sergeych.crypto2.initCrypto import net.sergeych.crypto2.initCrypto
import net.sergeych.kiloparsec.adapter.setupWebsocketServer import net.sergeych.kiloparsec.adapter.setupWebsocketServer
import net.sergeych.kiloparsec.adapter.websocketClient import net.sergeych.kiloparsec.adapter.websocketClient
import net.sergeych.kiloparsec.adapter.websocketTransportDevice
import net.sergeych.mp_logger.Log import net.sergeych.mp_logger.Log
import java.net.InetAddress import java.net.InetAddress
import kotlin.random.Random
import kotlin.test.Test import kotlin.test.Test
import kotlin.test.assertEquals import kotlin.test.assertEquals
import kotlin.test.assertFalse import kotlin.test.assertFalse
@@ -27,7 +42,7 @@ class ClientTest {
@Test @Test
fun webSocketTest() = runTest { fun webSocketTest1() = runTest {
initCrypto() initCrypto()
// fun Application. // fun Application.
val cmdClose by command<Unit, Unit>() val cmdClose by command<Unit, Unit>()
@@ -38,6 +53,7 @@ class ClientTest {
Log.connectConsole(Log.Level.DEBUG) Log.connectConsole(Log.Level.DEBUG)
data class Session(var foo: String = "not set") data class Session(var foo: String = "not set")
var closeCounter = 0 var closeCounter = 0
val serverInterface = KiloInterface<Session>().apply { val serverInterface = KiloInterface<Session>().apply {
var connectedCalled = false var connectedCalled = false
@@ -50,17 +66,20 @@ class ClientTest {
} }
} }
val ns: NettyApplicationEngine = embeddedServer(Netty, port = 8080, host = "0.0.0.0", module = { val port = Random.nextInt(8080, 9090)
val ns = embeddedServer(Netty, port = port, host = "0.0.0.0", module = {
setupWebsocketServer(serverInterface) { Session() } setupWebsocketServer(serverInterface) { Session() }
}).start(wait = false) }).start(wait = false)
val client = websocketClient<Unit>("ws://localhost:8080/kp") val client = websocketClient<Unit>("ws://localhost:$port/kp")
val states = mutableListOf<Boolean>() val states = mutableListOf<Boolean>()
val collector = launch { val collector = launch {
client.connectedStateFlow.collect { client.connectedStateFlow.collect {
println("got: $closeCounter/$it") println("got: $closeCounter/$it")
states += it states += it
if( !it) { closeCounter++ } if (!it) {
closeCounter++
}
} }
} }
assertEquals(true, client.call(cmdCheckConnected)) assertEquals(true, client.call(cmdCheckConnected))
@@ -75,6 +94,9 @@ class ClientTest {
} }
// connection should now be closed // connection should now be closed
// the problem is: it needs some unspecified time to close
// as it is async process.
delay(100)
assertFalse { client.connectedStateFlow.value } assertFalse { client.connectedStateFlow.value }
// this should be run on automatically reopen connection // this should be run on automatically reopen connection
@@ -88,4 +110,101 @@ class ClientTest {
// println("stopped server") // println("stopped server")
// println("closed client") // println("closed client")
} }
@Test
fun webSocketTest2() = runTest {
initCrypto()
// fun Application.
val cmdClose by command<Unit, Unit>()
val cmdGetFoo by command<Unit, String>()
val cmdSetFoo by command<String, Unit>()
val cmdCheckConnected by command<Unit, Boolean>()
Log.connectConsole(Log.Level.DEBUG)
data class Session(var foo: String = "not set")
var closeCounter = 0
val serverInterface = KiloInterface<Session>().apply {
var connectedCalled = false
onConnected { connectedCalled = true }
on(cmdGetFoo) { session.foo }
on(cmdSetFoo) { session.foo = it }
on(cmdCheckConnected) { connectedCalled }
on(cmdClose) {
throw LocalInterface.BreakConnectionException()
}
}
val port = Random.nextInt(8080, 9090)
val ns = embeddedServer(Netty, port = port, host = "0.0.0.0", module = {
setupWebsocketServer(serverInterface) { Session() }
}).start(wait = false)
val client = websocketClient<Unit>("ws://localhost:$port/kp", useTextFrames = true)
val states = mutableListOf<Boolean>()
val collector = launch {
client.connectedStateFlow.collect {
println("got: $closeCounter/$it")
states += it
if (!it) {
closeCounter++
}
}
}
assertEquals(true, client.call(cmdCheckConnected))
assertTrue { client.connectedStateFlow.value }
assertEquals("not set", client.call(cmdGetFoo))
client.call(cmdSetFoo, "foo")
assertEquals("foo", client.call(cmdGetFoo))
client.close()
ns.stop()
collector.cancel()
}
@Test
fun webSocketWaitForConnectTest() = runBlocking {
initCrypto()
// fun Application.
Log.connectConsole(Log.Level.DEBUG)
val clientInterface = KiloInterface<Unit>().apply {}
val port = Random.nextInt(8080, 9090)
var clientConnectCalls = 0
// It should repeatedly reconnect, and we will count:
KiloClient(clientInterface, SigningSecretKey.new()) {
clientConnectCalls++
KiloConnectionData(websocketTransportDevice("ws://localhost:$port/kp", true), Unit)
}
delay(1200)
// and check:
// println("connection attemtps: $clientConnectCalls")
assertTrue { clientConnectCalls > 1 }
}
@Test
fun webSocketWaitForConnectTest2() = runBlocking {
initCrypto()
// fun Application.
Log.connectConsole(Log.Level.DEBUG)
val clientInterface = KiloInterface<Unit>().apply {}
val port = Random.nextInt(8080, 9090)
var clientConnectCalls = 0
// It should repeatedly reconnect, and we will count:
KiloClient(clientInterface, SigningSecretKey.new()) {
clientConnectCalls++
KiloConnectionData(websocketTransportDevice("ws://localhost:$port/kp", false), Unit)
}
delay(1200)
// and check:
// println("connection attemtps: $clientConnectCalls")
assertTrue { clientConnectCalls > 1 }
}
} }
@@ -0,0 +1,29 @@
package net.sergeych.kiloparsec.adapter
import java.nio.file.Files
import java.nio.file.Path
import kotlinx.coroutines.delay
import kotlinx.coroutines.runBlocking
import kotlin.test.Test
import kotlin.test.assertTrue
class WebsocketClientResourceTest {
@Test
fun failedReconnectsDoNotLeakFileDescriptors() = runBlocking {
val descriptors = Path.of("/proc/self/fd")
if (!Files.isDirectory(descriptors)) return@runBlocking
val client = websocketClient<Unit>("ws://127.0.0.1:1/kp")
try {
delay(2_500)
val before = descriptorCount(descriptors)
delay(7_000)
val after = descriptorCount(descriptors)
assertTrue(after <= before + 3, "file descriptors grew from $before to $after")
} finally {
client.close()
}
}
private fun descriptorCount(path: Path): Long = Files.list(path).use { it.count() }
}
@@ -1,8 +1,19 @@
/*
* Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
package net.sergeych.kiloparsec.adapter package net.sergeych.kiloparsec.adapter
import io.ktor.network.selector.* import io.ktor.network.selector.*
import io.ktor.network.sockets.* import io.ktor.network.sockets.*
import io.ktor.utils.io.* import io.ktor.utils.io.*
import io.ktor.utils.io.writeByte
import kotlinx.coroutines.* import kotlinx.coroutines.*
import kotlinx.coroutines.CancellationException import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.channels.Channel import kotlinx.coroutines.channels.Channel
@@ -11,15 +22,11 @@ import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.flow import kotlinx.coroutines.flow.flow
import kotlinx.coroutines.sync.Mutex import kotlinx.coroutines.sync.Mutex
import kotlinx.coroutines.sync.withLock import kotlinx.coroutines.sync.withLock
import kotlinx.datetime.Clock import net.sergeych.kiloparsec.*
import net.sergeych.kiloparsec.AsyncVarint
import net.sergeych.kiloparsec.KiloClient
import net.sergeych.kiloparsec.KiloServer
import net.sergeych.kiloparsec.LocalInterface
import net.sergeych.mp_logger.* import net.sergeych.mp_logger.*
import net.sergeych.mp_tools.globalLaunch import net.sergeych.mp_tools.globalLaunch
import net.sergeych.tools.AtomicCounter import net.sergeych.tools.AtomicCounter
import net.sergeych.tools.AtomicValue import kotlin.time.Clock
import kotlin.time.Duration.Companion.seconds import kotlin.time.Duration.Companion.seconds
private val logCounter = AtomicCounter(0) private val logCounter = AtomicCounter(0)
@@ -35,8 +42,8 @@ internal val PING_INACTIVITY_TIME = 30.seconds
*/ */
fun acceptTcpDevice(port: Int, localInterface: String = "0.0.0.0"): Flow<InetTransportDevice> { fun acceptTcpDevice(port: Int, localInterface: String = "0.0.0.0"): Flow<InetTransportDevice> {
val selectorManager = SelectorManager(Dispatchers.IO) val selectorManager = SelectorManager(Dispatchers.IO)
val serverSocket = aSocket(selectorManager).tcp().bind(localInterface, port)
return flow { return flow {
val serverSocket = aSocket(selectorManager).tcp().bind(localInterface, port)
while (true) { while (true) {
serverSocket.accept().let { sock -> serverSocket.accept().let { sock ->
emit(inetTransportDevice(sock, "srv")) emit(inetTransportDevice(sock, "srv"))
@@ -45,7 +52,13 @@ fun acceptTcpDevice(port: Int,localInterface: String = "0.0.0.0"): Flow<InetTran
} }
} }
suspend fun connectTcpDevice(address: String) = connectTcpDevice(address.toNetworkAddress())
/**
* Connect to the TCP/IP server (see [KiloServer]) at the specified address and provide th compatible
* [InetTransportDevice] to use with [KiloClient]. [hostPortAddress] is a string in the form of `host:port`.
*/
suspend fun connectTcpDevice(hostPortAddress: String): InetTransportDevice =
connectTcpDevice(hostPortAddress.toNetworkAddress())
/** /**
* Connect to the TCP/IP server (see [KiloServer]) at the specified address and provide th compatible * Connect to the TCP/IP server (see [KiloServer]) at the specified address and provide th compatible
@@ -74,7 +87,7 @@ private fun inetTransportDevice(
val outputBlocks = Channel<UByteArray>(4096) val outputBlocks = Channel<UByteArray>(4096)
val log = LogTag("TCPT${logCounter.incrementAndGet()}:$suffix:$networkAddress") val log = LogTag("TCPT${logCounter.incrementAndGet()}:$suffix:$networkAddress")
val job = AtomicValue<Job?>(null) val job = AtomicAsyncValue<Job?>(null)
val sockOutput = sock.openWriteChannel() val sockOutput = sock.openWriteChannel()
val sockInput = runCatching { sock.openReadChannel() }.getOrElse { val sockInput = runCatching { sock.openReadChannel() }.getOrElse {
@@ -82,7 +95,7 @@ private fun inetTransportDevice(
throw IllegalStateException("failed to open read channel") throw IllegalStateException("failed to open read channel")
} }
fun stop() { suspend fun stop() {
job.mutate { job.mutate {
if (it != null) { if (it != null) {
log.debug { "stopping" } log.debug { "stopping" }
@@ -91,7 +104,7 @@ private fun inetTransportDevice(
// The problem: on mac platofrms closing the socket does not close its input // The problem: on mac platofrms closing the socket does not close its input
// and output channels! // and output channels!
runCatching { sockInput.cancel() } runCatching { sockInput.cancel() }
runCatching { sockOutput.close() } runCatching { sockOutput.flushAndClose() }
if (!sock.isClosed) if (!sock.isClosed)
runCatching { runCatching {
log.debug { "closing socket by stop" } log.debug { "closing socket by stop" }
@@ -108,7 +121,8 @@ private fun inetTransportDevice(
} }
var lastActiveAt = Clock.System.now() var lastActiveAt = Clock.System.now()
job.value = globalLaunch { globalLaunch {
job.reset(globalLaunch {
launch { launch {
log.debug { "opening read channel" } log.debug { "opening read channel" }
@@ -126,7 +140,7 @@ private fun inetTransportDevice(
sockInput.readFully(data, 0, size) sockInput.readFully(data, 0, size)
inputBlocks.send(data.toUByteArray()) inputBlocks.send(data.toUByteArray())
} }
} catch (e: ClosedReceiveChannelException) { } catch (_: ClosedReceiveChannelException) {
log.error { "closed receive channel " } log.error { "closed receive channel " }
stop() stop()
break break
@@ -140,7 +154,7 @@ private fun inetTransportDevice(
} }
} }
} }
})
launch { launch {
val outAccess = Mutex() val outAccess = Mutex()
var lastSentAt = Clock.System.now() var lastSentAt = Clock.System.now()
@@ -1,7 +1,18 @@
/*
* Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
package net.sergeych.kiloparsec.adapter package net.sergeych.kiloparsec.adapter
import io.ktor.network.sockets.* import io.ktor.network.sockets.*
import io.ktor.utils.io.core.* import io.ktor.utils.io.core.*
import kotlinx.io.readByteArray
import net.sergeych.crypto2.toDump import net.sergeych.crypto2.toDump
import net.sergeych.kiloparsec.adapter.UdpBlock.Companion.CANCEL_BLOCK import net.sergeych.kiloparsec.adapter.UdpBlock.Companion.CANCEL_BLOCK
import net.sergeych.kiloparsec.adapter.UdpBlock.Companion.ESCAPE_BYTE import net.sergeych.kiloparsec.adapter.UdpBlock.Companion.ESCAPE_BYTE
@@ -97,6 +108,6 @@ sealed class UdpBlock {
} }
fun decode(datagram: Datagram) = fun decode(datagram: Datagram) =
decode(datagram.packet.readBytes().toUByteArray()) decode(datagram.packet.readByteArray().toUByteArray())
} }
} }
@@ -1,3 +1,13 @@
/*
* Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
package net.sergeych.kiloparsec.adapter package net.sergeych.kiloparsec.adapter
import io.ktor.network.sockets.* import io.ktor.network.sockets.*
@@ -1,3 +1,13 @@
/*
* Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
package net.sergeych.kiloparsec.adapter package net.sergeych.kiloparsec.adapter
import io.ktor.network.selector.* import io.ktor.network.selector.*
@@ -87,7 +97,7 @@ fun acceptUdpDevice(
* the module automatically issues pings on inactivity when there is no data often enough * the module automatically issues pings on inactivity when there is no data often enough
* to maintain the connection open. * to maintain the connection open.
*/ */
fun connectUdpDevice( suspend fun connectUdpDevice(
hostPort: String, hostPort: String,
maxInactivityTimeout: Duration = 2.minutes, maxInactivityTimeout: Duration = 2.minutes,
) = connectUdpDevice(hostPort.toNetworkAddress(), maxInactivityTimeout) ) = connectUdpDevice(hostPort.toNetworkAddress(), maxInactivityTimeout)
@@ -107,16 +117,16 @@ fun connectUdpDevice(
* the module automatically issues pings on inactivity when there is no data often enough * the module automatically issues pings on inactivity when there is no data often enough
* to maintain the connection open. * to maintain the connection open.
*/ */
fun connectUdpDevice( suspend fun connectUdpDevice(
addr: NetworkAddress, addr: NetworkAddress,
maxInactivityTimeout: Duration = 2.minutes, maxInactivityTimeout: Duration = 2.minutes,
): InetTransportDevice { ): InetTransportDevice {
val selectorManager = SelectorManager(Dispatchers.IO) val selectorManager = SelectorManager(Dispatchers.IO)
val remoteAddress = InetSocketAddress(addr.host, addr.port) val remoteAddress = InetSocketAddress(addr.host, addr.port)
val socket = aSocket(selectorManager).udp().connect(remoteAddress)
val done = CompletableDeferred<Unit>() val done = CompletableDeferred<Unit>()
val socket = aSocket(selectorManager).udp().connect(remoteAddress)
val transport = UdpSocketTransport(object : UdpConnector { val transport = UdpSocketTransport(object : UdpConnector {
override suspend fun sendBlock(block: UdpBlock, toAddress: SocketAddress) { override suspend fun sendBlock(block: UdpBlock, toAddress: SocketAddress) {
socket.send(block.toDatagram(remoteAddress)) socket.send(block.toDatagram(remoteAddress))
@@ -1,3 +1,13 @@
/*
* Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
package net.sergeych.kiloparsec.adapter package net.sergeych.kiloparsec.adapter
import io.ktor.network.selector.* import io.ktor.network.selector.*
@@ -14,6 +24,7 @@ import net.sergeych.mp_logger.LogTag
import net.sergeych.mp_logger.Loggable import net.sergeych.mp_logger.Loggable
import net.sergeych.mp_logger.debug import net.sergeych.mp_logger.debug
import net.sergeych.mp_logger.exception import net.sergeych.mp_logger.exception
import net.sergeych.mp_tools.globalDefer
import kotlin.time.Duration import kotlin.time.Duration
import kotlin.time.Duration.Companion.minutes import kotlin.time.Duration.Companion.minutes
@@ -51,7 +62,9 @@ class UdpServer(val port: Int, localInterface: String = "0.0.0.0", maxInactivity
private val access = Mutex() private val access = Mutex()
private val selectorManager = SelectorManager(Dispatchers.IO) private val selectorManager = SelectorManager(Dispatchers.IO)
private val serverSocket = aSocket(selectorManager).udp().bind(InetSocketAddress(localInterface, port)) private val serverSocket = globalDefer {
aSocket(selectorManager).udp().bind(InetSocketAddress(localInterface, port))
}
override suspend fun disconnectClient(address: SocketAddress) { override suspend fun disconnectClient(address: SocketAddress) {
access.withLock { sessions.remove(address) } access.withLock { sessions.remove(address) }
@@ -65,7 +78,7 @@ class UdpServer(val port: Int, localInterface: String = "0.0.0.0", maxInactivity
flow { flow {
while (true) { while (true) {
try { try {
val datagram = serverSocket.receive() val datagram = serverSocket.await().receive()
val block = UdpBlock.decode(datagram) val block = UdpBlock.decode(datagram)
val remoteAddress = datagram.address val remoteAddress = datagram.address
@@ -97,10 +110,10 @@ class UdpServer(val port: Int, localInterface: String = "0.0.0.0", maxInactivity
} }
override suspend fun sendBlock(block: UdpBlock, toAddress: SocketAddress) { override suspend fun sendBlock(block: UdpBlock, toAddress: SocketAddress) {
serverSocket.send(block.toDatagram(toAddress)) serverSocket.await().send(block.toDatagram(toAddress))
} }
val isClosed: Boolean get() = serverSocket.isClosed suspend fun isClosed(): Boolean = serverSocket.await().isClosed
/** /**
* Close the UDP server. Calling it will cause: * Close the UDP server. Calling it will cause:
@@ -113,8 +126,8 @@ class UdpServer(val port: Int, localInterface: String = "0.0.0.0", maxInactivity
*/ */
suspend fun close() { suspend fun close() {
access.withLock { access.withLock {
if (!isClosed) { if (!isClosed()) {
runCatching { serverSocket.close() } runCatching { serverSocket.await().close() }
} }
} }
while (sessions.isNotEmpty()) { while (sessions.isNotEmpty()) {
@@ -1,3 +1,13 @@
/*
* Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
package net.sergeych.kiloparsec.adapter package net.sergeych.kiloparsec.adapter
import io.ktor.network.sockets.* import io.ktor.network.sockets.*
@@ -9,13 +19,13 @@ import kotlinx.coroutines.channels.ClosedSendChannelException
import kotlinx.coroutines.coroutineScope import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.delay import kotlinx.coroutines.delay
import kotlinx.coroutines.launch import kotlinx.coroutines.launch
import kotlinx.datetime.Clock
import net.sergeych.kiloparsec.SyncValue import net.sergeych.kiloparsec.SyncValue
import net.sergeych.mp_logger.Log import net.sergeych.mp_logger.Log
import net.sergeych.mp_logger.Loggable import net.sergeych.mp_logger.Loggable
import net.sergeych.mp_logger.debug import net.sergeych.mp_logger.debug
import net.sergeych.mp_logger.exception import net.sergeych.mp_logger.exception
import net.sergeych.mp_tools.globalLaunch import net.sergeych.mp_tools.globalLaunch
import kotlin.time.Clock
import kotlin.time.Duration import kotlin.time.Duration
/** /**
@@ -161,10 +171,10 @@ internal class UdpSocketTransport(
while (!isClosed) { while (!isClosed) {
try { try {
server.sendBlock(UdpBlock.Data(outputDataBlocks.receive()), socketAddress) server.sendBlock(UdpBlock.Data(outputDataBlocks.receive()), socketAddress)
} catch (e: CancellationException) { } catch (_: CancellationException) {
// this is ok // this is ok
break break
} catch (e: ClosedReceiveChannelException) { } catch (_: ClosedReceiveChannelException) {
debug { "input channel is closed, closing" } debug { "input channel is closed, closing" }
close() close()
break break
@@ -1,3 +1,13 @@
/*
* Copyright (c) 2025. Sergey S. Chernov - All Rights Reserved
*
* You may use, distribute and modify this code under the
* terms of the private license, which you must obtain from the author
*
* To obtain the license, contact the author: https://t.me/real_sergeych or email to
* real dot sergeych at gmail.
*/
package net.sergeych.kiloparsec.adapter package net.sergeych.kiloparsec.adapter
import assertThrows import assertThrows
@@ -10,7 +20,7 @@ import kotlin.test.Test
import kotlin.test.assertEquals import kotlin.test.assertEquals
import kotlin.test.assertIs import kotlin.test.assertIs
class InternetrTest { class InternetTest {
class TestException : Exception("test1") class TestException : Exception("test1")
@Test @Test
@@ -26,9 +36,11 @@ class InternetrTest {
val cmdSave by command<String, Unit>() val cmdSave by command<String, Unit>()
val cmdLoad by command<Unit, String>() val cmdLoad by command<Unit, String>()
val cmdDrop by command<Unit, Unit>() val cmdDrop by command<Unit, Unit>()
val cmdPing by command<String, String>()
val cmdException by command<Unit, Unit>() val cmdException by command<Unit, Unit>()
val cmdCallClient by command<String, String>()
val cli = KiloInterface<Session>().apply { val serverInterface = KiloInterface<Session>().apply {
registerError { TestException() } registerError { TestException() }
onConnected { session.data = "start" } onConnected { session.data = "start" }
on(cmdSave) { session.data = it } on(cmdSave) { session.data = it }
@@ -41,15 +53,26 @@ class InternetrTest {
on(cmdDrop) { on(cmdDrop) {
throw LocalInterface.BreakConnectionException() throw LocalInterface.BreakConnectionException()
} }
on(cmdCallClient) {
remote.call(cmdPing, it)
} }
val server = KiloServer(cli, acceptTcpDevice(port)) { }
val server = KiloServer(serverInterface, acceptTcpDevice(port)) {
Session("unknown") Session("unknown")
} }
val client = KiloClient<Unit>() { data class LocalSession(val localFoo: String)
addErrors(cli)
val client = KiloClient {
addErrors(serverInterface)
session { LocalSession("unknown") }
// TODO: add register error variant // TODO: add register error variant
connect { connectTcpDevice("localhost:$port") } connect { connectTcpDevice("localhost:$port") }
local {
on(cmdPing) {
"pong! $it"
}
}
} }
assertEquals("start", client.call(cmdLoad)) assertEquals("start", client.call(cmdLoad))
@@ -65,7 +88,7 @@ class InternetrTest {
// reconnect? // reconnect?
assertEquals("start", client.call(cmdLoad)) assertEquals("start", client.call(cmdLoad))
assertEquals("pong! 42", client.call(cmdCallClient, "42"))
server.close() server.close()
} }
@@ -104,7 +127,7 @@ class InternetrTest {
val client = KiloClient<Unit>() { val client = KiloClient<Unit>() {
addErrors(cli) addErrors(cli)
connect { connectUdpDevice("localhost:$port") } connect { connectUdpDevice("127.0.0.1:$port") }
} }
assertEquals("start", client.call(cmdLoad)) assertEquals("start", client.call(cmdLoad))
@@ -132,7 +155,7 @@ class InternetrTest {
var data: String, var data: String,
) )
val port = 27170 + Random.nextInt(1, 200) val port = 27170 + Random.nextInt(1, 900)
val cmdSave by command<String, Unit>() val cmdSave by command<String, Unit>()
val cmdLoad by command<Unit, String>() val cmdLoad by command<Unit, String>()
@@ -154,19 +177,28 @@ class InternetrTest {
} }
} }
val uServer = UdpServer(port) val uServer = UdpServer(port)
KiloServer(cli, uServer.transportFlow) { KiloServer(cli, uServer.transportFlow) {
Session("unknown") Session("unknown")
} }
// second server
KiloServer(cli,acceptUdpDevice(uServer.port+1)) { Session("unknown2") }
val client = KiloClient<Unit>() { val client = KiloClient<Unit>() {
addErrors(cli) addErrors(cli)
connect { connectUdpDevice("localhost:$port") } connect { connectUdpDevice("127.0.0.1:$port") }
} }
val client2 = KiloClient<Unit>() { connect { connectUdpDevice("127.0.0.1:${port+1}") } }
assertEquals("start", client.call(cmdLoad)) assertEquals("start", client.call(cmdLoad))
assertEquals("start", client2.call(cmdLoad))
client.call(cmdSave, "foobar") client.call(cmdSave, "foobar")
client2.call(cmdSave, "buzz")
assertEquals("foobar", client.call(cmdLoad)) assertEquals("foobar", client.call(cmdLoad))
assertEquals("buzz", client2.call(cmdLoad))
val res = kotlin.runCatching { client.call(cmdException) } val res = kotlin.runCatching { client.call(cmdException) }
assertIs<TestException>(res.exceptionOrNull()) assertIs<TestException>(res.exceptionOrNull())