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.