thron 0.7.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 828717f3d643a94ede20ded4f7d5ffec9515244c
+  data.tar.gz: 6ac41767ca932862c830b22933651e49b8d68e45
+SHA512:
+  metadata.gz: a37a51677d948af316337b411a051add6b6d78717fb20d2531076912040559349f4a2ec7023523d12e93ce41eb48fd29c65f0f60cc421e86ea880045ab1bfe30
+  data.tar.gz: 6f21a2b5e729e4cef36063593218acad88c46c838c4ebc37a6bfa687a04823a7d7223d6b4b8f12cbfcd13b841e2e3e025477722824109c25e0bd9df90eade41c

data/.env.example

@@ -0,0 +1,4 @@
+THRON_CLIENT_ID=<the client id subscribed to Thron APIs>
+VERBOSE=<a boolean indicating if the remote calls has to be printed on screen, useful when dealing with REPL>
+LOGGER_LEVEL=<the logger level you want, default to WARN>
+CIRCUIT_BREAKER_THRESHOLD=<the number of tries before circuit breaker open the circuit in case of communication issues, set to zero to disable the circuit breaker>

data/.gitignore

@@ -0,0 +1,13 @@
+.env
+/tags
+/.vagrant/
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.gem

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - 2.1.8
+  - 2.2.1
+  - 2.3.0
+before_install: gem install bundler -v 1.11.2

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in thron.gemspec
+gemspec

data/README.md

@@ -0,0 +1,182 @@
+## Table of Contents
+* [Warning](#warning)
+* [Scope](#scope)
+* [Setup](#setup)
+* [HTTPArty](#httparty)
+* [Architecture](#architecture)
+  * [Gateways](#gateways)
+    * [Routing](#routing)
+    * [Paginator](#paginator)
+  * [Response](#response)
+  * [Dynamic Entities](#dynamic-entities)
+  * [User Aggregate](#user-aggregate)
+* [Interface](#interface)
+  * [Access](#access)
+  * [Contents](#contents)
+  * [Groups](#groups)
+  * [Categories](#categories)
+  * [Disguise](#disguise)
+
+## Warning
+I do not maintain this gem anymore. Please do copy with latest Thron APIs and integrate them into this facade if you need to use it.
+
+## Scope
+This gem provides a simple Ruby client for the [Thron](https://developer.4me.it/index.php) (ex 4me) APIs.
+The aim of this gem is to provide a simple interface for your ruby application
+that need to communicate with Thron services. 
+I've also managed to keep the gem's dependencies footprint as small as possible (i
+hate bulky Gemfile...).
+
+## Setup
+This gem use at least a **Ruby 2.1** compatible parser.  
+Thron is a payment service, is assumed you have a valid account in order to use this gem.  
+Once you have valid credentials to access the Thron APIs, you have to enter the **THRON_CLIENT_ID** value
+inside of your *.env* file, this way the gem can reads from it and configure itself properly.
+
+## HTTParty
+This gem uses the [HTTParty](https://github.com/jnunemaker/httparty) library to communicate with the Thron APIs.
+HTTParty has proven to be reliable and simple, so it's a natural candidate.
+
+## Architecture
+This gem is architected on these concepts:
+
+### Gateways
+Several gateways objects are used to communicate with the Thron APIs: each of them
+mimic the original Thron API namespace (find a complete list on Thron site).
+Each gateway derive from a basic class, which includes the HTTParty interface.
+
+#### Routing
+A simple routing engine is encapsulated into the gateway objects: a class-level
+hash declares the routes that matches the API name, by specifying the
+format and verb.  
+Some extra parameters are used to factory the route URL, in some cases lazily (by returning a proc object), since some APIs need to access the method arguments early to compose the URL.
+
+#### Paginator
+Thron APIs that return a list of results are limited to a maximum of **50**.  
+To avoid repeating the same call many times by passing an augmented offset, 
+is possible to call a wrapper method on the gateway objects that returns a paginator object.
+Once the paginator is loaded, it allows to navigate the results by using the following interface:
+* **next**: loads the first offset and move forward, returning last when max offset is reached
+* **prev**: move backwards from the current offset, returning first when minimum offset is reached
+* **preload**: does not move the offset, but indeed preload the specified number of
+  data by performing an asynchronous call (wrapped in a thread).
+
+Paginator keeps an internal cache to avoid hitting the remote service more than
+once. The same is used when preloading results. Keep that in mind when you need to get fresh data.
+
+### Response
+The HTTParty response has been wrapped in order to return a logical object that wraps the APIs return values.  
+The main attributes are:
+* http_code: the HTTP code of the response
+* body: the body of the response, in case the result is JSON data, it contains the data parsed into an appropriate entity (read below)
+* total: in case the API returns a list of results, it indicates the total number of records; it's used by paginator
+* error: the error message, if any, returned by the API
+
+### Dynamic Entities
+Some of the Thron APIs return a JSON representation of an entity. I have initially
+considered wrapping each entity into its own PORO object, but gave up after few
+days since the quality of the returned entities is very large.  
+I opted instead to wrap returned data into a sub-class of the OpenStruct object, having the same
+dynamic behaviour while adding some sugar features:
+* it converts the lower-camel-case parameters into (more rubesque) snake-case
+* it does recursive mapping of nested attributes
+* it converts time and date values to appropriate Ruby objects  
+The same object can be used when passing complex parameters to some of the APIs: in this case is sufficent to call the *#to_payload* method on the entity
+to convert the object in an hash with lower-camle-case keys (see examples below).
+
+### User Aggregate
+To avoid accessing the multitude of Thron APIs via several objects, an aggregate has been created (DDD anyone?).  
+The **User** aggregate delegates most of its methods directly to the gateway objects (it uses the *Forwardable* module).
+It keeps a registry of the gateway objects in order to refresh them on login: this
+is requested to update the token id that identifies the current session and that is
+stored internally by the gateway objects.
+
+To create the user aggregate simply instantiate it without arguments:
+```ruby
+user = Thron::User::new
+```
+
+## Interface
+The following examples illustrates how to use this library.
+Thron APIs include a broad range of methods, for a complete list of them please  consult the [official APIs documentation](https://developer.thron.com/index.php).  
+For the APIs that accepts composed arguments simply use the dynamic entity described
+above: just be aware to name its attributes by snake-case and not as the 
+lower-camel-case specified in the Thron documentation.
+
+### Access
+To get a valid session token just login with your credentials:
+```ruby
+user.login(username: '<your_username>', password: '<your_password>')
+```
+From here you can check current user with the available methods, for example:
+```ruby
+user.validate_token
+```
+Or you can query the APIs to return other details:
+```ruby
+user.user_detail(username: '<a_username>')
+```
+Uploads the avatar image for a user (it relies on Linux *file* system call):
+```ruby
+avatar = Thron::Entity::Image::new(path: '<path_to_an_image>').to_payload
+user.update_image(username: '<a_username>', image: avatar)
+```
+
+### Contents
+Thron is all about managing users contents, so no surprise there is a plethora of
+methods at your disposal:
+
+Find the contents by using the paginator object:
+```ruby
+paginator = user.find_contents_paginator
+paginator.preload(10) # preload the first 10 calls
+paginator.next        # fetch first result set from preloaded cache
+```
+Show the contents by category (slightly more efficient):
+```ruby
+user.show_contents(category_id: '<a_category_id>')
+```
+Load specific content detail:
+```ruby
+user.content_detail(content_id: '<a_content_id>')
+```
+
+### Groups
+Users are arranged into different groups.
+
+Create a new group:
+```ruby
+group = Thron::Entity::Base::new(active: true, name: 'my new group').to_payload
+user.create_group(data: group)
+```
+List existing groups:
+```ruby
+paginator = user.find_gropus
+paginator.next
+```
+
+### Categories
+Thron contents are organized by categories.
+
+List existing categories (without paginator):
+```ruby
+user.find_categories
+```
+Create a new locale for a category:
+```ruby
+locale = Thron::Entity::Base::new(name: 'photos', description: 'JPG and PNG images', locale: 'EN').to_payload
+user.create_category_locale(category_id: '<a_category_id>', locale: locale)
+```
+
+### Disguise
+Thron APIs allow to disguise another user via its apps sub-system.
+
+Disguising only works inside the block:
+```ruby
+user.disguise(app_id: '<app_id_that_can_disguise>', username: '<username_to_disguise>') do
+  # load the disguised user contents, each gateway will now use the disguised token id
+  contents = user.find_contents
+  # do something with contents
+end
+# finished disguising, it returns disguised token id
+```

data/Rakefile

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

data/Vagrantfile

@@ -0,0 +1,80 @@
+# -*- mode: ruby -*-
+# vi: set ft=ruby :
+
+# All Vagrant configuration is done below. The "2" in Vagrant.configure
+# configures the configuration version (we support older styles for
+# backwards compatibility). Please don't change it unless you know what
+# you're doing.
+Vagrant.configure(2) do |config|
+  # The most common configuration options are documented and commented below.
+  # For a complete reference, please see the online documentation at
+  # https://docs.vagrantup.com.
+
+  # Every Vagrant development environment requires a box. You can search for
+  # boxes at https://atlas.hashicorp.com/search.
+  config.vm.box = "ubuntu/trusty64"
+
+  # Disable automatic box update checking. If you disable this, then
+  # boxes will only be checked for updates when the user runs
+  # `vagrant box outdated`. This is not recommended.
+  config.vm.box_check_update = false
+
+  # Create a forwarded port mapping which allows access to a specific port
+  # within the machine from a port on the host machine. In the example below,
+  # accessing "localhost:8080" will access port 80 on the guest machine.
+  # config.vm.network "forwarded_port", guest: 80, host: 8080
+
+  # Create a private network, which allows host-only access to the machine
+  # using a specific IP.
+  config.vm.network "private_network", ip: "192.168.33.22"
+
+  # Create a public network, which generally matched to bridged network.
+  # Bridged networks make the machine appear as another physical device on
+  # your network.
+  # config.vm.network "public_network"
+
+  # Share an additional folder to the guest VM. The first argument is
+  # the path on the host to the actual folder. The second argument is
+  # the path on the guest to mount the folder. And the optional third
+  # argument is a set of non-required options.
+  # config.vm.synced_folder "../data", "/vagrant_data"
+
+  # Provider-specific configuration so you can fine-tune various
+  # backing providers for Vagrant. These expose provider-specific options.
+  # Example for VirtualBox:
+  #
+  config.vm.provider "virtualbox" do |vb|
+    # Display the VirtualBox GUI when booting the machine
+    #vb.gui = true
+ 
+    # Customize the amount of memory on the VM:
+    vb.memory = "6144"
+    vb.cpus = 3
+  end
+  #
+  # View the documentation for the provider you are using for more
+  # information on available options.
+
+  # Define a Vagrant Push strategy for pushing to Atlas. Other push strategies
+  # such as FTP and Heroku are also available. See the documentation at
+  # https://docs.vagrantup.com/v2/push/atlas.html for more information.
+  # config.push.define "atlas" do |push|
+  #   push.app = "YOUR_ATLAS_USERNAME/YOUR_APPLICATION_NAME"
+  # end
+
+  # Enable provisioning with a shell script. Additional provisioners such as
+  # Puppet, Chef, Ansible, Salt, and Docker are also available. Please see the
+  # documentation for more information about their specific syntax and use.
+  # config.vm.provision "shell", inline: <<-SHELL
+  #   sudo apt-get update
+  #   sudo apt-get install -y apache2
+  # SHELL 
+  $script = [
+    "sudo apt-add-repository ppa:brightbox/ruby-ng",
+    "sudo apt-get update",
+    "sudo apt-get -y -q install build-essential libssl-dev git",
+    "sudo apt-get -y -q install ruby2.3 ruby2.3-dev",
+    "sudo gem install bundler"]
+
+  config.vm.provision "shell", inline: $script.join(" && ")
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "thron"
+
+# 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.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

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

data/config/thron.yml

@@ -0,0 +1,10 @@
+logger:
+  level: <%= ENV.fetch('LOGGER_LEVEL') { 'warn' } %>
+  verbose: <%= ENV.fetch('VERBOSE') { false } %>
+
+circuit_breaker:
+  threshold: <%= ENV.fetch('CIRCUIT_BREAKER_THRESHOLD') { 0 } %> 
+
+thron:
+  client_id: <%= ENV.fetch('THRON_CLIENT_ID') { 'none' } %>
+  protocol: <%= ENV.fetch('THRON_PROTOCOL') { 'https' } %>

data/lib/thron.rb

@@ -0,0 +1,3 @@
+require 'thron/version'
+require 'thron/root'
+require 'thron/user'

data/lib/thron/circuit_breaker.rb

@@ -0,0 +1,46 @@
+module Thron
+  class CircuitBreaker
+    class OpenError < StandardError; end
+
+    %w[open closed].each do |name|
+      const_set(name.upcase.to_sym, name.to_sym)
+    end
+
+    def initialize(options = {})
+      @state = CLOSED
+      @threshold = options.fetch(:threshold) { 5 }
+      @error_count = 0
+      @ignored = options[:ignored].to_a
+    end
+
+    def monitor
+      return yield if @threshold.zero?
+      fail OpenError, 'the circuit breaker is open!' if open?
+      result = yield
+      handle_success
+      result
+    rescue OpenError
+      raise
+    rescue => error
+      handle_error(error) unless @ignored.include?(error.class)
+      raise
+    end
+
+    def open?
+      @state == OPEN
+    end
+
+    private
+
+    def handle_success
+      @error_count = 0
+    end
+
+    def handle_error(error)
+      @error_count += 1
+      if @error_count >= @threshold
+        @state = OPEN
+      end
+    end
+  end
+end

data/lib/thron/config.rb

@@ -0,0 +1,35 @@
+require 'yaml'
+require 'erb'
+require 'dotenv'
+require 'ostruct'
+require 'logger'
+require 'thron/root'
+
+module Thron
+  module Config
+    extend self
+
+    CONFIG_YML = Thron::root.join('config', 'thron.yml')
+
+    def dump_yaml
+      Dotenv.load
+      @yaml ||= YAML.load(ERB.new(File.read(CONFIG_YML)).result)
+    end
+
+    def logger
+      @logger ||= begin
+                    level = dump_yaml.fetch('logger').fetch('level')
+                    verbose = dump_yaml.fetch('logger').fetch('verbose')
+                    OpenStruct.new(level: Logger::const_get(level.upcase), verbose: verbose)
+                  end
+    end
+
+    def circuit_breaker
+      @circuit_breaker ||= OpenStruct.new(dump_yaml['circuit_breaker'])
+    end
+
+    def thron
+      @thron ||= OpenStruct.new(dump_yaml['thron'])
+    end
+  end
+end

data/lib/thron/entity/base.rb

@@ -0,0 +1,78 @@
+require 'ostruct'
+require 'time'
+require 'thron/string_extensions'
+
+module Thron
+  using StringExtensions
+  module Entity
+    class Base < OpenStruct
+      TIME_REGEX = /\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.+/
+      DATE_REGEX = /\A\d{4}-\d{2}-\d{2}/
+
+      def self.factory(args)
+        case args
+        when Hash
+          new(args)
+        when Array
+          args.map { |data| new(data) }
+        end
+      end
+
+      def initialize(hash = {})
+        @table = {}
+        hash.each do |k,v|
+          k = k.to_s.snakecase.to_sym
+          @table[k] = case v
+                      when Hash
+                        self.class.new(v)
+                      when Array
+                        if v.first.is_a?(Hash)
+                          v.map { |e| self.class.new(e) }
+                        else
+                          v
+                        end
+                      when TIME_REGEX
+                        Time::parse(v)
+                      when DATE_REGEX
+                        Date::parse(v)
+                      else
+                        v
+                      end
+          new_ostruct_member(k)
+        end
+      end
+
+      def to_h
+        self.each_pair.reduce({}) do |acc, (k,v)|
+          acc[k] = fetch_value(v, :to_h); acc
+        end
+      end
+
+      def to_payload
+        self.each_pair.reduce({}) do |acc, (k,v)|
+          k = k.to_s.camelize_low
+          acc[k] = fetch_value(v, :to_payload); acc
+        end
+      end
+
+      private
+      
+      def fetch_value(value, message)
+        case value
+        when Base
+          value.send(message)
+        when Array
+          if value.first.is_a?(Base)
+            value.map { |entity| entity.send(message) }
+          else
+            value
+          end
+        when Date, Time
+          value.iso8601
+        else
+          value
+        end
+      end
+    end
+  end
+end