airspace 1.0.0

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'airspace'
+
+# 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/lib/airspace.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+require_relative 'airspace/airspace'

data/lib/airspace/airspace.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+require 'forwardable'
+require 'json'
+require 'securerandom'
+require 'time'
+
+require_relative 'key'
+require_relative 'info_keys'
+require_relative 'chunker'
+require_relative 'metadata'
+require_relative 'has_metadata'
+require_relative 'dataset'
+require_relative 'serializer'
+require_relative 'reader'
+require_relative 'store'
+
+# Top-level namespace for primary public API.
+module Airspace
+  class << self
+    def set(client, id: nil, data: {}, pages: [], options: {})
+      ::Airspace::Dataset.new(
+        client,
+        id: id,
+        data: data,
+        pages: pages,
+        options: options
+      ).save.id
+    end
+
+    def get(client, id, options: {})
+      ::Airspace::Reader.find_by_id(client, id, options: options)
+    end
+
+    def del(client, id, options: {})
+      reader = get(client, id, options: options)
+
+      return false unless reader
+
+      reader.delete
+    end
+  end
+end

data/lib/airspace/chunker.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Airspace
+  # Chunking here is defined as: taking an array of pages and grouping them into groups of pages
+  # (chunks) in order to find a middle-ground of server-side page and entire dataset fetches.
+  class Chunker
+    Location = Struct.new(:chunk_index, :page_index)
+    Chunk    = Struct.new(:chunk_index, :page_index_start, :page_index_end)
+
+    attr_reader :pages_per_chunk
+
+    def initialize(pages_per_chunk)
+      raise ArgumentError unless pages_per_chunk.positive?
+
+      @pages_per_chunk = pages_per_chunk
+    end
+
+    def count(page_total)
+      (page_total / pages_per_chunk.to_f).ceil
+    end
+
+    def each(page_total)
+      return enum_for(:each, page_total) unless block_given?
+
+      (0...count(page_total)).each do |chunk_index|
+        page_index_start = chunk_index * pages_per_chunk
+        page_index_end   = page_index_start + pages_per_chunk - 1
+
+        yield Chunk.new(chunk_index, page_index_start, page_index_end)
+      end
+    end
+
+    def locate(index)
+      chunk_index = (index / pages_per_chunk.to_f).floor
+      page_index = index % pages_per_chunk
+
+      Location.new(chunk_index, page_index)
+    end
+  end
+end

data/lib/airspace/dataset.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Airspace
+  # This is the main input class that can persist data.
+  class Dataset
+    include ::Airspace::InfoKeys
+    include ::Airspace::HasMetadata
+
+    attr_reader :client,
+                :data,
+                :id,
+                :pages,
+                :prefix,
+                :serializer
+
+    def initialize(client, id: nil, data: {}, pages: [], options: {})
+      raise ArgumentError, 'client is required' unless client
+
+      @client     = client
+      @data       = data || {}
+      @id         = id || SecureRandom.uuid
+      @pages      = pages || []
+      @prefix     = options[:prefix].to_s
+      @serializer = options[:serializer] || ::Airspace::Serializer.new
+
+      @metadata = ::Airspace::Metadata.new(
+        expires_in_seconds: options[:expires_in_seconds],
+        page_count: pages.length,
+        pages_per_chunk: options[:pages_per_chunk]
+      )
+
+      freeze
+    end
+
+    def save
+      store.persist(key, info_hash, chunks, expires_in_seconds)
+
+      self
+    end
+
+    private
+
+    def info_hash
+      {}.tap do |hash|
+        hash[DATA_KEY]      = serializer.serialize_data(data)
+        hash[METADATA_KEY]  = metadata.to_json
+      end
+    end
+
+    def chunks
+      chunks = []
+
+      chunker.each(page_count) do |chunk|
+        chunk_data = pages[chunk.page_index_start..chunk.page_index_end]
+
+        chunks << chunk_data.map do |page|
+          page.map { |row| serializer.serialize_row(row) }
+        end
+      end
+
+      chunks
+    end
+
+    def store
+      ::Airspace::Store.new(client)
+    end
+
+    def key
+      ::Airspace::Key.new(id, prefix: prefix)
+    end
+  end
+end

data/lib/airspace/has_metadata.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Airspace
+  # This mix-in allows for classes to be composed of a Metadata instance
+  module HasMetadata
+    extend Forwardable
+
+    attr_reader :metadata
+
+    def_delegators  :metadata,
+                    :chunk_count,
+                    :chunker,
+                    :expires_in_seconds,
+                    :page_count,
+                    :pages_per_chunk
+  end
+end

data/lib/airspace/info_keys.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Airspace
+  # Holds shared data among how to internally access data.
+  module InfoKeys
+    DATA_KEY        = 'd'
+    METADATA_KEY    = 'm'
+    SEPARATOR_CHAR  = ':'
+  end
+end

data/lib/airspace/key.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Airspace
+  # This class understands how to build keys and subkeys for storing data inside Redis.
+  class Key
+    SEPARATOR_CHAR = ':'
+
+    private_constant :SEPARATOR_CHAR
+
+    attr_reader :id, :prefix
+
+    def initialize(id, prefix: '')
+      @id     = id.to_s
+      @prefix = prefix.to_s
+    end
+
+    def root
+      return id if prefix.empty?
+
+      [prefix, id].join(SEPARATOR_CHAR)
+    end
+    alias to_s root
+
+    def chunk(index)
+      [root, index].join(SEPARATOR_CHAR)
+    end
+  end
+end

data/lib/airspace/metadata.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Airspace
+  # Metdata is 'data about a dataset.'  These are key pieces of information we need to store with
+  # the data then later retrieve with the data.
+  class Metadata
+    DEFAULT_PAGES_PER_CHUNK = 5
+
+    attr_reader :expires_in_seconds,
+                :page_count,
+                :pages_per_chunk
+
+    def initialize(expires_in_seconds: nil, page_count: 0, pages_per_chunk: DEFAULT_PAGES_PER_CHUNK)
+      @expires_in_seconds = expires_in_seconds ? expires_in_seconds.to_i : nil
+      @page_count         = page_count.to_i
+      @pages_per_chunk    = pages_per_chunk ? pages_per_chunk.to_i : DEFAULT_PAGES_PER_CHUNK
+
+      freeze
+    end
+
+    def chunker
+      ::Airspace::Chunker.new(pages_per_chunk)
+    end
+
+    def chunk_count
+      chunker.count(page_count)
+    end
+
+    def to_json
+      {
+        expires_in_seconds: expires_in_seconds,
+        page_count: page_count,
+        pages_per_chunk: pages_per_chunk
+      }.to_json
+    end
+  end
+end

data/lib/airspace/reader.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Airspace
+  # This is the main class that knows how to fetch and interpret the dataset.
+  # It is optimized for chunking/paging and allows you to only pull back specific
+  # pages (if desired.)
+  class Reader
+    extend Forwardable
+    extend ::Airspace::InfoKeys
+    include ::Airspace::HasMetadata
+
+    class << self
+      def find_by_id(client, id, options: {})
+        key        = ::Airspace::Key.new(id, prefix: options[:prefix])
+        serializer = options[:serializer] || ::Airspace::Serializer.new
+        hash       = fetch_and_transform(client, key, serializer)
+        return nil unless hash
+
+        metadata_args = hash[METADATA_KEY].map { |k, v| [k.to_sym, v] }.to_h
+
+        new(
+          client,
+          data: hash[DATA_KEY],
+          key: key,
+          metadata: ::Airspace::Metadata.new(metadata_args),
+          serializer: serializer
+        )
+      end
+
+      private
+
+      def fetch_and_transform(client, key, serializer)
+        hash = ::Airspace::Store.new(client).retrieve(key)
+        return nil unless hash
+
+        {}.tap do |h|
+          h[DATA_KEY] = serializer.deserialize_data(hash[DATA_KEY])
+          h[METADATA_KEY] = JSON.parse(hash[METADATA_KEY])
+        end
+      end
+    end
+
+    attr_reader :client,
+                :data,
+                :key,
+                :metadata,
+                :serializer
+
+    def_delegators :key, :id
+
+    def initialize(client, data:, key:, metadata:, serializer:)
+      @client     = client
+      @key        = key
+      @data       = data
+      @metadata   = metadata
+      @serializer = serializer
+
+      freeze
+    end
+
+    def pages
+      store.chunks(key, chunk_count).map do |chunk|
+        chunk.map { |r| serializer.deserialize_row(r) }
+      end
+    end
+
+    def page(number)
+      page_index  = number - 1
+      location    = chunker.locate(page_index)
+      chunk       = store.chunk(key, location.chunk_index)
+
+      chunk[location.page_index].map { |r| serializer.deserialize_row(r) }
+    end
+
+    def delete
+      store.delete(key, page_count)
+    end
+
+    private
+
+    def store
+      ::Airspace::Store.new(client)
+    end
+  end
+end

data/lib/airspace/serializer.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Airspace
+  # This class dictates how data is stored and retrieved.  You can subclass this and
+  # change its implementation that suits your overall data/space requirements.
+  class Serializer
+    def serialize_data(obj)
+      json_serialize(obj)
+    end
+
+    def deserialize_data(json)
+      json_deserialize(json)
+    end
+
+    def serialize_row(obj)
+      json_serialize(obj)
+    end
+
+    def deserialize_row(json)
+      json_deserialize(json)
+    end
+
+    private
+
+    def json_deserialize(json)
+      return nil unless json
+
+      JSON.parse(json)
+    end
+
+    def json_serialize(obj)
+      obj.to_json
+    end
+  end
+end