lightstreamer 0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: bf90908d8a97af1417f8391f16e2c26a10baf73d
+  data.tar.gz: 6e89354b80f3712ca9c4278f09342123d3844878
+SHA512:
+  metadata.gz: a17d1e9276c986f6c436e3aad883f4f068b319e9e88e30b7e7eb844b1af33ca18c35dab74a76e2e25763263199c7f251acf45d999a07afeb749b424d6ea58985
+  data.tar.gz: d359e20a661d5dc953f5ba02d3984f4db0206886b38ebdc1ab555c20c5b367eab9aa8499071eef6ba6f074da116925cf2774742c043e314bdd21f419126535a9

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Lightstreamer Changelog
+
+### 0.1 — July 23, 2016
+
+- Initial release

data/LICENSE.md

@@ -0,0 +1,25 @@
+The MIT License (MIT)
+=====================
+
+Copyright © 2015-2016 Richard Viney
+
+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.md

@@ -0,0 +1,109 @@
+# Ruby Lightstreamer Client Gem
+
+[![Gem][gem-badge]][gem-link]
+[![Build Status][travis-ci-badge]][travis-ci-link]
+[![Test Coverage][test-coverage-badge]][test-coverage-link]
+[![Code Climate][code-climate-badge]][code-climate-link]
+[![Dependencies][dependencies-badge]][dependencies-link]
+[![Documentation][documentation-badge]][documentation-link]
+[![License][license-badge]][license-link]
+
+Easily interface with a Lightstreamer service from Ruby. Written against the
+[official API specification](http://www.lightstreamer.com/docs/client_generic_base/Network%20Protocol%20Tutorial.pdf).
+
+## License
+
+Licensed under the MIT license. You must read and agree to its terms to use this software.
+
+## Installation
+
+Install the latest version of the `lightstreamer` gem with the following command:
+
+```
+$ gem install lightstreamer
+```
+
+## Usage — Library
+
+The two primary classes that make up the public API are:
+
+- [`Lightstreamer::Session`](http://www.rubydoc.info/github/rviney/lightstreamer/Lightstreamer/Session)
+- [`Lightstreamer::Subscription`](http://www.rubydoc.info/github/rviney/lightstreamer/Lightstreamer/Subscription)
+
+The following code snippet demonstrates how to setup a Lightstreamer session, a subscription, then print streaming
+output as it comes in.
+
+```ruby
+require 'lightstreamer'
+
+# Create a new session that connects to the Lightstreamer demo server, which needs no authentication
+session = Lightstreamer::Session.new server_url: 'http://push.lightstreamer.com',
+                                     adapter_set: 'DEMO', username: '', password: ''
+
+# Connect the session
+session.connect
+
+# Create a new subscription that subscribes to five items and to four fields on each item
+subscription = Lightstreamer::Subscription.new items: %w(item1 item2 item3 item4 item5),
+                                               fields: [:time, :stock_name, :bid, :ask],
+                                               mode: :merge, adapter: 'QUOTE_ADAPTER'
+
+# Create a thread-safe queue
+queue = Queue.new
+
+# When new data becomes available for the subscription it will be put on the queue. This callback
+# will be run on a worker thread.
+subscription.add_data_callback do |subscription, item_name, item_data, new_values|
+  queue.push item_data
+end
+
+# Activate the subscription
+session.subscribe subscription
+
+# Loop printing out new data as soon as it becomes available on the queue
+loop do
+  data = queue.pop
+  puts "#{data[:time]} - #{data[:stock_name]} - bid: #{data[:bid]}, ask: #{data[:ask]}"
+end
+```
+
+## Usage — Command-Line Client
+
+This gem provides a simple command-line client that can connect to a Lightstreamer server, activate a
+subscription, then print streaming output from the server as it becomes available.
+
+To print streaming data from the demo server run the following command:
+
+```
+lightstreamer --address http://push.lightstreamer.com --adapter-set DEMO --adapter QUOTE_ADAPTER \
+              --items item1 item2 item3 item4 item5 --fields time stock_name bid ask bid
+```
+
+To see a full list of available options run the following command:
+
+```
+lightstreamer help stream
+```
+
+## Documentation
+
+API documentation is available [here](http://www.rubydoc.info/github/rviney/lightstreamer).
+
+## Contributors
+
+Gem created by Richard Viney. All contributions welcome.
+
+[gem-link]: https://rubygems.org/gems/lightstreamer
+[gem-badge]: https://badge.fury.io/rb/lightstreamer.svg
+[travis-ci-link]: http://travis-ci.org/rviney/lightstreamer
+[travis-ci-badge]: https://travis-ci.org/rviney/lightstreamer.svg?branch=master
+[test-coverage-link]: https://codeclimate.com/github/rviney/lightstreamer/coverage
+[test-coverage-badge]: https://codeclimate.com/github/rviney/lightstreamer/badges/coverage.svg
+[code-climate-link]: https://codeclimate.com/github/rviney/lightstreamer
+[code-climate-badge]: https://codeclimate.com/github/rviney/lightstreamer/badges/gpa.svg
+[dependencies-link]: https://gemnasium.com/rviney/lightstreamer
+[dependencies-badge]: https://gemnasium.com/rviney/lightstreamer.svg
+[documentation-link]: https://inch-ci.org/github/rviney/lightstreamer
+[documentation-badge]: https://inch-ci.org/github/rviney/lightstreamer.svg?branch=master
+[license-link]: https://github.com/rviney/lightstreamer/blob/master/LICENSE.md
+[license-badge]: https://img.shields.io/badge/license-MIT-blue.svg

data/bin/lightstreamer

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift File.dirname(File.realpath(__FILE__)) + '/../lib'
+
+require 'lightstreamer'
+
+Lightstreamer::CLI::Main.bootstrap ARGV

data/lib/lightstreamer.rb

@@ -0,0 +1,18 @@
+require 'rest-client'
+require 'thor'
+
+require 'lightstreamer/control_connection'
+require 'lightstreamer/line_buffer'
+require 'lightstreamer/protocol_error'
+require 'lightstreamer/request_error'
+require 'lightstreamer/session'
+require 'lightstreamer/stream_connection'
+require 'lightstreamer/subscription'
+require 'lightstreamer/version'
+
+require 'lightstreamer/cli/main'
+require 'lightstreamer/cli/stream_command'
+
+# This module contains all the code for the Lightstreamer gem. See `README.md` to get started with using this gem.
+module Lightstreamer
+end

data/lib/lightstreamer/cli/main.rb

@@ -0,0 +1,24 @@
+module Lightstreamer
+  # This module contains the code for the CLI frontend. See `README.md` for usage details.
+  module CLI
+    # Implements the `lightstreamer` command-line client.
+    class Main < Thor
+      default_task :stream
+
+      class << self
+        # This is the initial entry point for the execution of the command-line client. It is responsible for the
+        # --version/-v options and then invoking the main application.
+        #
+        # @param [Array<String>] argv The array of command-line arguments.
+        def bootstrap(argv)
+          if argv.index('--version') || argv.index('-v')
+            puts VERSION
+            exit
+          end
+
+          start argv
+        end
+      end
+    end
+  end
+end

data/lib/lightstreamer/cli/stream_command.rb

@@ -0,0 +1,50 @@
+module Lightstreamer
+  module CLI
+    # Implements the `lightstreamer stream` command.
+    class Main < Thor
+      desc 'stream', 'Streams a set of items and fields from a Lightstreamer server and prints the live output'
+
+      option :address, required: true, desc: 'The address of the Lightstreamer server'
+      option :username, desc: 'The username for the session'
+      option :password, desc: 'The password for the session'
+      option :adapter_set, desc: 'The name of the adapter set for the session'
+      option :adapter, desc: 'The name of the data adapter to stream data from'
+      option :items, type: :array, required: true, desc: 'The names of the item(s) to stream'
+      option :fields, type: :array, required: true, desc: 'The field(s) to stream'
+      option :mode, enum: %w(distinct merge), default: :merge, desc: 'The operation mode'
+
+      def stream
+        session = create_session
+        session.connect
+
+        @queue = Queue.new
+
+        session.subscribe create_subscription
+
+        loop do
+          puts @queue.pop
+        end
+      end
+
+      private
+
+      # Creates a new session from the specified options.
+      def create_session
+        Lightstreamer::Session.new server_url: options[:address], username: options[:username],
+                                   password: options[:password], adapter_set: options[:adapter_set]
+      end
+
+      # Creates a new subscription from the specified options.
+      def create_subscription
+        subscription = Lightstreamer::Subscription.new items: options[:items], fields: options[:fields],
+                                                       mode: options[:mode], adapter: options[:adapter]
+
+        subscription.add_data_callback do |_subscription, item_name, _item_data, new_values|
+          @queue.push "#{item_name} - #{new_values.map { |key, value| "#{key}: #{value}" }.join ', '}"
+        end
+
+        subscription
+      end
+    end
+  end
+end

data/lib/lightstreamer/control_connection.rb

@@ -0,0 +1,70 @@
+module Lightstreamer
+  # This is an internal class used by {Session} and is responsible for sending Lightstreamer control requests.
+  class ControlConnection
+    # Initializes this class for sending Lightstreamer control requests using the specified session ID and control
+    # address.
+    #
+    # @param [String] session_id The Lightstreamer session ID.
+    # @param [String] control_url The URL of the server to send Lightstreamer control requests to.
+    def initialize(session_id, control_url)
+      @session_id = session_id
+      @control_url = URI.join(control_url, '/lightstreamer/control.txt').to_s
+    end
+
+    # Sends a Lightstreamer control request with the specified options. If an error occurs then {RequestError} or
+    # {ProtocolError} will be raised.
+    #
+    # @param [Hash] options The control request options.
+    # @option options [Fixnum] :table The ID of the table this request pertains to. Required.
+    # @option options [:add, :add_silent, :start, :delete] :operation The operation to perform. Required.
+    # @option options [String] :adapter The name of the data adapter to use. Optional.
+    # @option options [Array<String>] :items The names of the items that this request pertains to. Required if
+    #                 `:operation` is `:add` or `:add_silent`.
+    # @option options [Array<String>] :fields The names of the fields that this request pertains to. Required if
+    #                 `:operation` is `:add` or `:add_silent`.
+    # @option options [:raw, :merge, :distinct, :command] :mode The subscription mode.
+    def execute(options)
+      result = execute_post_request build_payload(options)
+
+      return if result.first == 'OK'
+      raise ProtocolError, result[2], result[1] if result.first == 'ERROR'
+
+      warn "Lightstreamer: unexpected response from server: #{result}"
+    end
+
+    private
+
+    # Executes a POST request to the control address with the specified payload. Raises an error if the HTTP request
+    # fails. Returns the response from the server split into individual lines.
+    def execute_post_request(payload)
+      response = RestClient::Request.execute method: :post, url: @control_url, payload: payload
+
+      response.body.split("\n").map(&:strip)
+    rescue RestClient::Exception => exception
+      raise RequestError, exception.message
+    rescue SocketError => socket_error
+      raise RequestError, socket_error
+    end
+
+    # Constructs the payload for a Lightstreamer control request based on the given options hash. See {#execute} for
+    # details on the supported keys.
+    def build_payload(options)
+      params = {
+        LS_session: @session_id,
+        LS_table: options.fetch(:table),
+        LS_op: options.fetch(:operation)
+      }
+
+      build_optional_payload_fields options, params
+
+      URI.encode_www_form params
+    end
+
+    def build_optional_payload_fields(options, params)
+      params[:LS_data_adapter] = options[:adapter] if options.key? :adapter
+      params[:LS_id] = options[:items].join(' ') if options.key? :items
+      params[:LS_schema] = options[:fields].map(&:to_s).join(' ') if options.key? :fields
+      params[:LS_mode] = options[:mode].to_s.upcase if options.key? :mode
+    end
+  end
+end

data/lib/lightstreamer/line_buffer.rb

@@ -0,0 +1,22 @@
+module Lightstreamer
+  # Helper class that takes an incoming stream of ASCII data and yields back individual lines as they become complete.
+  class LineBuffer
+    def initialize
+      @buffer = ''
+    end
+
+    # Appends a new piece of ASCII data to this buffer. Any lines that are now complete will be yielded back.
+    #
+    # @param [String] data The new piece of ASCII data.
+    def process(data)
+      @buffer << data
+
+      lines = @buffer.split "\n"
+      @buffer = @buffer.end_with?("\n") ? '' : lines.pop
+
+      lines.each do |line|
+        yield line.strip
+      end
+    end
+  end
+end

data/lib/lightstreamer/protocol_error.rb

@@ -0,0 +1,22 @@
+module Lightstreamer
+  # This error class is raised by {Session} when a request to the Lightstreamer API fails with a Lightstreamer-specific
+  # error code and error message.
+  class ProtocolError < StandardError
+    # @return [String] A description of the Lightstreamer error that occurred.
+    attr_reader :error
+
+    # @return [Fixnum] The numeric code of the Lightstreamer error.
+    attr_reader :code
+
+    # Initializes this protocol error with the specific message and code.
+    #
+    # @param [String] error The error description.
+    # @param [Integer] code The numeric code for the error.
+    def initialize(error, code)
+      @error = error.to_s
+      @http_code = code.to_i
+
+      super "Lightstreamer error: #{@error}, code: #{code}"
+    end
+  end
+end

data/lib/lightstreamer/request_error.rb

@@ -0,0 +1,21 @@
+module Lightstreamer
+  # This error class is raised by {Session} when a request to the Lightstreamer API fails.
+  class RequestError < StandardError
+    # @return [String] A description of the error that occurred when the request was attempted.
+    attr_reader :error
+
+    # @return [Fixnum] The HTTP code that was returned, or `nil` if unknown.
+    attr_reader :http_code
+
+    # Initializes this request error with a message and an HTTP code.
+    #
+    # @param [String] error The error description.
+    # @param [Integer] http_code The HTTP code for the request failure, if known.
+    def initialize(error, http_code = nil)
+      @error = error.to_s
+      @http_code = http_code ? http_code.to_i : nil
+
+      super "Request error: #{error}#{http_code ? ", http code: #{http_code}" : ''}"
+    end
+  end
+end

data/lib/lightstreamer/session.rb

@@ -0,0 +1,143 @@
+module Lightstreamer
+  # This class is responsible for managing a Lightstreamer session, and along with the {Subscription} class is the
+  # primary interface for working with Lightstreamer.
+  class Session
+    # @return [String] The URL of the Lightstreamer server to connect to. Set by {#initialize}.
+    attr_reader :server_url
+
+    # @return [String] The username to connect to the Lightstreamer server with. Set by {#initialize}.
+    attr_reader :username
+
+    # @return [String] The password to connect to the Lightstreamer server with. Set by {#initialize}.
+    attr_reader :password
+
+    # @return [String] The name of the adapter set to request from the Lightstreamer server. Set by {#initialize}.
+    attr_reader :adapter_set
+
+    # Initializes this new Lightstreamer session with the passed options.
+    #
+    # @param [Hash] options The options to create the session with.
+    # @option options [String] :server_url The URL of the Lightstreamer server. Required.
+    # @option options [String] :username The username to connect to the server with. Optional.
+    # @option options [String] :password The password to connect to the server with. Optional.
+    # @option options [String] :adapter_set The name of the adapter set to request from the server. Optional.
+    def initialize(options = {})
+      @subscriptions = []
+      @subscriptions_mutex = Mutex.new
+
+      @server_url = options.fetch :server_url
+      @username = options[:username]
+      @password = options[:password]
+      @adapter_set = options[:adapter_set]
+    end
+
+    # Creates a new Lightstreamer session using the details passed to {#initialize}. If an error occurs then
+    # {ProtocolError} will be raised.
+    def connect
+      @stream_connection = StreamConnection.new self
+      @subscriptions = []
+
+      first_line = @stream_connection.read_line
+
+      if first_line == 'OK'
+        @session_id = read_session_id
+        create_control_connection
+        create_processing_thread
+      elsif first_line == 'ERROR'
+        handle_connection_error
+      end
+    end
+
+    # Subscribes this Lightstreamer session to the specified subscription.
+    #
+    # @param [Subscription] subscription The new subscription to subscribe to.
+    def subscribe(subscription)
+      subscription.clear_data
+
+      @subscriptions_mutex.synchronize { @subscriptions << subscription }
+
+      begin
+        @control_connection.execute table: subscription.id, operation: :add, mode: subscription.mode,
+                                    items: subscription.items, fields: subscription.fields,
+                                    adapter: subscription.adapter
+      rescue
+        @subscriptions_mutex.synchronize { @subscriptions.delete subscription }
+        raise
+      end
+    end
+
+    # Unsubscribes this Lightstreamer session from the specified subscription.
+    #
+    # @param [Subscription] subscription The existing subscription to unsubscribe from.
+    def unsubscribe(subscription)
+      @subscriptions_mutex.synchronize do
+        raise ArgumentError, 'Unknown subscription' unless @subscriptions.detect subscription
+      end
+
+      @control_connection.execute table: subscription.id, operation: :delete
+
+      @subscriptions_mutex.synchronize { @subscriptions.delete subscription }
+    end
+
+    private
+
+    # Parses the next line of data from the stream connection as the session ID and returns it.
+    def read_session_id
+      @stream_connection.read_line.match(/^SessionId:(.*)$/).captures.first
+    end
+
+    # Attempts to parses the next line of data from the stream connection as a custom control address and then uses this
+    # address to create the control connection. Note that the control address is optional and if it is absent then
+    # {#server_url} will be used instead of a custom control address.
+    def create_control_connection
+      match = @stream_connection.read_line.match(/^ControlAddress:(.*)$/)
+      control_address = (match && match.captures.first) || server_url
+
+      # The rest of the contents in the header is ignored, so read up until the blank line that marks its ending
+      loop { break if @stream_connection.read_line == '' }
+
+      # If the control URL doesn't have a schema then use the same schema as the server URL
+      control_address = "#{URI(server_url).scheme}://#{control_address}" unless control_address.start_with? 'http'
+
+      @control_connection = ControlConnection.new @session_id, control_address
+    end
+
+    # Starts the processing thread that reads and processes incoming data from the stream connection.
+    def create_processing_thread
+      @processing_thread = Thread.new do
+        begin
+          loop do
+            process_stream_data @stream_connection.read_line
+          end
+        rescue StandardError => error
+          warn "Lightstreamer: exception in processing thread: #{error}"
+          exit 1
+        end
+      end
+    end
+
+    # Processes a single line of incoming stream data by passing it to all the active subscriptions until one
+    # successfully processes it. This method is always run on the processing thread.
+    def process_stream_data(line)
+      was_processed = @subscriptions_mutex.synchronize do
+        @subscriptions.detect do |subscription|
+          subscription.process_stream_data line
+        end
+      end
+
+      warn "Lightstreamer: unprocessed stream data '#{line}'" unless was_processed
+    end
+
+    # Handles a failure to establish a stream connection by reading off the error code and error message then raising
+    # a {ProtocolError}.
+    def handle_connection_error
+      error_code = @stream_connection.read_line
+      error_message = @stream_connection.read_line
+
+      @stream_connection = nil
+      @control_connection = nil
+
+      raise ProtocolError, error_message, error_code
+    end
+  end
+end

data/lib/lightstreamer/stream_connection.rb

@@ -0,0 +1,79 @@
+module Lightstreamer
+  # Manages a long-running Lightstreamer connection that handles incoming streaming data on a separate thread and
+  # makes it available for consumption via the {#read_line} method.
+  class StreamConnection
+    # Establishes a new stream connection using the authentication details from the passed session.
+    #
+    # @param [Session] session The session to create a stream connection for.
+    def initialize(session)
+      @session = session
+      @queue = Queue.new
+
+      create_stream
+      create_stream_thread
+    end
+
+    # Reads the next line of streaming data. This method blocks the calling thread until a line of data is available.
+    def read_line
+      @queue.pop
+    end
+
+    private
+
+    def create_stream
+      @stream = Net::HTTP.new stream_uri.host, stream_uri.port
+      @stream.use_ssl = true if stream_uri.port == 443
+    end
+
+    def create_stream_thread
+      @thread = Thread.new do
+        begin
+          connect_stream_and_queue_data
+
+          warn 'Lightstreamer: stream connection closed'
+        rescue StandardError => error
+          warn "Lightstreamer: exception in stream thread: #{error}"
+          exit 1
+        end
+      end
+    end
+
+    def initiate_stream_post_request
+      Net::HTTP::Post.new(stream_uri.path).tap do |request|
+        request.body = stream_create_parameters
+      end
+    end
+
+    def connect_stream_and_queue_data
+      @stream.request initiate_stream_post_request do |response|
+        buffer = LineBuffer.new
+        response.read_body do |data|
+          buffer.process data do |line|
+            @queue.push line unless ignore_line? line
+          end
+        end
+      end
+    end
+
+    def stream_uri
+      URI.join @session.server_url, '/lightstreamer/create_session.txt'
+    end
+
+    def stream_create_parameters
+      params = {
+        LS_op2: 'create',
+        LS_cid: 'mgQkwtwdysogQz2BJ4Ji kOj2Bg',
+        LS_user: @session.username,
+        LS_password: @session.password
+      }
+
+      params[:LS_adapter_set] = @session.adapter_set if @session.adapter_set
+
+      URI.encode_www_form params
+    end
+
+    def ignore_line?(line)
+      line =~ /^(PROBE|Preamble:.*)$/
+    end
+  end
+end

data/lib/lightstreamer/subscription.rb

@@ -0,0 +1,194 @@
+module Lightstreamer
+  # Describes a subscription that can be bound to a Lightstreamer session in order to consume its data. A subscription
+  # is described by the options passed to {#initialize}. Incoming data can be consumed by registering an asynchronous
+  # data callback using {#add_data_callback}, or by polling {#retrieve_item_data}. Subscriptions start receiving data
+  # only once they are attached to a Lightstreamer session using {Session#subscribe}.
+  class Subscription
+    # @return [Fixnum] The unique identification number of this subscription. This is used to identify the subscription
+    #                  in incoming Lightstreamer data.
+    attr_reader :id
+
+    # @return [Array<String>] The names of the items to subscribe to.
+    attr_reader :items
+
+    # @return [Array<String>] The names of the fields to subscribe to on the items.
+    attr_reader :fields
+
+    # @return [:distinct, :merge] The operation mode of this subscription.
+    attr_reader :mode
+
+    # @return [String] The name of the data adapter from the Lightstreamer session's adapter set that should be used.
+    #                  If `nil` then the default data adapter will be used.
+    attr_reader :adapter
+
+    # Initializes a new Lightstreamer subscription with the specified options. This can then be passed to
+    # {Session#subscribe} to activate the subscription on a Lightstreamer session.
+    #
+    # @param [Hash] options The options to create the subscription with.
+    # @option options [Array<String>] :items The names of the items to subscribe to.
+    # @option options [Array<String>] :fields The names of the fields to subscribe to on the items.
+    # @option options [:distinct, :merge] :mode The operation mode of this subscription.
+    # @option options [String] :adapter The name of the data adapter from the Lightstreamer session's adapter set that
+    #                 should be used. If `nil` then the default data adapter will be used.
+    def initialize(options)
+      @id = self.class.next_id
+
+      @items = Array(options.fetch(:items))
+      @fields = Array(options.fetch(:fields))
+      @mode = options.fetch(:mode).to_sym
+      @adapter = options[:adapter]
+
+      @data_mutex = Mutex.new
+      clear_data
+
+      @data_callbacks = []
+    end
+
+    # Clears all current data stored for this subscription. New data will continue to be processed as it becomes
+    # available.
+    def clear_data
+      @data_mutex.synchronize do
+        @data = (0...items.size).map { { distinct: [], merge: {} }.fetch(mode) }
+      end
+    end
+
+    # Clears the current data stored for the specified item. This is important to do when {#mode} is `:distinct` as
+    # otherwise the incoming data will build up indefinitely.
+    #
+    # @param [String] item_name The name of the item to clear the current data of.
+    def clear_data_for_item(item_name)
+      index = @items.index item_name
+      raise ArgumentError, 'Unrecognized item name' unless index
+
+      @data_mutex.synchronize do
+        @data[index] = { distinct: [], merge: {} }.fetch(mode)
+      end
+    end
+
+    # Adds the passed block to the list of callbacks that will be run when new data for this subscription arrives. The
+    # block will be called on a worker thread and so the code that is run by the block must be thread-safe. The
+    # arguments passed to the block are `|subscription, item_name, item_data, new_values|`.
+    #
+    # @param [Proc] block The callback block that is to be run when new data arrives.
+    #
+    # @return [Proc] The same `Proc` object that was passed to this method. This can be used to remove this data
+    #         callback at a later stage using {#remove_data_callback}.
+    def add_data_callback(&block)
+      raise ArgumentError, 'Data callbacks must take four arguments' unless block.arity == 4
+
+      @data_mutex.synchronize { @data_callbacks << block }
+
+      block
+    end
+
+    # Removes a data callback that was added by {#add_data_callback}.
+    #
+    # @param [Proc] block The data callback block to remove.
+    def remove_data_callback(block)
+      @data_mutex.synchronize { @data_callbacks.delete block }
+    end
+
+    # Returns the current data of one of this subscription's items.
+    #
+    # @param [String] item_name The name of the item to return the current data for.
+    #
+    # @return [Hash, Array] The item data. Will be a `Hash` if {#mode} is `:merge`, and an `Array` if {#mode} is
+    #         `:distinct`.
+    def retrieve_item_data(item_name)
+      index = @items.index item_name
+      raise ArgumentError, 'Unrecognized item name' unless index
+
+      @data_mutex.synchronize do
+        @data[index].dup
+      end
+    end
+
+    # Processes a line of stream data if it is relevant to this subscription. This method is thread-safe and is intended
+    # to be called by the session's processing thread.
+    #
+    # @param [String] line The line of stream data to process.
+    #
+    # @return [Boolean] Whether the passed line of stream data was relevant to this subscription and was successfully
+    #         processed by it.
+    def process_stream_data(line)
+      item_index, values = parse_stream_data line
+      return false unless item_index
+
+      @data_mutex.synchronize do
+        data = @data[item_index]
+
+        data << values if mode == :distinct
+        data.merge!(values) if mode == :merge
+
+        @data_callbacks.each { |callback| callback.call self, @items[item_index], data, values }
+      end
+
+      true
+    end
+
+    # Returns the next unique ID to use for a new subscription.
+    #
+    # @return [Fixnum]
+    def self.next_id
+      @next_id ||= 0
+      @next_id += 1
+    end
+
+    private
+
+    # Attempts to parse an line of stream data.
+    #
+    # @param [String] line The line of stream data to parse.
+    #
+    # @return [Array] The first value is the item index, and the second is a hash of the values contained in the stream
+    #                 data. Will be nil if the stream data was not able to be parsed.
+    def parse_stream_data(line)
+      match = line.match stream_data_regex
+      return unless match
+
+      item_index = match.captures[0].to_i - 1
+      return unless item_index < @items.size
+
+      [item_index, parse_values(match.captures[1..-1])]
+    end
+
+    # Returns the regular expression that will match a single line of data in the incoming stream that is relevant to
+    # this subscription. The ID at the beginning must match, as well as the number of fields.
+    #
+    # @return [Regexp]
+    def stream_data_regex
+      Regexp.new "^#{id},(\\d+)#{'\|(.*)' * fields.size}"
+    end
+
+    # Parses an array of values from an incoming line of stream data into a hash where the keys are the field names
+    # defined for this subscription.
+    #
+    # @param [String] values The raw values from the incoming stream data.
+    #
+    # @return [Hash] The parsed values as a hash where the keys are the field names of this subscription.
+    def parse_values(values)
+      hash = {}
+
+      values.each_with_index do |value, index|
+        next if value == ''
+
+        # These conversions are specified in the Lightstreamer specification
+        value = '' if value == '$'
+        value = nil if value == '#'
+        value = value[1..-1] if value =~ /^($|#)/
+
+        hash[fields[index]] = convert_utf16_characters value
+      end
+
+      hash
+    end
+
+    # Non-ASCII characters are transmitted as UTF-16 escape sequences in the form '\uXXXX' or '\uXXXX\uYYYY'. This
+    # method is respnsible for converting such escape sequences into native Unicode characters.
+    #
+    # @todo Implement this method.
+    def convert_utf16_characters(value)
+      value
+    end
+  end
+end

data/lib/lightstreamer/version.rb

@@ -0,0 +1,4 @@
+module Lightstreamer
+  # The version of this gem.
+  VERSION = '0.1'.freeze
+end

metadata

@@ -0,0 +1,213 @@
+--- !ruby/object:Gem::Specification
+name: lightstreamer
+version: !ruby/object:Gem::Version
+  version: '0.1'
+platform: ruby
+authors:
+- Richard Viney
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-07-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.19'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.19'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: codeclimate-test-reporter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: factory_girl
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.7'
+- !ruby/object:Gem::Dependency
+  name: github-markup
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+- !ruby/object:Gem::Dependency
+  name: rspec-mocks
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.41'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.41'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: 
+email: richard.viney@gmail.com
+executables:
+- lightstreamer
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.md
+- README.md
+- bin/lightstreamer
+- lib/lightstreamer.rb
+- lib/lightstreamer/cli/main.rb
+- lib/lightstreamer/cli/stream_command.rb
+- lib/lightstreamer/control_connection.rb
+- lib/lightstreamer/line_buffer.rb
+- lib/lightstreamer/protocol_error.rb
+- lib/lightstreamer/request_error.rb
+- lib/lightstreamer/session.rb
+- lib/lightstreamer/stream_connection.rb
+- lib/lightstreamer/subscription.rb
+- lib/lightstreamer/version.rb
+homepage: https://github.com/rviney/lightstreamer
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: Ruby client for accessing a Lightstreamer server.
+test_files: []