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.

0.7.0*