0.3.1 release: async pushes and better binary format

README.md

@@ -1,15 +1,23 @@
 # Kiloparsec
 
+__Recommended version is `0.3.1`: to keep the code compatible with current and further versions we
+ask to upgrade to `0.3.1` at least.__
+
 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
 provides the following transports:
 
-| name           | JVM | JS | native   |
-|----------------|-----|----|----------|
-| TCP/IP server  | ✓   |    | β @0.2.6 |
-| TCP/IP client  | ✓   |    | β @0.2.6 |
-| Websock server | ✓   |    |          |
-| Websock client | ✓   | ✓  | ✓        |
+| name           | JVM | JS | native    |
+|----------------|-----|----|-----------|
+| TCP/IP server  | ✓   |    | >= 0.2.6  |
+| TCP/IP client  | ✓   |    | >= @0.2.6 |
+| Websock server | ✓   |    |           |
+| Websock client | ✓   | ✓  | ✓         |
+
+### Note on version compatibility
+
+Protocols >= 0.3.0 are not binary compatible with previous version due to more compact binary
+format. The format from 0.3.0 onwards is supposed to keep compatible.
 
 ### Supported native targets
 
@@ -59,7 +67,7 @@ It could be, depending on your project structure, something like:
 ```kotlin
 val commonMain by getting {
     dependencies {
-        api("net.sergeych:kiloparsec:0.2.6")
+        api("net.sergeych:kiloparsec:0.3.1")
     }
 }
 ```
@@ -118,7 +126,7 @@ assertEquals(FooArgs("bar", 117), client.call(cmdGetFoo))
 ## Create ktor-based server
 
 Normally server side needs some session. It is convenient and avoid sending repeating data on each request speeding up
-the protocol. With KILOPARSEC it is rather basic operation:\
+the protocol. With KILOPARSEC it is rather basic operation:
 
 ~~~kotlin
 // Our session just keeps Foo for cmd{Get|Set}Foo:
@@ -143,9 +151,32 @@ val ns: NettyApplicationEngine = embeddedServer(Netty, port = 8080, host = "0.0.
     setupWebsocketServer(serverInterface) { Session() }
 }).start(wait = false)
 
-
 ~~~
 
+### TCP/IP client and server
+
+Using plain TCP/IP is even simpler, and it works way faster than websocket one, and is _the same
+protected as `wss://` variant abovve 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.
+
+Documentation is available in samples here:
+
+- [TCP/IP server creation](https://code.sergeych.net/docs/kiloparsec/kiloparsec/net.sergeych.kiloparsec/-kilo-server/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 aysnchronous 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
+
+- [connectTcpDevice](https://code.sergeych.net/docs/kiloparsec/kiloparsec/net.sergeych.kiloparsec.adapter/connect-tcp-device.html) to connect to the server
+
+### 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.
+
+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.
+
 ## See also:
 
 - [Source documentation](https://code.sergeych.net/docs/kiloparsec/)