Skip to main content

Overview

Automorph is a Scala RPC client and server library for calling and serving remote APIs in a few lines of code.

Goals​

  • Provide efficient calling and serving of remote APIs
  • Ensure there is no boilerplate API code and minimal dependencies are required
  • Support manipulation of transport protocol metadata and dynamic message payload
  • Facilitate smooth integration by supporting wide range of existing technology
  • Allow for easy customization and extension of library features

Features​

Client​

Server​

General​

Usage​

Platform requirements​

Main interface​

// Define a remote API
trait Api:
  def hello(n: Int): Future[String]

// Create server implementation of the remote API
val service = new Api:
  def hello(n: Int): Future[String] = Future(s"Hello world $n")

// Expose a server API implementation to be called remotely
val apiServer = server.bind(service)

// Create a type-safe local proxy for the remote API from an API trait
val remoteApi = client.bind[Api]

// Call the remote API function via the local proxy
remoteApi.hello(1)

// Call the remote API function dynamically not using the API trait
client.call[String]("hello")("n" -> 1)

Note: Mundane parts of the code are omitted and can be found in the full example.

API​

The following classes represent primary entry points to Automorph functionality:

  • RPC client - Used to perform type-safe remote API calls or send one-way messages.
  • RPC server - Used to serve remote API requests and invoke bound API methods to process them.
  • RPC endpoint - Used to handle remote API requests as part of an existing server and invoke bound API methods to process them.

Various combinations of RPC protocol, effect system, message codec and transport layer can be utilized by supplying the desired plugin instances to the factory methods of the primary classes listed above.

There are also additional factory methods for creating primary class instances with default plugins.

SPI​

The following traits define interfaces for implementing various Automorph plugins:

  • RPC protocol - Enables use of a specific RPC protocol.
  • Effect system - Enables remote APIs to use specific effect handling abstraction.
  • Message codec - Enables serialization of RPC messages into specific structured data format.
  • Client transport - Enables RPC client to send requests and receive responses using specific transport protocol.
  • Server transport - Enables RPC server to receive requests and send responses using specific transport protocol.
  • Endpoint transport - Enables RPC endpoint to integrate with and handle requests from an existing server infrastructure.

Limitations​

Known issues​

  • Mangled signatures of a few nonessential methods in the API documentation caused by a Scaladoc defect

Supported standards​

The following technical standards are supported by freely combining appropriate plugins.

RPC protocols​

Transport protocols​

Message formats​

Effect handling​

API schemas​

Author​

  • Martin Ockajak

Special thanks​

  • Luigi Antognini

Inspired by​