Simplex.Messaging.Protocol

Types, parsers, serializers and functions to send and receive SMP protocol commands and responses.

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

SMP protocol types

data Command (a :: Party) where

Parameterized type for SMP protocol commands from all participants.

Constructors

NEW :: RecipientPublicKey -> Command Recipient

SUB :: Command Recipient

KEY :: SenderPublicKey -> Command Recipient

ACK :: Command Recipient

OFF :: Command Recipient

DEL :: Command Recipient

SEND :: MsgBody -> Command Sender

PING :: Command Sender

IDS :: RecipientId -> SenderId -> Command Broker

MSG :: MsgId -> UTCTime -> MsgBody -> Command Broker

END :: Command Broker

OK :: Command Broker

ERR :: ErrorType -> Command Broker

PONG :: Command Broker

Instances

Eq (Command a)

Defined in Simplex.Messaging.Protocol

Methods

(==) :: Command a -> Command a -> Bool

(/=) :: Command a -> Command a -> Bool

Show (Command a)

Defined in Simplex.Messaging.Protocol

Methods

showsPrec :: Int -> Command a -> ShowS

show :: Command a -> String

showList :: [Command a] -> ShowS

data Party

SMP protocol participants.

Constructors

Broker

Recipient

Sender

Instances

Show Party

Defined in Simplex.Messaging.Protocol

Methods

showsPrec :: Int -> Party -> ShowS

show :: Party -> String

showList :: [Party] -> ShowS

data Cmd

Type for command or response of any participant.

Constructors

forall a. Cmd (SParty a) (Command a)

Instances

Show Cmd

Defined in Simplex.Messaging.Protocol

Methods

showsPrec :: Int -> Cmd -> ShowS

show :: Cmd -> String

showList :: [Cmd] -> ShowS

data SParty :: Party -> Type where

Singleton types for SMP protocol participants.

Constructors

SBroker :: SParty Broker

SRecipient :: SParty Recipient

SSender :: SParty Sender

Instances

Show (SParty a)

Defined in Simplex.Messaging.Protocol

Methods

showsPrec :: Int -> SParty a -> ShowS

show :: SParty a -> String

showList :: [SParty a] -> ShowS

data ErrorType

Type for protocol errors.

Constructors

BLOCK

incorrect block format, encoding or signature size

CMD CommandError

SMP command is unknown or has invalid syntax

AUTH

command authorization error - bad signature or non-existing SMP queue

QUOTA

SMP queue capacity is exceeded on the server

NO_MSG

ACK command is sent without message to be acknowledged

INTERNAL

internal server error

DUPLICATE_

used internally, never returned by the server (to be removed)

Instances

Eq ErrorType

Defined in Simplex.Messaging.Protocol

Methods

(==) :: ErrorType -> ErrorType -> Bool

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

Read ErrorType

Defined in Simplex.Messaging.Protocol

Methods

readsPrec :: Int -> ReadS ErrorType

readList :: ReadS [ErrorType]

readPrec :: ReadPrec ErrorType

readListPrec :: ReadPrec [ErrorType]

Show ErrorType

Defined in Simplex.Messaging.Protocol

Methods

showsPrec :: Int -> ErrorType -> ShowS

show :: ErrorType -> String

showList :: [ErrorType] -> ShowS

Generic ErrorType

Defined in Simplex.Messaging.Protocol

Associated Types

type Rep ErrorType :: Type -> Type

Methods

from :: ErrorType -> Rep ErrorType x

to :: Rep ErrorType x -> ErrorType

Arbitrary ErrorType

Defined in Simplex.Messaging.Protocol

Methods

arbitrary :: Gen ErrorType

shrink :: ErrorType -> [ErrorType]

type Rep ErrorType

Defined in Simplex.Messaging.Protocol

type Rep ErrorType = D1 ('MetaData "ErrorType" "Simplex.Messaging.Protocol" "simplexmq-0.4.1-3ajLTyZJIzSCIq5kBRn4h6" 'False) ((C1 ('MetaCons "BLOCK" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "CMD" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 CommandError)) :+: C1 ('MetaCons "AUTH" 'PrefixI 'False) (U1 :: Type -> Type))) :+: ((C1 ('MetaCons "QUOTA" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "NO_MSG" 'PrefixI 'False) (U1 :: Type -> Type)) :+: (C1 ('MetaCons "INTERNAL" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "DUPLICATE_" 'PrefixI 'False) (U1 :: Type -> Type))))

data CommandError

SMP command error type.

Constructors

PROHIBITED

server response sent from client or vice versa

KEY_SIZE

bad RSA key size in NEW or KEY commands (only 1024, 2048 and 4096 bits keys are allowed)

SYNTAX

error parsing command

NO_AUTH

transmission has no required credentials (signature or queue ID)

HAS_AUTH

transmission has credentials that are not allowed for this command

NO_QUEUE

transmission has no required queue ID

Instances

Eq CommandError

Defined in Simplex.Messaging.Protocol

Methods

(==) :: CommandError -> CommandError -> Bool

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

Read CommandError

Defined in Simplex.Messaging.Protocol

Methods

readsPrec :: Int -> ReadS CommandError

readList :: ReadS [CommandError]

readPrec :: ReadPrec CommandError

readListPrec :: ReadPrec [CommandError]

Show CommandError

Defined in Simplex.Messaging.Protocol

Methods

showsPrec :: Int -> CommandError -> ShowS

show :: CommandError -> String

showList :: [CommandError] -> ShowS

Generic CommandError

Defined in Simplex.Messaging.Protocol

Associated Types

type Rep CommandError :: Type -> Type

Methods

from :: CommandError -> Rep CommandError x

to :: Rep CommandError x -> CommandError

Arbitrary CommandError

Defined in Simplex.Messaging.Protocol

Methods

arbitrary :: Gen CommandError

shrink :: CommandError -> [CommandError]

type Rep CommandError

Defined in Simplex.Messaging.Protocol

type Rep CommandError = D1 ('MetaData "CommandError" "Simplex.Messaging.Protocol" "simplexmq-0.4.1-3ajLTyZJIzSCIq5kBRn4h6" 'False) ((C1 ('MetaCons "PROHIBITED" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "KEY_SIZE" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "SYNTAX" 'PrefixI 'False) (U1 :: Type -> Type))) :+: (C1 ('MetaCons "NO_AUTH" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "HAS_AUTH" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "NO_QUEUE" 'PrefixI 'False) (U1 :: Type -> Type))))

type Transmission = (CorrId, QueueId, Cmd)

SMP transmission without signature.

type SignedTransmission = (Signature, Transmission)

SMP transmission with signature.

type SignedTransmissionOrError = (Signature, TransmissionOrError)

signed parsed transmission, with parsing error.

type RawTransmission = (ByteString, ByteString, ByteString, ByteString)

unparsed SMP transmission with signature.

type SignedRawTransmission = (Signature, ByteString)

unparsed SMP transmission with signature.

newtype CorrId

Transmission correlation ID.

A newtype to avoid accidentally changing order of transmission parts.

Constructors

CorrId

Fields

• bs :: ByteString

Instances

Eq CorrId

Defined in Simplex.Messaging.Protocol

Methods

(==) :: CorrId -> CorrId -> Bool

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

Ord CorrId

Defined in Simplex.Messaging.Protocol

Methods

compare :: CorrId -> CorrId -> Ordering

(<) :: CorrId -> CorrId -> Bool

(<=) :: CorrId -> CorrId -> Bool

(>) :: CorrId -> CorrId -> Bool

(>=) :: CorrId -> CorrId -> Bool

max :: CorrId -> CorrId -> CorrId

min :: CorrId -> CorrId -> CorrId

Show CorrId

Defined in Simplex.Messaging.Protocol

Methods

showsPrec :: Int -> CorrId -> ShowS

show :: CorrId -> String

showList :: [CorrId] -> ShowS

IsString CorrId

Defined in Simplex.Messaging.Protocol

Methods

fromString :: String -> CorrId

type QueueId = Encoded

SMP queue ID on the server.

type RecipientId = QueueId

SMP queue ID for the recipient.

type SenderId = QueueId

SMP queue ID for the sender.

type RecipientPrivateKey = SafePrivateKey

Recipient's private key used by the recipient to authorize (sign) SMP commands.

Only used by SMP agent, kept here so its definition is close to respective public key.

type RecipientPublicKey = PublicKey

Recipient's public key used by SMP server to verify authorization of SMP commands.

type SenderPrivateKey = SafePrivateKey

Sender's private key used by the recipient to authorize (sign) SMP commands.

Only used by SMP agent, kept here so its definition is close to respective public key.

type SenderPublicKey = PublicKey

Sender's public key used by SMP server to verify authorization of SMP commands.

type Encoded = ByteString

Base-64 encoded string.

type MsgId = Encoded

SMP message server ID.

type MsgBody = ByteString

SMP message body.

Parse and serialize

serializeTransmission :: Transmission -> ByteString

Serialize SMP transmission.

serializeCommand :: Cmd -> ByteString

Serialize SMP command.

serializeErrorType :: ErrorType -> ByteString

Serialize SMP error.

transmissionP :: Parser RawTransmission

SMP transmission parser.

commandP :: Parser Cmd

SMP command parser.

errorTypeP :: Parser ErrorType

SMP error parser.

TCP transport functions

tPut :: Transport c => THandle c -> SignedRawTransmission -> IO (Either TransportError ())

Send signed SMP transmission to TCP transport.

tGet :: forall c m. (Transport c, MonadIO m) => (Cmd -> Either ErrorType Cmd) -> THandle c -> m SignedTransmissionOrError

Receive client and server transmissions.

The first argument is used to limit allowed senders. fromClient or fromServer should be used here.

fromClient :: Cmd -> Either ErrorType Cmd

Validate that it is an SMP client command, used with tGet by Server.

fromServer :: Cmd -> Either ErrorType Cmd

Validate that it is an SMP server command, used with tGet by Client.