Urbit | ||
.build.yml | ||
.ghci | ||
.gitignore | ||
default.nix | ||
fakezod.sh | ||
LICENSE | ||
Main.hs | ||
nixpkgs.nix | ||
README.md | ||
shell.nix | ||
test.hs | ||
urbit-airlock.cabal | ||
urbit-airlock.nix |
Haskell Urbit API
This library helps you talk to your Urbit from Haskell, via HTTP.
The "Urbit Airlock" API is a command-query API that lets you hook into apps running on your Urbit. You can submit commands (called "pokes") and subscribe to responses.
See the test.hs
file for some example usages.
Design
The Urbit vane eyre
is responsible for defining the API interface. The path to
the API is /~/channel/...
, where we send messages to the global log (called
poke
s) 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 wire
s.
urbit-airlock
handles most of the path, session, and HTTP request stuff
automatically. See the
haddocks
for more details.
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.
Example usage
import qualified Data.Aeson as Aeson
import Data.Aeson ((.=))
import qualified Data.Text as Text
import qualified Data.UUID.V4 as UUID
import Urbit.Airlock
main :: IO ()
main = do
let fakezod = Ship
{ uid = "0123456789abcdef",
name = "zod",
lastEventId = 1,
url = "http://localhost:8081",
code = "lidlut-tabwed-pillex-ridrup"
}
-- Establish connection
sess <- connect ship
-- Send a message by poking the chat-hook
uuid <- UUID.nextRandom
poke sess ship "zod" "chat-hook" "json" $
Aeson.object
[ "message"
.= Aeson.object
[ "path" .= Text.pack "/~/~zod/mc",
"envelope"
.= Aeson.object
[ "uid" .= UUID.toText uuid,
"number" .= (1 :: Int),
"author" .= Text.pack "~zod",
"when" .= (1602118786225 :: Int),
"letter" .= Aeson.object ["text" .= Text.pack "hello world from haskell!"]
]
]
]
TODO
- fix test suite on travis (OOM when trying to compile urbit)
- more sophisticated test cases, also use cabal test instead of homegrown thing
- add an exe that wraps the library with a cli
- port to ghcjs
- put some examples in the docs