simplexmq-0.3.1: SimpleXMQ message broker
Copyright(c) simplex.chat
LicenseAGPL-3
Maintainerchat@simplex.chat
Stabilityexperimental
Portabilitynon-portable
Safe HaskellNone
LanguageHaskell2010

Simplex.Messaging.Client

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

Connect (disconnect) client to (from) SMP server

data SMPClient Source #

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) Source #

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 () Source #

Disconnects SMP client from the server and terminates client threads.

SMP protocol command functions

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

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 () Source #

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 () 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

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

Send SMP message.

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

ackSMPMessage :: SMPClient -> RecipientPrivateKey -> QueueId -> 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

suspendSMPQueue :: SMPClient -> RecipientPrivateKey -> 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 -> RecipientPrivateKey -> QueueId -> 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

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

Send any SMP command (Cmd type).

Supporting types and client configuration

data SMPClientError Source #

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

Instances details
Eq SMPClientError Source # 
Instance details

Defined in Simplex.Messaging.Client

Methods

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

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

Show SMPClientError Source # 
Instance details

Defined in Simplex.Messaging.Client

Methods

showsPrec :: Int -> SMPClientError -> ShowS #

show :: SMPClientError -> String #

showList :: [SMPClientError] -> ShowS #

Exception SMPClientError Source # 
Instance details

Defined in Simplex.Messaging.Client

Methods

toException :: SMPClientError -> SomeException #

fromException :: SomeException -> Maybe SMPClientError #

displayException :: SMPClientError -> String #

data SMPClientConfig Source #

SMP client configuration.

Constructors

SMPClientConfig 

Fields

  • qSize :: Natural

    size of TBQueue to use for server commands and responses

  • defaultPort :: ServiceName

    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)

  • smpCommandSize :: Int

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

smpDefaultConfig :: SMPClientConfig Source #

Default SMP client configuration.

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

Type synonym for transmission from some SPM server queue.