ndb-rails 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 407a37e97a7c0f50f39d4ca365e59bd9ecec788a9fe357e4ff4fbc61add79962
-  data.tar.gz: 0de5474707d6bf68b55d1a44f56b612a8d5a59bc24cd7e96ff8066af00e98f8b
+  metadata.gz: 93088e1e11be89558d972761a9e2a7a565d617f165b90361e732240ee92c9361
+  data.tar.gz: e9e5eca9058d1bfa6ea840c4cc8fb17c734c69d5373b933f48b1d3dfb968ebfd
 SHA512:
-  metadata.gz: 5eeed45c9f972b596dd588122600f1f7729ca07957ca771a8af0d0ca34085aa8b3c8e76d898a9605e034a6402c8370bdf57e209b2da5320a84d5904176fbeb50
-  data.tar.gz: d52fa0af1af45659950dd152a68a5561aa311b98c7b3296f70df1185d6071b70740eae7f95763bb58d1aafc35984a6aa11cf04b822d05ab98ed2a02de208a88b
+  metadata.gz: c509825a020a9efff7a220a3fbbb842bde284f32c66d66368948234de6aa258585a0cac17b4da57feb1ff44b123fbf5c8d6cde8f998978f51aa406500cbb10ee
+  data.tar.gz: 853957c1575a0653c04f91bd8f16efb65415cd42656ab5a9de44f39360820d434d63d2df2a54301ec1964805c4b286dcdde969f04fefe54b79ebd5b6784452ed

data/README.md

@@ -132,6 +132,32 @@ rescue Ndb::StaleObjectError
 end
 ```
 
+## Expiry (TTL like Redis)
+
+Give the model an `expires: true` attribute. The daemon sets it for you.
+
+```ruby
+class Session < Ndb::Record
+  primary_key :sid
+
+  attribute :user, :string
+  attribute :expires_at, :datetime, expires: true
+end
+
+Session.create!({ sid: "s1", user: "u" }, expire_in: 1.hour)   # also create, save, update (seconds, a Duration or "30m")
+session = Session.find("s1")
+
+session.expire(30.minutes)   # EXPIRE: sets expires_at in the object, other unsaved changes stay
+session.ttl                  # => 1799, -1 (never expires), or nil (missing or expired)
+session.persist_ttl!         # PERSIST: removes the expiry
+```
+
+- `persist_ttl!` is not called `persist!`: ActiveModel already uses `persisted?` for something else.
+- `expire_in:` on `create`, `save` and `update` goes in the same write. `expire_in` wins over the `expires_at` value. After a write with `expire_in`, load the record again (`Session.find`) to see `expires_at`.
+- `expire` and `persist_ttl!` raise `Ndb::NotFound` for a missing or expired document, and `Ndb::TtlNotEnabled` when the model has no `expires: true` attribute.
+- The class-level `ttl 24.hours` stays: every document expires that long after its time field. `expire` and `persist_ttl!` raise `Ndb::TtlDerived` for it.
+- Disk space of expired documents returns after compaction, and fully only with `wal_retention`; see [Freeing disk](https://github.com/thadeu/ndb/blob/main/docs/dev/configuration.md#freeing-disk).
+
 ## Query
 
 Relations are lazy and immutable. The request goes out when you call `to_a`, `first`, `each`, `count` and so on.
@@ -312,6 +338,7 @@ The transport and daemon errors are defined by the gem `ndb`. They all live in t
 | `InvalidCursor` | `cursor_invalid`, `cursor_mismatch`, `cursor_expired` |
 | `WatchLagged` | `watch_lagged` |
 | `HistoryTruncated` | `history_truncated` |
+| `TtlNotEnabled`, `TtlDerived` | `ttl_not_enabled`, `ttl_derived` |
 | `RecordInvalid` | ActiveModel validation failed (has `record`) |
 | `RecordNotSaved` | `save!` returned false without errors |
 | `ConnectionError` | cannot reach the daemon. Subclasses: `ConnectError` (nothing was sent), `TimeoutError` |

data/lib/ndb/rails/persistence.rb

@@ -12,24 +12,28 @@ module Ndb
     end
 
     class_methods do
-      def create(attrs = {}, &block)
-        return attrs.map { |a| create(a, &block) } if attrs.is_a?(Array)
+      def create(attrs = {}, expire_in: nil, **rest, &block)
+        return attrs.map { |a| create(a, expire_in: expire_in, &block) } if attrs.is_a?(Array)
+
+        attrs = attrs.merge(rest)
 
         record = new(attrs)
 
         yield record if block
-        record.save
+        record.save(expire_in: expire_in)
 
         record
       end
 
-      def create!(attrs = {}, &block)
-        return attrs.map { |a| create!(a, &block) } if attrs.is_a?(Array)
+      def create!(attrs = {}, expire_in: nil, **rest, &block)
+        return attrs.map { |a| create!(a, expire_in: expire_in, &block) } if attrs.is_a?(Array)
+
+        attrs = attrs.merge(rest)
 
         record = new(attrs)
 
         yield record if block
-        record.save!
+        record.save!(expire_in: expire_in)
 
         record
       end
@@ -71,26 +75,57 @@ module Ndb
       persisted? ? [id] : nil
     end
 
-    def save(validate: true)
+    # expire_in (seconds, an ActiveSupport::Duration or "30m") makes the daemon
+    # set the expires field to now + expire_in in the same write. The model
+    # needs an `expires: true` attribute (Ndb::TtlNotEnabled otherwise).
+    def save(validate: true, expire_in: nil)
       return false if validate && !valid?(new_record? ? :create : :update)
 
+      @expire_in = wire_duration(expire_in)
+
       run_callbacks(:save) { new_record? ? create_record : update_record } ? true : false
+    ensure
+      @expire_in = nil
     end
 
     def save!(**)
       save(**) || raise(errors.any? ? RecordInvalid.new(self) : RecordNotSaved.new("Failed to save the record"))
     end
 
-    def update(attrs)
-      assign_attributes(attrs)
+    def update(attrs = {}, expire_in: nil, **rest)
+      assign_attributes(attrs.merge(rest))
+
+      save(expire_in: expire_in)
+    end
+
+    def update!(attrs = {}, expire_in: nil, **rest)
+      assign_attributes(attrs.merge(rest))
+
+      save!(expire_in: expire_in)
+    end
+
+    # Makes the stored document expire in a duration (like EXPIRE in Redis):
+    # `session.expire(30.minutes)`. The version and the expires attribute are
+    # refreshed; other unsaved changes stay unsaved. Raises Ndb::NotFound for
+    # a missing or expired document and Ndb::TtlNotEnabled without an
+    # `expires: true` attribute.
+    def expire(duration)
+      result = Rails.client.expire(self.class.collection_name, id, in: wire_duration(duration))
 
-      save
+      refresh_expiry(result, Time.iso8601(result["expires_at"]))
     end
 
-    def update!(attrs)
-      assign_attributes(attrs)
+    # Removes the expiry of the stored document (PERSIST in Redis). It is not
+    # called `persist!` or `persisted?`, which mean something else in
+    # ActiveModel.
+    def persist_ttl!
+      refresh_expiry(Rails.client.persist(self.class.collection_name, id), nil)
+    end
 
-      save!
+    # The seconds left (Integer), -1 when the document never expires, nil when
+    # it is missing or expired.
+    def ttl
+      Rails.client.ttl(self.class.collection_name, id)
     end
 
     def destroy
@@ -108,6 +143,23 @@ module Ndb
 
     private
 
+    def wire_duration(value)
+      value.is_a?(ActiveSupport::Duration) ? value.to_i : value
+    end
+
+    def refresh_expiry(result, expires_at)
+      @version = result["v"]
+
+      field = self.class.expires_field
+
+      return self unless field
+
+      public_send("#{field}=", expires_at)
+      clear_attribute_changes([field])
+
+      self
+    end
+
     def loaded!(version)
       @persisted = true
       @version = version
@@ -117,7 +169,7 @@ module Ndb
 
     def create_record
       run_callbacks(:create) do
-        result = self.class.ndb_insert(insert_document)
+        result = self.class.ndb_insert(insert_document, expire_in: @expire_in)
 
         self.id = result["id"] if id.nil?
         loaded!(result["v"])
@@ -130,8 +182,8 @@ module Ndb
       run_callbacks(:update) do
         set, unset = changed_fields
 
-        unless set.empty? && unset.empty?
-          result = self.class.ndb_update(id, set: set, unset: unset, if_version: version)
+        unless set.empty? && unset.empty? && @expire_in.nil?
+          result = self.class.ndb_update(id, set: set, unset: unset, if_version: version, expire_in: @expire_in)
 
           @version = result["v"]
         end

data/lib/ndb/rails/record.rb

@@ -137,10 +137,10 @@ module Ndb
         Rails.client.aggregate(collection_name, body)
       end
 
-      def ndb_insert(doc)
+      def ndb_insert(doc, expire_in: nil)
         ensure_collection!
 
-        Rails.client.insert(collection_name, [doc]).first
+        Rails.client.insert(collection_name, [doc], expire_in: expire_in).first
       end
 
       def ndb_update(id, **change)

data/lib/ndb/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Ndb
   module Rails
-    VERSION = "0.1.0"
+    VERSION = "0.1.1"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ndb-rails
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - thadeu