urbit-api 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 626e3718491acdc2cd451fc847e489bac5bb4eb1490797bf6417fb9352c8b17b
-  data.tar.gz: a744f2e30e52b901d1e681bdb8a2109f48facd9bcdc45cfc9148a11a0f32d059
+  metadata.gz: 8ffd645b7c5236244e5c081587835863586b11d035d3197e7e286fa223bc3c0f
+  data.tar.gz: 19e8360fbdf96a1149a99dc7218bd835ac3af5338f5ff0b0cfc0c907ea383f27
 SHA512:
-  metadata.gz: 31738b651665457fb50113b26e6f3fe319473bc8112c01ba9fedc58f27c474a62a40a1619ee0c1c765dbf70582f61c54885521a3b53c91bcd30b963ff6ca0d5b
-  data.tar.gz: 36f2bcab1490c8dfe2b83cd875dba0d9571f53f65e7760d0cdfd38ccd8b5eb21753cf039cda46d11cff9f493d9cf4d818397ec36a8b66ea334e79459f8cf3d1c
+  metadata.gz: 84a0d8b5144e08a43080f3d4b0caaecba73e9fd5a74f2d5f1c04f66f1577dc64ebdf44e2fb91716c2ce746b4c96062e0615a24c5a54d760fd1a0ae9ec8b9af36
+  data.tar.gz: 41e5ffab8a9b67bce7c1373ee932ab17834e5684da3de41bb6bc19fa44b115e0fea4472e78e672b4ddd7c74c4e970ba0a20cf9123f27db1d5b763d67ca1f2185

data/README.md

@@ -3,6 +3,8 @@
 
 This library wraps the Urbit ship http interface exposing it as a Ruby gem.
 
+[![awesome urbit badge](https://img.shields.io/badge/~-awesome%20urbit-lightgrey)](https://github.com/urbit/awesome-urbit)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -21,39 +23,107 @@ Or install it yourself as:
 
 ## Usage
 
-```rb
-# TODO: fix namespacing :)
-require 'urbit/urbit'
+```sh
+> bin/console
 
 # This will instantiate a ship that connects to the fake `~zod` dev server by default
 # See Urbit docs for more info: https://urbit.org/using/develop/
-ship = Urbit.new
+[1] pry(main)> ship = Urbit.new
 # => #<Urbit::Ship:0x00007fa74b87f920 ...
 
-ship.logged_in?
+OR... with config file...
+> ship = Urbit.connect(config_file: '_config-barsyr-latreb.yml')
+
+> ship.logged_in?
 # => false
 
-ship.login
+> ship.login
 # => #<Urbit::Ship:0x00007fa74b87f920 ...
 
-ship.logged_in?
+> ship.logged_in?
 # => true
 
-channel = ship.open_channel('my-channel')
-# => #<Urbit::Channel:0x00007fa74b291e50 ...
+> ship.to_s
+# => "a Ship(name: '~barsyr-latreb', host: 'http://localhost', port: '8080')"
 
-channel.key
-# => "16142890875c348d"
+> receiver = ship.subscribe('graph-store', '/updates')
+# => #<Urbit::Receiver:0x00007fd3928eba58
+
+# Subscribing works by opening a Channel. Your ships has a collection of all it's open Channels.
+> channel = ship.open_channels.first
+# => #<Urbit::Channel:0x00007fa74b291e50 ...
 
-ship.channels.first.key
+# Every Channel has a unique key to identify it.
+> channel.key
 # => "16142890875c348d"
 
-receiver = channel.subscribe(app: 'graph-store', path: '/updates')
-# => #<Urbit::Receiver:0x00007fd3928eba58
+# The receiver will now be listening on the app and path you specified. Each time an event is sent in it will be stored in the receiver's facts collection.
+> receiver.facts.count
+=> 12
+
+> receiver.facts.last
+=> {:message=>
+     {"json"=>
+       {"graph-update"=>
+         {"add-nodes"=>
+           {"resource"=>{"name"=>"test0-996", "ship"=>"barsyr-latreb"},
+            "nodes"=>
+             {"/170141184504954066298369929365830487769"=>
+               {"post"=>
+                 {"index"=>"/170141184504954066298369929365830487769",
+                  "author"=>"barsyr-latreb",
+                  "time-sent"=>1615564146267,
+                  "signatures"=>[],
+                  "contents"=>[],
+                  "hash"=>"0x92b0.c976.58f0.3035.c126.64a0.3043.b962"},
+                "children"=>
+                 {"2"=>
+                   {"post"=>
+                     {"index"=>"/170141184504954066298369929365830487769/2",
+                      "author"=>"barsyr-latreb",
+                      "time-sent"=>1615564146267,
+                      "signatures"=>[],
+                      "contents"=>[],
+                      "hash"=>"0x2ffe.3ca7.20eb.11af.51f8.fbab.2b88.9f48"},
+                    "children"=>nil},
+                  "1"=>
+                   {"post"=>
+                     {"index"=>"/170141184504954066298369929365830487769/1",
+                      "author"=>"barsyr-latreb",
+                      "time-sent"=>1615564146267,
+                      "signatures"=>[],
+                      "contents"=>[],
+                      "hash"=>"0x2ffe.3ca7.20eb.11af.51f8.fbab.2b88.9f48"},
+                    "children"=>
+                     {"1"=>
+                       {"post"=>
+                         {"index"=>"/170141184504954066298369929365830487769/1/1",
+                          "author"=>"barsyr-latreb",
+                          "time-sent"=>1615564146267,
+                          "signatures"=>[],
+                          "contents"=>[{"text"=>"Test 0.8"}, {"text"=>"Test 0.8"}],
+                          "hash"=>"0x9516.25fc.ca7a.5bb9.356b.2fce.b29a.f372"},
+                        "children"=>nil}}}}}}}}},
+      "id"=>2,
+      "response"=>"diff"
+    }
+  }
+
+#  Your ship keeps a collection of all the messages sent to urbit:
+> channel.sent_messages.collect {|m| m.to_s}
+=> [
+    "a Message({:action=>"poke", :app=>"hood", :id=>1, :json=>"Opening Airlock", :mark=>"helm-hi", :ship=>"barsyr-latreb"})",
+    "a Message({:action=>"subscribe", :app=>"graph-store", :id=>2, :path=>"/updates", :ship=>"barsyr-latreb"})",
+    "a Message({"id"=>3, "action"=>"ack", "event-id"=>"0"})",
+    "a Message({"id"=>4, "action"=>"ack", "event-id"=>"1"})",
+    "a Message({"id"=>5, "action"=>"ack", "event-id"=>"2"})"
+   ]
+
+# Retrieving your ship's base hash using scry....
+> ship.scry('file-server', '/clay/base/hash', 'json')
+# => {:status=>200, :code=>"ok", :body=>"\"e75k5\""}
 
-# This receiver will now be listening on the app and path you specified. Each time an event is sent in it will be stored in the receiver's events collection.
 ```
-
 ### Configuration
 
 Configure your ship using a config file or constructor keyword arguments. Either or both can be used; the keyword args will override any values set via config file.

data/lib/urbit/ack_message.rb

@@ -1,18 +1,15 @@
-require 'json'
-
-require 'urbit/message'
-
 module Urbit
   class AckMessage < Message
+    attr_reader :ack_id
+
     def initialize(channel, sse_message_id)
-      @action  = 'ack'
-      @channel = channel
-      @id      = 0
+      super(channel, 'ack')
       @ack_id  = sse_message_id
     end
 
     def to_h
-      {'id' => id, 'action' => action, 'event-id' => @ack_id}
+      # Need to use the older hash style due to the key having a dash.
+      {'id' => self.id, 'action' => self.action, 'event-id' => self.ack_id}
     end
   end
 end

data/lib/urbit/api/version.rb

@@ -1,5 +1,5 @@
 module Urbit
   module Api
-    VERSION = "0.1.0"
+    VERSION = "0.1.2"
   end
 end

data/lib/urbit/channel.rb

@@ -1,8 +1,9 @@
-require 'faraday'
 require 'securerandom'
 
 require 'urbit/message'
 require 'urbit/receiver'
+require 'urbit/close_message'
+require 'urbit/poke_message'
 require 'urbit/subscribe_message'
 
 module Urbit
@@ -29,8 +30,11 @@ module Urbit
       !@is_open
     end
 
+    #
+    # We open a channel by "poking" the urbit app 'hood' using the mark 'helm-hi'
+    #
     def open(a_message_string)
-      m = Urbit::Message.new(self, "poke", "hood", "helm-hi", a_message_string)
+      m = Urbit::PokeMessage.new(self, "hood", "helm-hi", a_message_string)
       @is_open = self.send_message(m)
     end
 
@@ -58,6 +62,10 @@ module Urbit
       self.open? ? "Open" : "Closed"
     end
 
+    #
+    # Subscribe to an app at a path.
+    # Returns a Receiver which will begin to get back a stream of facts... which is a... Dictionary? Encyclopedia?
+    #
     def subscribe(app, path)
       m = Urbit::SubscribeMessage.new(self, app, path)
       @is_subscribed = self.send_message(m)

data/lib/urbit/close_message.rb

@@ -0,0 +1,11 @@
+module Urbit
+  class CloseMessage < Message
+    def initialize(channel)
+      super(channel, 'delete')
+    end
+
+    def to_h
+      {id: self.id, action: self.action}
+    end
+  end
+end

data/lib/urbit/message.rb

@@ -1,3 +1,4 @@
+require 'faraday'
 require 'json'
 
 module Urbit
@@ -5,7 +6,7 @@ module Urbit
     attr_accessor :id
     attr_reader :action, :app, :channel, :json, :mark
 
-    def initialize(channel, action, app, mark, json)
+    def initialize(channel, action, app = nil, mark = nil, json = nil)
       @action  = action
       @app     = app
       @channel = channel
@@ -57,16 +58,4 @@ module Urbit
       response
     end
   end
-
-  class CloseMessage < Message
-    def initialize(channel)
-      @action  = 'delete'
-      @channel = channel
-      @id      = 0
-    end
-
-    def to_h
-      {id: id, action: action}
-    end
-  end
 end

data/lib/urbit/poke_message.rb

@@ -0,0 +1,7 @@
+module Urbit
+  class PokeMessage < Message
+    def initialize(channel, app, mark, a_string)
+      super(channel, 'poke', app, mark, a_string)
+    end
+  end
+end

data/lib/urbit/receiver.rb

@@ -4,21 +4,21 @@ require 'urbit/ack_message'
 
 module Urbit
   class Receiver < SSE::Client
-    attr_accessor :events
+    attr_accessor :facts
 
     def initialize(channel)
-      @events = []
+      @facts = []
       @headers = {'cookie' => channel.ship.cookie}
       super(channel.url, {headers: @headers}) do |rec|
         rec.on_event do |event|
           typ = event.type
           dat = JSON.parse(event.data)
-          self.events << {typ => dat}
+          self.facts << {typ => dat}
           channel.send_message(AckMessage.new(channel, event.id))
         end
 
         rec.on_error do |error|
-          self.events += ["I received an error: #{error.class}"]
+          self.facts += ["I received an error fact: #{error.class}"]
         end
       end
     end

data/lib/urbit/ship.rb

@@ -48,31 +48,65 @@ module Urbit
       config.name
     end
 
-    # Opening a channel always creates a new channel which will
-    # remain open until this ship is disconnected at which point it
-    # will be closed.
-    def open_channel(a_name)
-      login
-      (c = Channel.new self, a_name).open("Opening Airlock")
-      self.channels << c
-      c
-    end
-
     def open_channels
       @channels.select {|c| c.open?}
     end
 
+    def scry(app, path, mark)
+      self.login
+      scry_url = "#{self.config.api_base_url}/~/scry/#{app}#{path}.#{mark}"
+
+      response = Faraday.get(scry_url) do |req|
+        req.headers['Accept'] = 'application/json'
+        req.headers['Cookie'] = self.cookie
+      end
+
+      {status: response.status, code: response.reason_phrase, body: response.body}
+    end
+
+    def spider(mark_in, mark_out, thread, data)
+      self.login
+      url = "#{self.config.api_base_url}/spider/#{mark_in}/#{thread}/#{mark_out}.json"
+
+      response = Faraday.post(url) do |req|
+        req.headers['Accept'] = 'application/json'
+        req.headers['Cookie'] = self.cookie
+        req.body = data
+      end
+
+      {status: response.status, code: response.reason_phrase, body: response.body}
+    end
+
+    #
+    # Subscribe to an app at a path.
+    # Returns a Receiver which will begin to get back a stream of facts... which is a... Dictionary? Encyclopedia?
+    #
+    def subscribe(app, path)
+      self.login
+      (c = Channel.new self, self.make_channel_name).open("Creating a Subscription Channel.")
+      self.channels << c
+      c.subscribe(app, path)
+    end
+
     def to_s
       "a Ship(name: '#{self.pat_p}', host: '#{self.config.host}', port: '#{self.config.port}')"
     end
 
     private
 
+    def make_channel_name
+      "Channel-#{self.open_channels.count}"
+    end
+
     def ensure_connections_closed
       # Make sure all our created channels are closed by the GC
       ObjectSpace.define_finalizer( self, self.class.finalize(channels) )
     end
 
+    def login_url
+      "#{config.api_base_url}/~/login"
+    end
+
     def parse_cookie(resp)
       cookie = resp.headers['set-cookie']
       return unless cookie
@@ -80,9 +114,5 @@ module Urbit
       @auth_cookie, @path, @max_age = cookie.split(';')
       self.logged_in = true if @auth_cookie
     end
-
-    def login_url
-      "#{config.api_base_url}/~/login"
-    end
   end
 end

data/lib/urbit/subscribe_message.rb

@@ -1,19 +1,14 @@
-require 'json'
-
 module Urbit
   class SubscribeMessage < Message
     attr_reader :path
 
     def initialize(channel, app, path)
-      @action  = 'subscribe'
-      @app     = app
-      @channel = channel
-      @id      = 0
-      @path    = path
+      super(channel, 'subscribe', app)
+      @path = path
     end
 
     def to_h
-      {action: action, app: app, id: id, path: path, ship: ship.untilded_name}
+      {action: self.action, app: self.app, id: self.id, path: self.path, ship: self.ship.untilded_name}
     end
   end
 end

data/urbit-api.gemspec

@@ -13,8 +13,6 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = Gem::Requirement.new(">= 2.7.2")
 
-  # spec.metadata["allowed_push_host"] = "TODO: Set to 'http://mygemserver.com'"
-
   spec.metadata["homepage_uri"]    = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/Zaxonomy/urbit-ruby"
   spec.metadata["changelog_uri"]   = "https://github.com/Zaxonomy/urbit-ruby/CHANGELOG.md"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: urbit-api
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Daryl Richter
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-02-26 00:00:00.000000000 Z
+date: 2021-04-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -90,8 +90,10 @@ files:
 - lib/urbit/api.rb
 - lib/urbit/api/version.rb
 - lib/urbit/channel.rb
+- lib/urbit/close_message.rb
 - lib/urbit/config.rb
 - lib/urbit/message.rb
+- lib/urbit/poke_message.rb
 - lib/urbit/receiver.rb
 - lib/urbit/ship.rb
 - lib/urbit/subscribe_message.rb