+str #24229 move SinkRef / SourceRef to akka.stream

+str #24229 remove protobuf changes, which do not need to be made in this PR

docs

moved things

config object

subscription timeout confifmed working, also, attributes

document attributes for sub timeout

tests for the source also failing when it should

additional demand test

implemented protection from materializing "in cycles"; would be nice in
types but that breaks the niceness of use of the types
SinkRef/SourceRef...

cleanup

no idle timeout built in, can use the Timeout stages

more docs

simplest change to prevent exposing SinkRef => SourceRef => SinkRef cycle

Things to decide:
 * is it ok to require using `getSource` / `getSink` as Java API, is there better naming?
 * where should the constructors go? I'd say just in regular javadsl/scaladsl `Source`/ `Sink` objects

move constructors to {javadsl,scaladsl}.{Source,Sink} companion objects

Remove now useless "canMaterialize" field

Separate stage (implementation) from ref (wrapped actor ref) to make it clearer what is serialized

Clarify that partner refs are not optional in on-the-wire interfaces

minor cleanup in SourceRefStage

Renamed the stages but questionable if that really helps ;)

cleanups, better docs

cleanup, fix docs compilation

fix mima

got rid of Futures in the materialized values of stream refs

akka-docs/src/test/scala/docs/stream/FlowStreamRefsDocSpec.scala

@@ -0,0 +1,125 @@
+/**
+ * Copyright (C) 2018 Lightbend Inc. <http://www.lightbend.com>
+ */
+package docs.stream
+
+import akka.NotUsed
+import akka.actor.{ Actor, Props }
+import akka.stream.ActorMaterializer
+import akka.stream.scaladsl._
+import akka.testkit.AkkaSpec
+import docs.CompileOnlySpec
+
+class FlowStreamRefsDocSpec extends AkkaSpec with CompileOnlySpec {
+
+  "offer a source ref" in compileOnlySpec {
+    //#offer-source
+    import akka.stream.SourceRef
+
+    case class RequestLogs(streamId: Int)
+    case class LogsOffer(streamId: Int, sourceRef: SourceRef[String])
+
+    class DataSource extends Actor {
+
+      implicit val mat = ActorMaterializer()(context)
+
+      def receive = {
+        case RequestLogs(streamId) ⇒
+          // obtain the source you want to offer:
+          val source: Source[String, NotUsed] = streamLogs(streamId)
+
+          // materialize the SourceRef:
+          val ref: SourceRef[String] = source.runWith(Sink.sourceRef())
+
+          // wrap the SourceRef in some domain message, such that the sender knows what source it is
+          val reply: LogsOffer = LogsOffer(streamId, ref)
+
+          // reply to sender
+          sender() ! reply
+      }
+
+      def streamLogs(streamId: Long): Source[String, NotUsed] = ???
+    }
+    //#offer-source
+
+    implicit val mat = ActorMaterializer()
+    //#offer-source-use
+    val sourceActor = system.actorOf(Props[DataSource], "dataSource")
+
+    sourceActor ! RequestLogs(1337)
+    val offer = expectMsgType[LogsOffer]
+
+    // implicitly converted to a Source:
+    offer.sourceRef.runWith(Sink.foreach(println))
+    // alternatively explicitly obtain Source from SourceRef:
+    // offer.sourceRef.source.runWith(Sink.foreach(println))
+
+    //#offer-source-use
+  }
+
+  "offer a sink ref" in compileOnlySpec {
+    //#offer-sink
+    import akka.pattern._
+    import akka.stream.SinkRef
+
+    case class PrepareUpload(sourceId: String)
+    case class MeasurementsSinkReady(sourceId: String, sinkRef: SinkRef[String])
+
+    class DataReceiver extends Actor {
+
+      import context.dispatcher
+      implicit val mat = ActorMaterializer()(context)
+
+      def receive = {
+        case PrepareUpload(nodeId) ⇒
+          // obtain the source you want to offer:
+          val sink: Sink[String, NotUsed] = logsSinkFor(nodeId)
+
+          // materialize the SinkRef (the remote is like a source of data for us):
+          val ref: SinkRef[String] = Source.sinkRef[String]().to(sink).run()
+
+          // wrap the SinkRef in some domain message, such that the sender knows what source it is
+          val reply: MeasurementsSinkReady = MeasurementsSinkReady(nodeId, ref)
+
+          // reply to sender
+          sender() ! reply
+      }
+
+      def logsSinkFor(nodeId: String): Sink[String, NotUsed] = ???
+    }
+
+    //#offer-sink
+
+    implicit val mat = ActorMaterializer()
+    def localMetrics(): Source[String, NotUsed] = Source.single("")
+
+    //#offer-sink-use
+    val receiver = system.actorOf(Props[DataReceiver], "receiver")
+
+    receiver ! PrepareUpload("system-42-tmp")
+    val ready = expectMsgType[MeasurementsSinkReady]
+
+    // stream local metrics to Sink's origin:
+    localMetrics().runWith(ready.sinkRef)
+    //#offer-sink-use
+  }
+
+  "show how to configure timeouts with attrs" in compileOnlySpec {
+
+    implicit val mat: ActorMaterializer = null
+    //#attr-sub-timeout
+    // configure the timeout for source
+    import scala.concurrent.duration._
+    import akka.stream.StreamRefAttributes
+
+    // configuring SourceRef.sink (notice that we apply the attributes to the Sink!):
+    Source.repeat("hello")
+      .runWith(Sink.sourceRef().addAttributes(StreamRefAttributes.subscriptionTimeout(5.seconds)))
+
+    // configuring SinkRef.source:
+    Source.sinkRef().addAttributes(StreamRefAttributes.subscriptionTimeout(5.seconds))
+      .runWith(Sink.ignore) // not very interesting Sink, just an example
+    //#attr-sub-timeout
+  }
+
+}