ndb 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d05135b99146700c912046914e228098dc99c4bd67181074f39ea399c1d2e375
-  data.tar.gz: 76be9b065c8505b1a7c59ce69bf66bce0aa179bb6e4368f73facaea10e30c848
+  metadata.gz: b60b364a32410e0d6c1356e427e4844bba9b31a65dcd0d5afb4fcb9acbafa3aa
+  data.tar.gz: e2a3603636b2ab7bcf922c9c0d759a98d871dc292bc9a2299ef3d284c6faaf26
 SHA512:
-  metadata.gz: b3e6fa3bded8d9ee8824f7c0038e2fe74c462cdd95561b20f0a1548c59b40ff825bb1cd41348c9a2b919166fba3ba2ded2c5b58f61133cd729adf2f915e7c0b9
-  data.tar.gz: 5ace970046bad037e2977795771133017dc594ef83f64ee914799d732fb4b71baca7446e2788464644d9e56e75320d0c7987f87305801730a36a1f043d4a6ceb
+  metadata.gz: e26d00115fc7530e4f766437f1019202a644ada9a4a0127f96dbd23efcf9e83d6afefda557f2ad63f892be159d8a7c38bd18112bc75744fb740f6ceeddd9edf5
+  data.tar.gz: 45dde6bb1ceb82b3a381f2047f2bf09e33d1d8182214422537ee2a6dc97a0bdb01463e7f2eadeb4371007863f71a1566653081e53fb9db49620c1c77e9a4565c

data/README.md

@@ -80,26 +80,46 @@ results = ndb.insert("calls", [
 ])
 results   # => [{"id" => "c1", "v" => 1}, {"id" => "c2", "v" => 1}]
 
-ndb.update("calls", "c1", set: { status: "done" }, unset: ["caller"])   # => {"id" => "c1", "v" => 2}
-ndb.update("calls", "c1", set: { duration: 50 }, if_version: 2)         # only if the version is still 2
+# Atomic update by filter: the filter, then the write operators.
+ndb.update("calls", { call_id: "c1" }, { "$set" => { status: "done" }, "$unset" => { caller: true } })
+# => {"matched" => 1, "modified" => 1, "doc" => {"call_id" => "c1", ..., "_v" => 2}}
 
-ndb.delete("calls", "c2")
-ndb.delete("calls", "c1", if_version: 3)
+ndb.update("calls", { call_id: "c1", _v: 2 }, { "$set" => { duration: 50 } })   # only if the version is still 2
+ndb.update("stock", { sku: "a", qty: { "$gte" => 1 } }, { "$inc" => { qty: -1 } })   # guarded decrement
+
+ndb.update("calls", { status: "failed" }, { "$set" => { status: "retry" } }, many: true)   # => {"matched" => 3, "modified" => 3}
+ndb.update("counters", { name: "hits" }, { "$inc" => { n: 1 } }, upsert: true)
+
+ndb.delete("calls", { call_id: "c2" })                  # => {"deleted" => 1}
+ndb.delete("calls", { status: "failed" }, many: true)
 ```
 
-- `if_version:` is optimistic locking. If another writer changed the document first, you get `Ndb::VersionConflict` (code `version_conflict`). Reload and try again.
+- Operators: `$set`, `$unset`, `$inc`, `$push` (with `{ "$each" => [...] }`), `$pull`, `$min`, `$max`. Field names can be dot paths. A key of the operators without `$` raises `ArgumentError` before anything is sent.
+- Nothing matched is not an error: `matched` is 0. A stale `_v` is a filter that matches nothing, so read again and retry. `modified` is 0 when the operators leave the document as it is.
+- `many: true` needs the id or an indexed field in the filter (`Ndb::UnindexedMany`). `upsert: true` creates the document from the equality fields of the filter. The answer has `doc` only for one document.
+- The contract errors are `Ndb::UnknownOperator`, `NoUpdate`, `ConflictingUpdate`, `InvalidField`, `UnindexedMany` and `EmptyFilter`, all under `Ndb::InvalidUpdate`.
 - A duplicate id raises `Ndb::UniqueViolation` (code `duplicate_id`). A broken unique field raises it too (code `unique_violation`).
-- A missing document raises `Ndb::NotFound`.
+
+## Expiry (TTL like Redis)
+
+The collection needs `expires_field`.
 
 ```ruby
-begin
-  ndb.update("calls", "c1", set: { status: "done" }, if_version: version)
-rescue Ndb::VersionConflict
-  version = ndb.find("calls", where: { call_id: "c1" }, versions: true).rows.first["_v"]
-  retry
-end
+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", { sid: "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)
+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`.
@@ -255,7 +275,7 @@ All errors inherit from `Ndb::Error`, which has `code` (the daemon code) and `st
 | `NotReady` | `not_ready` |
 | `NotFound` | `not_found` |
 | `UnknownCollection` | `unknown_collection` |
-| `VersionConflict` | `version_conflict` |
+| `InvalidUpdate` and its subclasses | `unknown_operator`, `no_update`, `conflicting_update`, `invalid_field`, `unindexed_many`, `empty_filter` |
 | `UniqueViolation` | `unique_violation`, `duplicate_id` |
 | `CatalogConflict` | `catalog_conflict` |
 | `CatalogInvalid` | `catalog_invalid` |
@@ -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,22 +41,65 @@ 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
+
+    # Atomic update by filter. The filter and the write operators go in one
+    # body; the daemon matches and writes in one step on the newest state, so
+    # concurrent updates never interleave.
+    #
+    #   client.update("stock", { sku: "a", qty: { "$gte" => 1 } }, { "$inc" => { qty: -1 } })
+    #   # => {"matched" => 1, "modified" => 1, "doc" => {...with "_v"}}
+    #
+    # Operators: $set, $unset, $inc, $push, $pull, $min, $max (dot paths work).
+    # Nothing matched is not an error: {"matched" => 0, "modified" => 0}. A
+    # version guard is a filter: { id: "x", _v: 7 }. many: true updates every
+    # match (no "doc" in the answer) and needs the id or an indexed field in
+    # the filter. upsert: true creates the document from the equality fields
+    # of the filter when nothing matches. expire_in (seconds, or "30m") sets
+    # the expires_field.
+    def update(coll, filter, ops, many: false, upsert: false, expire_in: nil)
+      query = write_query(many: many, upsert: upsert, expire_in: expire_in)
+
+      json(post(coll, "update#{query}", merge_update(filter, ops)))
     end
 
-    def update(coll, id, set: {}, unset: [], if_version: nil)
-      change = { id: id, set: set, unset: unset }
-      change[:if_version] = if_version if if_version
+    # Deletes the documents that the filter matches (one, or every match with
+    # many: true, which needs the id or an indexed field). {"deleted" => n}
+    def delete(coll, filter, many: false)
+      json(post(coll, "delete#{write_query(many: many)}", filter))
+    end
 
-      json(post(coll, "update", update: change))
+    # 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, **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]
+
+      json(post(coll, "expire", body))
     end
 
-    def delete(coll, id, if_version: nil)
-      change = { id: id }
-      change[:if_version] = if_version if if_version
+    # Removes the expiry of a document, like PERSIST in Redis.
+    def persist(coll, id)
+      json(post(coll, "persist", id: id))
+    end
 
-      json(post(coll, "delete", delete: change))
+    # 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
@@ -109,6 +153,28 @@ module Ndb
       value.to_s.strip.empty? ? nil : value
     end
 
+    def write_query(many: false, upsert: false, expire_in: nil)
+      params = {}
+
+      params["many"] = "true" if many
+      params["upsert"] = "true" if upsert
+      params["expire_in"] = expire_in.to_s if expire_in
+
+      params.empty? ? "" : "?#{URI.encode_www_form(params)}"
+    end
+
+    # The filter and the operators in one body. An operator key without "$"
+    # would be read as a filter key by the daemon, so it is refused here.
+    def merge_update(filter, ops)
+      ops.each_key do |key|
+        next if key.to_s.start_with?("$")
+
+        raise ArgumentError, "update operator #{key.to_s.inspect} must start with $ (for example \"$set\")"
+      end
+
+      filter.to_h.transform_keys(&:to_s).merge(ops.to_h.transform_keys(&:to_s))
+    end
+
     def post(coll, verb, body)
       request("POST", "#{path(coll)}/#{verb}", body)
     end

data/lib/ndb/errors.rb

@@ -25,7 +25,6 @@ module Ndb
   class Unauthorized < Error; end
   class NotFound < Error; end
   class UnknownCollection < Error; end
-  class VersionConflict < Error; end
   class UniqueViolation < Error; end
   class CatalogConflict < Error; end
   class CatalogInvalid < Error; end
@@ -33,6 +32,19 @@ module Ndb
   class InvalidQuery < Error; end
   class InvalidCursor < Error; end
 
+  # The update or delete body breaks the contract (see Client#update).
+  class InvalidUpdate < Error; end
+  class UnknownOperator < InvalidUpdate; end
+  class NoUpdate < InvalidUpdate; end
+  class ConflictingUpdate < InvalidUpdate; end
+  class InvalidField < InvalidUpdate; end
+  class UnindexedMany < InvalidUpdate; end
+  class EmptyFilter < InvalidUpdate; 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
 
@@ -46,7 +58,6 @@ module Ndb
     "not_ready" => NotReady,
     "not_found" => NotFound,
     "unknown_collection" => UnknownCollection,
-    "version_conflict" => VersionConflict,
     "unique_violation" => UniqueViolation,
     "duplicate_id" => UniqueViolation,
     "catalog_conflict" => CatalogConflict,
@@ -58,7 +69,15 @@ module Ndb
     "cursor_mismatch" => InvalidCursor,
     "cursor_expired" => InvalidCursor,
     "watch_lagged" => WatchLagged,
-    "history_truncated" => HistoryTruncated
+    "history_truncated" => HistoryTruncated,
+    "ttl_not_enabled" => TtlNotEnabled,
+    "ttl_derived" => TtlDerived,
+    "unknown_operator" => UnknownOperator,
+    "no_update" => NoUpdate,
+    "conflicting_update" => ConflictingUpdate,
+    "invalid_field" => InvalidField,
+    "unindexed_many" => UnindexedMany,
+    "empty_filter" => EmptyFilter
   }.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.2"
 end

metadata

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