Simplex.Messaging.Client

This module provides a functional client API for SMP protocol.

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

Connect (disconnect) client to (from) SMP server

data SMPClient

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

The only exported selector is blockSize that is negotiated with the server during the TCP transport handshake.

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

getSMPClient :: SMPServer -> SMPClientConfig -> TBQueue SMPServerTransmission -> IO () -> IO (Either SMPClientError SMPClient)

Connects to SMPServer 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.

closeSMPClient :: SMPClient -> IO ()

Disconnects SMP client from the server and terminates client threads.

SMP protocol command functions

createSMPQueue :: SMPClient -> RecipientPrivateKey -> RecipientPublicKey -> ExceptT SMPClientError IO (RecipientId, SenderId)

Create a new SMP queue.

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

subscribeSMPQueue :: SMPClient -> RecipientPrivateKey -> RecipientId -> ExceptT SMPClientError IO ()

Subscribe to the SMP queue.

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

secureSMPQueue :: SMPClient -> RecipientPrivateKey -> RecipientId -> SenderPublicKey -> ExceptT SMPClientError IO ()

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

sendSMPMessage :: SMPClient -> Maybe SenderPrivateKey -> SenderId -> MsgBody -> ExceptT SMPClientError IO ()

Send SMP message.

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

ackSMPMessage :: SMPClient -> RecipientPrivateKey -> QueueId -> ExceptT SMPClientError IO ()

Acknowledge message delivery (server deletes the message).

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

suspendSMPQueue :: SMPClient -> RecipientPrivateKey -> QueueId -> ExceptT SMPClientError IO ()

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 -> RecipientPrivateKey -> QueueId -> ExceptT SMPClientError IO ()

Irreversibly delete SMP queue and all messages in it.

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

sendSMPCommand :: SMPClient -> Maybe SafePrivateKey -> QueueId -> Cmd -> ExceptT SMPClientError IO Cmd

Send any SMP command (Cmd type).

Supporting types and client configuration

data SMPClientError

SMP client error type.

Constructors

SMPServerError ErrorType

Correctly parsed SMP server ERR response. This error is forwarded to the agent client as `ERR SMP err`.

SMPResponseError ErrorType

Invalid server response that failed to parse. Forwarded to the agent client as `ERR BROKER RESPONSE`.

SMPUnexpectedResponse

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

SMPResponseTimeout

Used for TCP connection and command response timeouts. Forwarded to the agent client as `ERR BROKER TIMEOUT`.

SMPNetworkError

Failure to establish TCP connection. Forwarded to the agent client as `ERR BROKER NETWORK`.

SMPTransportError TransportError

TCP transport handshake or some other transport error. Forwarded to the agent client as `ERR BROKER TRANSPORT e`.

SMPSignatureError CryptoError

Error when cryptographically "signing" the command.

Instances

Eq SMPClientError

Defined in Simplex.Messaging.Client

Methods

(==) :: SMPClientError -> SMPClientError -> Bool

(/=) :: SMPClientError -> SMPClientError -> Bool

Show SMPClientError

Defined in Simplex.Messaging.Client

Methods

showsPrec :: Int -> SMPClientError -> ShowS

show :: SMPClientError -> String

showList :: [SMPClientError] -> ShowS

Exception SMPClientError

Defined in Simplex.Messaging.Client

Methods

toException :: SMPClientError -> SomeException

fromException :: SomeException -> Maybe SMPClientError

displayException :: SMPClientError -> String

data SMPClientConfig

SMP client configuration.

Constructors

SMPClientConfig

Fields

• qSize :: Natural

  size of TBQueue to use for server commands and responses

• defaultTransport :: (ServiceName, ATransport)

  default SMP server port if port is not specified in SMPServer

• tcpTimeout :: Int

  timeout of TCP commands (microseconds)

• smpPing :: Int

  period for SMP ping commands (microseconds)

• smpBlockSize :: Maybe Int

  SMP transport block size, Nothing - the block size will be set by the server. Allowed sizes are 4, 8, 16, 32, 64 KiB (* 1024 bytes).

• smpCommandSize :: Int

  estimated maximum size of SMP command excluding message body, determines the maximum allowed message size

smpDefaultConfig :: SMPClientConfig

Default SMP client configuration.

type SMPServerTransmission = (SMPServer, RecipientId, Command 'Broker)

Type synonym for transmission from some SPM server queue.