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 Akka Streams class. The connector uses JNI and so there are no native dependencies.

The binding and connecting APIs are extremely similar to the Tcp Akka 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:

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

Project Info: Alpakka Unix Domain Socket
Artifact	com.lightbend.akka akka-stream-alpakka-unix-domain-socket 9.0.0 Snapshots are available
JDK versions	Eclipse Temurin JDK 11 Eclipse Temurin JDK 17
Scala versions	2.13.12
JPMS module name	akka.stream.alpakka.unixdomainsocket
License	BUSL-1.1
Readiness level	Community-driven Since 0.16, 2018-01-11
Home page	https://doc.akka.io/libraries/alpakka/current
API documentation	API (Scaladoc)
Forums	Akka Discuss
Release notes	GitHub releases
Issues	Github issues
Sources	https://github.com/akka/alpakka

Artifacts

The Akka dependencies are available from Akka’s library repository. To access them there, you need to configure the URL for this repository.

sbt

resolvers += "Akka library repository".at("https://repo.akka.io/maven")

Maven

<project>
  ...
  <repositories>
    <repository>
      <id>akka-repository</id>
      <name>Akka library repository</name>
      <url>https://repo.akka.io/maven</url>
    </repository>
  </repositories>
</project>

Gradle

repositories {
    mavenCentral()
    maven {
        url "https://repo.akka.io/maven"
    }
}

Additionally, add the dependencies as below.

sbt

val AkkaVersion = "2.10.0"
libraryDependencies ++= Seq(
  "com.lightbend.akka" %% "akka-stream-alpakka-unix-domain-socket" % "9.0.0",
  "com.typesafe.akka" %% "akka-stream" % AkkaVersion
)

Maven

<properties>
  <akka.version>2.10.0</akka.version>
  <scala.binary.version>2.13</scala.binary.version>
</properties>
<dependencies>
  <dependency>
    <groupId>com.lightbend.akka</groupId>
    <artifactId>akka-stream-alpakka-unix-domain-socket_${scala.binary.version}</artifactId>
    <version>9.0.0</version>
  </dependency>
  <dependency>
    <groupId>com.typesafe.akka</groupId>
    <artifactId>akka-stream_${scala.binary.version}</artifactId>
    <version>${akka.version}</version>
  </dependency>
</dependencies>

Gradle

def versions = [
  AkkaVersion: "2.10.0",
  ScalaBinary: "2.13"
]
dependencies {
  implementation "com.lightbend.akka:akka-stream-alpakka-unix-domain-socket_${versions.ScalaBinary}:9.0.0"
  implementation "com.typesafe.akka:akka-stream_${versions.ScalaBinary}:${versions.AkkaVersion}"
}

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

Direct dependencies

Organization	Artifact	Version
com.github.jnr	jffi	1.3.13
com.github.jnr	jnr-unixsocket	0.38.22
com.typesafe.akka	akka-stream_2.13	2.10.0
org.scala-lang	scala-library	2.13.12

Dependency tree

com.github.jnr    jffi    1.3.13    The Apache Software License, Version 2.0
com.github.jnr    jnr-unixsocket    0.38.22    The Apache Software License, Version 2.0
    com.github.jnr    jnr-constants    0.10.4    The Apache Software License, Version 2.0
    com.github.jnr    jnr-enxio    0.32.17    The Apache Software License, Version 2.0
        com.github.jnr    jnr-constants    0.10.4    The Apache Software License, Version 2.0
        com.github.jnr    jnr-ffi    2.2.16    The Apache Software License, Version 2.0
            com.github.jnr    jffi    1.3.13    The Apache Software License, Version 2.0
            com.github.jnr    jnr-a64asm    1.0.0    The Apache Software License, Version 2.0
            com.github.jnr    jnr-x86asm    1.0.2    MIT License
            org.ow2.asm    asm-analysis    9.2    BSD-3-Clause
                org.ow2.asm    asm-tree    9.2    BSD-3-Clause
                    org.ow2.asm    asm    9.2    BSD-3-Clause
            org.ow2.asm    asm-commons    9.2    BSD-3-Clause
                org.ow2.asm    asm-analysis    9.2    BSD-3-Clause
                    org.ow2.asm    asm-tree    9.2    BSD-3-Clause
                        org.ow2.asm    asm    9.2    BSD-3-Clause
                org.ow2.asm    asm-tree    9.2    BSD-3-Clause
                    org.ow2.asm    asm    9.2    BSD-3-Clause
                org.ow2.asm    asm    9.2    BSD-3-Clause
            org.ow2.asm    asm-tree    9.2    BSD-3-Clause
                org.ow2.asm    asm    9.2    BSD-3-Clause
            org.ow2.asm    asm-util    9.2    BSD-3-Clause
                org.ow2.asm    asm-analysis    9.2    BSD-3-Clause
                    org.ow2.asm    asm-tree    9.2    BSD-3-Clause
                        org.ow2.asm    asm    9.2    BSD-3-Clause
                org.ow2.asm    asm-tree    9.2    BSD-3-Clause
                    org.ow2.asm    asm    9.2    BSD-3-Clause
                org.ow2.asm    asm    9.2    BSD-3-Clause
            org.ow2.asm    asm    9.2    BSD-3-Clause
    com.github.jnr    jnr-ffi    2.2.16    The Apache Software License, Version 2.0
        com.github.jnr    jffi    1.3.13    The Apache Software License, Version 2.0
        com.github.jnr    jnr-a64asm    1.0.0    The Apache Software License, Version 2.0
        com.github.jnr    jnr-x86asm    1.0.2    MIT License
        org.ow2.asm    asm-analysis    9.2    BSD-3-Clause
            org.ow2.asm    asm-tree    9.2    BSD-3-Clause
                org.ow2.asm    asm    9.2    BSD-3-Clause
        org.ow2.asm    asm-commons    9.2    BSD-3-Clause
            org.ow2.asm    asm-analysis    9.2    BSD-3-Clause
                org.ow2.asm    asm-tree    9.2    BSD-3-Clause
                    org.ow2.asm    asm    9.2    BSD-3-Clause
            org.ow2.asm    asm-tree    9.2    BSD-3-Clause
                org.ow2.asm    asm    9.2    BSD-3-Clause
            org.ow2.asm    asm    9.2    BSD-3-Clause
        org.ow2.asm    asm-tree    9.2    BSD-3-Clause
            org.ow2.asm    asm    9.2    BSD-3-Clause
        org.ow2.asm    asm-util    9.2    BSD-3-Clause
            org.ow2.asm    asm-analysis    9.2    BSD-3-Clause
                org.ow2.asm    asm-tree    9.2    BSD-3-Clause
                    org.ow2.asm    asm    9.2    BSD-3-Clause
            org.ow2.asm    asm-tree    9.2    BSD-3-Clause
                org.ow2.asm    asm    9.2    BSD-3-Clause
            org.ow2.asm    asm    9.2    BSD-3-Clause
        org.ow2.asm    asm    9.2    BSD-3-Clause
    com.github.jnr    jnr-posix    3.1.19    Eclipse Public License - v 2.0
        com.github.jnr    jnr-constants    0.10.4    The Apache Software License, Version 2.0
        com.github.jnr    jnr-ffi    2.2.16    The Apache Software License, Version 2.0
            com.github.jnr    jffi    1.3.13    The Apache Software License, Version 2.0
            com.github.jnr    jnr-a64asm    1.0.0    The Apache Software License, Version 2.0
            com.github.jnr    jnr-x86asm    1.0.2    MIT License
            org.ow2.asm    asm-analysis    9.2    BSD-3-Clause
                org.ow2.asm    asm-tree    9.2    BSD-3-Clause
                    org.ow2.asm    asm    9.2    BSD-3-Clause
            org.ow2.asm    asm-commons    9.2    BSD-3-Clause
                org.ow2.asm    asm-analysis    9.2    BSD-3-Clause
                    org.ow2.asm    asm-tree    9.2    BSD-3-Clause
                        org.ow2.asm    asm    9.2    BSD-3-Clause
                org.ow2.asm    asm-tree    9.2    BSD-3-Clause
                    org.ow2.asm    asm    9.2    BSD-3-Clause
                org.ow2.asm    asm    9.2    BSD-3-Clause
            org.ow2.asm    asm-tree    9.2    BSD-3-Clause
                org.ow2.asm    asm    9.2    BSD-3-Clause
            org.ow2.asm    asm-util    9.2    BSD-3-Clause
                org.ow2.asm    asm-analysis    9.2    BSD-3-Clause
                    org.ow2.asm    asm-tree    9.2    BSD-3-Clause
                        org.ow2.asm    asm    9.2    BSD-3-Clause
                org.ow2.asm    asm-tree    9.2    BSD-3-Clause
                    org.ow2.asm    asm    9.2    BSD-3-Clause
                org.ow2.asm    asm    9.2    BSD-3-Clause
            org.ow2.asm    asm    9.2    BSD-3-Clause
com.typesafe.akka    akka-stream_2.13    2.10.0    BUSL-1.1
    com.typesafe.akka    akka-actor_2.13    2.10.0    BUSL-1.1
        com.typesafe    config    1.4.3    Apache-2.0
        org.scala-lang    scala-library    2.13.12    Apache-2.0
    com.typesafe.akka    akka-protobuf-v3_2.13    2.10.0    BUSL-1.1
    org.reactivestreams    reactive-streams    1.0.4    MIT-0
    org.scala-lang    scala-library    2.13.12    Apache-2.0
org.scala-lang    scala-library    2.13.12    Apache-2.0

Binding to a file

Scala

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

Java

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

Connecting to a file

Scala

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

Java

sourceCompletionStage<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);