sequencescape-client-api 0.3.5

data/lib/sequencescape-api/locale/en.yml

@@ -0,0 +1,7 @@
+en:
+  activemodel:
+    attributes:
+      sequencescape:
+        api:
+          resource:
+            uuid: "UUID"

data/lib/sequencescape-api/rails.rb

@@ -0,0 +1,88 @@
+module Sequencescape::Api::Rails
+  # Including this module into your Rails ApplicationController adds a before filter that will
+  # provide a user (based on the WTSISignOn cookie) specific Sequencescape::Api instance to
+  # use, accessible through `api`.
+  module ApplicationController
+    def self.included(base)
+      base.class_eval do
+        attr_reader :api
+        private :api
+
+        if respond_to?(:before_action)
+          before_action :configure_api
+        else
+          before_filter :configure_api
+        end
+
+        # Order is important here: later ones override earlier.
+        rescue_from(::Sequencescape::Api::Error,                :with => :sequencescape_api_error_handler)
+        rescue_from(::Sequencescape::Api::UnauthenticatedError, :with => :sequencescape_api_unauthenticated_handler)
+      end
+    end
+
+    def api_class
+      ::Sequencescape::Api
+    end
+    private :api_class
+
+    def configure_api
+      @api = api_class.new({ :cookie => cookies['WTSISignOn'] }.merge(api_connection_options))
+    end
+    private :configure_api
+
+    def api_connection_options
+      { }
+    end
+    private :api_connection_options
+
+    def sequencescape_api_error_handler(exception)
+      Rails.logger.error "#{exception}, #{exception.backtrace}"
+      raise StandardError, "There is an issue with the API connection to Sequencescape (#{exception.message})"
+    end
+    private :sequencescape_api_error_handler
+
+    def sequencescape_api_unauthenticated_handler(exception)
+      Rails.logger.error "#{exception}, #{exception.backtrace}"
+      raise StandardError, "You are not authenticated; please visit the WTSI login page"
+    end
+    private :sequencescape_api_unauthenticated_handler
+  end
+
+  # Including this module into your Rails model indicates that the model is associated with
+  # a remote resource.  This then means that your model table needs a string 'uuid' column
+  # and that when you perform a save the remote resource will also be saved if it can or
+  # needs to be.  The remote resource is exposed through `remote_resource` which you are
+  # advised to use `delegate` to hand off to.
+  module Resourced
+    def self.included(base)
+      base.class_eval do
+        attr_protected :remote_resource, :uuid
+        validates_presence_of :uuid, :allow_blank => false
+        before_save :save_remote_resource
+      end
+    end
+
+    def remote_resource=(resource)
+      @remote_resource = resource
+      self[:uuid] = @remote_resource.uuid
+    end
+
+    def uuid
+      self[:uuid]
+    end
+    private :uuid
+
+    def remote_resource
+      @remote_resource ||= api.find(uuid)
+    end
+    private :remote_resource
+
+    def save_remote_resource
+      return true if @remote_resource.nil?
+      return true unless @remote_resource.can_save?
+      self[:uuid] = @remote_resource
+      @remote_resource.save
+    end
+    private :save_remote_resource
+  end
+end

data/lib/sequencescape-api/resource/active_model.rb

@@ -0,0 +1,17 @@
+require 'active_model/conversion'
+require 'active_model/attribute_methods'
+require 'active_model/dirty'
+
+# Code that is required to support the ActiveModel basic interface.
+module Sequencescape::Api::Resource::ActiveModel
+  def self.included(base)
+    base.class_eval do
+      include ::ActiveModel::Conversion
+      include ::ActiveModel::Dirty
+    end
+  end
+
+  def persisted?
+    not self.uuid.nil?
+  end
+end

data/lib/sequencescape-api/resource/attribute_groups.rb

@@ -0,0 +1,94 @@
+require 'active_model/dirty'
+
+module Sequencescape::Api::Resource::Groups
+  module InstanceMethods
+    def attribute_groups
+      @attribute_groups ||= {}
+    end
+
+    def attribute_group_json(options)
+      attribute_groups.each_with_object({}) do |(k,v), agj|
+        agj[k.to_s] = v.send(:as_json_for_update, options) if v.changed?
+      end
+    end
+    private :attribute_group_json
+
+    def changed?
+      super or attribute_groups.values.any?(&:changed?)
+    end
+
+    def clear_changed_attributes
+      super
+      attribute_groups.values.map(&:clear_changed_attributes)
+    end
+
+    def eager_loaded_attribute?(name)
+      super or attribute_groups.key?(name.to_sym)
+    end
+  end
+
+  module Json
+    def as_json_for_update(options)
+      super.tap do |json|
+        begin
+          if options[:root]
+            json.fetch(json_root).merge!(attribute_group_json(options))
+          else
+            json.merge!(attribute_group_json(options))
+          end
+        rescue KeyError => e
+          # If we get a key error, append the json to out exception to assist diagnosing issues
+          e.message << " in #{json.to_json}"
+          raise e
+        end
+      end
+    end
+    private :as_json_for_update
+  end
+
+  def self.extended(base)
+    base.class_eval do
+      include InstanceMethods
+    end
+  end
+
+  def attribute_group(name, &block)
+    proxy_class = Class.new(Proxy)
+    proxy_class.instance_eval(&block)
+    define_method(name)       {              attribute_groups[name.to_sym] ||= proxy_class.new(self) }
+    define_method("#{name}=") { |attributes| attribute_groups[name.to_sym]   = proxy_class.new(self, attributes) }
+  end
+end
+
+class Sequencescape::Api::Resource::Groups::Proxy
+  module InstanceMethods
+    def self.included(base)
+      base.class_eval do
+        attr_reader :attributes
+        private :attributes
+      end
+    end
+
+    def initialize(owner, attributes = {})
+      @owner, @attributes = owner, {}
+      attributes.each { |k,v| send(:"#{k}=", v) if respond_to?(:"#{k}=", :include_private_methods) }
+    end
+
+    def as_json_for_update(options)
+      attribute_group_json(options).tap do |agj|
+        changes.each { |k, (_, v)| agj[k.to_s] = v }
+      end
+    end
+    private :as_json_for_update
+
+    def clear_changed_attributes
+      changed_attributes.clear
+    end
+    private :clear_changed_attributes
+  end
+
+  include InstanceMethods
+  include ::ActiveModel::Dirty
+  extend Sequencescape::Api::Resource::Attributes
+  extend Sequencescape::Api::Resource::Groups
+end

data/lib/sequencescape-api/resource/attributes.rb

@@ -0,0 +1,87 @@
+require 'time'
+require 'active_support/core_ext/string/conversions'
+
+module Sequencescape::Api::Resource::Attributes
+  def self.extended(base)
+    base.class_eval do
+      include InstanceMethods
+      class_attribute :defined_attributes, :instance_writer => false
+      self.defined_attributes = Set.new
+    end
+  end
+
+  module InstanceMethods
+    def is_attribute?(name)
+      defined_attributes.include?(name.to_sym)
+    end
+
+    def eager_loaded_attribute?(name)
+      is_attribute?(name) and attributes.key?(name.to_s)
+    end
+  end
+
+  def generate_attribute_reader(*names)
+    options    = names.extract_options!
+    conversion = options[:conversion].blank? ? nil : "try(#{options[:conversion].to_sym.inspect})"
+
+    names.each do |name|
+      defined_attributes << name.to_sym
+      converted = [ "#{name}_before_type_cast", conversion ].compact.join('.')
+
+      line = __LINE__ + 1
+      class_eval(%Q{
+        def #{name}
+          #{converted}
+        end
+
+        def #{name}_before_type_cast
+          attributes[#{name.to_s.inspect}]
+        end
+      }, __FILE__, line)
+    end
+    extend_attribute_methods(names)
+  end
+  private :generate_attribute_reader
+
+  def generate_attribute_writer(*names)
+    options = names.extract_options!
+
+    names.each do |name|
+      defined_attributes << name.to_sym
+
+      line = __LINE__ + 1
+      class_eval(%Q{
+        def #{name}=(value)
+          #{name}_will_change! if not attributes.key?(#{name.to_s.inspect}) or #{name} != value
+          attributes[#{name.to_s.inspect}] = value
+        end
+      }, __FILE__, line)
+    end
+    extend_attribute_methods(names)
+  end
+  private :generate_attribute_writer
+
+  def attribute_reader(*names)
+    attribute_accessor(*names)
+    class_eval { names.map { |m| private :"#{m}=" } }
+  end
+  private :attribute_reader
+
+  def attribute_writer(*names)
+    attribute_accessor(*names)
+    class_eval { names.map(&method(:private)) }
+  end
+  private :attribute_writer
+
+  def attribute_accessor(*names)
+    generate_attribute_reader(*names)
+    generate_attribute_writer(*names)
+  end
+  private :attribute_accessor
+
+  def extend_attribute_methods(names)
+    @attribute_methods_generated = false
+    define_attribute_methods(names)
+  end
+  private :extend_attribute_methods
+end

data/lib/sequencescape-api/resource/instance_methods.rb

@@ -0,0 +1,24 @@
+module Sequencescape::Api::Resource::InstanceMethods
+  def self.included(base)
+    base.class_eval do
+      attr_reader :api, :actions, :attributes, :uuid
+      private :api, :actions, :attributes
+      alias_method(:model, :class)
+      alias_method(:id, :uuid)
+
+      delegate :hash, :to => :uuid
+      delegate :read_timeout, :to => :api
+
+      attribute_accessor :created_at, :updated_at, :conversion => :to_time
+    end
+  end
+
+  def eql?(object_or_proxy)
+    return false unless object_or_proxy.respond_to?(:uuid)
+    self.uuid.eql?(object_or_proxy.uuid)
+  end
+
+  def initialize(api, json = nil, wrapped = false)
+    @api, @attributes = api, {}
+  end
+end

data/lib/sequencescape-api/resource/json.rb

@@ -0,0 +1,114 @@
+module Sequencescape::Api::Resource::Json
+  def self.included(base)
+    base.class_eval do
+      extend ClassMethods
+    end
+  end
+
+  module ClassMethods
+    def self.extended(base)
+      base.delegate :json_root, :to => 'self.class'
+    end
+
+    def json_root
+      self.name.demodulize.underscore
+    end
+  end
+
+  class CoercionHandler
+    include Sequencescape::Api::BasicErrorHandling
+
+    def initialize(api, owner)
+      @api, @owner = api, owner
+    end
+
+    attr_reader :api
+
+    def new(*args, &block)
+      # TODO: Consider updating
+      @owner.__send__(:new, *args, &block)
+    end
+    private :new
+
+    private :api, :new
+
+    def success(json)
+      new(api, json, true)
+    end
+  end
+
+  # Coerces the current object instance to another class.
+  def coerce_to(klazz)
+    api.read_uuid(self.uuid, CoercionHandler.new(api, klazz))
+  end
+
+  def as_json(options = nil)
+    options = { :action => :create, :root => true }.merge(options || {})
+    send(:"as_json_for_#{options[:action]}", options)
+  end
+
+  # Returns the appropriate JSON for when we are creating a resource.  If the resource already exists
+  # then we assume that we aren't actually being created, but are being used in the creation of another
+  # resource, and send our UUID.  If we are not persisted then all of our attributes need to be sent,
+  # regardless of whether we are involved in the creation of ourselves or another resource.
+  def as_json_for_create(options)
+    persisted? ? uuid : as_json_for_update(options)
+  end
+  private :as_json_for_create
+
+  # Returns the appropriate JSON for when we are updating a resource.
+  def as_json_for_update(options)
+    if must_output_full_json?(options)
+      json = { }
+      json['uuid'] = uuid if options[:uuid] and uuid.present?
+
+      json.merge!(attributes_for_json(options))
+      json.merge!(associations_for_json(options.merge(:root => false)))
+
+      return json unless options[:root]
+      { json_root => json }
+    elsif options[:root]
+      # We are the root element so we must output something!
+      { json_root => { } }
+    else
+      # We are not a root element, we haven't been changed, so we might as well not exist!
+      nil
+    end
+  end
+  private :as_json_for_update
+
+  def unwrapped_json(json)
+    json[(json.keys - [ 'uuids_to_ids' ]).first]
+  end
+  private :unwrapped_json
+
+  def changed?
+    super or associations.values.any?(&:changed?)
+  end
+
+  def attributes_for_json(options)
+    attributes_to_send_to_server(options).tap do |changed_attributes|
+      [ 'created_at', 'updated_at' ].map(&changed_attributes.method(:delete))
+    end
+  end
+  private :attributes_for_json
+
+  def attributes_to_send_to_server(options)
+    return attributes if options[:force] or (options[:action] == :create)
+    changes.keys.each_with_object({}) { |k, attributes| attributes[k.to_s] = send(k) }
+  end
+  private :attributes_to_send_to_server
+
+  def associations_for_json(options)
+    associations.each_with_object({}) do |(k, v), associations|
+      next unless must_output_full_json?(options, v)
+      associations[k.to_s] = v.as_json(options)
+    end
+  end
+  private :associations_for_json
+
+  def must_output_full_json?(options, target = self)
+    options[:force] or (options[:action] == :create) or target.changed?
+  end
+  private :must_output_full_json?
+end

data/lib/sequencescape-api/resource/modifications.rb

@@ -0,0 +1,111 @@
+class Sequencescape::Api::ModifyingHandler
+  include Sequencescape::Api::BasicErrorHandling
+
+  def initialize(owner)
+    @owner = owner
+  end
+
+  def update_from_json(*args, &block)
+    # TODO: Consider updating
+    @owner.__send__(:update_from_json, *args, &block)
+  end
+  private :update_from_json
+
+  def error(field_and_errors_pair)
+    field, errors = field_and_errors_pair
+    Array(errors).each { |error| @owner.errors.add(field, error) }
+  end
+  private :error
+
+  def object_error(message)
+    @owner.errors.add(:base, message)
+  end
+  private :object_error
+
+  def success(json)
+    update_from_json(json, true)
+  end
+
+  def failure(json)
+    Array(json.fetch('content', [])).map(&method(:error))
+    Array(json.fetch('general', [])).map(&method(:object_error))
+
+    raise Sequencescape::Api::ResourceInvalid, @owner
+  end
+end
+
+module Sequencescape::Api::Resource::Modifications
+  def initialize(api, json = nil, wrapped = false)
+    super
+    update_from_json(json, wrapped)
+    changed_attributes.clear
+  end
+
+  def update_attributes!(attributes)
+    changed_attributes.clear
+    update_from_json(attributes, false)
+    modify!(:action => :update)
+  end
+  alias update! update_attributes!
+
+  def save!(options = nil)
+    action = persisted? ? :update : :create
+    modify!((options || {}).merge({ :action => action }))
+  end
+
+  def modify!(options)
+    raise Sequencescape::Api::Error, "No actions exist" if options[:url].nil? and actions.nil?
+
+    action    = options[:action]
+    skip_json = options[:skip_json]||false
+    http_verb = options[:http_verb] || options[:action]
+    url       = options[:url]
+    url     ||= (actions.send(action) or raise Sequencescape::Api::Error, "Cannot perform #{action}")
+    raise Sequencescape::Api::Error, "Cannot perform modification without a URL" if url.blank?
+
+    self.tap do
+      run_validations! or raise Sequencescape::Api::ResourceInvalid, self
+
+      object = skip_json ? {} : self
+
+      api.send(
+        http_verb,
+        url,
+        object,
+        Sequencescape::Api::ModifyingHandler.new(self)
+      )
+
+      changed_attributes.clear
+    end
+  end
+  private :modify!
+
+  def update_from_json(json, wrapped = false)
+    unwrapped = (wrapped ? unwrapped_json(json) : json) || {}
+    unwrapped.map(&method(:update_attribute))
+  end
+  private :update_from_json
+
+  def update_attribute(name_and_value_pair)
+    name, value = name_and_value_pair
+    case
+    when name.to_s == 'actions'                     then update_actions(value)
+    when name.to_s == 'uuid'                        then @uuid = (value || @uuid)
+    when respond_to?(:"#{name}=", :include_private) then send(:"#{name}=", value)
+    else # TODO: Maybe we need debug logging in here at some point!
+    end
+  end
+  private :update_attribute
+
+  def update_actions(actions_from_attributes)
+    actions_before_update = @actions
+
+    # We're kind of in a situation where an update of the attributes could be coming from the API
+    # or from the client code.  We know that the API will always include 'actions' so we can assume that
+    # if it's set then that's what we should use, or we should use the previous actions.
+    #
+    # TODO: This isn't ideal as it's open to abuse but we can live with it for the moment.
+    @actions = actions_from_attributes.nil? ? actions_before_update : OpenStruct.new(actions_from_attributes)
+  end
+  private :update_actions
+end