Safe Haskell	Safe-Inferred
Language	Haskell2010

Ouroboros.Network.ConnectionManager.Types

Contents

Connection manager core types
Connection Manager
Exceptions
Counters
Mux types
Promise
Tracing

Description

Connection manager core types.

Connection manager is responsible for managing uni- and bi-directional connections and threads which are running network applications using 'network-mux'. In particular it is responsible for:

opening new connection / reusing connections (for bidirectional connections) and exposes a method to register inbound connections;
run connection handler, i.e. ConnectionHandler, which runs handshake negotiation, notifies connection manager on the results and starts the multiplexer;
error handling for connection threads;
keeping track of handshake negotiation: whether a unidirectional or duplex connection was negotiated;
tracking state of each connection;
keep inbound connections under limits.

Connection manager is designed to work for any MuxMode, though the most useful ones are ResponderMode and InitiatorResponderMode:

InitiatorResponderMode - useful for node-to-node applications, which needs to create outbound connections as well as accept inbound ones;
ResponderMode - useful for server side of node-to-client; it allows us to share the same server between node-to-client and node-to-node;
InitiatorMode - could be used on client side of node-to-client applications.

The calls requestOutboundConnection and includeInboundConnection return once a connection has been negotiated. The returned handle contains all the information that is needed to start and monitor mini-protocols through the mux interface.

For inbound connections, the connection manager will pass handle (also after negotiation).

┌────────────────────────┐
│                        │        ┏━━━━━━━━━━━━━━━━┓
│   ConnectionHandler    │        ┃                ┃
│                        ┝━━━━━━━▶┃     handle     ┃
│  inbound / outbound    │        ┃                ┃
│         ┃              │        ┗━━┳━━━━━━━━━━━━━┛
└─────────╂──────────────┘           ┃
          ┃                          ┃
          ▼                          ┃
   ┏━━━━━━━━━━━━━━━━━┓               ┃
   ┃ Control Channel ┃               ┃
   ┗━━━━━━┳━━━━━━━━━━┛               ┃
          ┃                          ┃
          ┃                          ┃
          ▼                          ┃
┌────────────────────────┐           ┃
│                        │           ┃
│         Server         │◀━━━━━━━━━━┛
│                        │
└────────────────────────┘

Termination procedure as well as connection state machine is not described in this haddock, see associated specification.

The handle is used in `ouroboros-network` package to construct PeerStateActions which allow for the outbound governor to

Synopsis

data AddressType
- = IPv4Address
- | IPv6Address
data Provenance
- = Inbound
- | Outbound
data DataFlow
- = Unidirectional
- | Duplex
data TimeoutExpired
- = Expired
- | Ticking
data ConnectionType
- = UnnegotiatedConn !Provenance
- | InboundIdleConn !DataFlow
- | OutboundIdleConn !DataFlow
- | NegotiatedConn !Provenance !DataFlow
- | DuplexConn
newtype MaskedAction m a = MaskedAction {
- runWithUnmask ∷ (∀ x. m x → m x) → m a
}
type ConnectionHandlerFn handlerTrace socket peerAddr handle handleError version m = socket → PromiseWriter m (Either handleError (HandshakeConnectionResult handle version)) → Tracer m handlerTrace → ConnectionId peerAddr → (DiffTime → socket → m (MuxBearer m)) → MaskedAction m ()
newtype ConnectionHandler muxMode handlerTrace socket peerAddr handle handleError version m = ConnectionHandler {
- connectionHandler ∷ WithMuxTuple muxMode (ConnectionHandlerFn handlerTrace socket peerAddr handle handleError version m)
}
data Inactive
- = Active MiniProtocolDir
- | Inactive
data ExceptionInHandler where
- ExceptionInHandler ∷ ∀ peerAddr. (Typeable peerAddr, Show peerAddr) ⇒ !peerAddr → !SomeException → ExceptionInHandler
data HandleErrorType
- = HandshakeFailure
- | HandshakeProtocolViolation
data HandshakeConnectionResult handle version
- = HandshakeConnectionQuery
- | HandshakeConnectionResult handle version
type PrunePolicy peerAddr = StdGen → Map peerAddr ConnectionType → Int → Set peerAddr
simplePrunePolicy ∷ Ord peerAddr ⇒ PrunePolicy peerAddr
data ConnectionManager (muxMode ∷ MuxMode) socket peerAddr handle handleError m = ConnectionManager {
- getConnectionManager ∷ WithMuxMode muxMode (OutboundConnectionManager muxMode socket peerAddr handle handleError m) (InboundConnectionManager muxMode socket peerAddr handle handleError m)
- readState ∷ STM m (Map peerAddr AbstractState)
- waitForOutboundDemotion ∷ peerAddr → STM m ()
}
data Connected peerAddr handle handleError
- = Connected !(ConnectionId peerAddr) !DataFlow !handle
- | Disconnected !(ConnectionId peerAddr) !(Maybe handleError)
data OperationResult a
- = UnsupportedState !AbstractState
- | OperationSuccess !a
- | TerminatedConnection !AbstractState
resultInState ∷ OperationResult AbstractState → AbstractState
data DemotedToColdRemoteTr
- = CommitTr
- | KeepTr
type RequestOutboundConnection peerAddr handle handleError m = peerAddr → m (Connected peerAddr handle handleError)
type IncludeInboundConnection socket peerAddr handle handleError m = Word32 → socket → peerAddr → m (Connected peerAddr handle handleError)
requestOutboundConnection ∷ HasInitiator muxMode ~ True ⇒ ConnectionManager muxMode socket peerAddr handle handleError m → RequestOutboundConnection peerAddr handle handleError m
promotedToWarmRemote ∷ HasResponder muxMode ~ True ⇒ ConnectionManager muxMode socket peerAddr handle handleError m → peerAddr → m (OperationResult AbstractState)
demotedToColdRemote ∷ HasResponder muxMode ~ True ⇒ ConnectionManager muxMode socket peerAddr handle handleError m → peerAddr → m (OperationResult AbstractState)
unregisterOutboundConnection ∷ HasInitiator muxMode ~ True ⇒ ConnectionManager muxMode socket peerAddr handle handleError m → peerAddr → m (OperationResult AbstractState)
includeInboundConnection ∷ HasResponder muxMode ~ True ⇒ ConnectionManager muxMode socket peerAddr handle handleError m → IncludeInboundConnection socket peerAddr handle handleError m
unregisterInboundConnection ∷ HasResponder muxMode ~ True ⇒ ConnectionManager muxMode socket peerAddr handle handleError m → peerAddr → m (OperationResult DemotedToColdRemoteTr)
numberOfConnections ∷ HasResponder muxMode ~ True ⇒ ConnectionManager muxMode socket peerAddr handle handleError m → STM m Int
data OutboundConnectionManager (muxMode ∷ MuxMode) socket peerAddr handle handleError m where
- OutboundConnectionManager ∷ HasInitiator muxMode ~ True ⇒ {..} → OutboundConnectionManager muxMode socket peerAddr handle handleError m
data InboundConnectionManager (muxMode ∷ MuxMode) socket peerAddr handle handleError m where
- InboundConnectionManager ∷ HasResponder muxMode ~ True ⇒ {..} → InboundConnectionManager muxMode socket peerAddr handle handleError m
data ConnectionManagerError peerAddr
- = ConnectionExists !Provenance !peerAddr !CallStack
- | ForbiddenConnection !(ConnectionId peerAddr) !CallStack
- | ImpossibleConnection !(ConnectionId peerAddr) !CallStack
- | ConnectionTerminating !(ConnectionId peerAddr) !CallStack
- | ConnectionTerminated !peerAddr !CallStack
- | ImpossibleState !peerAddr !CallStack
- | ForbiddenOperation !peerAddr !AbstractState !CallStack
- | UnknownPeer !peerAddr !CallStack
data SomeConnectionManagerError = ∀ addr.(Typeable addr, Show addr) ⇒ SomeConnectionManagerError !(ConnectionManagerError addr)
data AbstractState
- = UnknownConnectionSt
- | ReservedOutboundSt
- | UnnegotiatedSt !Provenance
- | InboundIdleSt !DataFlow
- | InboundSt !DataFlow
- | OutboundUniSt
- | OutboundDupSt !TimeoutExpired
- | OutboundIdleSt !DataFlow
- | DuplexSt
- | WaitRemoteIdleSt
- | TerminatingSt
- | TerminatedSt
data ConnectionManagerCounters = ConnectionManagerCounters {
- fullDuplexConns ∷ !Int
- duplexConns ∷ !Int
- unidirectionalConns ∷ !Int
- inboundConns ∷ !Int
- outboundConns ∷ !Int
}
data WithMuxMode (mode ∷ MuxMode) a b where
- WithInitiatorMode ∷ a → WithMuxMode InitiatorMode a b
- WithResponderMode ∷ b → WithMuxMode ResponderMode a b
- WithInitiatorResponderMode ∷ a → b → WithMuxMode InitiatorResponderMode a b
withInitiatorMode ∷ HasInitiator mode ~ True ⇒ WithMuxMode mode a b → a
withResponderMode ∷ HasResponder mode ~ True ⇒ WithMuxMode mode a b → b
newEmptyPromiseIO ∷ (MonadSTM m, MonadThrow (STM m)) ⇒ m (PromiseReader m a, PromiseWriter m a)
newtype PromiseReader m a = PromiseReader {
- readPromise ∷ STM m a
}
readPromiseIO ∷ MonadSTM m ⇒ PromiseReader m a → m a
data PromiseWriter m a = PromiseWriter {
- writePromise ∷ a → STM m ()
- forcePromise ∷ a → STM m ()
}
data PromiseWriterException = PromiseWriterBlocked
data AssertionLocation peerAddr
- = UnregisterInboundConnection !(Maybe (ConnectionId peerAddr)) !AbstractState
- | RequestOutboundConnection !(Maybe (ConnectionId peerAddr)) !AbstractState
- | UnregisterOutboundConnection !(Maybe (ConnectionId peerAddr)) !AbstractState
- | PromotedToWarmRemote !(Maybe (ConnectionId peerAddr)) !AbstractState
- | DemotedToColdRemote !(Maybe (ConnectionId peerAddr)) !AbstractState
data ConnectionManagerTrace peerAddr handlerTrace
- = TrIncludeConnection Provenance peerAddr
- | TrUnregisterConnection Provenance peerAddr
- | TrConnect (Maybe peerAddr) peerAddr
- | TrConnectError (Maybe peerAddr) peerAddr SomeException
- | TrTerminatingConnection Provenance (ConnectionId peerAddr)
- | TrTerminatedConnection Provenance peerAddr
- | TrConnectionHandler (ConnectionId peerAddr) handlerTrace
- | TrShutdown
- | TrConnectionExists Provenance peerAddr AbstractState
- | TrForbiddenConnection (ConnectionId peerAddr)
- | TrConnectionFailure (ConnectionId peerAddr)
- | TrConnectionNotFound Provenance peerAddr
- | TrForbiddenOperation peerAddr AbstractState
- | TrPruneConnections (Set peerAddr) Int (Set peerAddr)
- | TrConnectionCleanup (ConnectionId peerAddr)
- | TrConnectionTimeWait (ConnectionId peerAddr)
- | TrConnectionTimeWaitDone (ConnectionId peerAddr)
- | TrConnectionManagerCounters ConnectionManagerCounters
- | TrState (Map peerAddr AbstractState)
- | TrUnexpectedlyFalseAssertion (AssertionLocation peerAddr)
data MaybeUnknown state
- = Known !state
- | Race !state
- | Unknown
data Transition' state = Transition {
- fromState ∷ !state
- toState ∷ !state
}
type Transition state = Transition' (MaybeUnknown state)
type AbstractTransition = Transition' AbstractState
mkTransition ∷ state → state → Transition state
type TransitionTrace peerAddr state = TransitionTrace' peerAddr (MaybeUnknown state)
data TransitionTrace' peerAddr state = TransitionTrace {
- ttPeerAddr ∷ peerAddr
- ttTransition ∷ Transition' state
}
type AbstractTransitionTrace peerAddr = TransitionTrace' peerAddr AbstractState

Connection manager core types

Connection Types

data AddressType Source #

Connection manager supports IPv4 and IPv6 addresses.

Constructors

IPv4Address
IPv6Address

Instances

Instances details

Show AddressType Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec ∷ Int → AddressType → ShowS # show ∷ AddressType → String # showList ∷ [AddressType] → ShowS #

data Provenance Source #

Each connection is is either initiated locally (outbound) or by a remote peer (inbound).

Constructors

Inbound	An inbound connection: one that was initiated by a remote peer.
Outbound	An outbound connection: one that was initiated by us.

Instances

Instances details

Show Provenance Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec ∷ Int → Provenance → ShowS # show ∷ Provenance → String # showList ∷ [Provenance] → ShowS #
Eq Provenance Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods (==) ∷ Provenance → Provenance → Bool # (/=) ∷ Provenance → Provenance → Bool #
Ord Provenance Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods compare ∷ Provenance → Provenance → Ordering # (<) ∷ Provenance → Provenance → Bool # (<=) ∷ Provenance → Provenance → Bool # (>) ∷ Provenance → Provenance → Bool # (>=) ∷ Provenance → Provenance → Bool # max ∷ Provenance → Provenance → Provenance # min ∷ Provenance → Provenance → Provenance #

data DataFlow Source #

Each connection negotiates if it is uni- or bi-directional. DataFlow is a life time property of a connection, once negotiated it never changes.

Constructors

Unidirectional
Duplex

Instances

Instances details

Show DataFlow Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec ∷ Int → DataFlow → ShowS # show ∷ DataFlow → String # showList ∷ [DataFlow] → ShowS #
Eq DataFlow Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods (==) ∷ DataFlow → DataFlow → Bool # (/=) ∷ DataFlow → DataFlow → Bool #
Ord DataFlow Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods compare ∷ DataFlow → DataFlow → Ordering # (<) ∷ DataFlow → DataFlow → Bool # (<=) ∷ DataFlow → DataFlow → Bool # (>) ∷ DataFlow → DataFlow → Bool # (>=) ∷ DataFlow → DataFlow → Bool # max ∷ DataFlow → DataFlow → DataFlow # min ∷ DataFlow → DataFlow → DataFlow #

data TimeoutExpired Source #

Boolean like type which indicates if the timeout on OutboundStateDuplex has expired.

Constructors

Expired
Ticking

Instances

Instances details

Show TimeoutExpired Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec ∷ Int → TimeoutExpired → ShowS # show ∷ TimeoutExpired → String # showList ∷ [TimeoutExpired] → ShowS #
Eq TimeoutExpired Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods (==) ∷ TimeoutExpired → TimeoutExpired → Bool # (/=) ∷ TimeoutExpired → TimeoutExpired → Bool #
Ord TimeoutExpired Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods compare ∷ TimeoutExpired → TimeoutExpired → Ordering # (<) ∷ TimeoutExpired → TimeoutExpired → Bool # (<=) ∷ TimeoutExpired → TimeoutExpired → Bool # (>) ∷ TimeoutExpired → TimeoutExpired → Bool # (>=) ∷ TimeoutExpired → TimeoutExpired → Bool # max ∷ TimeoutExpired → TimeoutExpired → TimeoutExpired # min ∷ TimeoutExpired → TimeoutExpired → TimeoutExpired #

data ConnectionType Source #

Either unnegotiated or negotiated unidirectional or duplex connections. This is not a static property of a connection. It is used by PrunePolicy.

Note: the order matters, it can be used by a PickPolicy, e.g. simplePickPolicy.

Constructors

UnnegotiatedConn !Provenance	An unnegotiated connection.
InboundIdleConn !DataFlow	An inbound idle connection.
OutboundIdleConn !DataFlow	An outbound idle connection.
NegotiatedConn !Provenance !DataFlow	A negotiated connection, which is used in only one direction indicated by `Provenance`. The connection could itself negotiated either `Duplex` or `Unidirectional` data flow.
DuplexConn	A connection which is running in full duplex mode.

Instances

Instances details

Show ConnectionType Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec ∷ Int → ConnectionType → ShowS # show ∷ ConnectionType → String # showList ∷ [ConnectionType] → ShowS #
Eq ConnectionType Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods (==) ∷ ConnectionType → ConnectionType → Bool # (/=) ∷ ConnectionType → ConnectionType → Bool #
Ord ConnectionType Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods compare ∷ ConnectionType → ConnectionType → Ordering # (<) ∷ ConnectionType → ConnectionType → Bool # (<=) ∷ ConnectionType → ConnectionType → Bool # (>) ∷ ConnectionType → ConnectionType → Bool # (>=) ∷ ConnectionType → ConnectionType → Bool # max ∷ ConnectionType → ConnectionType → ConnectionType # min ∷ ConnectionType → ConnectionType → ConnectionType #

Connection Handler

ConnectionHandler provides monadic action which runs handshake negotiation and starts the multiplexer. It's the component which has access to underlying socket. There's one-to-one correspondence between sockets and threads that run the handler.

ConnectionHandlerFn: is the type of callback executed for each connection. All arguments are provided by the connection manager.
ConnectionHandler: is a newtype wrapper which provides inbound / outbound handlers depending on MuxMode.

newtype MaskedAction m a Source #

Handler action is started with asynchronous exceptions masked; this allows to install exception handlers in an async-safe way.

Constructors

MaskedAction
Fields runWithUnmask ∷ (∀ x. m x → m x) → m a

type ConnectionHandlerFn handlerTrace socket peerAddr handle handleError version m = socket → PromiseWriter m (Either handleError (HandshakeConnectionResult handle version)) → Tracer m handlerTrace → ConnectionId peerAddr → (DiffTime → socket → m (MuxBearer m)) → MaskedAction m () Source #

MaskedAction which is executed by thread designated for a given connection.

PromiseWriter allows to notify the ConnectionManager about the result of handshake negotiation.

Note: PromiseWriter could be replaced with an stm action which is accessing the TVar which holds state of the connection.

newtype ConnectionHandler muxMode handlerTrace socket peerAddr handle handleError version m Source #

Connection handler action. It is index by muxMode :: MuxMode. There's one ConnectionHandlerFn per provenance, possibly limited by muxMode.

Constructors

ConnectionHandler
Fields connectionHandler ∷ WithMuxTuple muxMode (ConnectionHandlerFn handlerTrace socket peerAddr handle handleError version m) Connection handler.

data Inactive Source #

Boolean like type

Constructors

Active MiniProtocolDir
Inactive

Instances

Instances details

Show Inactive Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec ∷ Int → Inactive → ShowS # show ∷ Inactive → String # showList ∷ [Inactive] → ShowS #
Eq Inactive Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods (==) ∷ Inactive → Inactive → Bool # (/=) ∷ Inactive → Inactive → Bool #

data ExceptionInHandler where Source #

Exception which where caught in the connection thread and were re-thrown in the main thread by the rethrowPolicy.

Constructors

ExceptionInHandler ∷ ∀ peerAddr. (Typeable peerAddr, Show peerAddr) ⇒ !peerAddr → !SomeException → ExceptionInHandler

Instances

Instances details

Exception ExceptionInHandler Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods toException ∷ ExceptionInHandler → SomeException # fromException ∷ SomeException → Maybe ExceptionInHandler # displayException ∷ ExceptionInHandler → String #
Show ExceptionInHandler Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec ∷ Int → ExceptionInHandler → ShowS # show ∷ ExceptionInHandler → String # showList ∷ [ExceptionInHandler] → ShowS #

data HandleErrorType Source #

Data type used to classify handleErrors.

Constructors

HandshakeFailure	Handshake negotiation failed. This is not a protocol error.
HandshakeProtocolViolation	Handshake protocol error. This should include timeout errors or any IO errors.

data HandshakeConnectionResult handle version Source #

Constructors

HandshakeConnectionQuery	Handshake saw a query.
HandshakeConnectionResult handle version	Handshake resulted in a connection and version.

Prune Policy

type PrunePolicy peerAddr = StdGen → Map peerAddr ConnectionType → Int → Set peerAddr Source #

PrunePolicy allows to pick a select peers from which we will disconnect (we use TCP reset). The chosen connections will be terminated by the connection manger once it detects that there are too many inbound connections.

simplePrunePolicy ∷ Ord peerAddr ⇒ PrunePolicy peerAddr Source #

The simplest PrunePolicy, it should only be used for tests.

Connection Manager

Connection Manager Arguments

data ConnectionManager (muxMode ∷ MuxMode) socket peerAddr handle handleError m Source #

ConnectionManager.

We identify resources (e.g. Socket or HANDLE) by their address. It is enough for us to use just the remote address rather than connection identifier, since we need one connection towards that peer, even if we are connected through multiple local addresses. It is safe to share a connection manager with multiple listening sockets.

Constructors

ConnectionManager

Fields

getConnectionManager ∷ WithMuxMode muxMode (OutboundConnectionManager muxMode socket peerAddr handle handleError m) (InboundConnectionManager muxMode socket peerAddr handle handleError m)
readState ∷ STM m (Map peerAddr AbstractState)
waitForOutboundDemotion ∷ peerAddr → STM m ()
This STM action will block until the given connection is fully closed/terminated. If the connection manager doesn't have any connection to that peer it won't block.

API

data Connected peerAddr handle handleError Source #

Result of requestOutboundConnection or includeInboundConnection.

Constructors

Connected !(ConnectionId peerAddr) !DataFlow !handle

We are connected and mux is running.

Disconnected !(ConnectionId peerAddr) !(Maybe handleError)

There was an error during handshake negotiation.

Implementation detail: we return Maybe handleError, rather than handleError. In case of an existing inbound connection, the implementation of requestOutboundConnection is awaiting on handshake through the connection state. The TerminatingState or TerminatedState are not only used for handshake errors, but also for normal termination, hence the Maybe. We could await on update from the handshake instead, but this would introduce a race between inbound / outbound threads.

data OperationResult a Source #

Custom either type for result of various methods.

Constructors

UnsupportedState !AbstractState
OperationSuccess !a
TerminatedConnection !AbstractState

Instances

Instances details

Functor OperationResult Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods fmap ∷ (a → b) → OperationResult a → OperationResult b # (<$) ∷ a → OperationResult b → OperationResult a #
Show a ⇒ Show (OperationResult a) Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec ∷ Int → OperationResult a → ShowS # show ∷ OperationResult a → String # showList ∷ [OperationResult a] → ShowS #

resultInState ∷ OperationResult AbstractState → AbstractState Source #

data DemotedToColdRemoteTr Source #

Return value of unregisterInboundConnection to inform the caller about the transition.

Constructors

CommitTr	`Commit^{dataFlow}` transition from `InboundIdleState dataFlow`.
KeepTr	Either `DemotedToCold^{Remote}` transition from `DuplexState`, or a level triggered `Awake^{Duplex}_{Local}` transition. In both cases the server must keep the responder side of all protocols ready.

Instances

Instances details

Show DemotedToColdRemoteTr Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec ∷ Int → DemotedToColdRemoteTr → ShowS # show ∷ DemotedToColdRemoteTr → String # showList ∷ [DemotedToColdRemoteTr] → ShowS #

type RequestOutboundConnection peerAddr handle handleError m = peerAddr → m (Connected peerAddr handle handleError) Source #

type IncludeInboundConnection socket peerAddr handle handleError m Source #

Arguments

= Word32	inbound connections hard limit. NOTE: Check TODO over at includeInboundConnectionImpl definition.
→ socket
→ peerAddr
→ m (Connected peerAddr handle handleError)

Outbound side

requestOutboundConnection ∷ HasInitiator muxMode ~ True ⇒ ConnectionManager muxMode socket peerAddr handle handleError m → RequestOutboundConnection peerAddr handle handleError m Source #

Include outbound connection into ConnectionManager.

This executes:

$Reserve$ to $Negotiated^{*}_{Outbound}$ transitions
$PromotedToWarm^{Duplex}_{Local}$ transition
$Awake^{Duplex}_{Local}$ transition

promotedToWarmRemote ∷ HasResponder muxMode ~ True ⇒ ConnectionManager muxMode socket peerAddr handle handleError m → peerAddr → m (OperationResult AbstractState) Source #

Notify the ConnectionManager that a remote end promoted us to a warm peer.

This executes either:

$PromotedToWarm^{Duplex}_{Remote}$ transition,
$Awake^{*}_{Remote}$ transition

from the specification.

demotedToColdRemote ∷ HasResponder muxMode ~ True ⇒ ConnectionManager muxMode socket peerAddr handle handleError m → peerAddr → m (OperationResult AbstractState) Source #

Notify the ConnectionManager that a remote end demoted us to a /cold peer/.

This executes:

$DemotedToCold^{*}_{Remote}$ transition.

This method is idempotent.

unregisterOutboundConnection Source #

Arguments

∷ HasInitiator muxMode ~ True
⇒ ConnectionManager muxMode socket peerAddr handle handleError m
→ peerAddr
→ m (OperationResult AbstractState)	reports the from-state.

Unregister outbound connection.

This executes:

$DemotedToCold^{*}_{Local}$ transitions

Inbound side

includeInboundConnection ∷ HasResponder muxMode ~ True ⇒ ConnectionManager muxMode socket peerAddr handle handleError m → IncludeInboundConnection socket peerAddr handle handleError m Source #

Include an inbound connection into ConnectionManager. This executes:

$Reserve$ to $Negotiated^{*}_{Outbound}$ transitions
$PromotedToWarm^{Duplex}_{Local}$ transition
$Awake^{Duplex}_{Local}$ transition

unregisterInboundConnection ∷ HasResponder muxMode ~ True ⇒ ConnectionManager muxMode socket peerAddr handle handleError m → peerAddr → m (OperationResult DemotedToColdRemoteTr) Source #

Unregister outbound connection. Returns if the operation was successful.

This executes:

$Commit*{*}$ transition
$TimeoutExpired$ transition

numberOfConnections ∷ HasResponder muxMode ~ True ⇒ ConnectionManager muxMode socket peerAddr handle handleError m → STM m Int Source #

Number of connections tracked by the server.

Private API

data OutboundConnectionManager (muxMode ∷ MuxMode) socket peerAddr handle handleError m where Source #

Outbound connection manager API.

Constructors

OutboundConnectionManager
Fields ∷ HasInitiator muxMode ~ True ⇒ { ocmRequestConnection ∷ RequestOutboundConnection peerAddr handle handleError m , ocmUnregisterConnection ∷ peerAddr → m (OperationResult AbstractState) } → OutboundConnectionManager muxMode socket peerAddr handle handleError m

data InboundConnectionManager (muxMode ∷ MuxMode) socket peerAddr handle handleError m where Source #

Inbound connection manager API. For a server implementation we also need to know how many connections are now managed by the connection manager.

This type is an internal detail of ConnectionManager

Constructors

InboundConnectionManager

Fields

∷ HasResponder muxMode ~ True
⇒ { icmIncludeConnection ∷ IncludeInboundConnection socket peerAddr handle handleError m
, icmUnregisterConnection ∷ peerAddr → m (OperationResult DemotedToColdRemoteTr)
, icmPromotedToWarmRemote ∷ peerAddr → m (OperationResult AbstractState)
, icmDemotedToColdRemote ∷ peerAddr → m (OperationResult AbstractState)
, icmNumberOfConnections ∷ STM m Int
} → InboundConnectionManager muxMode socket peerAddr handle handleError m

Exceptions

data ConnectionManagerError peerAddr Source #

Exceptions used by ConnectionManager.

Constructors

ConnectionExists !Provenance !peerAddr !CallStack	A connection manager was asked for an outbound connection and there either exists a connection used in outbound direction or a reservation for an outbound connection.
ForbiddenConnection !(ConnectionId peerAddr) !CallStack	Connection manager was asked for an outbound connection which turned out to be unidirectional inbound, and thus it cannot be re-used..
ImpossibleConnection !(ConnectionId peerAddr) !CallStack	Connections that would be forbidden by the kernel (`TCP` semantics).
ConnectionTerminating !(ConnectionId peerAddr) !CallStack	Connection is now terminating.
ConnectionTerminated !peerAddr !CallStack	Connection has terminated.
ImpossibleState !peerAddr !CallStack	Connection manager in impossible state.
ForbiddenOperation !peerAddr !AbstractState !CallStack	A forbidden operation in the given connection state.
UnknownPeer !peerAddr !CallStack	A connection does not exists. Only thrown when an existing connection was expected.

Instances

Instances details

(Show peerAddr, Typeable peerAddr) ⇒ Exception (ConnectionManagerError peerAddr) Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods toException ∷ ConnectionManagerError peerAddr → SomeException # fromException ∷ SomeException → Maybe (ConnectionManagerError peerAddr) # displayException ∷ ConnectionManagerError peerAddr → String #
Show peerAddr ⇒ Show (ConnectionManagerError peerAddr) Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec ∷ Int → ConnectionManagerError peerAddr → ShowS # show ∷ ConnectionManagerError peerAddr → String # showList ∷ [ConnectionManagerError peerAddr] → ShowS #

data SomeConnectionManagerError Source #

Existential wrapper for ConnectionManagerError peerAddr. It allows to use fromException, without being bothered about the address type.

Constructors

∀ addr.(Typeable addr, Show addr) ⇒ SomeConnectionManagerError !(ConnectionManagerError addr)

Instances

Instances details

Exception SomeConnectionManagerError Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods toException ∷ SomeConnectionManagerError → SomeException # fromException ∷ SomeException → Maybe SomeConnectionManagerError # displayException ∷ SomeConnectionManagerError → String #
Show SomeConnectionManagerError Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec ∷ Int → SomeConnectionManagerError → ShowS # show ∷ SomeConnectionManagerError → String # showList ∷ [SomeConnectionManagerError] → ShowS #

data AbstractState Source #

Useful for tracing and error messages.

Constructors

UnknownConnectionSt	Unknown connection. This state indicates the connection manager removed this connection from its state.
ReservedOutboundSt
UnnegotiatedSt !Provenance
InboundIdleSt !DataFlow
InboundSt !DataFlow
OutboundUniSt
OutboundDupSt !TimeoutExpired
OutboundIdleSt !DataFlow
DuplexSt
WaitRemoteIdleSt
TerminatingSt
TerminatedSt

Instances

Instances details

Show AbstractState Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec ∷ Int → AbstractState → ShowS # show ∷ AbstractState → String # showList ∷ [AbstractState] → ShowS #
Eq AbstractState Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods (==) ∷ AbstractState → AbstractState → Bool # (/=) ∷ AbstractState → AbstractState → Bool #
Ord AbstractState Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods compare ∷ AbstractState → AbstractState → Ordering # (<) ∷ AbstractState → AbstractState → Bool # (<=) ∷ AbstractState → AbstractState → Bool # (>) ∷ AbstractState → AbstractState → Bool # (>=) ∷ AbstractState → AbstractState → Bool # max ∷ AbstractState → AbstractState → AbstractState # min ∷ AbstractState → AbstractState → AbstractState #

Counters

data ConnectionManagerCounters Source #

Counters for tracing and analysis purposes

Constructors

ConnectionManagerCounters
Fields fullDuplexConns ∷ !Int number of full duplex connections duplexConns ∷ !Int number of negotiated duplex connections (including DuplexState connections) unidirectionalConns ∷ !Int number of negotiated unidirectional connections inboundConns ∷ !Int number of inbound connections outboundConns ∷ !Int number of outbound connections

Instances

Instances details

Monoid ConnectionManagerCounters Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods mempty ∷ ConnectionManagerCounters # mappend ∷ ConnectionManagerCounters → ConnectionManagerCounters → ConnectionManagerCounters # mconcat ∷ [ConnectionManagerCounters] → ConnectionManagerCounters #
Semigroup ConnectionManagerCounters Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods (<>) ∷ ConnectionManagerCounters → ConnectionManagerCounters → ConnectionManagerCounters # sconcat ∷ NonEmpty ConnectionManagerCounters → ConnectionManagerCounters # stimes ∷ Integral b ⇒ b → ConnectionManagerCounters → ConnectionManagerCounters #
Show ConnectionManagerCounters Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec ∷ Int → ConnectionManagerCounters → ShowS # show ∷ ConnectionManagerCounters → String # showList ∷ [ConnectionManagerCounters] → ShowS #
Eq ConnectionManagerCounters Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods (==) ∷ ConnectionManagerCounters → ConnectionManagerCounters → Bool # (/=) ∷ ConnectionManagerCounters → ConnectionManagerCounters → Bool #
Ord ConnectionManagerCounters Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods compare ∷ ConnectionManagerCounters → ConnectionManagerCounters → Ordering # (<) ∷ ConnectionManagerCounters → ConnectionManagerCounters → Bool # (<=) ∷ ConnectionManagerCounters → ConnectionManagerCounters → Bool # (>) ∷ ConnectionManagerCounters → ConnectionManagerCounters → Bool # (>=) ∷ ConnectionManagerCounters → ConnectionManagerCounters → Bool # max ∷ ConnectionManagerCounters → ConnectionManagerCounters → ConnectionManagerCounters # min ∷ ConnectionManagerCounters → ConnectionManagerCounters → ConnectionManagerCounters #

Mux types

data WithMuxMode (mode ∷ MuxMode) a b where Source #

Constructors

WithInitiatorMode ∷ a → WithMuxMode InitiatorMode a b
WithResponderMode ∷ b → WithMuxMode ResponderMode a b
WithInitiatorResponderMode ∷ a → b → WithMuxMode InitiatorResponderMode a b

withInitiatorMode ∷ HasInitiator mode ~ True ⇒ WithMuxMode mode a b → a Source #

withResponderMode ∷ HasResponder mode ~ True ⇒ WithMuxMode mode a b → b Source #

Promise

Promise interface, backed by a StrictTMVar.

Making two separate interfaces: PromiseWriter and PromiseReader allows us to make a clear distinction between consumer and producers threads.

newEmptyPromiseIO ∷ (MonadSTM m, MonadThrow (STM m)) ⇒ m (PromiseReader m a, PromiseWriter m a) Source #

newtype PromiseReader m a Source #

Constructors

PromiseReader
Fields readPromise ∷ STM m a A blocking read operation.

readPromiseIO ∷ MonadSTM m ⇒ PromiseReader m a → m a Source #

data PromiseWriter m a Source #

Constructors

PromiseWriter
Fields writePromise ∷ a → STM m () `putPromise`, is a non-blocking operation, it throws `PromiseWriterException` if it would block. forcePromise ∷ a → STM m () If the promise is empty it fills it, if it is non-empty it replaces the current value.

data PromiseWriterException Source #

Constructors

PromiseWriterBlocked

Instances

Instances details

Exception PromiseWriterException Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods toException ∷ PromiseWriterException → SomeException # fromException ∷ SomeException → Maybe PromiseWriterException # displayException ∷ PromiseWriterException → String #
Show PromiseWriterException Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec ∷ Int → PromiseWriterException → ShowS # show ∷ PromiseWriterException → String # showList ∷ [PromiseWriterException] → ShowS #

Tracing

data AssertionLocation peerAddr Source #

AssertionLocation contains constructors that situate the location of the tracing so one can be sure where the assertion came from as well as the all relevant information.

Constructors

UnregisterInboundConnection !(Maybe (ConnectionId peerAddr)) !AbstractState
RequestOutboundConnection !(Maybe (ConnectionId peerAddr)) !AbstractState
UnregisterOutboundConnection !(Maybe (ConnectionId peerAddr)) !AbstractState
PromotedToWarmRemote !(Maybe (ConnectionId peerAddr)) !AbstractState
DemotedToColdRemote !(Maybe (ConnectionId peerAddr)) !AbstractState

Instances

Instances details

Show peerAddr ⇒ Show (AssertionLocation peerAddr) Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec ∷ Int → AssertionLocation peerAddr → ShowS # show ∷ AssertionLocation peerAddr → String # showList ∷ [AssertionLocation peerAddr] → ShowS #

data ConnectionManagerTrace peerAddr handlerTrace Source #

ConnectionManagerTrace contains a hole for a trace of single connection which is filled with ConnectionHandlerTrace.

Constructors

TrIncludeConnection Provenance peerAddr
TrUnregisterConnection Provenance peerAddr
TrConnect
Fields (Maybe peerAddr) local address peerAddr remote address
TrConnectError
Fields (Maybe peerAddr) local address peerAddr remote address SomeException
TrTerminatingConnection Provenance (ConnectionId peerAddr)
TrTerminatedConnection Provenance peerAddr
TrConnectionHandler (ConnectionId peerAddr) handlerTrace
TrShutdown
TrConnectionExists Provenance peerAddr AbstractState
TrForbiddenConnection (ConnectionId peerAddr)
TrConnectionFailure (ConnectionId peerAddr)
TrConnectionNotFound Provenance peerAddr
TrForbiddenOperation peerAddr AbstractState
TrPruneConnections
Fields (Set peerAddr) pruning set Int number connections that must be pruned (Set peerAddr) choice set
TrConnectionCleanup (ConnectionId peerAddr)
TrConnectionTimeWait (ConnectionId peerAddr)
TrConnectionTimeWaitDone (ConnectionId peerAddr)
TrConnectionManagerCounters ConnectionManagerCounters
TrState (Map peerAddr AbstractState)	traced on SIGUSR1 signal, installed in `runDataDiffusion`
TrUnexpectedlyFalseAssertion (AssertionLocation peerAddr)	This case is unexpected at call site.

Instances

Instances details

(Show handlerTrace, Show peerAddr) ⇒ Show (ConnectionManagerTrace peerAddr handlerTrace) Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec ∷ Int → ConnectionManagerTrace peerAddr handlerTrace → ShowS # show ∷ ConnectionManagerTrace peerAddr handlerTrace → String # showList ∷ [ConnectionManagerTrace peerAddr handlerTrace] → ShowS #

data MaybeUnknown state Source #

A custom version of Maybe type, which allows to explicitly represent connections which are not registered by the connection manager.

Constructors

Known !state	Known connection in `state`
Race !state	There is a possible race condition between connection finalizer and either inbound or outbound connection registration. If that happens we use `Race` constructor.
Unknown	Connection is is not known to the connection manager.

Instances

Instances details

Functor MaybeUnknown Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods fmap ∷ (a → b) → MaybeUnknown a → MaybeUnknown b # (<$) ∷ a → MaybeUnknown b → MaybeUnknown a #
Show state ⇒ Show (MaybeUnknown state) Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec ∷ Int → MaybeUnknown state → ShowS # show ∷ MaybeUnknown state → String # showList ∷ [MaybeUnknown state] → ShowS #

data Transition' state Source #

Constructors

Transition
Fields fromState ∷ !state toState ∷ !state

Instances

Instances details

Functor Transition' Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods fmap ∷ (a → b) → Transition' a → Transition' b # (<$) ∷ a → Transition' b → Transition' a #
Show state ⇒ Show (Transition' state) Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec ∷ Int → Transition' state → ShowS # show ∷ Transition' state → String # showList ∷ [Transition' state] → ShowS #
Eq state ⇒ Eq (Transition' state) Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods (==) ∷ Transition' state → Transition' state → Bool # (/=) ∷ Transition' state → Transition' state → Bool #

type Transition state = Transition' (MaybeUnknown state) Source #

type AbstractTransition = Transition' AbstractState Source #

mkTransition ∷ state → state → Transition state Source #

type TransitionTrace peerAddr state = TransitionTrace' peerAddr (MaybeUnknown state) Source #

data TransitionTrace' peerAddr state Source #

Constructors

TransitionTrace
Fields ttPeerAddr ∷ peerAddr ttTransition ∷ Transition' state

Instances

Instances details

Functor (TransitionTrace' peerAddr) Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods fmap ∷ (a → b) → TransitionTrace' peerAddr a → TransitionTrace' peerAddr b # (<$) ∷ a → TransitionTrace' peerAddr b → TransitionTrace' peerAddr a #
(Show peerAddr, Show state) ⇒ Show (TransitionTrace' peerAddr state) Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec ∷ Int → TransitionTrace' peerAddr state → ShowS # show ∷ TransitionTrace' peerAddr state → String # showList ∷ [TransitionTrace' peerAddr state] → ShowS #

type AbstractTransitionTrace peerAddr = TransitionTrace' peerAddr AbstractState Source #