magic-wormhole-0.2.0: Interact with Magic Wormhole

Safe HaskellNone
LanguageHaskell2010

MagicWormhole.Internal.Messages

Description

Messages sent to and from the Rendezvous server.

Synopsis

Documentation

data ClientMessage Source #

A message sent from a rendezvous client to the server.

Constructors

Bind AppID Side

Set the application ID and the "side" for the duration of the connection.

List

Get a list of all allocated nameplates.

Allocate

Ask the server to allocate a nameplate

Claim Nameplate

Claim a nameplate.

Release (Maybe Nameplate)

Release a claimed nameplate.

If no nameplate is provided, the server will attempt to release the nameplate claimed (via Claim) earlier in this connection.

Open Mailbox

Open a mailbox.

Add Phase Body

Send a message to an open mailbox. The message will be delivered to all connected clients that also have that mailbox open, including this one.

Close (Maybe Mailbox) (Maybe Mood)

Close a mailbox. Since only one mailbox can be open at a time, if mailbox isn't specified, then close the open mailbox.

Ping Int

Internal "ping". Response is Pong. Used for testing.

data ServerMessage Source #

A message received from the server.

Some open questions: * general message stuff--how are we going to model this? * outgoing messages include a randomly generated id field, which is returned by the server * messages from the server include server_tx, a float timestamp recording when the server received the message * messages from the server that are direct responses include a server_rx timestamp--unclear what this means? * do we want a separate Haskell type for each message type? e.g. PingMessage * if we do that, how do associate request/response pairs? e.g. PingMessage & PongMessage? * do we want to (can we even?) structurally distinguish between messages that make sense outside the scope of a binding (e.g. ping) and messages that only make sense after a bind (e.g. allocate)

Constructors

Welcome WelcomeMessage

Sent by the server on initial connection.

Nameplates

Sent in response to "list"

Fields

Allocated

Sent in response to "allocate"

Fields

Claimed

Sent in response to "claim"

Fields

Released

Sent in response to "release"

Message MailboxMessage

A message sent to the mailbox

Closed

Sent in response to "close"

Ack

Sent immediately after every message. Unused.

Pong Int

Sent in response to "pong"

Error

Sent by the server when it receives something from the client that it does not understand.

Fields

newtype AppID Source #

Short string to identify the application. Clients must use the same application ID if they wish to communicate with each other.

Recommendation is to use "$DNSNAME/$APPNAME", e.g. the Python wormhole command-line tool uses lothar.com/wormhole/text-or-file-xfer.

Constructors

AppID Text 

Instances

Eq AppID Source # 

Methods

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

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

Show AppID Source # 

Methods

showsPrec :: Int -> AppID -> ShowS #

show :: AppID -> String #

showList :: [AppID] -> ShowS #

ToJSON AppID Source # 

Methods

toJSON :: AppID -> Value

toEncoding :: AppID -> Encoding

toJSONList :: [AppID] -> Value

toEncodingList :: [AppID] -> Encoding

FromJSON AppID Source # 

Methods

parseJSON :: Value -> Parser AppID

parseJSONList :: Value -> Parser [AppID]

data MailboxMessage Source #

A message sent to a mailbox.

Constructors

MailboxMessage 

Fields

  • side :: Side

    Which side sent the message. Might be our side.

  • phase :: Phase

    Which phase of the client protocol we are in.

  • messageID :: Maybe MessageID

    An identifier for the message. Unused.

    According to the protocol docs, this should always be set, but the Python server will happily mirror an absent id field as null.

  • body :: Body

    The body of the message. To be interpreted by the client protocol.

data WelcomeMessage Source #

Message received on initial connection to the server.

Constructors

WelcomeMessage 

Fields

  • motd :: Maybe Text

    A message to be displayed to users when they connect to the server

  • welcomeErrorMessage :: Maybe Text

    If present, the server does not want the client to proceed. Here's the reason why.

newtype MessageID Source #

Identifier sent with every client message that is included in the matching server responses.

Constructors

MessageID Int16 

Instances

Eq MessageID Source # 
Show MessageID Source # 
Hashable MessageID Source # 
ToJSON MessageID Source # 

Methods

toJSON :: MessageID -> Value

toEncoding :: MessageID -> Encoding

toJSONList :: [MessageID] -> Value

toEncodingList :: [MessageID] -> Encoding

FromJSON MessageID Source # 

Methods

parseJSON :: Value -> Parser MessageID

parseJSONList :: Value -> Parser [MessageID]

newtype Side Source #

Short string used to differentiate between echoes of our own messages and real messages from other clients.

TODO: This needs to be cleanly encoded to ASCII, so update the type or provide a smart constructor.

Constructors

Side Text 

Instances

Eq Side Source # 

Methods

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

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

Show Side Source # 

Methods

showsPrec :: Int -> Side -> ShowS #

show :: Side -> String #

showList :: [Side] -> ShowS #

ToJSON Side Source # 

Methods

toJSON :: Side -> Value

toEncoding :: Side -> Encoding

toJSONList :: [Side] -> Value

toEncodingList :: [Side] -> Encoding

FromJSON Side Source # 

Methods

parseJSON :: Value -> Parser Side

parseJSONList :: Value -> Parser [Side]

generateSide :: MonadRandom randomly => randomly Side Source #

Generate a random Side

data Phase Source #

A phase in the peer-to-peer (aka "client") protocol.

Phases proceed in strict order: PakePhase, VersionPhase, then many ApplicationPhase.

Constructors

PakePhase

Sent immediately on opening the mailbox.

VersionPhase

Used to negotiate capabilities.

ApplicationPhase Int

Reserved for application data. Messages with these phases will be delivered in numeric order.

Instances

Eq Phase Source # 

Methods

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

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

Show Phase Source # 

Methods

showsPrec :: Int -> Phase -> ShowS #

show :: Phase -> String #

showList :: [Phase] -> ShowS #

ToJSON Phase Source # 

Methods

toJSON :: Phase -> Value

toEncoding :: Phase -> Encoding

toJSONList :: [Phase] -> Value

toEncodingList :: [Phase] -> Encoding

FromJSON Phase Source # 

Methods

parseJSON :: Value -> Parser Phase

parseJSONList :: Value -> Parser [Phase]

phaseName :: Phase -> Text Source #

Get the name of the phase. Used to derive message keys.

newtype Body Source #

The body of a Magic Wormhole message.

This can be any arbitrary bytestring that is sent to or received from a wormhole peer.

Constructors

Body ByteString 

Instances

Eq Body Source # 

Methods

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

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

Show Body Source # 

Methods

showsPrec :: Int -> Body -> ShowS #

show :: Body -> String #

showList :: [Body] -> ShowS #

ToJSON Body Source # 

Methods

toJSON :: Body -> Value

toEncoding :: Body -> Encoding

toJSONList :: [Body] -> Value

toEncodingList :: [Body] -> Encoding

FromJSON Body Source # 

Methods

parseJSON :: Value -> Parser Body

parseJSONList :: Value -> Parser [Body]

newtype Nameplate Source #

Identifier for a "nameplate".

A nameplate is a very short string that identifies one peer to another. Its purpose is to allow peers to find each other without having to communicate the Mailbox identifier, which is generally too lengthy and cumbersome to be easily shared between humans.

Typically, one peer will allocate a nameplate and then communicate it out-of-band to the other peer.

Constructors

Nameplate Text 

Instances

Eq Nameplate Source # 
Show Nameplate Source # 
ToJSON Nameplate Source # 

Methods

toJSON :: Nameplate -> Value

toEncoding :: Nameplate -> Encoding

toJSONList :: [Nameplate] -> Value

toEncodingList :: [Nameplate] -> Encoding

FromJSON Nameplate Source # 

Methods

parseJSON :: Value -> Parser Nameplate

parseJSONList :: Value -> Parser [Nameplate]

newtype Mailbox Source #

Identifier for a mailbox.

A mailbox is a shared access point between Magic Wormhole peers within the same application (specified by AppID). To get a mailbox, you must first acquire a Nameplate and then claim that nameplate for your side with claim.

A mailbox ID is defined in the spec as a "large random string", but in practice is a 13 character, lower-case, alpha-numeric string.

Constructors

Mailbox Text 

Instances

Eq Mailbox Source # 

Methods

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

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

Show Mailbox Source # 
ToJSON Mailbox Source # 

Methods

toJSON :: Mailbox -> Value

toEncoding :: Mailbox -> Encoding

toJSONList :: [Mailbox] -> Value

toEncodingList :: [Mailbox] -> Encoding

FromJSON Mailbox Source # 

Methods

parseJSON :: Value -> Parser Mailbox

parseJSONList :: Value -> Parser [Mailbox]

data Mood Source #

How the client feels. Reported by the client to the server at the end of a wormhole session.

Constructors

Happy

The client had a great session with its peer.

Lonely

The client never saw its peer.

Scary

The client saw a peer it could not trust.

Errory

The client encountered some problem.

Instances

Eq Mood Source # 

Methods

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

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

Show Mood Source # 

Methods

showsPrec :: Int -> Mood -> ShowS #

show :: Mood -> String #

showList :: [Mood] -> ShowS #

ToJSON Mood Source # 

Methods

toJSON :: Mood -> Value

toEncoding :: Mood -> Encoding

toJSONList :: [Mood] -> Value

toEncodingList :: [Mood] -> Encoding

FromJSON Mood Source # 

Methods

parseJSON :: Value -> Parser Mood

parseJSONList :: Value -> Parser [Mood]