io.github.sorted-falnyd/clj-airlock-api

Urbit Airlock API implementation in Clojure

WIP

Usage

Leiningen

[io.github.sorted-falnyd/clj-airlock-api "..."]

Deps

io.github.sorted-falnyd/clj-airlock-api {:mvn/version "..."}

Require

(ns user
  (:require
   [sorted-falnyd.airlock.client.api :as api]))

Set up a connection

(def conn
  (api/client
   {:port 80
    ;; :ship-name "sampel-planet"
    ;; :code "topse-cret"
    ;; :uri "http://sampel-planet.arvo.network"
    }))

Actions

(require '[sorted-falnyd.airlock.action :as action])

Poke

(api/send! conn (action/poke "hood" "helm-hi" "Knock knock"))

(api/send! conn (action/subscribe "graph-store" "/updates"))
(api/send! conn (action/subscribe "metadata-store" "/all"))

Send posts

(require '[sorted-falnyd.airlock.graph :as graph])
(->> [{:text "I am the post"}]
     (graph/make-post "zod")
     (graph/add-post "zod" "my-chat-1686")
     (api/send! conn))

Convenient posting

(require '[sorted-falnyd.airlock.client.graph.api :as graph.api])


(graph.api/chat!
 conn
 {:post/content [{"text" "Hello, mars"}]
  :resource/name "channel-1-6870"
  :resource/ship "zod"})
  
;;; Or bind the resource dynamically

(graph.api/with-resource #:resource{:name "channel-1-6870", :ship "zod"}
  (graph.api/chat!
   conn
   {:post/content [{"text" "Hello, Mars!"}]}))
   
;;; Author can be explicitly stated

(graph.api/chat!
 conn
 {:post/author "zod"
  :post/content [{"text" "Hello, mars"}]
  :resource/name "channel-1-6870"
  :resource/ship "zod"})

Channel

The connection map contains a core.async channel which receives all incoming messages on the initial subscription channel

(:channel conn)

Further actions, indexing, etc can be performed by subscribing on it.

Parsing updates

The updates coming over a channel and responses to HTTP requests are structurally encoded.

To get back decoded, tagged data, construct a decoder:

(require '[sorted-falnyd.airlock.schema.parser :as parser])
(def decoder (parser/decoder))

A successfully decoded datum will return as a tagged tuple, otherwise, a map containing the error.

A decoded response can be parsed:

(parser/parse-response (decoder datum))

A parsed response will contain a unique key for each response type, :urbit.airlock/response.

Further actions can dispatch on the key instead of parsing the data.

Currently implemented parsers

dm hook
harks
graph update
contact update
metadata update
group update

Development

Schemas

Using ts-json-schema-generator on the urbit API, emit schemas that can be parsed

./node_modules/.bin/ts-json-schema-generator -e all --additional-properties true -f tsconfig.json --type 'Graph'  > ~/Urbit/clj-airlock-api/src/dev/resources/graph-update2.json

Parse the schema to a basic malli schema

(parse-definitions (json/read-value (slurp "graph.json")))

Merge the registries and parse incoming events

Adding a parser

All unqualified function names refer to the sorted-falnyd.airlock.schema.parser.registry namespace.

Add a registry. Either from JSON schema or write one out manually.
Add a dispatch value for the new mark under "Diff" in response-registry.
Load your registry in master-registry.
Add a sorted-falnyd.airlock.schema.parser/parse-diff implementation for the new mark.
Make sure the parsed response contains the key :urbit.airlock/response.

License

Distributed under the Eclipse Public License version 1.0.

sorted-falnyd / clj-airlock-client Goto Github PK

clj-airlock-client's Introduction