{"id":13611309,"url":"https://github.com/rjaros/kilua-rpc","last_synced_at":"2025-04-15T06:15:33.399Z","repository":{"id":226786174,"uuid":"767482664","full_name":"rjaros/kilua-rpc","owner":"rjaros","description":"Fullstack RPC library for Kotlin/Wasm and Kotlin/JS","archived":false,"fork":false,"pushed_at":"2025-04-14T10:41:06.000Z","size":520,"stargazers_count":38,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-15T06:15:19.378Z","etag":null,"topics":["javascript","kotlin","rpc","wasm"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rjaros.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,"zenodo":null},"funding":{"github":"rjaros","custom":["https://paypal.me/RobertJaros"]}},"created_at":"2024-03-05T11:25:17.000Z","updated_at":"2025-04-14T10:41:09.000Z","dependencies_parsed_at":"2024-03-16T15:14:31.184Z","dependency_job_id":"8fd4bb09-3bc7-4f1e-a773-c3c7ba46ea85","html_url":"https://github.com/rjaros/kilua-rpc","commit_stats":null,"previous_names":["rjaros/kilua-rpc"],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rjaros%2Fkilua-rpc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rjaros%2Fkilua-rpc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rjaros%2Fkilua-rpc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rjaros%2Fkilua-rpc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rjaros","download_url":"https://codeload.github.com/rjaros/kilua-rpc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249016641,"owners_count":21198833,"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":["javascript","kotlin","rpc","wasm"],"created_at":"2024-08-01T19:01:54.035Z","updated_at":"2025-04-15T06:15:33.394Z","avatar_url":"https://github.com/rjaros.png","language":"Kotlin","funding_links":["https://github.com/sponsors/rjaros","https://paypal.me/RobertJaros"],"categories":["Kotlin","开发框架"],"sub_categories":["RPC框架"],"readme":"# Kilua RPC\n\nFullstack RPC library for Kotlin/Wasm and Kotlin/JS.\n\n[![Maven Central](https://img.shields.io/maven-central/v/dev.kilua/kilua-rpc-core.svg?label=Maven%20Central)](https://central.sonatype.com/search?namespace=dev.kilua\u0026name=kilua-rpc-core)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nKilua RPC is a powerful Remote Procedure Call (RPC) library designed for fullstack applications \ncreated with the Kotlin programming language. Is can be used with frontend apps developed for \n[Kotlin/Wasm](https://kotlinlang.org/docs/wasm-overview.html) and [Kotlin/JS](https://kotlinlang.org/docs/js-overview.html) targets. On the backend side different popular Kotlin/JVM web frameworks \nare fully supported:\n\n- [Ktor](https://ktor.io/)\n- [Jooby](https://jooby.io)\n- [Spring Boot](https://spring.io/projects/spring-boot)\n- [Javalin](https://javalin.io)\n- [Vert.x](https://vertx.io)\n- [Micronaut](https://micronaut.io)\n\nKilua RPC is a new project, but it is mostly based on stable and production ready \nfullstack interfaces implemented in the [KVision](https://kvision.io) framework. \n\nKilua RPC can be used with all Kotlin/JS and Kotlin/Wasm web frameworks to easily build fullstack \napplications with shared code for data model and business logic.\n\n## Features\n\n- Compile the same application code for Kotlin/Wasm and Kotlin/JS targets.\n- Support for serializable [kotlinx-datetime](https://github.com/Kotlin/kotlinx-datetime) types.\n- Built-in `Decimal` type automatically mapped to `Double` in the \nbrowser and to `BigDecimal` on the server. \n- Support for `Result\u003cT\u003e` as a return type of remote methods.\n- Automatic exceptions propagation from the server to the client, \nincluding support for custom exception types.\n- Support two-way communication with [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API).\n- Support [SSE (Server-Sent Events)](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events).\n- Automatic endpoints generation configurable with simple annotations.\n- Gradle plugin for easy project setup and packaging.\n\n## Code overview\n\nThis is a short overview of how to use Kilua RPC. It contains just the basic concepts and ideas.\n\n### Common source set\n\nDeclare an annotated interface with one or more suspending methods.\n\n```kotlin\nimport dev.kilua.rpc.annotations.RpcService\nimport kotlinx.serialization.Serializable\n\n@Serializable\nenum class EncodingType {\n    BASE64, URLENCODE, HEX\n}\n\n@RpcService\ninterface IEncodingService {\n    suspend fun encode(input: String, encodingType: EncodingType): String\n}\n```\n### Frontend source set\n\nJust use the class instance provided by the library calling its methods directly.\n\n```kotlin\nimport dev.kilua.rpc.getService\n\nval service = getService\u003cIEncodingService\u003e()\nlaunch {\n    val result: String = service.encode(\"Lorem ipsum\", EncodingType.BASE64)\n    // do something with the result\n}\n```\n### Backend source set (Ktor)\n\nImplement the interface and initialize the library routing with a few lines of code.\n\n```kotlin\nimport java.net.URLEncoder\nimport acme.Base64Encoder\nimport acme.HexEncoder\nimport dev.kilua.rpc.applyRoutes\nimport dev.kilua.rpc.getAllServiceManagers\nimport dev.kilua.rpc.initRpc\nimport io.ktor.server.application.*\nimport io.ktor.server.plugins.compression.*\nimport io.ktor.server.routing.*\n\nclass EncodingService : IEncodingService {\n    override suspend fun encode(input: String, encodingType: EncodingType): String {\n        return when (encodingType) {\n                EncodingType.BASE64 -\u003e {\n                    Base64Encoder.encode(input)\n                }\n                EncodingType.URLENCODE -\u003e {\n                    URLEncoder.encode(input, \"UTF-8\")\n                }\n                EncodingType.HEX -\u003e {\n                    HexEncoder.encode(input)\n                }\n        }\n    }\n}\n\nfun Application.main() {\n    install(Compression)\n    routing {\n        getAllServiceManagers().forEach { applyRoutes(it) }\n    }\n    initRpc {\n        registerService\u003cIEncodingService\u003e { EncodingService() }\n    }\n}\n```\nEverything else happens automatically - a call on the client side will run the code on the server and the result will be sent back to the caller.\n\n## Rules\n\nDesigning the interface is probably the most important step, and during this process you have to stick to some important rules.\n\n#### An interface must be annotated with `@RpcService` annotation.\n\nKilua RPC compiler plugin will generate common, backend and frontend code based on the interface name.\n\n#### A method must be suspending\n\nKotlin coroutines allow the framework to translate asynchronous calls into synchronous-like code.\n\n#### A method must have from zero to six parameters\n\nThis is the restriction of the current version of the framework. It may change in the future.\n\n#### A method can't return nullable value\n\n`Unit` return type is not supported as well.\n\n#### Method parameters and return value must be of supported types\n\nSupported types are:\n\n* all basic Kotlin types (`String`, `Boolean`, `Int`, `Long`, `Short`, `Char`, `Byte`,  `Float`, `Double`)\n* `Enum` classes defined in common code and annotated with `@Serializable` annotation\n* All date and time types from `kotlinx-datetime` library\n* A `dev.kilua.rpc.types.Decimal` type, which is automatically mapped to `Double` on the frontend side and `java.math.BigDecimal` on the backend side\n* any class defined in common code with a `@Serializable` annotation\n* a `List\u003cT\u003e`, where T is one of the above types\n* a `T?`, where T is one of the above types (allowed only as method parameters - see previous rule)\n* a `Result\u003cT\u003e`, where T is one of the above types, can be used as a method return value.\n\nNote: Default parameters values are supported.\n\nEven with the above restrictions, the set of supported types is quite rich and you should be able to model almost any use case for your applications. With the help of `@Serializable` annotation you can always wrap any data structure into a serializable data class. It's also a simple way to pass around the parameters count limit.\n\n## Examples\n\nEach application server is configured a bit differently. You can check\nthe `examples` directory for simple applications created with all supported servers. \nYou will notice the frontend applications are identical - the only real difference \nis the backend app dependencies list and the main initialization code. \n\n## Gradle tasks\n\nKilua RPC gradle plugin defines custom tasks to run and package fullstack applications. \nNo matter which server is used these tasks are always available:\n\n- `jsBrowserDevelopmentRun` - run the frontend JS application in the development mode\n- `wasmJsBrowserDevelopmentRun` - run the frontend WASM application in the development mode\n- `jvmRun` - run the backend application in the development mode\n- `jarWithJs` - package the fullstack application with JS frontend as a single JAR file\n- `jarWithWasmJs` - package the fullstack application with WASM frontend as a single JAR file\n\n## Additional documentation\n\nIf you need more advanced information, until better documentation is ready, you can currently look into\nthe [KVision fullstack development guide](https://kvision.gitbook.io/kvision-guide/6.-full-stack-development-guide),\nbecause the general Kilua RPC rules are the same as KVision.\n\n## Leave a star\n\nIf you like this project, please give it a star on GitHub. Thank you!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frjaros%2Fkilua-rpc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frjaros%2Fkilua-rpc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frjaros%2Fkilua-rpc/lists"}