Copyright	(c) simplex.chat
License	AGPL-3
Maintainer	chat@simplex.chat
Stability	experimental
Portability	non-portable
Safe Haskell	Safe-Inferred
Language	Haskell2010

Simplex.Messaging.Client

Contents

Connect (disconnect) client to (from) SMP server
SMP protocol command functions
Supporting types and client configuration
For testing
For debugging

Description

This module provides a functional client API for SMP protocol.

See https://github.com/simplex-chat/simplexmq/blob/master/protocol/simplex-messaging.md

Synopsis

type TransportSession msg = (UserId, ProtoServer msg, Maybe ByteString)
type SMPTransportSession = TransportSession BrokerMsg
data ProtocolClient v err msg
type SMPClient = ProtocolClient SMPVersion ErrorType BrokerMsg
data ProxiedRelay = ProxiedRelay {
- prSessionId :: SessionId
- prVersion :: VersionSMP
- prBasicAuth :: Maybe BasicAuth
- prServerKey :: PublicKeyX25519
}
getProtocolClient :: forall v err msg. Protocol v err msg => TVar ChaChaDRG -> NetworkRequestMode -> TransportSession msg -> ProtocolClientConfig v -> [HostName] -> Maybe (TBQueue (ServerTransmissionBatch v err msg)) -> UTCTime -> (ProtocolClient v err msg -> IO ()) -> IO (Either (ProtocolClientError err) (ProtocolClient v err msg))
closeProtocolClient :: ProtocolClient v err msg -> IO ()
protocolClientServer :: ProtocolTypeI (ProtoType msg) => ProtocolClient v err msg -> String
protocolClientServer' :: ProtocolClient v err msg -> ProtoServer msg
transportHost' :: ProtocolClient v err msg -> TransportHost
transportSession' :: ProtocolClient v err msg -> TransportSession msg
useWebPort :: NetworkConfig -> [HostName] -> ProtocolServer p -> Bool
isPresetDomain :: [HostName] -> TransportHost -> Bool
createSMPQueue :: SMPClient -> NetworkRequestMode -> Maybe CbNonce -> AAuthKeyPair -> RcvPublicDhKey -> Maybe BasicAuth -> SubscriptionMode -> QueueReqData -> Maybe NewNtfCreds -> ExceptT SMPClientError IO QueueIdsKeys
subscribeSMPQueue :: SMPClient -> RcvPrivateAuthKey -> RecipientId -> ExceptT SMPClientError IO (Maybe ServiceId)
subscribeSMPQueues :: SMPClient -> NonEmpty (RecipientId, RcvPrivateAuthKey) -> IO (NonEmpty (Either SMPClientError (Maybe ServiceId)))
streamSubscribeSMPQueues :: SMPClient -> NonEmpty (RecipientId, RcvPrivateAuthKey) -> ([(RecipientId, Either SMPClientError (Maybe ServiceId))] -> IO ()) -> IO ()
getSMPMessage :: SMPClient -> RcvPrivateAuthKey -> RecipientId -> ExceptT SMPClientError IO (Maybe RcvMessage)
subscribeSMPQueueNotifications :: SMPClient -> NtfPrivateAuthKey -> NotifierId -> ExceptT SMPClientError IO (Maybe ServiceId)
subscribeSMPQueuesNtfs :: SMPClient -> NonEmpty (NotifierId, NtfPrivateAuthKey) -> IO (NonEmpty (Either SMPClientError (Maybe ServiceId)))
subscribeService :: forall p. (PartyI p, ServiceParty p) => SMPClient -> SParty p -> ExceptT SMPClientError IO Int64
smpClientService :: SMPClient -> Maybe THClientService
secureSMPQueue :: SMPClient -> NetworkRequestMode -> RcvPrivateAuthKey -> RecipientId -> SndPublicAuthKey -> ExceptT SMPClientError IO ()
secureSndSMPQueue :: SMPClient -> NetworkRequestMode -> SndPrivateAuthKey -> SenderId -> ExceptT SMPClientError IO ()
proxySecureSndSMPQueue :: SMPClient -> NetworkRequestMode -> ProxiedRelay -> SndPrivateAuthKey -> SenderId -> ExceptT SMPClientError IO (Either ProxyClientError ())
addSMPQueueLink :: SMPClient -> NetworkRequestMode -> RcvPrivateAuthKey -> RecipientId -> LinkId -> QueueLinkData -> ExceptT SMPClientError IO ()
deleteSMPQueueLink :: SMPClient -> NetworkRequestMode -> RcvPrivateAuthKey -> RecipientId -> ExceptT SMPClientError IO ()
secureGetSMPQueueLink :: SMPClient -> NetworkRequestMode -> SndPrivateAuthKey -> LinkId -> ExceptT SMPClientError IO (SenderId, QueueLinkData)
proxySecureGetSMPQueueLink :: SMPClient -> NetworkRequestMode -> ProxiedRelay -> SndPrivateAuthKey -> LinkId -> ExceptT SMPClientError IO (Either ProxyClientError (SenderId, QueueLinkData))
getSMPQueueLink :: SMPClient -> NetworkRequestMode -> LinkId -> ExceptT SMPClientError IO (SenderId, QueueLinkData)
proxyGetSMPQueueLink :: SMPClient -> NetworkRequestMode -> ProxiedRelay -> LinkId -> ExceptT SMPClientError IO (Either ProxyClientError (SenderId, QueueLinkData))
enableSMPQueueNotifications :: SMPClient -> RcvPrivateAuthKey -> RecipientId -> NtfPublicAuthKey -> RcvNtfPublicDhKey -> ExceptT SMPClientError IO (NotifierId, RcvNtfPublicDhKey)
disableSMPQueueNotifications :: SMPClient -> RcvPrivateAuthKey -> RecipientId -> ExceptT SMPClientError IO ()
enableSMPQueuesNtfs :: SMPClient -> NonEmpty (RecipientId, RcvPrivateAuthKey, NtfPublicAuthKey, RcvNtfPublicDhKey) -> IO (NonEmpty (Either SMPClientError (NotifierId, RcvNtfPublicDhKey)))
disableSMPQueuesNtfs :: SMPClient -> NonEmpty (RecipientId, RcvPrivateAuthKey) -> IO (NonEmpty (Either SMPClientError ()))
sendSMPMessage :: SMPClient -> NetworkRequestMode -> Maybe SndPrivateAuthKey -> SenderId -> MsgFlags -> MsgBody -> ExceptT SMPClientError IO ()
ackSMPMessage :: SMPClient -> RcvPrivateAuthKey -> QueueId -> MsgId -> ExceptT SMPClientError IO ()
suspendSMPQueue :: SMPClient -> NetworkRequestMode -> RcvPrivateAuthKey -> QueueId -> ExceptT SMPClientError IO ()
deleteSMPQueue :: SMPClient -> NetworkRequestMode -> RcvPrivateAuthKey -> RecipientId -> ExceptT SMPClientError IO ()
deleteSMPQueues :: SMPClient -> NetworkRequestMode -> NonEmpty (RecipientId, RcvPrivateAuthKey) -> IO (NonEmpty (Either SMPClientError ()))
connectSMPProxiedRelay :: SMPClient -> NetworkRequestMode -> SMPServer -> Maybe BasicAuth -> ExceptT SMPClientError IO ProxiedRelay
proxySMPMessage :: SMPClient -> NetworkRequestMode -> ProxiedRelay -> Maybe SndPrivateAuthKey -> SenderId -> MsgFlags -> MsgBody -> ExceptT SMPClientError IO (Either ProxyClientError ())
forwardSMPTransmission :: SMPClient -> CorrId -> VersionSMP -> PublicKeyX25519 -> EncTransmission -> ExceptT SMPClientError IO EncResponse
getSMPQueueInfo :: SMPClient -> NetworkRequestMode -> APrivateAuthKey -> QueueId -> ExceptT SMPClientError IO QueueInfo
sendProtocolCommand :: forall v err msg. Protocol v err msg => ProtocolClient v err msg -> NetworkRequestMode -> Maybe APrivateAuthKey -> EntityId -> ProtoCommand msg -> ExceptT (ProtocolClientError err) IO msg
sendProtocolCommands :: forall v err msg. Protocol v err msg => ProtocolClient v err msg -> NetworkRequestMode -> NonEmpty (ClientCommand msg) -> IO (NonEmpty (Response err msg))
data ProtocolClientError err
- = PCEProtocolError err
- | PCEResponseError err
- | PCEUnexpectedResponse ByteString
- | PCEResponseTimeout
- | PCENetworkError NetworkError
- | PCEIncompatibleHost
- | PCEServiceUnavailable
- | PCETransportError TransportError
- | PCECryptoError CryptoError
- | PCEIOError IOException
type SMPClientError = ProtocolClientError ErrorType
data ProxyClientError
- = ProxyProtocolError {
  - protocolErr :: ErrorType
  }
- | ProxyUnexpectedResponse {
  - responseStr :: String
  }
- | ProxyResponseError {
  - responseErr :: ErrorType
  }
data Response err msg = Response {
- entityId :: EntityId
- response :: Either (ProtocolClientError err) msg
}
unexpectedResponse :: Show r => r -> ProtocolClientError err
data ProtocolClientConfig v = ProtocolClientConfig {
- qSize :: Natural
- defaultTransport :: (ServiceName, ATransport 'TClient)
- networkConfig :: NetworkConfig
- clientALPN :: Maybe [ALPN]
- serviceCredentials :: Maybe ServiceCredentials
- serverVRange :: VersionRange v
- agreeSecret :: Bool
- proxyServer :: Bool
- useSNI :: Bool
}
data NetworkConfig = NetworkConfig {
- socksProxy :: Maybe SocksProxyWithAuth
- socksMode :: SocksMode
- hostMode :: HostMode
- requiredHostMode :: Bool
- sessionMode :: TransportSessionMode
- smpProxyMode :: SMPProxyMode
- smpProxyFallback :: SMPProxyFallback
- smpWebPortServers :: SMPWebPortServers
- tcpConnectTimeout :: NetworkTimeout
- tcpTimeout :: NetworkTimeout
- tcpTimeoutPerKb :: Int64
- rcvConcurrency :: Int
- tcpKeepAlive :: Maybe KeepAliveOpts
- smpPingInterval :: Int64
- smpPingCount :: Int
- logTLSErrors :: Bool
}
data NetworkTimeout = NetworkTimeout {
- backgroundTimeout :: Int
- interactiveTimeout :: Int
}
data NetworkRequestMode
- = NRMBackground
- | NRMInteractive' {
  - retryCount :: Int
  }
pattern NRMInteractive :: NetworkRequestMode
data TransportSessionMode
- = TSMUser
- | TSMSession
- | TSMServer
- | TSMEntity
data HostMode
- = HMOnionViaSocks
- | HMOnion
- | HMPublic
data SocksMode
- = SMAlways
- | SMOnion
data SMPProxyMode
- = SPMAlways
- | SPMUnknown
- | SPMUnprotected
- | SPMNever
data SMPProxyFallback
- = SPFAllow
- | SPFAllowProtected
- | SPFProhibit
data SMPWebPortServers
- = SWPAll
- | SWPPreset
- | SWPOff
netTimeoutInt :: NetworkTimeout -> NetworkRequestMode -> Int
defaultClientConfig :: Maybe [ALPN] -> Bool -> VersionRange v -> ProtocolClientConfig v
defaultSMPClientConfig :: ProtocolClientConfig SMPVersion
defaultNetworkConfig :: NetworkConfig
transportClientConfig :: NetworkConfig -> NetworkRequestMode -> TransportHost -> Bool -> Maybe [ALPN] -> TransportClientConfig
clientSocksCredentials :: ProtocolTypeI (ProtoType msg) => NetworkConfig -> UTCTime -> TransportSession msg -> Maybe SocksCredentials
chooseTransportHost :: NetworkConfig -> NonEmpty TransportHost -> Either (ProtocolClientError err) TransportHost
temporaryClientError :: ProtocolClientError err -> Bool
smpClientServiceError :: SMPClientError -> Bool
smpProxyError :: SMPClientError -> ErrorType
smpErrorClientNotice :: SMPClientError -> Maybe (Maybe ClientNotice)
textToHostMode :: Text -> Either String HostMode
type ServerTransmissionBatch v err msg = (TransportSession msg, Version v, SessionId, NonEmpty (EntityId, ServerTransmission err msg))
data ServerTransmission err msg
- = STEvent (Either (ProtocolClientError err) msg)
- | STResponse (ProtoCommand msg) (Either (ProtocolClientError err) msg)
- | STUnexpectedError (ProtocolClientError err)
type ClientCommand msg = (EntityId, Maybe APrivateAuthKey, ProtoCommand msg)
type PCTransmission err msg = (Either TransportError SentRawTransmission, Request err msg)
mkTransmission :: Protocol v err msg => ProtocolClient v err msg -> ClientCommand msg -> IO (PCTransmission err msg)
authTransmission :: Maybe (THandleAuth 'TClient) -> Bool -> Maybe APrivateAuthKey -> CbNonce -> ByteString -> Either TransportError (Maybe TAuthorizations)
smpClientStub :: TVar ChaChaDRG -> ByteString -> VersionSMP -> Maybe (THandleAuth 'TClient) -> IO SMPClient
data TBQueueInfo = TBQueueInfo {
- qLength :: Int
- qFull :: Bool
}
getTBQueueInfo :: TBQueue a -> STM TBQueueInfo
getProtocolClientQueuesInfo :: ProtocolClient v err msg -> IO (TBQueueInfo, TBQueueInfo)
nonBlockingWriteTBQueue :: TBQueue a -> a -> IO ()

Connect (disconnect) client to (from) SMP server

type TransportSession msg = (UserId, ProtoServer msg, Maybe ByteString) Source #

Transport session key - includes entity ID if `sessionMode = TSMEntity`. Please note that for SMP connection ID is used as entity ID, not queue ID.

type SMPTransportSession = TransportSession BrokerMsg Source #

data ProtocolClient v err msg Source #

SMPClient is a handle used to send commands to a specific SMP server.

Use getSMPClient to connect to an SMP server and create a client handle.

type SMPClient = ProtocolClient SMPVersion ErrorType BrokerMsg Source #

data ProxiedRelay Source #

Constructors

ProxiedRelay
Fields prSessionId :: SessionId prVersion :: VersionSMP prBasicAuth :: Maybe BasicAuth prServerKey :: PublicKeyX25519

getProtocolClient :: forall v err msg. Protocol v err msg => TVar ChaChaDRG -> NetworkRequestMode -> TransportSession msg -> ProtocolClientConfig v -> [HostName] -> Maybe (TBQueue (ServerTransmissionBatch v err msg)) -> UTCTime -> (ProtocolClient v err msg -> IO ()) -> IO (Either (ProtocolClientError err) (ProtocolClient v err msg)) Source #

Connects to ProtocolServer using passed client configuration and queue for messages and notifications.

A single queue can be used for multiple SMPClient instances, as SMPServerTransmission includes server information.

closeProtocolClient :: ProtocolClient v err msg -> IO () Source #

Disconnects client from the server and terminates client threads.

protocolClientServer :: ProtocolTypeI (ProtoType msg) => ProtocolClient v err msg -> String Source #

protocolClientServer' :: ProtocolClient v err msg -> ProtoServer msg Source #

transportHost' :: ProtocolClient v err msg -> TransportHost Source #

transportSession' :: ProtocolClient v err msg -> TransportSession msg Source #

useWebPort :: NetworkConfig -> [HostName] -> ProtocolServer p -> Bool Source #

isPresetDomain :: [HostName] -> TransportHost -> Bool Source #

SMP protocol command functions

createSMPQueue :: SMPClient -> NetworkRequestMode -> Maybe CbNonce -> AAuthKeyPair -> RcvPublicDhKey -> Maybe BasicAuth -> SubscriptionMode -> QueueReqData -> Maybe NewNtfCreds -> ExceptT SMPClientError IO QueueIdsKeys Source #

Create a new SMP queue.

https://github.com/simplex-chat/simplexmq/blob/master/protocol/simplex-messaging.md#create-queue-command

subscribeSMPQueue :: SMPClient -> RcvPrivateAuthKey -> RecipientId -> ExceptT SMPClientError IO (Maybe ServiceId) Source #

Subscribe to the SMP queue.

https://github.com/simplex-chat/simplexmq/blob/master/protocol/simplex-messaging.md#subscribe-to-queue This command is always sent in background request mode

subscribeSMPQueues :: SMPClient -> NonEmpty (RecipientId, RcvPrivateAuthKey) -> IO (NonEmpty (Either SMPClientError (Maybe ServiceId))) Source #

Subscribe to multiple SMP queues batching commands if supported. This command is always sent in background request mode

streamSubscribeSMPQueues :: SMPClient -> NonEmpty (RecipientId, RcvPrivateAuthKey) -> ([(RecipientId, Either SMPClientError (Maybe ServiceId))] -> IO ()) -> IO () Source #

getSMPMessage :: SMPClient -> RcvPrivateAuthKey -> RecipientId -> ExceptT SMPClientError IO (Maybe RcvMessage) Source #

Get message from SMP queue. The server returns ERR PROHIBITED if a client uses SUB and GET via the same transport connection for the same queue

https://github.covm/simplex-chat/simplexmq/blob/master/protocol/simplex-messaging.md#receive-a-message-from-the-queue This command is always sent in interactive request mode, as NSE has limited time

subscribeSMPQueueNotifications :: SMPClient -> NtfPrivateAuthKey -> NotifierId -> ExceptT SMPClientError IO (Maybe ServiceId) Source #

Subscribe to the SMP queue notifications.

https://github.com/simplex-chat/simplexmq/blob/master/protocol/simplex-messaging.md#subscribe-to-queue-notifications This command is always sent in background request mode

subscribeSMPQueuesNtfs :: SMPClient -> NonEmpty (NotifierId, NtfPrivateAuthKey) -> IO (NonEmpty (Either SMPClientError (Maybe ServiceId))) Source #

Subscribe to multiple SMP queues notifications batching commands if supported. This command is always sent in background request mode

subscribeService :: forall p. (PartyI p, ServiceParty p) => SMPClient -> SParty p -> ExceptT SMPClientError IO Int64 Source #

smpClientService :: SMPClient -> Maybe THClientService Source #

secureSMPQueue :: SMPClient -> NetworkRequestMode -> RcvPrivateAuthKey -> RecipientId -> SndPublicAuthKey -> ExceptT SMPClientError IO () Source #

Secure the SMP queue by adding a sender public key.

https://github.com/simplex-chat/simplexmq/blob/master/protocol/simplex-messaging.md#secure-queue-command

secureSndSMPQueue :: SMPClient -> NetworkRequestMode -> SndPrivateAuthKey -> SenderId -> ExceptT SMPClientError IO () Source #

Secure the SMP queue via sender queue ID.

proxySecureSndSMPQueue :: SMPClient -> NetworkRequestMode -> ProxiedRelay -> SndPrivateAuthKey -> SenderId -> ExceptT SMPClientError IO (Either ProxyClientError ()) Source #

addSMPQueueLink :: SMPClient -> NetworkRequestMode -> RcvPrivateAuthKey -> RecipientId -> LinkId -> QueueLinkData -> ExceptT SMPClientError IO () Source #

Add or update date for queue link

deleteSMPQueueLink :: SMPClient -> NetworkRequestMode -> RcvPrivateAuthKey -> RecipientId -> ExceptT SMPClientError IO () Source #

Delete queue link

secureGetSMPQueueLink :: SMPClient -> NetworkRequestMode -> SndPrivateAuthKey -> LinkId -> ExceptT SMPClientError IO (SenderId, QueueLinkData) Source #

Get 1-time inviation SMP queue link data and secure the queue via queue link ID.

proxySecureGetSMPQueueLink :: SMPClient -> NetworkRequestMode -> ProxiedRelay -> SndPrivateAuthKey -> LinkId -> ExceptT SMPClientError IO (Either ProxyClientError (SenderId, QueueLinkData)) Source #

getSMPQueueLink :: SMPClient -> NetworkRequestMode -> LinkId -> ExceptT SMPClientError IO (SenderId, QueueLinkData) Source #

Get contact address SMP queue link data.

proxyGetSMPQueueLink :: SMPClient -> NetworkRequestMode -> ProxiedRelay -> LinkId -> ExceptT SMPClientError IO (Either ProxyClientError (SenderId, QueueLinkData)) Source #

enableSMPQueueNotifications :: SMPClient -> RcvPrivateAuthKey -> RecipientId -> NtfPublicAuthKey -> RcvNtfPublicDhKey -> ExceptT SMPClientError IO (NotifierId, RcvNtfPublicDhKey) Source #

Enable notifications for the queue for push notifications server.

https://github.com/simplex-chat/simplexmq/blob/master/protocol/simplex-messaging.md#enable-notifications-command

disableSMPQueueNotifications :: SMPClient -> RcvPrivateAuthKey -> RecipientId -> ExceptT SMPClientError IO () Source #

Disable notifications for the queue for push notifications server.

https://github.com/simplex-chat/simplexmq/blob/master/protocol/simplex-messaging.md#disable-notifications-command This command is always sent in background request mode

enableSMPQueuesNtfs :: SMPClient -> NonEmpty (RecipientId, RcvPrivateAuthKey, NtfPublicAuthKey, RcvNtfPublicDhKey) -> IO (NonEmpty (Either SMPClientError (NotifierId, RcvNtfPublicDhKey))) Source #

Enable notifications for the multiple queues for push notifications server. This command is always sent in background request mode

disableSMPQueuesNtfs :: SMPClient -> NonEmpty (RecipientId, RcvPrivateAuthKey) -> IO (NonEmpty (Either SMPClientError ())) Source #

Disable notifications for multiple queues for push notifications server. This command is always sent in background request mode

sendSMPMessage :: SMPClient -> NetworkRequestMode -> Maybe SndPrivateAuthKey -> SenderId -> MsgFlags -> MsgBody -> ExceptT SMPClientError IO () Source #

Send SMP message.

https://github.com/simplex-chat/simplexmq/blob/master/protocol/simplex-messaging.md#send-message

ackSMPMessage :: SMPClient -> RcvPrivateAuthKey -> QueueId -> MsgId -> ExceptT SMPClientError IO () Source #

Acknowledge message delivery (server deletes the message).

https://github.com/simplex-chat/simplexmq/blob/master/protocol/simplex-messaging.md#acknowledge-message-delivery This command is always sent in background request mode

suspendSMPQueue :: SMPClient -> NetworkRequestMode -> RcvPrivateAuthKey -> QueueId -> ExceptT SMPClientError IO () Source #

Irreversibly suspend SMP queue. The existing messages from the queue will still be delivered.

https://github.com/simplex-chat/simplexmq/blob/master/protocol/simplex-messaging.md#suspend-queue

deleteSMPQueue :: SMPClient -> NetworkRequestMode -> RcvPrivateAuthKey -> RecipientId -> ExceptT SMPClientError IO () Source #

Irreversibly delete SMP queue and all messages in it.

https://github.com/simplex-chat/simplexmq/blob/master/protocol/simplex-messaging.md#delete-queue

deleteSMPQueues :: SMPClient -> NetworkRequestMode -> NonEmpty (RecipientId, RcvPrivateAuthKey) -> IO (NonEmpty (Either SMPClientError ())) Source #

Delete multiple SMP queues batching commands if supported.

connectSMPProxiedRelay :: SMPClient -> NetworkRequestMode -> SMPServer -> Maybe BasicAuth -> ExceptT SMPClientError IO ProxiedRelay Source #

proxySMPMessage :: SMPClient -> NetworkRequestMode -> ProxiedRelay -> Maybe SndPrivateAuthKey -> SenderId -> MsgFlags -> MsgBody -> ExceptT SMPClientError IO (Either ProxyClientError ()) Source #

forwardSMPTransmission :: SMPClient -> CorrId -> VersionSMP -> PublicKeyX25519 -> EncTransmission -> ExceptT SMPClientError IO EncResponse Source #

getSMPQueueInfo :: SMPClient -> NetworkRequestMode -> APrivateAuthKey -> QueueId -> ExceptT SMPClientError IO QueueInfo Source #

sendProtocolCommand :: forall v err msg. Protocol v err msg => ProtocolClient v err msg -> NetworkRequestMode -> Maybe APrivateAuthKey -> EntityId -> ProtoCommand msg -> ExceptT (ProtocolClientError err) IO msg Source #

Send Protocol command

sendProtocolCommands :: forall v err msg. Protocol v err msg => ProtocolClient v err msg -> NetworkRequestMode -> NonEmpty (ClientCommand msg) -> IO (NonEmpty (Response err msg)) Source #

Send multiple commands with batching and collect responses

Supporting types and client configuration

data ProtocolClientError err Source #

SMP client error type.

Constructors

PCEProtocolError err	Correctly parsed SMP server ERR response. This error is forwarded to the agent client as `ERR SMP err`.
PCEResponseError err	Invalid server response that failed to parse. Forwarded to the agent client as `ERR BROKER RESPONSE`.
PCEUnexpectedResponse ByteString	Different response from what is expected to a certain SMP command, e.g. server should respond `IDS` or `ERR` to `NEW` command, other responses would result in this error. Forwarded to the agent client as `ERR BROKER UNEXPECTED`.
PCEResponseTimeout	Used for TCP connection and command response timeouts. Forwarded to the agent client as `ERR BROKER TIMEOUT`.
PCENetworkError NetworkError	Failure to establish TCP connection. Forwarded to the agent client as `ERR BROKER NETWORK`.
PCEIncompatibleHost	No host compatible with network configuration
PCEServiceUnavailable	Service is unavailable for command that requires service connection
PCETransportError TransportError	TCP transport handshake or some other transport error. Forwarded to the agent client as `ERR BROKER TRANSPORT e`.
PCECryptoError CryptoError	Error when cryptographically "signing" the command or when initializing crypto_box.
PCEIOError IOException	IO Error

Instances

Instances details

(Typeable err, Show err) => Exception (ProtocolClientError err) Source #
Instance details Defined in Simplex.Messaging.Client Methods toException :: ProtocolClientError err -> SomeException fromException :: SomeException -> Maybe (ProtocolClientError err) displayException :: ProtocolClientError err -> String
Show err => Show (ProtocolClientError err) Source #
Instance details Defined in Simplex.Messaging.Client Methods showsPrec :: Int -> ProtocolClientError err -> ShowS show :: ProtocolClientError err -> String showList :: [ProtocolClientError err] -> ShowS
Eq err => Eq (ProtocolClientError err) Source #
Instance details Defined in Simplex.Messaging.Client Methods (==) :: ProtocolClientError err -> ProtocolClientError err -> Bool (/=) :: ProtocolClientError err -> ProtocolClientError err -> Bool

type SMPClientError = ProtocolClientError ErrorType Source #

data ProxyClientError Source #

Constructors

ProxyProtocolError	protocol error response from proxy
Fields protocolErr :: ErrorType
ProxyUnexpectedResponse	unexpexted response
Fields responseStr :: String
ProxyResponseError	error between proxy and server
Fields responseErr :: ErrorType

Instances

Instances details

FromJSON ProxyClientError Source #
Instance details Defined in Simplex.Messaging.Client Methods parseJSON :: Value -> Parser ProxyClientError parseJSONList :: Value -> Parser [ProxyClientError] omittedField :: Maybe ProxyClientError
ToJSON ProxyClientError Source #
Instance details Defined in Simplex.Messaging.Client Methods toJSON :: ProxyClientError -> Value toEncoding :: ProxyClientError -> Encoding toJSONList :: [ProxyClientError] -> Value toEncodingList :: [ProxyClientError] -> Encoding omitField :: ProxyClientError -> Bool
Exception ProxyClientError Source #
Instance details Defined in Simplex.Messaging.Client Methods toException :: ProxyClientError -> SomeException fromException :: SomeException -> Maybe ProxyClientError displayException :: ProxyClientError -> String
Show ProxyClientError Source #
Instance details Defined in Simplex.Messaging.Client Methods showsPrec :: Int -> ProxyClientError -> ShowS show :: ProxyClientError -> String showList :: [ProxyClientError] -> ShowS
Eq ProxyClientError Source #
Instance details Defined in Simplex.Messaging.Client Methods (==) :: ProxyClientError -> ProxyClientError -> Bool (/=) :: ProxyClientError -> ProxyClientError -> Bool
StrEncoding ProxyClientError Source #
Instance details Defined in Simplex.Messaging.Client Methods strEncode :: ProxyClientError -> ByteString Source # strDecode :: ByteString -> Either String ProxyClientError Source # strP :: Parser ProxyClientError Source #

data Response err msg Source #

Constructors

Response
Fields entityId :: EntityId response :: Either (ProtocolClientError err) msg

unexpectedResponse :: Show r => r -> ProtocolClientError err Source #

data ProtocolClientConfig v Source #

protocol client configuration.

Constructors

ProtocolClientConfig

Fields

qSize :: Natural
size of TBQueue to use for server commands and responses
defaultTransport :: (ServiceName, ATransport 'TClient)
default server port if port is not specified in ProtocolServer
networkConfig :: NetworkConfig
network configuration
clientALPN :: Maybe [ALPN]
serviceCredentials :: Maybe ServiceCredentials
serverVRange :: VersionRange v
client-server protocol version range
agreeSecret :: Bool
agree shared session secret (used in SMP proxy for additional encryption layer)
proxyServer :: Bool
Whether connecting client is a proxy server. See comment in ClientHandshake
useSNI :: Bool
send SNI to server, False for SMP

data NetworkConfig Source #

network configuration for the client

Constructors

NetworkConfig

Fields

socksProxy :: Maybe SocksProxyWithAuth
use SOCKS5 proxy
socksMode :: SocksMode
when to use SOCKS proxy
hostMode :: HostMode
determines critera which host is chosen from the list
requiredHostMode :: Bool
if above criteria is not met, if the below setting is True return error, otherwise use the first host
sessionMode :: TransportSessionMode
transport sessions are created per user or per entity
smpProxyMode :: SMPProxyMode
SMP proxy mode
smpProxyFallback :: SMPProxyFallback
Fallback to direct connection when destination SMP relay does not support SMP proxy protocol extensions
smpWebPortServers :: SMPWebPortServers
use web port 443 for SMP protocol
tcpConnectTimeout :: NetworkTimeout
timeout for the initial client TCP/TLS connection (microseconds)
tcpTimeout :: NetworkTimeout
timeout of protocol commands (microseconds)
tcpTimeoutPerKb :: Int64
additional timeout per kilobyte (1024 bytes) to be sent
rcvConcurrency :: Int
break response timeouts into groups, so later responses get later deadlines
tcpKeepAlive :: Maybe KeepAliveOpts
TCP keep-alive options, Nothing to skip enabling keep-alive
smpPingInterval :: Int64
period for SMP ping commands (microseconds, 0 to disable)
smpPingCount :: Int
the count of timeout errors after which SMP client terminates (and will be reconnected), 0 to disable
logTLSErrors :: Bool

Instances

Instances details

FromJSON NetworkConfig Source #
Instance details Defined in Simplex.Messaging.Client Methods parseJSON :: Value -> Parser NetworkConfig parseJSONList :: Value -> Parser [NetworkConfig] omittedField :: Maybe NetworkConfig
ToJSON NetworkConfig Source #
Instance details Defined in Simplex.Messaging.Client Methods toJSON :: NetworkConfig -> Value toEncoding :: NetworkConfig -> Encoding toJSONList :: [NetworkConfig] -> Value toEncodingList :: [NetworkConfig] -> Encoding omitField :: NetworkConfig -> Bool
Show NetworkConfig Source #
Instance details Defined in Simplex.Messaging.Client Methods showsPrec :: Int -> NetworkConfig -> ShowS show :: NetworkConfig -> String showList :: [NetworkConfig] -> ShowS
Eq NetworkConfig Source #
Instance details Defined in Simplex.Messaging.Client Methods (==) :: NetworkConfig -> NetworkConfig -> Bool (/=) :: NetworkConfig -> NetworkConfig -> Bool

data NetworkTimeout Source #

Constructors

NetworkTimeout
Fields backgroundTimeout :: Int interactiveTimeout :: Int

Instances

Instances details

FromJSON NetworkTimeout Source #
Instance details Defined in Simplex.Messaging.Client Methods parseJSON :: Value -> Parser NetworkTimeout parseJSONList :: Value -> Parser [NetworkTimeout] omittedField :: Maybe NetworkTimeout
ToJSON NetworkTimeout Source #
Instance details Defined in Simplex.Messaging.Client Methods toJSON :: NetworkTimeout -> Value toEncoding :: NetworkTimeout -> Encoding toJSONList :: [NetworkTimeout] -> Value toEncodingList :: [NetworkTimeout] -> Encoding omitField :: NetworkTimeout -> Bool
Show NetworkTimeout Source #
Instance details Defined in Simplex.Messaging.Client Methods showsPrec :: Int -> NetworkTimeout -> ShowS show :: NetworkTimeout -> String showList :: [NetworkTimeout] -> ShowS
Eq NetworkTimeout Source #
Instance details Defined in Simplex.Messaging.Client Methods (==) :: NetworkTimeout -> NetworkTimeout -> Bool (/=) :: NetworkTimeout -> NetworkTimeout -> Bool

data NetworkRequestMode Source #

Constructors

NRMBackground
NRMInteractive'
Fields retryCount :: Int

pattern NRMInteractive :: NetworkRequestMode Source #

data TransportSessionMode Source #

Constructors

TSMUser
TSMSession
TSMServer
TSMEntity

Instances

Instances details

FromJSON TransportSessionMode Source #
Instance details Defined in Simplex.Messaging.Client Methods parseJSON :: Value -> Parser TransportSessionMode parseJSONList :: Value -> Parser [TransportSessionMode] omittedField :: Maybe TransportSessionMode
ToJSON TransportSessionMode Source #
Instance details Defined in Simplex.Messaging.Client Methods toJSON :: TransportSessionMode -> Value toEncoding :: TransportSessionMode -> Encoding toJSONList :: [TransportSessionMode] -> Value toEncodingList :: [TransportSessionMode] -> Encoding omitField :: TransportSessionMode -> Bool
Show TransportSessionMode Source #
Instance details Defined in Simplex.Messaging.Client Methods showsPrec :: Int -> TransportSessionMode -> ShowS show :: TransportSessionMode -> String showList :: [TransportSessionMode] -> ShowS
Eq TransportSessionMode Source #
Instance details Defined in Simplex.Messaging.Client Methods (==) :: TransportSessionMode -> TransportSessionMode -> Bool (/=) :: TransportSessionMode -> TransportSessionMode -> Bool

data HostMode Source #

Constructors

HMOnionViaSocks	prefer (or require) onion hosts when connecting via SOCKS proxy
HMOnion	prefer (or require) onion hosts
HMPublic	prefer (or require) public hosts

Instances

Instances details

FromJSON HostMode Source #
Instance details Defined in Simplex.Messaging.Client Methods parseJSON :: Value -> Parser HostMode parseJSONList :: Value -> Parser [HostMode] omittedField :: Maybe HostMode
ToJSON HostMode Source #
Instance details Defined in Simplex.Messaging.Client Methods toJSON :: HostMode -> Value toEncoding :: HostMode -> Encoding toJSONList :: [HostMode] -> Value toEncodingList :: [HostMode] -> Encoding omitField :: HostMode -> Bool
Show HostMode Source #
Instance details Defined in Simplex.Messaging.Client Methods showsPrec :: Int -> HostMode -> ShowS show :: HostMode -> String showList :: [HostMode] -> ShowS
Eq HostMode Source #
Instance details Defined in Simplex.Messaging.Client Methods (==) :: HostMode -> HostMode -> Bool (/=) :: HostMode -> HostMode -> Bool

data SocksMode Source #

Constructors

SMAlways	always use SOCKS proxy when enabled
SMOnion	use SOCKS proxy only for .onion hosts when no public host is available This mode is used in SMP proxy and in notifications server to minimize SOCKS proxy usage.

Instances

Instances details

FromJSON SocksMode Source #
Instance details Defined in Simplex.Messaging.Client Methods parseJSON :: Value -> Parser SocksMode parseJSONList :: Value -> Parser [SocksMode] omittedField :: Maybe SocksMode
ToJSON SocksMode Source #
Instance details Defined in Simplex.Messaging.Client Methods toJSON :: SocksMode -> Value toEncoding :: SocksMode -> Encoding toJSONList :: [SocksMode] -> Value toEncodingList :: [SocksMode] -> Encoding omitField :: SocksMode -> Bool
Show SocksMode Source #
Instance details Defined in Simplex.Messaging.Client Methods showsPrec :: Int -> SocksMode -> ShowS show :: SocksMode -> String showList :: [SocksMode] -> ShowS
Eq SocksMode Source #
Instance details Defined in Simplex.Messaging.Client Methods (==) :: SocksMode -> SocksMode -> Bool (/=) :: SocksMode -> SocksMode -> Bool
StrEncoding SocksMode Source #
Instance details Defined in Simplex.Messaging.Client Methods strEncode :: SocksMode -> ByteString Source # strDecode :: ByteString -> Either String SocksMode Source # strP :: Parser SocksMode Source #

data SMPProxyMode Source #

Constructors

SPMAlways
SPMUnknown
SPMUnprotected
SPMNever

Instances

Instances details

FromJSON SMPProxyMode Source #
Instance details Defined in Simplex.Messaging.Client Methods parseJSON :: Value -> Parser SMPProxyMode parseJSONList :: Value -> Parser [SMPProxyMode] omittedField :: Maybe SMPProxyMode
ToJSON SMPProxyMode Source #
Instance details Defined in Simplex.Messaging.Client Methods toJSON :: SMPProxyMode -> Value toEncoding :: SMPProxyMode -> Encoding toJSONList :: [SMPProxyMode] -> Value toEncodingList :: [SMPProxyMode] -> Encoding omitField :: SMPProxyMode -> Bool
Show SMPProxyMode Source #
Instance details Defined in Simplex.Messaging.Client Methods showsPrec :: Int -> SMPProxyMode -> ShowS show :: SMPProxyMode -> String showList :: [SMPProxyMode] -> ShowS
Eq SMPProxyMode Source #
Instance details Defined in Simplex.Messaging.Client Methods (==) :: SMPProxyMode -> SMPProxyMode -> Bool (/=) :: SMPProxyMode -> SMPProxyMode -> Bool
StrEncoding SMPProxyMode Source #
Instance details Defined in Simplex.Messaging.Client Methods strEncode :: SMPProxyMode -> ByteString Source # strDecode :: ByteString -> Either String SMPProxyMode Source # strP :: Parser SMPProxyMode Source #

data SMPProxyFallback Source #

Constructors

SPFAllow
SPFAllowProtected
SPFProhibit

Instances

Instances details

FromJSON SMPProxyFallback Source #
Instance details Defined in Simplex.Messaging.Client Methods parseJSON :: Value -> Parser SMPProxyFallback parseJSONList :: Value -> Parser [SMPProxyFallback] omittedField :: Maybe SMPProxyFallback
ToJSON SMPProxyFallback Source #
Instance details Defined in Simplex.Messaging.Client Methods toJSON :: SMPProxyFallback -> Value toEncoding :: SMPProxyFallback -> Encoding toJSONList :: [SMPProxyFallback] -> Value toEncodingList :: [SMPProxyFallback] -> Encoding omitField :: SMPProxyFallback -> Bool
Show SMPProxyFallback Source #
Instance details Defined in Simplex.Messaging.Client Methods showsPrec :: Int -> SMPProxyFallback -> ShowS show :: SMPProxyFallback -> String showList :: [SMPProxyFallback] -> ShowS
Eq SMPProxyFallback Source #
Instance details Defined in Simplex.Messaging.Client Methods (==) :: SMPProxyFallback -> SMPProxyFallback -> Bool (/=) :: SMPProxyFallback -> SMPProxyFallback -> Bool
StrEncoding SMPProxyFallback Source #
Instance details Defined in Simplex.Messaging.Client Methods strEncode :: SMPProxyFallback -> ByteString Source # strDecode :: ByteString -> Either String SMPProxyFallback Source # strP :: Parser SMPProxyFallback Source #

data SMPWebPortServers Source #

Constructors

SWPAll
SWPPreset
SWPOff

Instances

Instances details

FromJSON SMPWebPortServers Source #
Instance details Defined in Simplex.Messaging.Client Methods parseJSON :: Value -> Parser SMPWebPortServers parseJSONList :: Value -> Parser [SMPWebPortServers] omittedField :: Maybe SMPWebPortServers
ToJSON SMPWebPortServers Source #
Instance details Defined in Simplex.Messaging.Client Methods toJSON :: SMPWebPortServers -> Value toEncoding :: SMPWebPortServers -> Encoding toJSONList :: [SMPWebPortServers] -> Value toEncodingList :: [SMPWebPortServers] -> Encoding omitField :: SMPWebPortServers -> Bool
Show SMPWebPortServers Source #
Instance details Defined in Simplex.Messaging.Client Methods showsPrec :: Int -> SMPWebPortServers -> ShowS show :: SMPWebPortServers -> String showList :: [SMPWebPortServers] -> ShowS
Eq SMPWebPortServers Source #
Instance details Defined in Simplex.Messaging.Client Methods (==) :: SMPWebPortServers -> SMPWebPortServers -> Bool (/=) :: SMPWebPortServers -> SMPWebPortServers -> Bool
StrEncoding SMPWebPortServers Source #
Instance details Defined in Simplex.Messaging.Client Methods strEncode :: SMPWebPortServers -> ByteString Source # strDecode :: ByteString -> Either String SMPWebPortServers Source # strP :: Parser SMPWebPortServers Source #

netTimeoutInt :: NetworkTimeout -> NetworkRequestMode -> Int Source #

defaultClientConfig :: Maybe [ALPN] -> Bool -> VersionRange v -> ProtocolClientConfig v Source #

Default protocol client configuration.

defaultSMPClientConfig :: ProtocolClientConfig SMPVersion Source #

defaultNetworkConfig :: NetworkConfig Source #

transportClientConfig :: NetworkConfig -> NetworkRequestMode -> TransportHost -> Bool -> Maybe [ALPN] -> TransportClientConfig Source #

clientSocksCredentials :: ProtocolTypeI (ProtoType msg) => NetworkConfig -> UTCTime -> TransportSession msg -> Maybe SocksCredentials Source #

chooseTransportHost :: NetworkConfig -> NonEmpty TransportHost -> Either (ProtocolClientError err) TransportHost Source #

temporaryClientError :: ProtocolClientError err -> Bool Source #

smpClientServiceError :: SMPClientError -> Bool Source #

smpProxyError :: SMPClientError -> ErrorType Source #

smpErrorClientNotice :: SMPClientError -> Maybe (Maybe ClientNotice) Source #

textToHostMode :: Text -> Either String HostMode Source #

type ServerTransmissionBatch v err msg = (TransportSession msg, Version v, SessionId, NonEmpty (EntityId, ServerTransmission err msg)) Source #

Type synonym for transmission from SPM servers. Batch response is presented as a single ServerTransmissionBatch tuple.

data ServerTransmission err msg Source #

Constructors

STEvent (Either (ProtocolClientError err) msg)
STResponse (ProtoCommand msg) (Either (ProtocolClientError err) msg)
STUnexpectedError (ProtocolClientError err)

type ClientCommand msg = (EntityId, Maybe APrivateAuthKey, ProtoCommand msg) Source #

Type for client command data

For testing

type PCTransmission err msg = (Either TransportError SentRawTransmission, Request err msg) Source #

mkTransmission :: Protocol v err msg => ProtocolClient v err msg -> ClientCommand msg -> IO (PCTransmission err msg) Source #

authTransmission :: Maybe (THandleAuth 'TClient) -> Bool -> Maybe APrivateAuthKey -> CbNonce -> ByteString -> Either TransportError (Maybe TAuthorizations) Source #

smpClientStub :: TVar ChaChaDRG -> ByteString -> VersionSMP -> Maybe (THandleAuth 'TClient) -> IO SMPClient Source #

For debugging

data TBQueueInfo Source #

Constructors

TBQueueInfo
Fields qLength :: Int qFull :: Bool

Instances

Instances details

FromJSON TBQueueInfo Source #
Instance details Defined in Simplex.Messaging.Client Methods parseJSON :: Value -> Parser TBQueueInfo parseJSONList :: Value -> Parser [TBQueueInfo] omittedField :: Maybe TBQueueInfo
ToJSON TBQueueInfo Source #
Instance details Defined in Simplex.Messaging.Client Methods toJSON :: TBQueueInfo -> Value toEncoding :: TBQueueInfo -> Encoding toJSONList :: [TBQueueInfo] -> Value toEncodingList :: [TBQueueInfo] -> Encoding omitField :: TBQueueInfo -> Bool
Show TBQueueInfo Source #
Instance details Defined in Simplex.Messaging.Client Methods showsPrec :: Int -> TBQueueInfo -> ShowS show :: TBQueueInfo -> String showList :: [TBQueueInfo] -> ShowS

getTBQueueInfo :: TBQueue a -> STM TBQueueInfo Source #

getProtocolClientQueuesInfo :: ProtocolClient v err msg -> IO (TBQueueInfo, TBQueueInfo) Source #

nonBlockingWriteTBQueue :: TBQueue a -> a -> IO () Source #