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
2.0.1
JDK versions
Adopt OpenJDK 8
Adopt OpenJDK 11
Scala versions2.12.10, 2.11.12, 2.13.1
JPMS module nameakka.stream.alpakka.unixdomainsocket
License
Readiness level
Since 0.16, 2018-01-11
Home pagehttps://doc.akka.io/docs/alpakka/current
API documentation
Forums
Release notesIn the documentation
IssuesGithub issues
Sourceshttps://github.com/akka/alpakka

Artifacts

sbt
val AkkaVersion = "2.5.31"
libraryDependencies ++= Seq(
  "com.lightbend.akka" %% "akka-stream-alpakka-unix-domain-socket" % "2.0.1",
  "com.typesafe.akka" %% "akka-stream" % AkkaVersion
)
Maven
<properties>
  <akka.version>2.5.31</akka.version>
  <scala.binary.version>2.12</scala.binary.version>
</properties>
<dependency>
  <groupId>com.lightbend.akka</groupId>
  <artifactId>akka-stream-alpakka-unix-domain-socket_${scala.binary.version}</artifactId>
  <version>2.0.1</version>
</dependency>
<dependency>
  <groupId>com.typesafe.akka</groupId>
  <artifactId>akka-stream_${scala.binary.version}</artifactId>
  <version>${akka.version}</version>
</dependency>
Gradle
versions += [
  AkkaVersion: "2.5.31",
  ScalaBinary: "2.12"
]
dependencies {
  compile group: 'com.lightbend.akka', name: "akka-stream-alpakka-unix-domain-socket_${versions.ScalaBinary}", version: '2.0.1',
  compile group: 'com.typesafe.akka', name: "akka-stream_${versions.ScalaBinary}", version: versions.AkkaVersion
}

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

Direct dependencies
OrganizationArtifactVersion
com.github.jnrjffi1.2.23
com.github.jnrjnr-unixsocket0.28
com.typesafe.akkaakka-stream_2.122.5.31
org.scala-langscala-library2.12.10
Dependency tree
com.github.jnr    jffi    1.2.23
com.github.jnr    jnr-unixsocket    0.28
    com.github.jnr    jnr-constants    0.9.15
    com.github.jnr    jnr-enxio    0.25
        com.github.jnr    jnr-constants    0.9.15
        com.github.jnr    jnr-ffi    2.1.12
            com.github.jnr    jffi    1.2.23
            com.github.jnr    jnr-a64asm    1.0.0
            com.github.jnr    jnr-x86asm    1.0.2
            org.ow2.asm    asm-analysis    7.1
                org.ow2.asm    asm-tree    7.1
                    org.ow2.asm    asm    7.1
            org.ow2.asm    asm-commons    7.1
                org.ow2.asm    asm-analysis    7.1
                    org.ow2.asm    asm-tree    7.1
                        org.ow2.asm    asm    7.1
                org.ow2.asm    asm-tree    7.1
                    org.ow2.asm    asm    7.1
                org.ow2.asm    asm    7.1
            org.ow2.asm    asm-tree    7.1
                org.ow2.asm    asm    7.1
            org.ow2.asm    asm-util    7.1
                org.ow2.asm    asm-analysis    7.1
                    org.ow2.asm    asm-tree    7.1
                        org.ow2.asm    asm    7.1
                org.ow2.asm    asm-tree    7.1
                    org.ow2.asm    asm    7.1
                org.ow2.asm    asm    7.1
            org.ow2.asm    asm    7.1
    com.github.jnr    jnr-ffi    2.1.12
        com.github.jnr    jffi    1.2.23
        com.github.jnr    jnr-a64asm    1.0.0
        com.github.jnr    jnr-x86asm    1.0.2
        org.ow2.asm    asm-analysis    7.1
            org.ow2.asm    asm-tree    7.1
                org.ow2.asm    asm    7.1
        org.ow2.asm    asm-commons    7.1
            org.ow2.asm    asm-analysis    7.1
                org.ow2.asm    asm-tree    7.1
                    org.ow2.asm    asm    7.1
            org.ow2.asm    asm-tree    7.1
                org.ow2.asm    asm    7.1
            org.ow2.asm    asm    7.1
        org.ow2.asm    asm-tree    7.1
            org.ow2.asm    asm    7.1
        org.ow2.asm    asm-util    7.1
            org.ow2.asm    asm-analysis    7.1
                org.ow2.asm    asm-tree    7.1
                    org.ow2.asm    asm    7.1
            org.ow2.asm    asm-tree    7.1
                org.ow2.asm    asm    7.1
            org.ow2.asm    asm    7.1
        org.ow2.asm    asm    7.1
    com.github.jnr    jnr-posix    3.0.54
        com.github.jnr    jnr-constants    0.9.15
        com.github.jnr    jnr-ffi    2.1.12
            com.github.jnr    jffi    1.2.23
            com.github.jnr    jnr-a64asm    1.0.0
            com.github.jnr    jnr-x86asm    1.0.2
            org.ow2.asm    asm-analysis    7.1
                org.ow2.asm    asm-tree    7.1
                    org.ow2.asm    asm    7.1
            org.ow2.asm    asm-commons    7.1
                org.ow2.asm    asm-analysis    7.1
                    org.ow2.asm    asm-tree    7.1
                        org.ow2.asm    asm    7.1
                org.ow2.asm    asm-tree    7.1
                    org.ow2.asm    asm    7.1
                org.ow2.asm    asm    7.1
            org.ow2.asm    asm-tree    7.1
                org.ow2.asm    asm    7.1
            org.ow2.asm    asm-util    7.1
                org.ow2.asm    asm-analysis    7.1
                    org.ow2.asm    asm-tree    7.1
                        org.ow2.asm    asm    7.1
                org.ow2.asm    asm-tree    7.1
                    org.ow2.asm    asm    7.1
                org.ow2.asm    asm    7.1
            org.ow2.asm    asm    7.1
com.typesafe.akka    akka-stream_2.12    2.5.31
    com.typesafe.akka    akka-actor_2.12    2.5.31
        com.typesafe    config    1.3.3
        org.scala-lang.modules    scala-java8-compat_2.12    0.8.0
    com.typesafe.akka    akka-protobuf_2.12    2.5.31
    com.typesafe    ssl-config-core_2.12    0.3.8
        com.typesafe    config    1.3.3
        org.scala-lang.modules    scala-parser-combinators_2.12    1.1.2
    org.reactivestreams    reactive-streams    1.0.2
org.scala-lang    scala-library    2.12.10

Binding to a file

Scala
val path: java.nio.file.Path = // ...
val binding: Future[UnixDomainSocket.ServerBinding] =
  UnixDomainSocket().bindAndHandle(serverSideFlow, path)
Java
java.nio.file.Path path = // ...
final Source<IncomingConnection, CompletionStage<ServerBinding>> connections =
    UnixDomainSocket.get(system).bind(path);

Connecting to a file

Scala
val sendBytes = ByteString("Hello")
binding.flatMap { _ => // connection
  Source
    .single(sendBytes)
    .via(UnixDomainSocket().outgoingConnection(path))
    .runWith(Sink.ignore)
}
Java
CompletionStage<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(materializer);
Found an error in this documentation? The source code for this page can be found here. Please feel free to edit and contribute a pull request.