Akka.Streams: add a "valve" stage to Akka.Streams that can be open / closed from the outside to pause transfer of events

[Aaronontheweb]

Is your feature request related to a problem? Please describe.

I've had to implement a stage like this before in some of my own projects and I received a request from end-users to this effect earlier today:

graph TD
    Source --> Valve
    Valve --> Sink

    subgraph FlowShape
        Valve
    end

    classDef open fill:#f9f,stroke:#333,stroke-width:2px;
    class Valve open;

Loading

Traffic flows normally when the Valve is open. However, when the Valve is closed all of the stages above it get backpressured.

graph TD
    Source --> Valve
    Valve -.-> Sink

    subgraph FlowShape
        Valve
    end

    classDef closed fill:#f00,stroke:#333,stroke-width:2px;
    class Valve closed;

Loading

Describe the solution you'd like

The whole idea behind this design is to make the Valve open / closeable from outside the stream graph - to pause execution while we wait for something else to happen (i.e. a configuration change, or to wait for all consumers underneath a MergeHub to be added before we begin event production.)

[Aaronontheweb]

Looks like this exact design was introduced in #3421 but we never documented it anywhere - so I'm going to change this to a documentation issue and solve the problem that way.

[Aaronontheweb]

Resolved via #7219 and #3421