ocean-dynamo 1.0.8 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d978bad9958a6105af68a85d96d0d38b677f26b4
-  data.tar.gz: de5eecbb27c422971d41e5a78b905b4ea183cde0
+  metadata.gz: 5a5d6a93318aea2c36029d1f40d3496ad5cc16a1
+  data.tar.gz: 17f2f4d1edf4885662aea89e61948924d7e2bfdb
 SHA512:
-  metadata.gz: d8253aa7f354f8d3295be2482ab792aa5c00fd297473cbad21eba2b3e3dd3eb3e54cd1a10894a9229a4a22c4a114833809baed95b445f7e0b73bbf884732e74f
-  data.tar.gz: 6385f3c5adab407a884bddfe592a453830792a7da8985851c14ab5e047377135676fc7b11cc1519c6cd5a88736d622990d22d6575e76ae2d726516df679acd77
+  metadata.gz: d3f9aff5b1b2f3402946acb6c5806b32582e3baeefa758ea4d35183386cde1bb937e88204a8feb8fddabc107b16c13540c334bd0ddf04ce91b39822e9a3c6284
+  data.tar.gz: 1cfb33f43e6888a7f7f7417900baf99b9d777ef2797a52d96f5af36e090bedd46f2543210f62237f7e4db547570a67094cb1bd3e094ec13e36671b11154fe1eb

data/README.rdoc

@@ -18,16 +18,65 @@ closely and is of course based on ActiveModel.
 
 The attribute and persistence layer of OceanDynamo is modeled on that of ActiveRecord:
 there's +save+, +save!+, +create+, +update+, +update!+, +update_attributes+, +find_each+,
-+destroy_all+, +delete_all+ and all the other methods you're used to. The design goal 
-is always to implement as much of the ActiveRecord interface as possible, without 
-compromising scalability. This makes the task of switching from SQL to no-SQL much easier.
-
-Thanks to its structural similarity to ActiveRecord, OceanDynamo works with FactoryGirl.
++destroy_all+, +delete_all+, +read_attribute+, +write_attribute+ and all the other 
+methods you're used to. The design goal is always to implement as much of the ActiveRecord
+interface as possible, without compromising scalability. This makes the task of switching 
+from SQL to no-SQL much easier.
 
 OceanDynamo uses only primary indices to retrieve related table items and collections, 
 which means it will scale without limits.
 
-=== Example
+OceanDynamo is fully usable as an ActiveModel and can be used by Rails
+controllers. Thanks to its structural similarity to ActiveRecord, OceanDynamo works 
+with FactoryGirl.
+
+
+=== Current State
+
+* Local secondary indices are now supported! See below for more information.
+* Version 2 of the AWS Ruby SDK is now used. This required an internal reorganisation, 
+  but it also gives us access to local and global secondary indices.
+* Work begun on association proxies, etc.
+
+
+=== Future milestones
+
+* Association proxies, to implement ActiveRecord-style method chaining, e.g.: 
+  <code>blog_entry.comments.build(body: "Cool!").save!</code>
+* The +has_and_belongs_to_many+ assocation. 
+* A generator to install the <tt>config/aws.yml</tt> file.
+
+
+=== Current use
+
+OceanDynamo is used as a central component in Ocean, a Rails framework and development 
+pipeline for creating highly scalable HATEOAS microservice SOAs in the cloud.
+* http://wiki.oceanframework.net
+
+Ocean uses OceanDynamo to implement highly scalable job queues and authentication. 
+It will be used increasingly as features are added to OceanDynamo and will eventually 
+replace all ActiveRecord tables in Ocean. 
+
+However, OceanDynamo can of course also be used stand-alone.
+
+
+== Documentation
+
+* Ocean-dynamo gem on Rubygems: https://rubygems.org/gems/ocean-dynamo
+* Ocean-dynamo gem API: http://rubydoc.info/gems/ocean-dynamo/frames
+* Ocean-dynamo source and wiki: https://github.org/OceanDev/ocean-dynamo
+* AWS DynamoDB Ruby SDK v2: http://docs.aws.amazon.com/sdkforruby/api/Aws/DynamoDB.html
+
+
+== Contributing
+
+Contributions are welcome. Fork in the usual way. OceanDynamo is developed using
+TDD: the specs are extensive and test coverage is very near to 100 percent. Pull requests
+will not be considered unless all tests pass and coverage is equally high or higher.
+All contributed code must therefore also be exhaustively tested.
+
+
+=== Examples
 
 ==== Basic syntax
 
@@ -45,7 +94,7 @@ The following example shows the basic syntax for declaring a DynamoDB-based sche
       attribute :started_at,           :datetime
       attribute :last_completed_step,  :integer
       attribute :finished_at,          :datetime
-      attribute :destroy_at,           :datetime
+      attribute :destroy_at,           :datetime,   local_secondary_index: true
       attribute :created_by
       attribute :updated_by
       attribute :succeeded,            :boolean,    default: false
@@ -73,8 +122,8 @@ value will return the empty string, <tt>""</tt>.
 +dynamo_schema+ takes args and many options. Here's the full syntax:
 
  dynamo_schema(
-   table_hash_key: = :id,                  # The name of the hash key attribute
-   table_range_key: = nil,                 # The name of the range key attribute (or nil)
+   table_hash_key = :id,                   # The name of the hash key attribute
+   table_range_key = nil,                  # The name of the range key attribute (or nil)
    table_name: compute_table_name,         # The basename of the DynamoDB table
    table_name_prefix: nil,                 # A basename prefix string or nil
    table_name_suffix: nil,                 # A basename suffix string or nil
@@ -166,32 +215,40 @@ Nevertheless, as we now have switched to v2 of the DynamoDB API, we will be addi
 the possibility to define both local and secondary indices for Tables. 
 
 
-=== Current State
-
-OceanDynamo is fully usable as an ActiveModel and can be used by Rails
-controllers. OceanDynamo implements much of the infrastructure of ActiveRecord;
-for instance, +read_attribute+, +write_attribute+, and much of the control logic and
-internal organisation.
-
-* Version 2 of the AWS Ruby SDK is now used. This required an internal reorganisation, 
-  but it also gives us access to local and global secondary indices.
-* Work begun on collection proxies, etc.
+=== Local Secondary Indices
 
-=== Future milestones
+We now have basic support for local secondary indices. Up to five attributes can
+be declared as local secondary indices, in the following manner:
 
-* Association proxies, to implement ActiveRecord-style method chaining, e.g.: 
-  <code>blog_entry.comments.build(body: "Cool!").save!</code>
-
-* The +has_and_belongs_to_many+ assocation. 
-
-* A generator to install the <tt>config/aws.yml</tt> file.
+  class Authentication < OceanDynamo::Table
+    dynamo_schema(:username, :expires_at,
+                  timestamps: nil, locking: false
+                  table_name_suffix: Api.basename_suffix) do
+      attribute :token,       :string,   local_secondary_index: true
+      attribute :max_age,     :integer
+      attribute :created_at,  :datetime
+      attribute :expires_at,  :datetime
+      attribute :api_user_id, :string
+    end
+  end
 
+The items of the above table can be accessed by using the hash key :username and
+the range key :expires_at. The +local_secondary_index+ declaration makes it possible
+to access items using the same hash key :username but with :token as an alternate
+range key. Local secondary indices all use the same hash key as the primary index,
+substituting another attribute instead as the range key.
 
-=== Current use
+NB: The primary index [:username, :expires_at] requires all items to have a unique
+combination of keys. Secondary indices don't require the range key to be unique for
+the same hash key. This means that secondary index searches always will return a
+collection.
 
-OceanDynamo is currently used in the Ocean framework (http://wiki.oceanframework.net)
-e.g. to implement highly scalable job queues. It will be used increasingly as features are
-added to OceanDynamo and will eventually replace all ActiveRecord tables in Ocean.
+We will add support for specifying that a secondary index is to be used in +find_each+ 
+and its derivatives, but for now you will have to specify this explicitly in the
+options passed to +in_batches+, +query+, and +scan+. 
+* +query+: http://docs.aws.amazon.com/sdkforruby/api/Aws/DynamoDB/Table.html#query-instance_method.
+* +scan+: http://docs.aws.amazon.com/sdkforruby/api/Aws/DynamoDB/Table.html#scan-instance_method
+* +in_batches+, +find_each+: lib/ocean-dynamo/queries.rb
 
 
 == Installation
@@ -219,27 +276,6 @@ Enter your AWS credentials in the latter file. Eventually, there
 will be a generator to copy these files for you, but for now you need to do it manually. 
 
 
-== Documentation
-
-* Ocean-dynamo gem on Rubygems: https://rubygems.org/gems/ocean-dynamo
-* Ocean-dynamo gem API: http://rubydoc.info/gems/ocean-dynamo/frames
-* Ocean-dynamo source and wiki: https://github.org/OceanDev/ocean-dynamo
-* AWS DynamoDB Ruby SDK v2: http://docs.aws.amazon.com/sdkforruby/api/Aws/DynamoDB.html
-
-You might also want to take a look at Ocean, a Rails framework and development pipeline
-for creating highly scalable HATEOAS microservice SOAs in the cloud. Ocean uses 
-OceanDynamo as a central component:
-* http://wiki.oceanframework.net
-
-
-== Contributing
-
-Contributions are welcome. Fork in the usual way. OceanDynamo is developed using
-TDD: the specs are extensive and test coverage is very near to 100 percent. Pull requests
-will not be considered unless all tests pass and coverage is equally high or higher.
-All contributed code must therefore also be exhaustively tested.
-
-
 == Running the specs
 
 To run the specs for the OceanDynamo gem, you must first install DynamoDB Local. 

data/lib/ocean-dynamo/associations/has_many.rb

@@ -113,10 +113,7 @@ module OceanDynamo
     def condition_options(child_class)
       hash_key = child_class.table_hash_key
       range_key = child_class.table_range_key
-      ean = {}
-      ean["#H"] = hash_key.to_s
-      ean["#R"] = range_key.to_s if range_key
-      { expression_attribute_names: ean,
+      { expression_attribute_names: { "#H" => hash_key, "#R" => range_key },
         key_condition_expression: "#H = :hashval AND #R >= :rangeval",
         expression_attribute_values: { ":hashval" => id, ":rangeval" => "0" }
       }

data/lib/ocean-dynamo/persistence.rb

@@ -50,8 +50,8 @@ module OceanDynamo
       #
       def delete_all
         _late_connect?
-        ean = { "#H" => table_hash_key.to_s }
-        ean["#R"] = table_range_key.to_s if table_range_key
+        ean = { "#H" => table_hash_key }
+        ean["#R"] = table_range_key if table_range_key
         options = {
           consistent_read: true,
           projection_expression: "#H" + (table_range_key ? ", #R" : ""),

data/lib/ocean-dynamo/tables.rb

@@ -44,7 +44,7 @@ module OceanDynamo
 
 
       def establish_db_connection
-        setup_dynamo  
+        setup_dynamo
         if table_exists?(dynamo_table)
           wait_until_table_is_active
           self.table_connected = true
@@ -95,17 +95,19 @@ module OceanDynamo
 
 
        def create_table
-        attrs = table_attribute_definitions
+        attrs = table_attribute_definitions  # This already includes secondary indices
         keys = table_key_schema
         options = {
           table_name: table_full_name,
+          attribute_definitions: attrs,
+          key_schema: keys,
           provisioned_throughput: {
             read_capacity_units: table_read_capacity_units,
             write_capacity_units: table_write_capacity_units
-          },
-          attribute_definitions: attrs,
-          key_schema: keys
+          }
         }
+        lsi = local_secondary_indexes.collect { |n| local_secondary_index_declaration n }
+        options[:local_secondary_indexes] = lsi unless lsi.blank?
         dynamo_resource.create_table(options)
         sleep 1 until dynamo_table.table_status == "ACTIVE"
         setup_dynamo
@@ -126,10 +128,33 @@ module OceanDynamo
       end
 
 
+      def local_secondary_indexes
+        @local_secondary_indexes ||= begin
+          result = []
+          fields.each do |name, metadata|
+            (result << name) if metadata["local_secondary_index"]
+          end
+          result
+        end
+      end
+
+
+      def local_secondary_index_declaration(name)
+        { index_name: name,
+          key_schema: [{ attribute_name: table_hash_key.to_s, key_type: "HASH" },
+                       { attribute_name: name.to_s, key_type: "RANGE" }],
+          projection: { projection_type: "KEYS_ONLY" }
+        }
+      end
+
+
       def table_attribute_definitions
         attrs = []
         attrs << { attribute_name: table_hash_key.to_s, attribute_type: attribute_type(table_hash_key) }
         attrs << { attribute_name: table_range_key.to_s, attribute_type: attribute_type(table_range_key) }  if table_range_key
+        local_secondary_indexes.each do |name|
+          attrs << { attribute_name: name, attribute_type: attribute_type(name) }
+        end
         attrs
       end
 

data/lib/ocean-dynamo/version.rb

@@ -1,3 +1,3 @@
 module OceanDynamo
-  VERSION = "1.0.8"
+  VERSION = "1.1.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ocean-dynamo
 version: !ruby/object:Gem::Version
-  version: 1.0.8
+  version: 1.1.0
 platform: ruby
 authors:
 - Peter Bengtson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-09-17 00:00:00.000000000 Z
+date: 2015-09-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk