Akka Scala Documentation Release 2.4.20 Lightbend Inc August 10, 2017 CONTENTS 1 Security Announcements1 1.1 Receiving Security Advisories....................................1 1.2 Reporting Vulnerabilities.......................................1 1.3 Security Related Documentation...................................1 1.4 Fixed Security Vulnerabilities....................................1 2 Introduction 4 2.1 What is Akka?............................................4 2.2 Why Akka?..............................................5 2.3 Getting Started............................................6 2.4 The Obligatory Hello World..................................... 10 2.5 Use-case and Deployment Scenarios................................. 10 2.6 Examples of use-cases for Akka................................... 11 3 General 13 3.1 Terminology, Concepts........................................ 13 3.2 Actor Systems............................................ 15 3.3 What is an Actor?.......................................... 17 3.4 Supervision and Monitoring..................................... 19 3.5 Actor References, Paths and Addresses............................... 24 3.6 Location Transparency........................................ 30 3.7 Akka and the Java Memory Model.................................. 31 3.8 Message Delivery Reliability.................................... 33 3.9 Configuration............................................. 38 4 Actors 102 4.1 Actors................................................ 102 4.2 Akka Typed.............................................. 121 4.3 Fault Tolerance............................................ 126 4.4 Dispatchers.............................................. 137 4.5 Mailboxes.............................................. 141 4.6 Routing................................................ 148 4.7 FSM................................................. 166 4.8 Persistence.............................................. 174 4.9 Persistence - Schema Evolution................................... 203 4.10 Persistence Query.......................................... 215 4.11 Persistence Query for LevelDB................................... 224 4.12 Testing Actor Systems........................................ 227 4.13 Actor DSL.............................................. 244 4.14 Typed Actors............................................. 246 5 Futures and Agents 252 5.1 Futures................................................ 252 5.2 Agents................................................ 258 i 6 Networking 262 6.1 Cluster Specification......................................... 262 6.2 Cluster Usage............................................. 268 6.3 Cluster Singleton........................................... 287 6.4 Distributed Publish Subscribe in Cluster............................... 290 6.5 Cluster Client............................................. 294 6.6 Cluster Sharding........................................... 299 6.7 Cluster Metrics Extension...................................... 308 6.8 Distributed Data........................................... 314 6.9 Remoting............................................... 330 6.10 Remoting (codename Artery).................................... 342 6.11 Serialization............................................. 356 6.12 I/O.................................................. 361 6.13 Using TCP.............................................. 363 6.14 Using UDP.............................................. 372 6.15 Camel................................................. 374 7 Utilities 385 7.1 Event Bus............................................... 385 7.2 Logging................................................ 391 7.3 Scheduler............................................... 398 7.4 Duration............................................... 402 7.5 Circuit Breaker............................................ 404 7.6 Akka Extensions........................................... 408 7.7 Use-case and Deployment Scenarios................................. 410 8 Streams 413 8.1 Introduction............................................. 413 8.2 Quick Start Guide.......................................... 414 8.3 Reactive Tweets........................................... 416 8.4 Design Principles behind Akka Streams............................... 420 8.5 Basics and working with Flows................................... 423 8.6 Working with Graphs......................................... 430 8.7 Modularity, Composition and Hierarchy............................... 442 8.8 Buffers and working with rate.................................... 453 8.9 Dynamic stream handling...................................... 457 8.10 Custom stream processing...................................... 461 8.11 Integration.............................................. 479 8.12 Error Handling............................................ 491 8.13 Working with streaming IO..................................... 493 8.14 Pipelining and Parallelism...................................... 496 8.15 Testing streams............................................ 499 8.16 Overview of built-in stages and their semantics........................... 502 8.17 Streams Cookbook.......................................... 526 8.18 Configuration............................................. 538 8.19 Migration Guide 1.0 to 2.x...................................... 539 8.20 Migration Guide 2.0.x to 2.4.x.................................... 539 9 Akka HTTP Documentation (Scala) moved! 543 10 HowTo: Common Patterns 544 10.1 Throttling Messages......................................... 544 10.2 Balancing Workload Across Nodes................................. 544 10.3 Work Pulling Pattern to throttle and distribute work, and prevent mailbox overflow........ 544 10.4 Ordered Termination......................................... 544 10.5 Akka AMQP Proxies......................................... 545 10.6 Shutdown Patterns in Akka 2.................................... 545 10.7 Distributed (in-memory) graph processing with Akka........................ 545 10.8 Case Study: An Auto-Updating Cache Using Actors........................ 545 ii 10.9 Discovering message flows in actor systems with the Spider Pattern................ 546 10.10 Scheduling Periodic Messages.................................... 546 11 Experimental Modules 548 11.1 Multi Node Testing.......................................... 548 11.2 Actors (Java with Lambda Support)................................. 553 11.3 FSM (Java with Lambda Support).................................. 573 11.4 Persistence Query.......................................... 582 11.5 Akka Typed.............................................. 591 11.6 External Contributions........................................ 596 12 Information for Akka Developers 618 12.1 Building Akka............................................ 618 12.2 Multi JVM Testing.......................................... 620 12.3 I/O Layer Design........................................... 623 12.4 Developer Guidelines........................................ 625 12.5 Documentation Guidelines...................................... 626 13 Project Information 629 13.1 Migration Guides........................................... 629 13.2 Issue Tracking............................................ 647 13.3 Licenses............................................... 648 13.4 Sponsors............................................... 648 13.5 Project................................................ 648 14 Additional Information 651 14.1 Binary Compatibility Rules..................................... 651 14.2 Frequently Asked Questions..................................... 654 14.3 Books................................................. 657 14.4 Videos................................................ 657 14.5 Akka in OSGi............................................ 657 iii CHAPTER ONE SECURITY ANNOUNCEMENTS 1.1 Receiving Security Advisories The best way to receive any and all security announcements is to subscribe to the Akka security list. The mailing list is very low traffic, and receives notifications only after security reports have been managed by the core team and fixes are publicly available. 1.2 Reporting Vulnerabilities We strongly encourage people to report such problems to our private security mailing list first, before disclosing them in a public forum. Following best practice, we strongly encourage anyone to report potential security vulnerabilities to secu- [email protected] before disclosing them in a public forum like the mailing list or as a Github issue. Reports to this email address will be handled by our security team, who will work together with you to ensure that a fix can be provided without delay. 1.3 Security Related Documentation • Disabling the Java Serializer • Remote deployment whitelist • Remote Security 1.4 Fixed Security Vulnerabilities 1.4.1 Java Serialization, Fixed in Akka 2.4.17 Date 10 Feburary 2017 Description of Vulnerability An attacker that can connect to an ActorSystem exposed via Akka Remote over TCP can gain remote code execution capabilities in the context of the JVM process that runs the ActorSystem if: • JavaSerializer is enabled (default in Akka 2.4.x) 1 Akka Scala Documentation, Release 2.4.20 • and TLS is disabled or TLS is enabled with akka.remote.netty.ssl.security.require-mutual-authentication = false (which is still the default in Akka 2.4.x) • or if TLS is enabled with mutual authentication and the authentication keys of a host that is