Unix Domain Socket

From Wikipedia, A Unix domain socket or IPC socket (inter-process communication socket) is a data communications endpoint for exchanging data between processes executing on the same host operating system. Unix Domain Sockets leverage files and so operating system level access control can be utilized. This is a security advantage over using TCP/UDP where IPC is required without a more complex Transport Layer Security (TLS). Performance also favors Unix Domain Sockets over TCP/UDP given that the Operating System’s network stack is bypassed.

This connector provides an implementation of a Unix Domain Socket with interfaces modelled on the conventional Tcp Apache Pekko Streams class. The connector uses JNI and so there are no native dependencies.

The binding and connecting APIs are extremely similar to the Tcp Apache Pekko Streams class. UnixDomainSocket is generally substitutable for Tcp except that the SocketAddress is different (Unix Domain Sockets requires a java.io.File as opposed to a host and port). Please read the following for details:

• Scala user reference for Tcp
• Java user reference for Tcp

Note that Unix Domain Sockets, as the name implies, do not apply to Windows.

Artifacts

sbt

val PekkoVersion = "1.0.3"
libraryDependencies ++= Seq(
  "org.apache.pekko" %% "pekko-connectors-unix-domain-socket" % "1.0.2",
  "org.apache.pekko" %% "pekko-stream" % PekkoVersion
)

Maven

<properties>
  <pekko.version>1.0.3</pekko.version>
  <scala.binary.version>2.13</scala.binary.version>
</properties>
<dependencies>
  <dependency>
    <groupId>org.apache.pekko</groupId>
    <artifactId>pekko-connectors-unix-domain-socket_${scala.binary.version}</artifactId>
    <version>1.0.2</version>
  </dependency>
  <dependency>
    <groupId>org.apache.pekko</groupId>
    <artifactId>pekko-stream_${scala.binary.version}</artifactId>
    <version>${pekko.version}</version>
  </dependency>
</dependencies>

Gradle

def versions = [
  PekkoVersion: "1.0.3",
  ScalaBinary: "2.13"
]
dependencies {
  implementation "org.apache.pekko:pekko-connectors-unix-domain-socket_${versions.ScalaBinary}:1.0.2"
  implementation "org.apache.pekko:pekko-stream_${versions.ScalaBinary}:${versions.PekkoVersion}"
}

The table below shows direct dependencies of this module and the second tab shows all libraries it depends on transitively.

Binding to a file

Scala

copysourceval path: java.nio.file.Path = // ...
val binding: Future[UnixDomainSocket.ServerBinding] =
  UnixDomainSocket().bindAndHandle(serverSideFlow, path)

Java

copysourcejava.nio.file.Path path = // ...
final Source<IncomingConnection, CompletionStage<ServerBinding>> connections =
    UnixDomainSocket.get(system).bind(path);

Connecting to a file

Scala

copysourceval sendBytes = ByteString("Hello")
binding.flatMap { _ => // connection
  Source
    .single(sendBytes)
    .via(UnixDomainSocket().outgoingConnection(path))
    .runWith(Sink.ignore)
}

Java

copysourceCompletionStage<ServerBinding> futureBinding =
    connections
        .map(
            connection -> {
              log.info("New connection from: {}", connection.remoteAddress());

              final Flow<ByteString, ByteString, NotUsed> echo =
                  Flow.of(ByteString.class)
                      // server logic ...

              return connection.handleWith(echo, materializer);
            })
        .toMat(Sink.ignore(), Keep.left())
        .run(system);