MagicWormhole.Internal.Rendezvous

Interactions with a Magic Wormhole Rendezvous server.

Intended to be imported qualified, e.g. ``` import qualified MagicWormhole.Internal.Rendezvous as Rendezvous ```

Specific RPCs

ping :: HasCallStack => Session -> Int -> IO Int

Ping the server.

This is an in-band ping, used mostly for testing. It is not necessary to keep the connection alive.

Throws a ClientError if the server rejects the message for any reason.

list :: HasCallStack => Session -> IO [Nameplate]

List the nameplates on the server.

Throws a ClientError if the server rejects the message for any reason.

allocate :: HasCallStack => Session -> IO Nameplate

Allocate a nameplate on the server.

Throws a ClientError if the server rejects the message for any reason.

claim :: HasCallStack => Session -> Nameplate -> IO Mailbox

Claim a nameplate on the server.

Throws a ClientError if the server rejects the message for any reason.

release :: HasCallStack => Session -> Maybe Nameplate -> IO ()

Release a nameplate on the server.

TODO: Document semantics around "optional" nameplate.

TODO: Make this impossible to call unless we have already claimed a namespace.

Throws a ClientError if the server rejects the message for any reason.

open :: HasCallStack => Session -> Mailbox -> IO Connection

Open a mailbox on the server.

If there's already a mailbox open, the server will send an error message. In the current implementation, that error will arise in a strange and unexpected place.

See https://github.com/warner/magic-wormhole/issues/261#issuecomment-343192449

close :: HasCallStack => Session -> Maybe Mailbox -> Maybe Mood -> IO ()

Close a mailbox on the server.

Throws a ClientError if the server rejects the message for any reason.

Running a Rendezvous client

runClient

Arguments

:: HasCallStack

=> WebSocketEndpoint

The websocket to connect to

-> AppID

ID for your application (e.g. example.com/your-application)

-> Side

Identifier for your side

-> Maybe Socket

Just an existing socket to use or Nothing to create and use a new one

-> (Session -> IO a)

Action to perform inside the Magic Wormhole session

-> IO a

The result of the action

Run a Magic Wormhole Rendezvous client. Use this to interact with a Magic Wormhole server.

Will throw a ServerError if the server declares we are unwelcome.

data Session

Abstract type representing a Magic Wormhole session.

Use runClient to get a Session on the Magic Wormhole Rendezvous server. Once you have a Session, use ping, list, allocate, claim, release, open, and close to communicate with the Rendezvous server.

Errors

data ServerError

Error due to weirdness from the server.

Constructors

ResponseWithoutRequest ServerMessage

Server sent us a response for something that we hadn't requested.

UnexpectedMessage ServerMessage

We were sent a message other than Welcome on connect, or a Welcome message at any other time.

ErrorForNonRequest Text ClientMessage

We received an error message for a message that's not expected to have a response.

Unwelcome Text

Clients are not welcome on the server right now.

ParseError String

We couldn't understand the message from the server.

Instances

Eq ServerError

Defined in MagicWormhole.Internal.Rendezvous

Methods

(==) :: ServerError -> ServerError -> Bool

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

Show ServerError

Defined in MagicWormhole.Internal.Rendezvous

Methods

showsPrec :: Int -> ServerError -> ShowS

show :: ServerError -> String

showList :: [ServerError] -> ShowS

Exception ServerError

Defined in MagicWormhole.Internal.Rendezvous

Methods

toException :: ServerError -> SomeException

fromException :: SomeException -> Maybe ServerError

displayException :: ServerError -> String

data ClientError

Error caused by misusing the client.

Constructors

AlreadySent ClientMessage

We tried to do an RPC while another RPC with the same response type was in flight. See warner/magic-wormhole#260 for details.

NotAnRPC ClientMessage

Tried to send a non-RPC as if it were an RPC (i.e. expecting a response).

BadRequest Text ClientMessage

We sent a message that the server could not understand.

Instances

Eq ClientError

Defined in MagicWormhole.Internal.Rendezvous

Methods

(==) :: ClientError -> ClientError -> Bool

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

Show ClientError

Defined in MagicWormhole.Internal.Rendezvous

Methods

showsPrec :: Int -> ClientError -> ShowS

show :: ClientError -> String

showList :: [ClientError] -> ShowS

Exception ClientError

Defined in MagicWormhole.Internal.Rendezvous

Methods

toException :: ClientError -> SomeException

fromException :: SomeException -> Maybe ClientError

displayException :: ClientError -> String