ims_caliper 0.1.1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    ZDI0ZGY4YjFhMTE3M2NkYWMxNGNiMDA5OGViMWMzZjcwYzNmZTdkNQ==
+  data.tar.gz: !binary |-
+    ODk5NGZlMTBiZjdjZTM0N2U0ZjZhMDFhY2VlZWFjYWNhNDNjMjE2MQ==
+SHA512:
+  metadata.gz: !binary |-
+    MTA3OTY1NjE2ZTMxNTQ1ODFiYzI4MWYzMmQ3ODJiZjM5MGRiN2FkZjRiMTQ3
+    OTUzNDJjZjMwMzUyNGRiNDY3MGViN2UwMWM5OGJlMjg0YTNjNmI5NTBlMzAx
+    ODg1ODVlZWIyZWY5NjUwNzMwZTJjMGI2YmM5ODA5OGU4OTUxMTI=
+  data.tar.gz: !binary |-
+    ZjNmNzBjZjg3ZTYwYjQ3YWZhODNiM2RlMWNhOGM0N2Y1ZTY0MzJlMTA4NmUz
+    NmFmNWEwNWVmOTAzZTVlZWYwYmIyZDNiNDc2NDlkMDlkNDdhNDc5OGZmYTA0
+    ZmQ4YWNlNDVjOGUyNDJkOTNlYzU0NWU1NGZiOThmZTUxZWRkNWM=

data/Gemfile

@@ -0,0 +1,13 @@
+source "https://rubygems.org"
+
+# Declare your gem's dependencies in open_data_export.gemspec.
+# Bundler will treat runtime dependencies like base dependencies, and
+# development dependencies will be added by default to the :development group.
+
+# the atomic lib
+gem 'atomic', '~> 1.1.99'
+
+# translation and localization
+gem 'i18n'
+
+gem 'test-unit'

data/Gemfile.lock

@@ -0,0 +1,16 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    atomic (1.1.99)
+    i18n (0.7.0)
+    power_assert (0.2.2)
+    test-unit (3.0.9)
+      power_assert
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  atomic (~> 1.1.99)
+  i18n
+  test-unit

data/README.md

@@ -0,0 +1,16 @@
+caliper-ruby
+===================
+
+caliper-ruby is a Ruby client for [Caliper](http://www.imsglobal.org) that provides a Ruby implementation of the Caliper Sensor API
+
+## generate the Ruby Gem
+
+gem build caliper.gemspec
+
+=============
+Use Ruby Style Guide:
+
+
+https://github.com/styleguide/ruby
+
+https://github.com/bbatsov/ruby-style-guide

data/caliper.gemspec

@@ -0,0 +1,26 @@
+$:.push File.expand_path("../lib", __FILE__)
+
+require 'caliper/version'
+Gem::Specification.new do |g|
+	g.name        = "ims_caliper"
+	g.version     = Caliper::VERSION
+	g.authors     = ["Anthus Williams", "Zhen Qian"]
+	g.email       = ["aj@instructure.com", "zqian@umich.edu"]
+	g.homepage    = "https://github.com/IMSGlobal/caliper-ruby"
+	g.summary     = "Caliper Sensor API"
+	g.description = "This is the implementation of IMSGlobal Caliper in Ruby"
+	g.license     = "http://www.imsglobal.org/copyright.html"
+
+	#g.files = Dir["{app,config,db,lib}/**/*", "Rakefile"]
+	g.files     = `git ls-files`.split($\)
+	g.executables   = g.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+	g.test_files    = g.files.grep(%r{^(test|spec|features)/})
+	g.require_path = 'lib'
+
+	#g.add_dependency "activesupport", '~> 0'
+	#g.add_development_dependency "rspec", '~> 0'
+	#g.add_development_dependency "simplecov", '~> 0'
+	#g.add_development_dependency "simplecov-rcov", '~> 0'
+	#g.add_development_dependency "mocha", '~> 0'
+	#g.add_development_dependency 'atomic', '~> 1.1.99'
+end

data/config/locales/en.yml

@@ -0,0 +1,86 @@
+en:
+  actions:
+    annotation:
+      attached: "attached"
+      bookmarked: "bookmarked"
+      classified: "classified"
+      commented: "commented"
+      described: "described"
+      highlighted: "highlighted"
+      identified: "identified"
+      liked: "liked"
+      linked: "linked"
+      questioned: "questioned"
+      ranked: "ranked"
+      recommended: "recommended"
+      replied: "replied"
+      shared: "shared"
+      subscribed: "subscribed"
+      tagged: "tagged"
+
+    assessment:
+      paused: "paused"
+      restarted: "restarted"
+      started: "started"
+      submitted: "submitted"
+
+      item.completed: "completed"
+      item.skipped: "skipped"
+      item.started: "started"
+      item.reviewed: "reviewed"
+      item.viewed: "viewed"
+
+    assignable:
+      abandoned: "abandoned"
+      activated: "activated"
+      completed: "completed"
+      deactivated: "deactivated"
+      hid: "hid"
+      reviewed: "reviewed"
+      showed: "showed"
+      started: "started"
+
+    item:
+      downloaded: "downloaded"
+      uploaded: "uploaded"
+
+
+    media:
+      accessibility:
+        disabledClosedCaptioning: "disabled closed captioning"
+        enabledClosedCaptioning: "enabled closed captioning"
+      audio:
+        changedVolume: "changed volume"
+        muted: "muted"
+        unmuted: "unmuted"
+      playback:
+        changedSpeed: "changed speed"
+        ended: "ended"
+        forwardedTo: " forwarded to"
+        jumpedTo: "jumped to"
+        paused: "paused"
+        resumed: "resumed"
+        rewindedTo: "rewinded to"
+        started: "started"
+      viewer:
+        changedResolution: "changed resolution"
+        changedSize: "changed viewer size"
+        enteredFullScreen: "entered full screen"
+        openedPopout: "opened popout"
+        exitedFullScreen: "exited full screen"
+        closedPopout: "closed popout"
+
+    navigation:
+      navigatedTo: "navigated to"
+
+    outcome:
+      graded: "graded"
+
+    reading:
+      searched: "searched"
+      viewed: "viewed"
+
+    session:
+      loggedIn: "logged in"
+      loggedOut: "logged out"
+      timedOut: "timed out"

data/lib/caliper/client.rb

@@ -0,0 +1,33 @@
+
+module Caliper
+  class Client
+	  attr_accessor :api_key, :options, :stats
+    def initialize(key, opts = {})
+      if opts[:consumer]
+        opts[:consumer] = Object.const_get(opts[:consumer]) if opts[:consumer].is_a?(String)
+        opts[:consumer] = opts[:consumer].new(key, opts) if opts[:consumer].respond_to?(:new)
+        raise ArgumentError, "Expecting Caliper::Consumer but got #{opts[:consumer].class.to_s}" unless opts[:consumer].is_a?(Caliper::Consumer::Base)
+      end
+      @consumer = opts[:consumer] || Caliper::Consumer::Socket.new(key, opts)
+    end
+
+    def measure(event, timestamp=nil)
+      raise ArgumentError, "Expecting Caliper::Event but got #{event.class.to_s}" unless event.is_a?(Caliper::Event::Base)
+      #todo ensure timestamp is iso8601
+      timestamp ||= Time.now
+      action = event.action
+      # returned json will serialize nil contexts as []
+      learning_context = event.learning_context ? event.learning_context : nil
+      activity_context = event.activity_context ? event.activity_context : nil
+
+      @consumer.measure(action, learning_context, activity_context, timestamp)
+    end
+
+    def describe(entity, timestamp=nil)
+      raise ArgumentError, "Expecting Caliper::Entity but got #{entity.class.to_s}" unless entity.is_a?(Caliper::Entity::Base)
+      #todo ensure timestamp is iso8601
+      timestamp ||= Time.now
+      @consumer.describe(entity.type, entity.id, entity.properties, Time.now)
+    end
+  end
+end

data/lib/caliper/consumer/base.rb

@@ -0,0 +1,46 @@
+module Caliper
+  module Consumer
+    class Base
+      attr_reader :api_key
+
+      def initialize(key, opts = {})
+        @api_key = key
+        @options = validate_options(opts)
+      end
+
+      def describe(type, id, props, timestamp); end
+
+      def measure(action, learning_context, activity_context, timestamp); end
+
+      def with_debug?
+        @options[:debug] || false
+      end
+
+      def with_ssl?
+        @options[:ssl] || false
+      end
+
+      def on_error(error)
+        if with_debug?
+          #todo: log if debug
+        end
+
+        if @options[:on_error]
+          @options[:on_error].call(error)
+        end
+      end
+
+      def validate_options(opts)
+        hsh = {}
+        hsh[:debug] = opts[:debug] ? true : false
+        hsh[:ssl] = opts[:ssl] ? true : false
+        if opts[:on_error]
+          raise ArgumentError, "on_error option should be callable" unless opts[:on_error].is_a?(Proc) 
+          hsh[:on_error] = opts[:on_error]
+        end
+        hsh
+      end
+
+    end
+  end
+end

data/lib/caliper/consumer/queue.rb

@@ -0,0 +1,40 @@
+module Caliper
+  module Consumer
+    class Queue < Base
+      attr_reader :max_queue_size, :batch_size
+
+      def initialize(key, opts = {})
+        super
+        @queue = []
+      end
+
+      def validate_options(opts)
+        hsh = super
+        @max_queue_size = hsh[:max_queue_size] = opts[:max_queue_size].to_i
+        @batch_size = hsh[:batch_size] = opts[:batch_size].to_i
+        hsh
+      end
+
+      def measure(action, learning_context, activity_context, timestamp)
+        enqueue OpenStruct.new(api_key: @api_key, action: action, learning_context: learning_context, activity_context: activity_context, timestamp: timestamp, proc_name: "measure")
+      end
+
+      def describe(type, id, properties, timestamp)
+        enqueue OpenStruct.new(api_key: @api_key, entity_type: type, entity_id: id, properties: properties, timestamp: timestamp, proc_name: "describe")
+      end
+
+      def enqueue(item) 
+        if item.proc_name == "measure"
+          flush_measure(item)
+        elsif item.proc_name == "describe"
+          flush_describe(item)
+        end
+      end
+
+      def flush_measure(item); end
+
+      def flush_describe(item); end
+
+    end
+  end
+end

data/lib/caliper/consumer/socket.rb

@@ -0,0 +1,132 @@
+require 'socket'
+require 'openssl'
+require "active_support"
+
+module Caliper
+  module Consumer
+    class Socket < Queue
+      attr_reader :socket
+
+      def initialize(key, opts = {})
+        super
+      end
+
+      def validate_options(opts)
+        hsh = super(opts)
+        hsh[:timeout] = opts[:timeout] || 0.5
+        hsh[:host] = opts[:host] || "localhost"
+        hsh[:port] = opts[:port] || ( hsh[:ssl] ? 443 : 80 )
+        hsh[:max_response_size] = opts[:max_response_size] || 2048
+        hsh
+      end
+
+      private
+
+      def flush_describe(item)
+        socket = init_socket
+        return unless socket
+
+        send_request( socket, describe_body( @options[:host], ActiveSupport::JSON.encode(item)) )
+      end
+
+      def flush_measure(item)
+        socket = init_socket
+        return unless socket
+
+        send_request( socket, measure_body( @options[:host], ActiveSupport::JSON.encode(item)) )
+      end
+
+      # both describe_body and measure_body hardcode a URL as is the case with caliper-php
+      # todo: make this configurable
+      def describe_body(host, content)
+        <<-STR.gsub(/^ {10}/,'')
+          PUT /v1/describe HTTP/1.1/
+          Host: #{host}
+          Content-Type: application/json
+          Accept: application\json
+          Content-length: #{content.length}
+          
+          #{content}
+        STR
+      end
+
+      def measure_body(host, content)
+        <<-STR.gsub(/^ {10}/,'')
+          PUT /v1/learningevent HTTP/1.1/
+          Host: #{host}
+          Content-Type: application/json
+          Accept: application\json
+          Content-length: #{content.length}
+          
+          #{content}
+        STR
+      end
+
+      def init_socket
+        # if socket has failed, don't keep trying to connect on future events
+        return if @socket_failed
+        begin
+          s = TCPSocket.new(@options[:host], @options[:port])
+          if with_ssl?
+            s = OpenSSL::SSL::SSLSocket.new(s)
+            s.sync_close
+            s.connect
+          end
+        rescue SocketError => e
+          on_error(e)
+          @socket_failed = true
+          return
+        end
+        s
+      end
+
+      def send_request(socket, body, with_retries = 1)
+        written = 0
+        closed = false
+        while !closed && bytes_written < body.bytesize
+          begin
+             bytes_written = socket.write(body[bytes_written..-1])
+            if bytes_written.zero?
+              closed = true
+            else
+              written += bytes_written
+            end
+          rescue SocketError => e
+            on_error(e)
+            closed = true
+          end
+        end
+
+        if closed
+          socket.close
+          # attempt to retry connection up to with_retries times
+          unless with_retries.zero?
+            socket = init_socket
+            return send_request(socket, body, with_retries - 1) if socket
+          end
+          return false
+        end
+
+        success = true
+
+        # if debug is enabled, wait for response
+        if with_debug?
+          r = parse_response(socket.read(@options[:max_response_size]))
+          unless r.status == 200
+            #todo build exception and send it to on_error
+            success = false
+          end
+        end
+
+        return success
+      end
+
+      def parse_response(resp)
+        contents = resp.split("\n")
+        status = contents.first.split(" ")
+        OpenStruct.new(:status => (status.length > 1 ? status[1] : nil), :message => contents.last) 
+      end
+
+    end
+  end
+end

data/lib/caliper/defaults.rb

@@ -0,0 +1,8 @@
+module Caliper
+  class Defaults
+	  HOST = "http://dev-null.comt"
+		CONNECTION_TIMEOUT = 10000
+	  SO_TIMEOUT = 10000
+	  CONNECTION_REQUEST_TIMEOUT = 10000
+  end
+end

data/lib/caliper/entities/annotation/annotation.rb

@@ -0,0 +1,29 @@
+require_relative '../../entities/entity'
+require_relative '../../entities/schemadotorg/thing'
+
+module Caliper
+	module Entities
+		module Annotation
+			module AnnotationType
+				ANNOTATION = "http://purl.imsglobal.org/caliper/v1/Annotation"
+				BOOKMARK_ANNOTATION = "http://purl.imsglobal.org/caliper/v1/BookmarkAnnotation"
+				HIGHLIGHT_ANNOTATION = "http://purl.imsglobal.org/caliper/v1/HighlightAnnotation"
+				SHARED_ANNOTATION = "http://purl.imsglobal.org/caliper/v1/SharedAnnotation"
+				TAG_ANNOTATION = "http://purl.imsglobal.org/caliper/v1/TagAnnotation"
+			end
+
+			## implement the interface Thing
+			class Annotation < Entity
+				include Caliper::Entities::SchemaDotOrg::Thing
+				attr_accessor :target,
+			                :type
+
+				def initialize
+					super
+					type = AnnotationType::ANNOTATION
+					target = ''
+				end
+			end
+		end
+	end
+end

data/lib/caliper/entities/annotation/bookmark_annotation.rb

@@ -0,0 +1,17 @@
+require_relative 'annotation'
+
+module Caliper
+  module Entities
+    module Annotation
+      class Bookmark < Annotation
+        attr_accessor :type,
+                      :bookmark_notes
+
+        def initialize(action)
+          super
+          @type = AnnotationType::BOOKMARK_ANNOTATION
+        end
+      end
+    end
+  end
+end

data/lib/caliper/entities/annotation/highlight_annotation.rb

@@ -0,0 +1,18 @@
+require_relative 'annotation'
+
+module Caliper
+  module Entities
+    module Annotation
+      class HighlightAnnotation < Annotation
+        attr_accessor :type,
+                      :bookmark_notes
+
+        def initialize()
+          super
+          @type = AnnotationType::HIGHLIGHT_ANNOTATION
+          @bookmark_notes = ''
+        end
+      end
+    end
+  end
+end

data/lib/caliper/entities/annotation/shared_annotation.rb

@@ -0,0 +1,18 @@
+require_relative 'annotation'
+
+module Caliper
+  module Entities
+    module Annotation
+      class SharedAnnotation < Annotation
+        attr_accessor :with_agents, # list of Agent object
+                      :type
+
+        def initialize()
+          super
+          @type = AnnotationType::SHARED_ANNOTATION
+	        @with_agents = ''
+        end
+      end
+    end
+  end
+end

data/lib/caliper/entities/annotation/tag_annotation.rb

@@ -0,0 +1,17 @@
+require_relative 'Annotation'
+
+module Caliper
+  module Entities
+    module Annotation
+      class TagAnnotation < Annotation
+        attr_accessor :type,
+                      :tags
+
+        def initialize()
+          super
+          @type = AnnotationType::TAG_ANNOTATION
+        end
+      end
+    end
+  end
+end

data/lib/caliper/entities/annotation/text_position_selector.rb

@@ -0,0 +1,14 @@
+
+# An Selector which describes a range of text based on its start and end positions
+# Defined by: http://www.w3.org/ns/oa#d4e667
+
+module Caliper
+  module Entities
+    module Annotation
+      class TextPositionSelector
+        attr_accessor :start,
+                      :end
+      end
+    end
+  end
+end

data/lib/caliper/entities/digital_resource.rb

@@ -0,0 +1,52 @@
+require "json"
+require_relative 'entity'
+
+# Public: Caliper representation of a CreativeWork (https://schema.org/CreativeWork)
+# We add learning specific attributes, including a list of
+# LearningObjective learning objectives and a list of
+# String keywords
+#
+# Examples
+#
+
+module Caliper
+  module Entities
+	  module DigitalResourceType
+		  ASSIGNABLE_DIGITAL_RESOURCE = "http://purl.imsglobal.org/caliper/v1/AssignableDigitalResource"
+		  EPUB_CHAPTER = "http://www.idpf.org/epub/vocab/structure/#chapter"
+		  EPUB_PART = "http://www.idpf.org/epub/vocab/structure/#part"
+		  EPUB_SUB_CHAPTER = "http://www.idpf.org/epub/vocab/structure/#subchapter"
+		  EPUB_VOLUME = "http://www.idpf.org/epub/vocab/structure/#volume"
+		  FRAME = "http://purl.imsglobal.org/caliper/v1/Frame"
+		  MEDIA_LOCATION = "http://purl.imsglobal.org/caliper/v1/MediaLocation"
+		  MEDIA_OBJECT = "http://purl.imsglobal.org/caliper/v1/MediaObject"
+		  READING = "http://www.idpf.org/epub/vocab/structure"
+		  WEB_PAGE = "http://purl.imsglobal.org/caliper/v1/WebPage"
+	  end
+    class DigitalResource < Entity
+	    attr_accessor :type,
+	                  :object_types, # list of String
+	                  :learning_objectives, # a list of learning objectives
+	                  :keywords,
+	                  :is_part_of,
+	                  :date_published
+
+	    # Public:
+      def to_json(*a)
+	      {
+		      "type" => @type,
+		      "objectTypes" => @object_types,
+	        "learningObjective" => @learning_objectives,
+	        "keywords" => @keywords,
+	        "isPartOf" => @is_part_of,
+	        "datePublished" => @date_published
+	      }.to_json(*a)
+      end
+
+	    def initialize()
+		    super
+		    @type = EntityType::DIGITAL_RESOURCE
+	    end
+    end
+  end
+end

data/lib/caliper/entities/entity.rb

@@ -0,0 +1,44 @@
+require "json"
+
+##
+##  The base Caliper Entity.  Analogous to a schema.org Thing.
+##
+module Caliper
+  module Entities
+	  module EntityType
+		  AGENT = "http://purl.imsglobal.org/caliper/v1/Agent"
+		  ATTEMPT = "http://purl.imsglobal.org/caliper/v1/Attempt"
+		  DIGITAL_RESOURCE = "http://purl.imsglobal.org/caliper/v1/DigitalResource"
+		  ENTITY = "http://purl.imsglobal.org/caliper/v1/Entity"
+		  GENERATED = "http://purl.imsglobal.org/caliper/v1/Generated"
+		  LEARNING_OBJECTIVE = "http://purl.imsglobal.org/caliper/v1/LearningObjective"
+		  LIS_PERSON = "http://purl.imsglobal.org/caliper/v1/lis/Person"
+		  LIS_ORGANIZATION = "http://purl.imsglobal.org/caliper/v1/lis/Organization"
+		  RESULT = "http://purl.imsglobal.org/caliper/v1/Result"
+		  SESSION = "http://purl.imsglobal.org/caliper/v1/Session"
+		  SOFTWARE_APPLICATION = "http://purl.imsglobal.org/caliper/v1/SoftwareApplication"
+		  TARGET = "http://purl.imsglobal.org/caliper/v1/Target"
+		  VIEW = "http://purl.imsglobal.org/caliper/v1/View"
+	  end
+
+    class Entity
+			attr_accessor :id,
+			              :type,
+			              :name,
+			              :description,
+			              :properties,
+			              :date_created,
+			              :date_modified
+
+			def initialize()
+				@id = ""
+				@type = EntityType::ENTITY
+				@name = ""
+				@description = ""
+				@properties = ""
+				@date_created = Time.now.utc
+				@date_modified = Time.now.utc
+			end
+    end
+  end
+end

data/lib/caliper/entities/foaf/agent.rb

@@ -0,0 +1,12 @@
+require_relative '../../entities/entity'
+# Public: From http://xmlns.com/foaf/spec/#term_Agent An agent (eg. person,
+#        group, software or physical artifact)
+module Caliper
+  module Entities
+	  module FOAF
+      module Agent
+
+      end
+    end
+  end
+end

data/lib/caliper/entities/generatable.rb

@@ -0,0 +1,9 @@
+# The generatable interface marks an object type that is created or generated as a result of an action.
+# The interface allows Caliper to catch errors at compile time for instances of the marked class rather
+# than at runtime if a marker annotation was defined instead.
+module Caliper
+	module Entities
+		module Generatable
+		end
+	end
+end