{"id":13536667,"url":"https://github.com/rsocket/rsocket-kotlin","last_synced_at":"2025-04-13T19:32:29.693Z","repository":{"id":37692378,"uuid":"109894810","full_name":"rsocket/rsocket-kotlin","owner":"rsocket","description":"RSocket Kotlin multi-platform implementation","archived":false,"fork":false,"pushed_at":"2025-03-11T22:37:11.000Z","size":2091,"stargazers_count":591,"open_issues_count":33,"forks_count":40,"subscribers_count":19,"default_branch":"master","last_synced_at":"2025-04-06T17:08:22.194Z","etag":null,"topics":["android","async","coroutines","ios","kmp","kotlin","kotlin-multiplatform","ktor","multiplatform","rsocket","tcp","websockets"],"latest_commit_sha":null,"homepage":"http://rsocket.io","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rsocket.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-11-07T21:47:25.000Z","updated_at":"2025-03-29T16:56:22.000Z","dependencies_parsed_at":"2024-03-14T19:39:46.809Z","dependency_job_id":"8b985eeb-bb55-4e55-aa15-dfd077cab796","html_url":"https://github.com/rsocket/rsocket-kotlin","commit_stats":{"total_commits":227,"total_committers":16,"mean_commits":14.1875,"dds":0.5594713656387665,"last_synced_commit":"b7f27ba4c3a0d639d375731231f347e595ed307c"},"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rsocket%2Frsocket-kotlin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rsocket%2Frsocket-kotlin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rsocket%2Frsocket-kotlin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rsocket%2Frsocket-kotlin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rsocket","download_url":"https://codeload.github.com/rsocket/rsocket-kotlin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248767801,"owners_count":21158532,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","async","coroutines","ios","kmp","kotlin","kotlin-multiplatform","ktor","multiplatform","rsocket","tcp","websockets"],"created_at":"2024-08-01T09:00:46.913Z","updated_at":"2025-04-13T19:32:29.669Z","avatar_url":"https://github.com/rsocket.png","language":"Kotlin","readme":"# rsocket-kotlin\n\nRSocket Kotlin multi-platform implementation based on\n[kotlinx.coroutines](https://github.com/Kotlin/kotlinx.coroutines) and [kotlinx-io](https://github.com/Kotlin/kotlinx-io).\n\nRSocket is a binary application protocol providing Reactive Streams semantics for use on byte stream transports such as\nTCP, WebSockets, QUIC and Aeron.\n\nIt enables the following symmetric interaction models via async message passing over a single connection:\n\n* [Fire-and-Forget](https://rsocket.io/about/motivations#fire-and-forget)\n* [Request-Response](https://rsocket.io/about/motivations#requestresponse-single-response)\n* [Request-Stream](https://rsocket.io/about/motivations#requeststream-multi-response-finite)\n* [Request-Channel](https://rsocket.io/about/motivations#channel)\n\nLearn more at http://rsocket.io\n\n## Supported platforms and transports:\n\nLocal (in memory) transport is supported for all targets.\nStarting from [Ktor 3.1 release](https://blog.jetbrains.com/kotlin/2025/02/ktor-3-1-0-release/),\nall ktor-client, ktor-server and ktor-network modules are supported for all targets.\nSo all Ktor related transports (TCP and WebSocket) are supported by rsocket-kotlin for all targets.\nAdditionally, there is experimental JVM-only support for Netty TCP and QUIC transpots.\n\n## Using in your projects\n\nrsocket-kotlin is available on [Maven Central](https://mvnrepository.com/artifact/io.rsocket.kotlin):\n\n```kotlin\nrepositories {\n    mavenCentral()\n}\n```\n\n### Ktor plugins\n\nrsocket-kotlin provides [client](https://ktor.io/docs/client-plugins.html)\nand [server](https://ktor.io/docs/server-plugins.html) plugins for [ktor](https://ktor.io)\n\nDependencies:\n\n```kotlin\ndependencies {\n    // for client\n    implementation(\"io.rsocket.kotlin:ktor-client-rsocket:0.20.0\")\n\n    // for server\n    implementation(\"io.rsocket.kotlin:ktor-server-rsocket:0.20.0\")\n}\n```\n\nExample of client plugin usage:\n\n```kotlin\n//create ktor client\nval client = HttpClient {\n    install(WebSockets) // rsocket requires websockets plugin installed\n    install(RSocketSupport) {\n        // configure rSocket connector (all values have defaults)\n        connector {\n            connectionConfig {\n                // payload for setup frame\n                setupPayload {\n                    buildPayload {\n                        data(\"\"\"{ \"data\": \"setup\" }\"\"\")\n                    }\n                }\n\n                // mime types\n                payloadMimeType = PayloadMimeType(\n                    data = WellKnownMimeType.ApplicationJson,\n                    metadata = WellKnownMimeType.MessageRSocketCompositeMetadata\n                )\n            }\n        }\n    }\n}\n\n//connect to some url\nval rSocket: RSocket = client.rSocket(\"wss://demo.rsocket.io/rsocket\")\n\n//request stream\nval stream: Flow\u003cPayload\u003e = rSocket.requestStream(\n    buildPayload {\n        data(\"\"\"{ \"data\": \"hello world\" }\"\"\")\n    }\n)\n\n//take 5 values and print response\nstream.take(5).collect { payload: Payload -\u003e\n    println(payload.data.readString())\n}\n```\n\nExample of server plugin usage:\n\n```kotlin\n//create ktor server\nembeddedServer(CIO) {\n    install(WebSockets) // rsocket requires websockets plugin installed\n    install(RSocketSupport) {\n        // optionally configure rSocket server\n    }\n    routing {\n        rSocket(\"rsocket\") {\n            println(config.setupPayload.data.readString()) //print setup payload data\n\n            RSocketRequestHandler {\n                // handler for request/response\n                requestResponse { request: Payload -\u003e\n                    println(request.data.readString()) //print request payload data\n                    delay(500) // work emulation\n                    buildPayload {\n                        data(\"\"\"{ \"data\": \"Server response\" }\"\"\")\n                    }\n                }\n                // handler for request/stream      \n                requestStream { request: Payload -\u003e\n                    println(request.data.readString()) // print request payload data\n                    flow {\n                        repeat(10) { i -\u003e\n                            emit(\n                                buildPayload {\n                                    data(\"\"\"{ \"data\": \"Server stream response: $i\" }\"\"\")\n                                }\n                            )\n                        }\n                    }\n                }\n            }\n        }\n    }\n}.start(true)\n```\n\n### Standalone transports\n\nrsocket-kotlin also provides standalone transports which can be used to establish RSocket connection:\n\nDependencies:\n\n```kotlin\ndependencies {\n    implementation(\"io.rsocket.kotlin:rsocket-core:0.20.0\")\n\n    // TCP ktor client/server transport\n    implementation(\"io.rsocket.kotlin:rsocket-transport-ktor-tcp:0.20.0\")\n\n    // WS ktor client transport\n    implementation(\"io.rsocket.kotlin:rsocket-transport-ktor-websocket-client:0.20.0\")\n\n    // WS ktor server transport\n    implementation(\"io.rsocket.kotlin:rsocket-transport-ktor-websocket-server:0.20.0\")\n\n    // Netty TCP client/server transport\n    implementation(\"io.rsocket.kotlin:rsocket-transport-netty-tcp:0.20.0\")\n}\n```\n\nExample of usage standalone TCP ktor client transport:\n\n```kotlin\nval parentContext = Job()\nval target = KtorTcpClientTransport(parentContext) {\n    // optional configuration\n}.target(\"127.0.0.1\", 8080)\nval connector = RSocketConnector {\n    //configuration goes here\n}\nval rsocket: RSocket = connector.connect(target)\n//use rsocket to do request\nval response = rsocket.requestResponse(buildPayload { data(\"\"\"{ \"data\": \"hello world\" }\"\"\") })\nprintln(response.data.readString())\n```\n\nExample of usage standalone TCP ktor server transport:\n\n```kotlin\nval parentContext = Job()\nval target = KtorTcpServerTransport(parentContext) {\n    // optional configuration\n}.target(\"127.0.0.1\", 8080)\nval server = RSocketServer {\n    //configuration goes here\n}\nval serverInstance = server.startServer(target) {\n    RSocketRequestHandler {\n        //handler for request/response\n        requestResponse { request: Payload -\u003e\n            println(request.data.readString()) //print request payload data\n            delay(500) // work emulation\n            buildPayload {\n                data(\"\"\"{ \"data\": \"Server response\" }\"\"\")\n            }\n        }\n    }\n}\nserverInstance.coroutineContext.job.join() // wait for server to finish\n```\n\n### More samples:\n\n- [multiplatform-chat](samples/chat) - chat implementation with JVM/JS/Native server and JVM/JS/Native client with\n  shared classes and shared data serialization\n  using [kotlinx.serialization](https://github.com/Kotlin/kotlinx.serialization)\n\n## Reactive Streams Semantics\n\nFrom [RSocket protocol](https://github.com/rsocket/rsocket/blob/master/Protocol.md#reactive-streams-semantics):\n\n    Reactive Streams semantics are used for flow control of Streams, Subscriptions, and Channels. \n    This is a credit-based model where the Requester grants the Responder credit for the number of PAYLOADs it can send. \n    It is sometimes referred to as \"request-n\" or \"request(n)\".\n\n`kotlinx.coroutines` doesn't truly support `request(n)` semantic,\nbut it has flexible `CoroutineContext` which can be used to achieve something similar.\n`rsocket-kotlin` contains `RequestStrategy` coroutine context element, which defines,\nstrategy for sending of `requestN`frames.\n\nExample:\n\n```kotlin\n//assume we have client\nval client: RSocket = TODO()\n\n//and stream\nval stream: Flow\u003cPayload\u003e = client.requestStream(Payload(\"data\"))\n\n//now we can use `flowOn` to add request strategy to context of flow\n//here we use prefetch strategy which will send requestN for 10 elements, when, there is 5 elements left to collect\n//so on call `collect`, requestStream frame with requestN will be sent, and then, after 5 elements will be collected\n//new requestN with 5 will be sent, so collect will be smooth \nstream.flowOn(PrefetchStrategy(requestSize = 10, requestOn = 5)).collect { payload: Payload -\u003e\n    println(payload.data.readString())\n}\n```\n\n## Bugs and Feedback\n\nFor bugs, questions and discussions please use the [Github Issues](https://github.com/rsocket/rsocket-kotlin/issues).\n\n## LICENSE\n\nCopyright 2015-2024 the original author or authors.\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\nhttp://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n","funding_links":[],"categories":["Libraries","Network"],"sub_categories":["Network","🌎 Network","SQL"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frsocket%2Frsocket-kotlin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frsocket%2Frsocket-kotlin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frsocket%2Frsocket-kotlin/lists"}