ndb 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d05135b99146700c912046914e228098dc99c4bd67181074f39ea399c1d2e375
-  data.tar.gz: 76be9b065c8505b1a7c59ce69bf66bce0aa179bb6e4368f73facaea10e30c848
+  metadata.gz: b4be3ecd3f672ee851429ab1c7c80167be5a7f3d4c40e399eab1d1f301c55f4b
+  data.tar.gz: 2601743744f84d4962a395e6168432d60e67d0c557a9da48fa95b245050b4c1d
 SHA512:
-  metadata.gz: b3e6fa3bded8d9ee8824f7c0038e2fe74c462cdd95561b20f0a1548c59b40ff825bb1cd41348c9a2b919166fba3ba2ded2c5b58f61133cd729adf2f915e7c0b9
-  data.tar.gz: 5ace970046bad037e2977795771133017dc594ef83f64ee914799d732fb4b71baca7446e2788464644d9e56e75320d0c7987f87305801730a36a1f043d4a6ceb
+  metadata.gz: 4b5625d6c7158f777187868a0bb099155916eafc5774e0d275e2513a5adfd868834f5c15403a6501cf4148af1af43d330f8b12ae72d457b387d26351c678fc71
+  data.tar.gz: 0a2f5b44deddc4140f4de275a762da655bbb44e4bacb3dd91178f1ba5a5d77f61abc7aebb7b09886ae6eb9d1c0fb3746e16d888b9c3917692bacfc598154626f

data/README.md

@@ -100,6 +100,26 @@ rescue Ndb::VersionConflict
 end
 ```
 
+## Expiry (TTL like Redis)
+
+The collection needs `expires_field`.
+
+```ruby
+ndb.ensure_collection("sessions", { id: "sid", expires_field: "exp" })
+
+ndb.insert("sessions", [{ sid: "s1" }], expire_in: 3600)  # seconds, or "1h" / "30m" / "1d"
+ndb.update("sessions", "s1", set: { user: "u" }, expire_in: "30m")
+
+ndb.expire("sessions", "s1", in: 1800)                     # => {"id", "v", "expires_at"}
+ndb.expire("sessions", "s1", at: Time.now + 7200, if_version: 2)
+ndb.ttl("sessions", "s1")                                  # => 7199, -1 (never expires), or nil (missing or expired)
+ndb.persist("sessions", "s1")                              # => {"id", "v"}
+```
+
+- `expire_in` wins over a value of `expires_field` in the same call. `ttl` rounds up to whole seconds.
+- `expire` and `persist` raise `Ndb::NotFound` for a missing or expired document. `Ndb::TtlNotEnabled` means no `expires_field`; `Ndb::TtlDerived` means the expiry comes from `ttl` + `time`.
+- 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).
+
 ## Find
 
 `find` returns a `Ndb::Page` with `rows` (an array of Hash), `next_cursor`, `plan`, `examined` and `total`.
@@ -264,6 +284,7 @@ All errors inherit from `Ndb::Error`, which has `code` (the daemon code) and `st
 | `InvalidCursor` | `cursor_invalid`, `cursor_mismatch`, `cursor_expired` |
 | `WatchLagged` | `watch_lagged` |
 | `HistoryTruncated` | `history_truncated` |
+| `TtlNotEnabled`, `TtlDerived` | `ttl_not_enabled`, `ttl_derived` |
 | `ConnectionError` | cannot reach the daemon. Subclasses: `ConnectError` (nothing was sent), `TimeoutError` |
 
 Any other code is a plain `Ndb::Error`. A response that is not a daemon error has the code `http_status`.

data/lib/ndb/client.rb

@@ -2,6 +2,7 @@
 
 require "json"
 require "uri"
+require "time"
 
 module Ndb
   Page = Struct.new(:rows, :next_cursor, :plan, :examined, :total)
@@ -40,13 +41,19 @@ module Ndb
       page(post(coll, "aggregate", Conditions.regexps(body)))
     end
 
-    def insert(coll, docs)
-      json(post(coll, "insert", insert: docs)).fetch("results")
+    # expire_in (seconds, or "30m" / "1h" / "1d") sets the expires_field of
+    # every document to now + expire_in, in the same transaction.
+    def insert(coll, docs, expire_in: nil)
+      body = { insert: docs }
+      body[:expire_in] = expire_in if expire_in
+
+      json(post(coll, "insert", body)).fetch("results")
     end
 
-    def update(coll, id, set: {}, unset: [], if_version: nil)
+    def update(coll, id, set: {}, unset: [], if_version: nil, expire_in: nil)
       change = { id: id, set: set, unset: unset }
       change[:if_version] = if_version if if_version
+      change[:expire_in] = expire_in if expire_in
 
       json(post(coll, "update", update: change))
     end
@@ -58,6 +65,33 @@ module Ndb
       json(post(coll, "delete", delete: change))
     end
 
+    # Makes a document expire, like EXPIRE in Redis: in: seconds or "30m", or
+    # at: a Time or an RFC 3339 String. Returns {"id", "v", "expires_at"}.
+    # Raises NotFound for a missing or expired document, TtlNotEnabled when
+    # the collection has no expires_field, TtlDerived when the expiry comes
+    # from ttl + time.
+    def expire(coll, id, if_version: nil, **time)
+      body = { id: id }
+      body[:in] = time[:in] if time[:in]
+      body[:at] = time[:at].respond_to?(:utc) ? time[:at].utc.iso8601(9) : time[:at] if time[:at]
+      body[:if_version] = if_version if if_version
+
+      json(post(coll, "expire", body))
+    end
+
+    # Removes the expiry of a document, like PERSIST in Redis.
+    def persist(coll, id)
+      json(post(coll, "persist", id: id))
+    end
+
+    # The seconds left of a document (an Integer, rounded up), -1 when it
+    # never expires, nil when it is missing or expired.
+    def ttl(coll, id)
+      json(request("GET", "#{path(coll)}/ttl/#{URI.encode_www_form_component(id).gsub('+', '%20')}", nil)).fetch("ttl")
+    rescue NotFound
+      nil
+    end
+
     # Streams the changes of a collection for a named consumer: first the ones
     # after its last ack, then the new ones. Yields one Hash per event (pos,
     # op, id, v, doc). where is the same Hash/Range conditions as find, and

data/lib/ndb/errors.rb

@@ -33,6 +33,10 @@ module Ndb
   class InvalidQuery < Error; end
   class InvalidCursor < Error; end
 
+  # The collection has no expires_field, or its expiry comes from ttl + time.
+  class TtlNotEnabled < Error; end
+  class TtlDerived < Error; end
+
   # The consumer was too slow: call watch again, it resumes from the last ack.
   class WatchLagged < Error; end
 
@@ -58,7 +62,9 @@ module Ndb
     "cursor_mismatch" => InvalidCursor,
     "cursor_expired" => InvalidCursor,
     "watch_lagged" => WatchLagged,
-    "history_truncated" => HistoryTruncated
+    "history_truncated" => HistoryTruncated,
+    "ttl_not_enabled" => TtlNotEnabled,
+    "ttl_derived" => TtlDerived
   }.freeze
 
   def self.error_for(code, message, status)

data/lib/ndb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ndb
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

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