Safe Haskell	None
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 need to start and monitor mini-protocols through the mux interface.

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

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

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

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 :: ( forall x. m x -> m x) -> m a
}
type ConnectionHandlerFn handlerTrace socket peerAddr handle handleError version m = socket -> PromiseWriter m ( Either handleError (handle, version)) -> Tracer m handlerTrace -> ConnectionId peerAddr -> ( DiffTime -> socket -> m ( MuxBearer m)) -> MaskedAction m ()
data 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 peerAddr where
- ExceptionInHandler :: !peerAddr -> ! SomeException -> ExceptionInHandler peerAddr
data HandleErrorType
- = HandshakeFailure
- | HandshakeProtocolViolation
type PrunePolicy peerAddr stm = Map peerAddr ConnectionType -> Int -> stm ( Set peerAddr)
simplePrunePolicy :: ( Applicative stm, Ord peerAddr) => PrunePolicy peerAddr stm
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 :: m ( Map peerAddr AbstractState )
}
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 = forall 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)
- | TrImpossibleConnection ( 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 )
- | TrUnknownConnection ( ConnectionId peerAddr)
- | 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 Source # show :: AddressType -> String Source # showList :: [ AddressType ] -> ShowS Source #

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

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

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

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

data TimeoutExpired Source #

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

Constructors

Expired
Ticking

Instances

Instances details

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

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

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

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 :: ( forall x. m x -> m x) -> m a

type ConnectionHandlerFn handlerTrace socket peerAddr handle handleError version m = socket -> PromiseWriter m ( Either handleError (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.

data 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

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

data ExceptionInHandler peerAddr where Source #

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

Constructors

ExceptionInHandler :: !peerAddr -> ! SomeException -> ExceptionInHandler peerAddr

Instances

Instances details

Show peerAddr => Show ( ExceptionInHandler peerAddr) Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec :: Int -> ExceptionInHandler peerAddr -> ShowS Source # show :: ExceptionInHandler peerAddr -> String Source # showList :: [ ExceptionInHandler peerAddr] -> ShowS Source #
( Show peerAddr, Typeable peerAddr) => Exception ( ExceptionInHandler peerAddr) Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods toException :: ExceptionInHandler peerAddr -> SomeException Source # fromException :: SomeException -> Maybe ( ExceptionInHandler peerAddr) Source # displayException :: ExceptionInHandler peerAddr -> String Source #

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.

Prune Policy

type PrunePolicy peerAddr stm = Map peerAddr ConnectionType -> Int -> stm ( 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 :: ( Applicative stm, Ord peerAddr) => PrunePolicy peerAddr stm 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 :: m ( Map peerAddr AbstractState )

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 Source # (<$) :: a -> OperationResult b -> OperationResult a Source #
Show a => Show ( OperationResult a) Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec :: Int -> OperationResult a -> ShowS Source # show :: OperationResult a -> String Source # showList :: [ OperationResult a] -> ShowS Source #

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 Source # show :: DemotedToColdRemoteTr -> String Source # showList :: [ DemotedToColdRemoteTr ] -> ShowS Source #

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 successul.

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 => Show ( ConnectionManagerError peerAddr) Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec :: Int -> ConnectionManagerError peerAddr -> ShowS Source # show :: ConnectionManagerError peerAddr -> String Source # showList :: [ ConnectionManagerError peerAddr] -> ShowS Source #
( Show peerAddr, Typeable peerAddr) => Exception ( ConnectionManagerError peerAddr) Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods toException :: ConnectionManagerError peerAddr -> SomeException Source # fromException :: SomeException -> Maybe ( ConnectionManagerError peerAddr) Source # displayException :: ConnectionManagerError peerAddr -> String Source #

data SomeConnectionManagerError Source #

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

Constructors

forall addr.( Typeable addr, Show addr) => SomeConnectionManagerError !( ConnectionManagerError addr)

Instances

Instances details

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

data AbstractState Source #

Useful for tracing and error messages.

Constructors

UnknownConnectionSt
ReservedOutboundSt
UnnegotiatedSt ! Provenance
InboundIdleSt ! DataFlow
InboundSt ! DataFlow
OutboundUniSt
OutboundDupSt ! TimeoutExpired
OutboundIdleSt ! DataFlow
DuplexSt
WaitRemoteIdleSt
TerminatingSt
TerminatedSt

Instances

Instances details

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

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

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

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

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

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 Source # show :: AssertionLocation peerAddr -> String Source # showList :: [ AssertionLocation peerAddr] -> ShowS Source #

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)
TrImpossibleConnection ( ConnectionId peerAddr)
TrConnectionFailure ( ConnectionId peerAddr)
TrConnectionNotFound Provenance peerAddr
TrForbiddenOperation peerAddr AbstractState
TrPruneConnections
Fields ( Set peerAddr) prunning set Int number connections that must be prunned ( 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`
TrUnknownConnection ( ConnectionId peerAddr)
TrUnexpectedlyFalseAssertion ( AssertionLocation peerAddr)	This case is unexpected at call site.

Instances

Instances details

( Show peerAddr, Show handlerTrace) => Show ( ConnectionManagerTrace peerAddr handlerTrace) Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec :: Int -> ConnectionManagerTrace peerAddr handlerTrace -> ShowS Source # show :: ConnectionManagerTrace peerAddr handlerTrace -> String Source # showList :: [ ConnectionManagerTrace peerAddr handlerTrace] -> ShowS Source #

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 Source # (<$) :: a -> MaybeUnknown b -> MaybeUnknown a Source #
Show state => Show ( MaybeUnknown state) Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec :: Int -> MaybeUnknown state -> ShowS Source # show :: MaybeUnknown state -> String Source # showList :: [ MaybeUnknown state] -> ShowS Source #

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 Source # (<$) :: a -> Transition' b -> Transition' a Source #
Eq state => Eq ( Transition' state) Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods (==) :: Transition' state -> Transition' state -> Bool Source # (/=) :: Transition' state -> Transition' state -> Bool Source #
Show state => Show ( Transition' state) Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec :: Int -> Transition' state -> ShowS Source # show :: Transition' state -> String Source # showList :: [ Transition' state] -> ShowS Source #

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 Source # (<$) :: a -> TransitionTrace' peerAddr b -> TransitionTrace' peerAddr a Source #
( Show peerAddr, Show state) => Show ( TransitionTrace' peerAddr state) Source #
Instance details Defined in Ouroboros.Network.ConnectionManager.Types Methods showsPrec :: Int -> TransitionTrace' peerAddr state -> ShowS Source # show :: TransitionTrace' peerAddr state -> String Source # showList :: [ TransitionTrace' peerAddr state] -> ShowS Source #

type AbstractTransitionTrace peerAddr = TransitionTrace' peerAddr AbstractState Source #