urbit-api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 626e3718491acdc2cd451fc847e489bac5bb4eb1490797bf6417fb9352c8b17b
+  data.tar.gz: a744f2e30e52b901d1e681bdb8a2109f48facd9bcdc45cfc9148a11a0f32d059
+SHA512:
+  metadata.gz: 31738b651665457fb50113b26e6f3fe319473bc8112c01ba9fedc58f27c474a62a40a1619ee0c1c765dbf70582f61c54885521a3b53c91bcd30b963ff6ca0d5b
+  data.tar.gz: 36f2bcab1490c8dfe2b83cd875dba0d9571f53f65e7760d0cdfd38ccd8b5eb21753cf039cda46d11cff9f493d9cf4d818397ec36a8b66ea334e79459f8cf3d1c

data/.gitignore

@@ -0,0 +1,25 @@
+_config-*.yml
+*.gem
+*.rbc
+/coverage/
+/pkg/
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+Gemfile.lock
+.ruby-version
+# .ruby-gemset

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/CHANGELOG.md

@@ -0,0 +1 @@
+Nothing to see here.

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in urbit-api.gemspec
+gemspec
+
+gem "rake", "~> 12.0"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Daryl Richter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.gem.md

@@ -0,0 +1,4 @@
+
+Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/urbit/ruby`. To experiment with that code, run `bin/console` for an interactive prompt.
+
+TODO: Delete this and the text above, and describe your gem

data/README.md

@@ -0,0 +1,107 @@
+# Urbit::Api
+## The Ruby interface to the Urbit HTTP API
+
+This library wraps the Urbit ship http interface exposing it as a Ruby gem.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'urbit-api'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install urbit-api
+
+## Usage
+
+```rb
+# TODO: fix namespacing :)
+require 'urbit/urbit'
+
+# 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
+# => #<Urbit::Ship:0x00007fa74b87f920 ...
+
+ship.logged_in?
+# => false
+
+ship.login
+# => #<Urbit::Ship:0x00007fa74b87f920 ...
+
+ship.logged_in?
+# => true
+
+channel = ship.open_channel('my-channel')
+# => #<Urbit::Channel:0x00007fa74b291e50 ...
+
+channel.key
+# => "16142890875c348d"
+
+ship.channels.first.key
+# => "16142890875c348d"
+
+receiver = channel.subscribe(app: 'graph-store', path: '/updates')
+# => #<Urbit::Receiver:0x00007fd3928eba58
+
+# 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.
+
+Supported keys:
+- `code` - the auth code
+- `host` - the ship's host (e.g., 'localhost' or 'myship.net')
+- `name` - the ship's name (e.g, '~zod')
+- `port` - the open www port on your ship ('80' by default)
+
+#### Config File
+
+See [`_config.yml`](_config.yml) for an example config file. This will connect to a local fake zod, see creation instructions below.
+
+```rb
+ship = Urbit.new(config_file: 'my-moon.yml')
+```
+
+#### Constructor Keyword Arguments
+
+```rb
+ship = Urbit.new(host: '127.0.0.1', port: '8080')
+```
+
+## Testing
+
+```sh
+bin/test
+```
+### ~zod
+
+Tests assume that an instance of a ["fake" development Urbit ship](https://urbit.org/using/develop/) (one not connected to the live network) will be running, available at `http://localhost:8080`.
+
+To create a development ship:
+```sh
+./urbit -F zod
+```
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/urbit-api.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task :default => :test

data/_config.yml

@@ -0,0 +1,2 @@
+code: 'lidlut-tabwed-pillex-ridrup'
+ship: '~zod'

data/bin/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "pry"
+require "urbit/urbit"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+puts "e.g., ship = Urbit.new(config_file: 'my_config.yml')"
+Pry.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/bin/test

@@ -0,0 +1,2 @@
+#!/bin/sh
+bundle exec rspec -f d spec

data/lib/urbit/ack_message.rb

@@ -0,0 +1,18 @@
+require 'json'
+
+require 'urbit/message'
+
+module Urbit
+  class AckMessage < Message
+    def initialize(channel, sse_message_id)
+      @action  = 'ack'
+      @channel = channel
+      @id      = 0
+      @ack_id  = sse_message_id
+    end
+
+    def to_h
+      {'id' => id, 'action' => action, 'event-id' => @ack_id}
+    end
+  end
+end

data/lib/urbit/api.rb

@@ -0,0 +1,26 @@
+require "urbit/api/version"
+
+module Urbit
+  module Api
+    class Config
+      def initialize
+        require 'yaml'
+        config_file = YAML.load_file('_config.yml.example')
+        @ship_code = config_file['code']
+        @ship_name = config_file['ship']
+      end
+
+      def ship_code
+        @ship_code
+      end
+
+      def ship_name
+        @ship_name
+      end
+    end
+
+    class Error < StandardError;
+    end
+
+  end
+end

data/lib/urbit/api/version.rb

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

data/lib/urbit/channel.rb

@@ -0,0 +1,79 @@
+require 'faraday'
+require 'securerandom'
+
+require 'urbit/message'
+require 'urbit/receiver'
+require 'urbit/subscribe_message'
+
+module Urbit
+  class Channel
+    attr_accessor :messages
+    attr_reader :key, :name, :ship
+
+    def initialize(ship, name)
+      @ship          = ship
+      @key           = "#{Time.now.to_i}#{SecureRandom.hex(3)}"
+      @messages      = []
+      @name          = name
+      @is_open       = false
+      @is_subscribed = false
+    end
+
+    def close
+      # puts "closing #{name}"
+      m = Urbit::CloseMessage.new(self)
+      @is_open = !self.send_message(m)
+    end
+
+    def closed?
+      !@is_open
+    end
+
+    def open(a_message_string)
+      m = Urbit::Message.new(self, "poke", "hood", "helm-hi", a_message_string)
+      @is_open = self.send_message(m)
+    end
+
+    def open?
+      @is_open
+    end
+
+    def queue_message(a_message)
+      a_message.id = self.sent_messages.size + 1
+      @messages << a_message
+    end
+
+    # Answers true if message was successfully sent.
+    def send_message(a_message)
+      self.queue_message(a_message)
+      resp = a_message.transmit
+      resp.reason_phrase == "ok"
+    end
+
+    def sent_messages
+      @messages
+    end
+
+    def status
+      self.open? ? "Open" : "Closed"
+    end
+
+    def subscribe(app, path)
+      m = Urbit::SubscribeMessage.new(self, app, path)
+      @is_subscribed = self.send_message(m)
+      receiver = Urbit::Receiver.new(self)
+    end
+
+    def subscribed?
+      @is_subscribed
+    end
+
+    def to_s
+      "a Channel (#{self.status}) on #{self.ship.name}(name: '#{self.name}', key: '#{self.key}')"
+    end
+
+    def url
+      "http://localhost:8080/~/channel/#{self.key}"
+    end
+  end
+end

data/lib/urbit/config.rb

@@ -0,0 +1,36 @@
+require 'yaml'
+
+module Urbit
+  #  Injected into a Ship to provide configuration
+  class Config
+    attr_reader :code, :config_file, :host, :port, :name
+
+    DEFAULT_CODE        = 'lidlut-tabwed-pillex-ridrup'.freeze
+    DEFAULT_CONFIG_FILE = '_config.yml'.freeze
+    DEFAULT_HOST        = 'http://localhost'.freeze
+    DEFAULT_PORT        = '8080'.freeze
+    DEFAULT_NAME        = '~zod'.freeze
+
+    def initialize(code: nil,  config_file: nil, host: nil, name: nil, port: nil)
+      @config_file = config_file || DEFAULT_CONFIG_FILE
+      @code = code || loaded_config['code'] || DEFAULT_CODE
+      @host = host || loaded_config['host'] || DEFAULT_HOST
+      @name = name || loaded_config['ship'] || DEFAULT_NAME
+      @port = port || loaded_config['port'] || DEFAULT_PORT
+    end
+
+    def api_base_url
+      @api_base_url ||= "#{host}:#{port}"
+    end
+
+    private
+
+    def loaded_config
+      @loaded_config ||= begin
+        return {} unless File.exist?(config_file)
+
+        YAML.load_file(config_file)
+      end
+    end
+  end
+end

data/lib/urbit/message.rb

@@ -0,0 +1,72 @@
+require 'json'
+
+module Urbit
+  class Message
+    attr_accessor :id
+    attr_reader :action, :app, :channel, :json, :mark
+
+    def initialize(channel, action, app, mark, json)
+      @action  = action
+      @app     = app
+      @channel = channel
+      @id      = 0
+      @json    = json
+      @mark    = mark
+    end
+
+    def channel_url
+      "#{self.ship.config.api_base_url}/~/channel/#{self.channel.key}"
+    end
+
+    def request_body
+      self.to_a.to_json
+    end
+
+    def ship
+      self.channel.ship
+    end
+
+    def to_a
+      [self.to_h]
+    end
+
+    def to_h
+      {
+        action: action,
+        app:    app,
+        id:     id,
+        json:   json,
+        mark:   mark,
+        ship:   ship.untilded_name
+      }
+    end
+
+    def to_s
+      "a Message(#{self.to_h})"
+    end
+
+    def transmit
+      response = Faraday.put(channel_url) do |req|
+        req.headers['Cookie'] = self.ship.cookie
+        req.headers['Content-Type'] = 'application/json'
+        req.body = request_body
+        # puts req.body.to_s
+      end
+
+      # TODO: handle_error if response.status != 204
+      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/receiver.rb

@@ -0,0 +1,27 @@
+require 'ld-eventsource'
+
+require 'urbit/ack_message'
+
+module Urbit
+  class Receiver < SSE::Client
+    attr_accessor :events
+
+    def initialize(channel)
+      @events = []
+      @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}
+          channel.send_message(AckMessage.new(channel, event.id))
+        end
+
+        rec.on_error do |error|
+          self.events += ["I received an error: #{error.class}"]
+        end
+      end
+    end
+
+  end
+end

data/lib/urbit/ship.rb

@@ -0,0 +1,88 @@
+require 'faraday'
+
+require 'urbit/channel'
+require 'urbit/config'
+
+module Urbit
+  class Ship
+    attr_accessor :logged_in
+    attr_reader :auth_cookie, :channels, :config
+
+    def initialize(config: Config.new)
+      @auth_cookie = nil
+      @channels    = []
+      @config      = config
+      @logged_in   = false
+    end
+
+    def self.finalize(channels)
+      proc { channels.each { |c| c.close } }
+    end
+
+    def logged_in?
+      logged_in
+    end
+
+    def cookie
+      auth_cookie
+    end
+
+    def login
+      return self if logged_in?
+
+      ensure_connections_closed
+      response = Faraday.post(login_url, "password=#{config.code}")
+      parse_cookie(response)
+      self
+    end
+
+    def name
+      config.name
+    end
+
+    def untilded_name
+      name.gsub('~', '')
+    end
+
+    def pat_p
+      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 to_s
+      "a Ship(name: '#{self.pat_p}', host: '#{self.config.host}', port: '#{self.config.port}')"
+    end
+
+    private
+
+    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 parse_cookie(resp)
+      cookie = resp.headers['set-cookie']
+      return unless cookie
+
+      @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

@@ -0,0 +1,19 @@
+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
+    end
+
+    def to_h
+      {action: action, app: app, id: id, path: path, ship: ship.untilded_name}
+    end
+  end
+end

data/lib/urbit/urbit.rb

@@ -0,0 +1,24 @@
+require_relative './config'
+require_relative './ship'
+
+# This is the main namespace for Urbit.
+#
+# It provides a method to create {Urbit::Ship} objects.
+#
+# @example Helpful class method `.new` to create {Urbit::Ship} objects.
+#   ship = Urbit.new(port: 80)
+#   conn.get '/'
+module Urbit
+  class << self
+    def connect(**config_options)
+      config = Urbit::Config.new(**config_options)
+      ship = Urbit::Ship.new(config: config)
+      ship.login
+    end
+
+    def new(**config_options)
+      config = Urbit::Config.new(**config_options)
+      Urbit::Ship.new(config: config)
+    end
+  end
+end

data/urbit-api.gemspec

@@ -0,0 +1,37 @@
+require_relative 'lib/urbit/api/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "urbit-api"
+  spec.version       = Urbit::Api::VERSION
+  spec.authors       = ["Daryl Richter"]
+  spec.email         = ["daryl@deliverycircle.com"]
+
+  spec.summary       = %q{The Ruby interface to the Urbit HTTP API}
+  spec.description   = %q{Access your urbit ship the ruby way. It's a Martian gem.}
+  spec.homepage      = "https://www.ngzax.com"
+  spec.license       = "MIT"
+
+  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"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "faraday",        "~> 1.3.0"
+  spec.add_dependency "ld-eventsource", "~> 2.0.0"
+
+  spec.add_development_dependency "pry",   "~> 0.13"
+  spec.add_development_dependency "rspec", "~> 3.10"
+end

metadata

@@ -0,0 +1,126 @@
+--- !ruby/object:Gem::Specification
+name: urbit-api
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Daryl Richter
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2021-02-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.3.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.3.0
+- !ruby/object:Gem::Dependency
+  name: ld-eventsource
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.10'
+description: Access your urbit ship the ruby way. It's a Martian gem.
+email:
+- daryl@deliverycircle.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".ruby-version"
+- CHANGELOG.md
+- Gemfile
+- LICENSE.txt
+- README.gem.md
+- README.md
+- Rakefile
+- _config.yml
+- bin/console
+- bin/setup
+- bin/test
+- lib/urbit/ack_message.rb
+- lib/urbit/api.rb
+- lib/urbit/api/version.rb
+- lib/urbit/channel.rb
+- lib/urbit/config.rb
+- lib/urbit/message.rb
+- lib/urbit/receiver.rb
+- lib/urbit/ship.rb
+- lib/urbit/subscribe_message.rb
+- lib/urbit/urbit.rb
+- urbit-api.gemspec
+homepage: https://www.ngzax.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://www.ngzax.com
+  source_code_uri: https://github.com/Zaxonomy/urbit-ruby
+  changelog_uri: https://github.com/Zaxonomy/urbit-ruby/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.4
+signing_key:
+specification_version: 4
+summary: The Ruby interface to the Urbit HTTP API
+test_files: []