Urbit.Airlock

About the Urbit API

The "Urbit Airlock" API is a command-query API that lets you hook into apps running on your Urbit. You can submit commands and subscribe to responses.

The Urbit vane eyre is responsible for defining the API interface. The HTTP path to the API is /~/channel/..., where we send messages to the global log (called pokes) which are then dispatched to the appropriate apps. To receive responses, we stream messages from a path associated with the app, such as /mailbox/~/~zod/mc. Internally, I believe Urbit calls these wires.

About this library

This library helps you talk to your Urbit from Haskell, via HTTP. It handles most of the path, session, and HTTP request stuff automatically. You'll need to know what app and mark (data type) to send to, which path/wire listen to, and the shape of the message. The latter can be found in the Hoon source code, called the vase on the poke arm.

This library is built on req, conduit, and aeson, all of which are very stable and usable libraries for working with HTTP requests and web data. Released under the MIT License, same as Urbit.

Types

data Ship

Some information about your ship needed to establish connection.

Constructors

Ship

Fields

• uid :: Text

  A random string for your channel

• name :: Text

  The @p of your ship

• lastEventId :: Int

  Track the latest event we saw (needed for poking)

• url :: Text

  Network access point, with port if necessary, like https://sampel-palnet.arvo.network, or http://localhost:8080

• code :: Text

  Login code, +code in the dojo. Don't share this publically

Instances

Show Ship

Defined in Urbit.Airlock

Methods

showsPrec :: Int -> Ship -> ShowS

show :: Ship -> String

showList :: [Ship] -> ShowS

type Session = CookieJar

A wrapper type for the session cookies.

Functions

connect :: Ship -> IO Session

Connect and login to the ship.

poke

Arguments

:: ToJSON a

=> Session

Session cookie from connect

-> Ship

Your ship

-> Text

Name of the ship to poke

-> Text

Name of the gall application you want to poke

-> Text

The mark of the message you are sending

-> a

The actual JSON message, serialized via aeson

-> IO BsResponse

Poke a ship.

ack

Arguments

:: Session

Session cookie from connect

-> Ship

Your ship

-> Int

The event number

-> IO BsResponse

Acknowledge receipt of a message. (This clears it from the ship's queue.)

subscribe

Arguments

:: Session

Session cookie from connect

-> Ship

Your ship

-> Text

The path to subscribe to.

-> ConduitM ByteString Void (ResourceT IO) a

A handler conduit to receive the response from the server, e.g. Data.Conduit.Binary.sinkFile "my-file.out"

-> IO a

Subscribe to ship events on some path.

Orphan instances

MonadHttp (ConduitM i o (ResourceT IO))

Methods

handleHttpException :: HttpException -> ConduitM i o (ResourceT IO) a

getHttpConfig :: ConduitM i o (ResourceT IO) HttpConfig