universa 0.1.9 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3393ecdb08b1b7fe37288be48d86b47a740cf7e923575caa45295c8cdb861247
-  data.tar.gz: 76a9a13bdf1a39c8d5e9a0e838a3faf18283d9b357cd3bca18c75f076dbcc65f
+  metadata.gz: ff86a735f983f4cb94e6ca82be229c8c47749d975483fe52d11972a8664853d8
+  data.tar.gz: f1625ae689ba6bd1ff017c2a3926e16e3b6efcc71f90f7896b60ccce19839413
 SHA512:
-  metadata.gz: 44c450550570eb0e447f7824dae25129cfd59ead09cac86c19b8d3b261d226d7964b88ca3304fc19790ca7512509c5ae3575c0aed09da608133de588d1d1548c
-  data.tar.gz: 5b093f28766e602653ad3c9797f4ce6d6a63796c8cd45ab9252b4bd78e145a43aa9510c51370d210d23a97eeab7d4cd14049466f3bc3de0fd933db3b3c1a3467
+  metadata.gz: fd4b45a562f5340511e659fb1019642599b74d431cdb5c8277a168e014ac1c085518798232d6c156de43377a3bdb3eec819ff935518bd107aef65726515f60db
+  data.tar.gz: 00a4544555433540ca9317ee4ce3bb7a090c649b5489809b364e79a36d784d4905f2af5b42534ade5b79b809ba19fe1d98a63ea784aff4cb19bf0aeb3af514ca

data/README.md

@@ -6,6 +6,18 @@ for direct access to remote objects.
 This is an under-construction official gem from [Universa][universa] to facilitate access to the
 Java library using Universa's UMI protocol.  
 
+## News
+
+- alfa version of the local FS-based contract store.
+- ability to edit `contract.state` and `contract.transactional` in new revisions.
+- fixed errors with interchange builder and set based objects
+- ruby sugar for Universa native classes: Role, Adapter, Contract, Binder, HashId.
+- Contract creation, revocation, changing owner in ruby way
+- Network operation for white keys/private networks: parallel state check, contract recistration. 
+
+This gem is already used in new Universa projects and is being actively tested.
+
+
 ## Installation
 
 ### Prerequisites

data/lib/universa.rb

@@ -8,6 +8,9 @@ require "universa/keys"
 require "universa/binder"
 require "universa/contract"
 require "universa/client"
+require 'universa/stored_contract'
+require "universa/chain_store"
+require "universa/fs_store/file_store"
 
 # The Universa gem
 #

data/lib/universa/binder.rb

@@ -68,8 +68,8 @@ module Universa
     end
 
     # @return an array of values returned by the block
-    # @yiekd [key,value] pairs.
-    def map &block
+    # @yield [key,value] pairs.
+    def map(&block)
       keys.map {|k| block.call [k, __getobj__.get(k)]}
     end
 
@@ -86,7 +86,13 @@ module Universa
 
 end
 
+# enhance Hash with UMI access convenience methods.
 class Hash
+  # Convert the hash to the {}Binder} stored in the remote side and suitable for
+  # Universa UMI calls.
+  #
+  # @return [Binder] constructed reference to the remotely created Binder.
+  #
   def to_binder
     Binder.of self
   end

data/lib/universa/chain_store.rb

@@ -0,0 +1,54 @@
+require 'yaml'
+
+module Universa
+
+  # The storage interface capable to store contracts in chains, providing search and attributes.
+  # This class is not a store itself but the base class for it, having common boilerplate and
+  # sort of interface to implement.
+  class ChainStore
+
+    # Save contract to the store. When this method returns, the contract must me already stored.
+    # If the contract with such hasId is already stored, just returns it.
+    #
+    # @param [Object] contract to store
+    # @return [StoredContract] for this contract
+    def store_contract(contract)
+      raise NotImplementedError
+    end
+
+    # Same as {#store_contract} but returns store
+    # @param [Contract] contract to add
+    # @return [ChainStore] self
+    def <<(contract)
+      store_contract(contract)
+      self
+    end
+
+    # @return [Contract] with the corresponding id or nil
+    # @param [HashId] hash_id instance to look for
+    def find_by_id(hash_id)
+      raise NotImplementedError
+    end
+
+    # Count contracts in the store. This operation could be slow.
+    def count
+      raise NotImplementedError
+    end
+
+    # @return [Contract] with the corresponding id or raise.
+    # @param [HashId] hash_id instance to look for
+    # @raise [NotFoundError]
+    def find_by_id! hash_id
+      find_by_id(hash_id) or raise NotFoundError
+    end
+
+    # Find all contracts with this parent id.
+    # @param [HashId] hash_id of the parent contract
+    # @return [Array] all the contracts that match this criterion
+    def find_by_parent(hash_id)
+      raise NotImplementedError
+    end
+
+  end
+
+end

data/lib/universa/client.rb

@@ -172,9 +172,9 @@ module Universa
     # Register a single contract (on private network or if you have white key allowing free operations)
     # on a single node.
     #
-    # @param [Contract] contract, muts be sealed ({Contract#seal})
+    # @param [Contract] contract must be sealed ({Contract#seal})
     # @return [ContractState] of the result. Could contain errors.
-    def register_single contract
+    def register_single(contract)
       retry_with_timeout(15, 3) {
         result = ContractState.new(execute "approve", packedItem: contract.packed)
         while result.is_pending
@@ -205,8 +205,9 @@ module Universa
     # to the node.
     #
     # @param [String|Symbol] name of the command
+    # @param kwargs arguments to call
     # @return [SmartHash] with the command result
-    def execute name, **kwargs
+    def execute(name, **kwargs)
       connection.command name.to_s, *kwargs.to_a.flatten
     end
 

data/lib/universa/contract.rb

@@ -34,11 +34,12 @@ module Universa
       invoke_static 'with_digest', digest_bytes
     end
 
-    # Construct from string representation of the ID, not to confuse with binary one.
+    # Construct from string representation of the ID, not to confuse with binary one. This method takes both
+    # regular base64 representation and RFC3548 url-safe modification, as from {#to_url_safe_string}.
     #
     # @param [String] string_id id string representation, like from +hash_id_instance.to_s+. See {#to_s}.
     def self.from_string(string_id)
-      string_id.force_encoding 'utf-8'
+      string_id.force_encoding('utf-8').gsub('-','+').gsub('_','/')
       invoke_static 'with_digest', string_id
     end
 
@@ -57,6 +58,28 @@ module Universa
     def to_s
       Base64.encode64(get_digest).gsub(/\s/, '')
     end
+
+    # Converts to URL-safe varianot of base64, as RFC 3548 suggests:
+    #     the 63:nd / character with the underscore _
+    #     the 62:nd + character with the minus -
+    #
+    # Could be decoded safely back with {HashId.from_string} but not (most likely) with JAVA API itself
+    # @return [String] RFC3548 modified base64
+    def to_url_safe_string
+      Base64.encode64(get_digest).gsub(/\s/, '').gsub('/','_').gsub('+', '-')
+    end
+
+    # To use it as a hash key_address.
+    # @return hash calculated over the digest bytes
+    def hash
+      bytes.hash
+    end
+
+    # To use it as a hash key_address. Same as this == other.
+    def eql? other
+      self == other
+    end
+
   end
 
   # Universa contract adapter.
@@ -66,17 +89,17 @@ module Universa
     # Create simple contract with preset critical parts:
     #
     # - expiration set to 90 days unless specified else
-    # - issuer role is set to the address of the issuer key, short ot long
+    # - issuer role is set to the address of the issuer key_address, short ot long
     # - creator role is set as link to issuer
     # - owner role is set as link to issuer
     # - change owner permission is set to link to owner
     #
-    # The while contract is then signed by the issuer key. Not that it will not seal it: caller almost always
+    # The while contract is then signed by the issuer key_address. Not that it will not seal it: caller almost always
     # will add more data before it, then must call #seal().
     #
     # @param [PrivateKey] issuer_key also will be used to sign it
     # @param [Time] expires_at defaults to 90 days
-    # @param [Boolean] use_short_address set to true to use short address of the issuer key in the role
+    # @param [Boolean] use_short_address set to true to use short address of the issuer key_address in the role
     # @return [Contract] simple contact, not sealed
     def self.create issuer_key, expires_at: (Time.now + 90 * 24 * 60 * 60), use_short_address: false
       contract = Contract.new
@@ -92,6 +115,7 @@ module Universa
 
     # Load from transaction pack
     def self.from_packed packed
+      packed.nil? and raise ArgumentError, "packed contract required"
       packed.force_encoding 'binary'
       self.invoke_static "fromPackedTransaction", packed
     end
@@ -124,8 +148,10 @@ module Universa
       get_owner
     end
 
-    def owner= key
-      set_owner_key key
+    # Set owner to the key_address, usable only in the simplest case where owner is the single address.
+    # @param [KeyAddress | PublicKey] key_address
+    def owner=(key_address)
+      set_owner_key key_address
     end
 
     # Shortcut for is_ok
@@ -134,16 +160,29 @@ module Universa
     end
 
     # shortcut for getHashId
+    # @return [HashId] of the contracr
     def hash_id
-      get_id
+      getId()
+    end
+
+    # @return [HashId] of the origin contract
+    def origin
+      getOrigin()
     end
 
-    # shortcut for get_expires_at
+    # @return [HashId] pf the parent contracr
+    def parent
+      getParent()
+    end
+
+    # shortcut for get_expires_at. Get the contract expiration time.
     def expires_at
       get_expires_at
     end
 
-    def expires_at= time
+    # set +expires_at+ field
+    # @param [Time] time when this contract will be expired, if yet +APPROVED+.
+    def expires_at=(time)
       set_expires_at time
     end
 
@@ -152,6 +191,7 @@ module Universa
       @definition ||= get_definition.get_data
     end
 
+    # Return +state+ binder. Shortcut for Java API +getStateData()+
     def state
       @state ||= getStateData()
     end
@@ -175,7 +215,7 @@ module Universa
     # Write helper for many token-like contracts containing state.data.amount. Saves value
     # in state.data.anomount and properly encodes it so it will be preserved on packing.
     #
-    # @param [Object] value, should be some representation of a number (also string)
+    # @param [Object] value should be some representation of a number (also string)
     def amount= (value)
       state[:amount] = value.to_s.force_encoding('utf-8')
     end
@@ -203,7 +243,11 @@ module Universa
       getErrors.map {|e| "(#{e.object || ''}): #{e.error}"}.join(', ').strip
     end
 
-    def can_perform_role name, *keys
+    # Test that some set of keys could be used to perform some role.
+    #
+    # @param [String] name of the role to check
+    # @param [PublicKey] keys instances to check against
+    def can_perform_role(name, *keys)
       getRole(name.to_s).isAllowedForKeys(Set.new keys.map {|x|
         x.is_a?(PrivateKey) ? x.public_key : x
       })

data/lib/universa/errors.rb

@@ -16,6 +16,16 @@ module Universa
     end
   end
 
+  class StoreError < Error;
+  end
+
+  class NotFoundError < StoreError
+  end
+
+  class IllegalStateError < StoreError
+
+  end
+
   # Easy print stack trace refinement
   refine Exception do
 

data/lib/universa/fs_store/entry.rb

@@ -0,0 +1,118 @@
+module Universa::FSStore
+
+  # The {StoredContract} implementation to work with {FileStore}.
+  #
+  # @!method name
+  #   @return [String] the +contract.definition.data.name+ value or nil.
+  #
+  # @!method currency
+  #   @return [String] the +contract.definition.data.currency+ value or nil.
+  #
+  # @!method amount
+  #   @return [BigDecimal] +contract.state.data.amount+ or nil. See {Contract#amount} for more.
+  #
+  class Entry < Universa::StoredContract
+
+    extend Forwardable
+
+    # (see StoredContract#load)
+    def load(hash_id)
+      init_with_hash_id hash_id
+      self
+    end
+
+    # initialize new instance with an existing contract
+    # @param [Contract] contract to store
+    def init_with_contract(contract)
+      self.contract = contract
+      self
+    end
+
+    # initialize new instance with attributes YAML file
+    # @param [String] file_name of the +.unicon.yaml+ file
+    def load_from_yaml_file(file_name)
+      init_with_yaml_file_name file_name
+      self
+    end
+
+    # (see StoredContract#hash_id)
+    def hash_id
+      @id
+    end
+
+    # (see StoredContract#contract=)
+    def contract= new_contract
+      @id = new_contract.hash_id
+      prepare_file_names
+      super
+      # we will always rewrite existing file to be sure it is correct
+      open(@file_name, 'wb') {|f| f << contract.packed}
+      # now we are to extract and rewrite attributes
+      load_attributes_from_contract # it will save them too
+    end
+
+    # Implement lazy load logic
+    # @return [Contract] instance loaded at first call only
+    def contract
+      # load it if it is not
+      self.packed_contract = open(@file_name, 'rb') {|f| f.read} unless has_contract?
+      # @attributes must already be set
+      super
+    end
+
+    def_delegators :@attributes, :name, :currency, :amount
+
+    protected
+
+    # initialize instance for an existing file. Should be a contract already stored in the connected store.
+    # @param [Object] hash_id to construct from
+    def init_with_hash_id(hash_id)
+      raise IllegalStateError, "already initialized" if @id
+      @id = hash_id
+      prepare_file_names
+      load_attributes_from_file
+      # attrs are already in the file so we need not to save them
+    end
+
+    # Load from attributes file name
+    def init_with_yaml_file_name file_name
+      @attr_file_name = file_name
+      load_attributes_from_file
+      prepare_file_names
+    end
+
+    # save attributes to .yaml file
+    def save_attributes
+      open(@attr_file_name, 'w') {|f| YAML.dump(@attributes, f)}
+    end
+
+    # load attributes from a contract (already assigned) and store them in the .yaml file
+    def load_attributes_from_contract
+      state = contract.state
+      definition = contract.definition
+      @attributes = SmartHash.new({
+                                      id: hash_id.to_s,
+                                      parent: parent&.to_s,
+                                      origin: origin.to_s,
+                                      name: definition.name,
+                                      currency: definition.currency,
+                                      amount: state.amount
+                                  })
+      save_attributes
+    end
+
+    # load attributes from the .yaml file
+    def load_attributes_from_file
+      @attributes = SmartHash.new(YAML.load_file(@attr_file_name))
+      @id = HashId.from_string @attributes.id
+    end
+
+    # prepare file name fields (@file_name and @attr_file_name)
+    # @param [HashId] hash_id or ni to use one already set in @id
+    def prepare_file_names(hash_id = nil)
+      @file_name = "#{chain_store.root}/#{@id.to_url_safe_string[0..27]}.unicon"
+      @attr_file_name = "#@file_name.yaml"
+    end
+  end
+
+end

data/lib/universa/fs_store/file_store.rb

@@ -0,0 +1,63 @@
+require 'forwardable'
+require_relative './entry'
+
+# Filesystem-based storage. See {FileStore}.
+module Universa::FSStore
+
+  # Simple file-based store that could be efficiently user with per-file cloud storages like Dropbox,
+  # Google Disk, NextCloud and like.
+  #
+  # Notes to developers:
+  #
+  # - attributes are eager loaded: should always be contructed from contract or from file
+  # - contract is lazy loaded
+  class FileStore < Universa::ChainStore
+
+    # [String] The file store root path
+    attr :root
+
+    # Construct store in the path supplied. If the path is not empty, it will be scanned for stored contracts.
+    # @param [String] root_path of the store, must exist.
+    def initialize(root_path)
+      @root = root_path
+      @root = @root[0...-1] while (@root[-1] == '/')
+      init_cache
+    end
+
+    # (see ChainStore#store_contract)
+    def store_contract contract
+      entry = FSStore::Entry.new(self)
+      entry = entry.init_with_contract(contract)
+      add_to_cache entry
+    end
+
+    # (see ChainStore#find_by_id)
+    def find_by_id hash_id
+      @cache[hash_id]
+    end
+
+    # (see ChainStore#count)
+    def count
+      @cache.size
+    end
+
+    protected
+
+    # scan the root folder for attribute files and store them in the cache
+    def init_cache
+      @cache = {}
+      Dir[@root + "/*.unicon.yaml"].each {|name|
+        add_to_cache Entry.new(self).load_from_yaml_file(name)
+      }
+    end
+
+    # add single entry to the cache
+    # @param [Entry] entry to add. Could have contract not yet loaded but should be configured with attributes.
+    def add_to_cache(entry)
+      raise ArgumentError, "entry can't be nil" unless entry
+      @cache[entry.hash_id] = entry
+    end
+
+  end
+
+end

data/lib/universa/stored_contract.rb

@@ -0,0 +1,76 @@
+module Universa
+
+  # this is a base class for a contract stored in some contract chain. The implementation
+  # must inherit and implement its {#load} and {#save} methods at least. To do it,
+  # inherit and implement {ChainStore} to work with it.
+  #
+  # Notable features:
+  #
+  # - contract could be assigned only once, no matter how, so its fields could be cached.
+  # - origin, hash_id and parent are cached. So other contract parameters should be.
+  #
+  class StoredContract
+
+    # {ChainStore} instance to which it is connected
+    attr :chain_store
+    # {Contract} instance stored in it. Can be lazy-loaded
+    attr :contract
+    # {HashId} of the {#contract}
+    attr :hash_id
+
+    # @return [HashId] {#contract}.origin. See {Contract#origin}
+    def origin
+      @origin ||= @contract.origin
+    end
+
+    # @return [HashId] {#contract}.origin. See {Contract#parent}
+    def parent
+      @parent ||= @contract.parent
+    end
+
+    # Construct implementation connected to a given store
+    # @param [ChainStore] chain_store descendant class
+    def initialize(chain_store)
+      @chain_store = chain_store
+      @chain_store.is_a?(ChainStore) or raise ArgumentError, "ChainStore instance required"
+      @chain_store = chain_store
+    end
+
+    # For implementation logic, in particular, to make lazy loads.
+    # @return true if the stored contract is loaded into this instance
+    def has_contract?
+      !@contract.nil?
+    end
+
+    # Shortcut for `contract.packed`. See {Contract#packed}
+    # @return [String] binary string with contained contract packed transaction.
+    def packed_contract
+      @contract.packed
+    end
+
+    # override it to save the contract in the connected contract chain.
+    def save
+      raise NotFoundError
+    end
+
+    # override it to load the contract from the connected contract chain.
+    def load hash_id
+      raise NotFoundError
+    end
+
+    # Assign contract to the instance.
+    # @param [Contracy] new_contract to store
+    def contract=(new_contract)
+      raise IllegalStateError, "contract can't be reassigned" if has_contract?
+      @contract = new_contract
+      @hash_id = @contract.hash_id
+      @origin = @parent = nil
+    end
+
+    # Convenience method. Unoacks and stores the contract.
+    def packed_contract=(new_packed_contract)
+      self.contract = Contract.from_packed(new_packed_contract)
+    end
+
+  end
+end

data/lib/universa/tools.rb

@@ -7,14 +7,16 @@ module Universa
   class SmartHash < Farcall::SmartHash
   end
 
-  def retry_with_timeout(max_timeout = 15, max_times = 3, &block)
+  def retry_with_timeout(max_timeout = 25, max_times = 3, &block)
     attempt = 0
-    Timeout::timeout(max_timeout, &block)
-  rescue
-    attempt += 1
-    puts "timeout: retry (#$!): #{attempt}"
-    retry if attempt < max_times
-    raise
+    begin
+      Timeout::timeout(max_timeout, &block)
+    rescue
+      attempt += 1
+      puts "timeout: retry (#$!): #{attempt}"
+      retry if attempt < max_times
+      raise
+    end
   end
 
   module Parallel
@@ -26,7 +28,7 @@ module Universa
 
       @@pool = CachedThreadPool.new
 
-      # Enumerates in parallel all items. Like {Enumerable#each_with_index}, but requires block.
+      # Enumerates in parallel all items. Like +Enumerable#each_with_index+, but requires block.
       # Blocks until all items are processed.
       #
       # @param [Proc] block to call with (object, index) parameters
@@ -55,7 +57,7 @@ module Universa
         each_with_index {|x, i| block.call(x)}
       end
 
-      # Parallel version of the {Enumerable#map}. Creates a new array containing the values returned by the block,
+      # Parallel version of the +Enumerable#map+. Creates a new array containing the values returned by the block,
       # using parallel execution in threads.
       #
       # @return new array containing the values returned by the block.

data/lib/universa/version.rb

@@ -1,4 +1,4 @@
 module Universa
   # Current gem version
-  VERSION = "0.1.9"
+  VERSION = "0.2.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: universa
 version: !ruby/object:Gem::Version
-  version: 0.1.9
+  version: 0.2.1
 platform: ruby
 authors:
 - sergeych
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-11-30 00:00:00.000000000 Z
+date: 2018-12-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: farcall
@@ -154,11 +154,15 @@ files:
 - exe/universa
 - lib/universa.rb
 - lib/universa/binder.rb
+- lib/universa/chain_store.rb
 - lib/universa/client.rb
 - lib/universa/contract.rb
 - lib/universa/errors.rb
+- lib/universa/fs_store/entry.rb
+- lib/universa/fs_store/file_store.rb
 - lib/universa/keys.rb
 - lib/universa/service.rb
+- lib/universa/stored_contract.rb
 - lib/universa/string_utils.rb
 - lib/universa/tools.rb
 - lib/universa/umi.rb
@@ -185,7 +189,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.7.3
+rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
 summary: Expose Universa Java API to ruby