magic-wormhole-0.3.4: Interact with Magic Wormhole

Safe HaskellNone
LanguageHaskell2010

MagicWormhole.Internal.Rendezvous

Contents

Description

Interactions with a Magic Wormhole Rendezvous server.

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

Synopsis

Specific RPCs

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

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

List the nameplates on the server.

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

allocate :: HasCallStack => Session -> IO Nameplate Source #

Allocate a nameplate on the server.

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

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

Claim a nameplate on the server.

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

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

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

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

Close a mailbox on the server.

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

Running a Rendezvous client

runClient Source #

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

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

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.

data ClientError Source #

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.