IdeaLingua RPC & Domain Modeling Language
IdeaLingua is an RPC framework & Domain Modeling Language, it’s purpose is to:
- Publish APIs & data definitions in a common format and create idiomatic API clients and servers in any language.
- Enable remote calls to service via their public API definitions.
- Abstract irrelevant details such as network protocol and serialization format.
- Deliver our souls from REST and its brittle boilerplate.
User Service Example
Example definition of a user database service:
package user.api
enum Gender = Male | Female
id EntityID {
uuid: uuid
}
mixin Entity {
id: EntityID
}
mixin Person {
name: str
surname: str
gender: Gender
}
data User {
& Entity
+ Person
password: str
}
data PublicUser {
+ User
- password: str
}
adt Result = Success | Failure
data Success {
message: str
}
data Failure {
code: int8
}
service UserService {
def saveUser(user: User): Result
def findUserByName(name: str): list[PublicUser] | Failure
}
Pet Store Example
See izumi-petstore for examples in Scala, TypeScript, Go, C# and other languages.
Installation
Using SBT Plugin
Add the following to your project/plugins.sbt
file:
val izumi_version = "0.7.0-SNAPSHOT"
addSbtPlugin("com.github.pshirshov.izumi.r2" % "sbt-idealingua" % izumi_version)
Place your domain definitions into /src/main/izumi
directory, then enable the plugin for that project. For the generated code to compile, you will also need to add dependencies on the Idealingua RTS modules:
izumiProject
.enablePlugins(IdealinguaPlugin)
.settings(
libraryDependencies ++= Seq(
Izumi.R.idealingua_model
, Izumi.R.idealingua_runtime_rpc
, Izumi.R.idealingua_runtime_rpc_http4s
, Izumi.R.idealingua_runtime_rpc_circe
)
)
You can depend on the code generated by Idealinguain in your other Scala projects:
project.dependsOn(izumiProject)
Using the standalone compiler
The compiler executable is built as an uberjar and published on Maven Central.
The preferred way to install the compiler is with coursier
# install release executable
coursier bootstrap com.github.pshirshov.izumi.r2:idealingua-compiler_2.12:0.7.0-SNAPSHOT -o idlc
./idlc --help
To install snapshot:
# install snapshot
coursier bootstrap -r https://oss.sonatype.org/content/repositories/snapshots/ com.github.pshirshov.izumi.r2:idealingua-compiler_2.12:0.6.0-SNAPSHOT -o idlc
./idlc --help
Commandline examples:
./idlc -s src -t target -L scala=* -L typescript=*
./idlc -s src -t target -L scala=-AnyvalExtension -L typescript=*
Scala http4s Transport
Most likely you will need to use Kind Projector compiler plugin and enable partial unification:
scalacOptions += "-Ypartial-unification"
resolvers += Resolver.sonatypeRepo("releases")
addCompilerPlugin("org.spire-math" % "kind-projector" % "0.9.6" cross CrossVersion.binary)
You may find a test suite for the whole http4s pipeline here.
Please note that service definitons for the test suite are not generated from Idealingua definitions, you can find the Scala sources here.