ndb 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b4be3ecd3f672ee851429ab1c7c80167be5a7f3d4c40e399eab1d1f301c55f4b
-  data.tar.gz: 2601743744f84d4962a395e6168432d60e67d0c557a9da48fa95b245050b4c1d
+  metadata.gz: b60b364a32410e0d6c1356e427e4844bba9b31a65dcd0d5afb4fcb9acbafa3aa
+  data.tar.gz: e2a3603636b2ab7bcf922c9c0d759a98d871dc292bc9a2299ef3d284c6faaf26
 SHA512:
-  metadata.gz: 4b5625d6c7158f777187868a0bb099155916eafc5774e0d275e2513a5adfd868834f5c15403a6501cf4148af1af43d330f8b12ae72d457b387d26351c678fc71
-  data.tar.gz: 0a2f5b44deddc4140f4de275a762da655bbb44e4bacb3dd91178f1ba5a5d77f61abc7aebb7b09886ae6eb9d1c0fb3746e16d888b9c3917692bacfc598154626f
+  metadata.gz: e26d00115fc7530e4f766437f1019202a644ada9a4a0127f96dbd23efcf9e83d6afefda557f2ad63f892be159d8a7c38bd18112bc75744fb740f6ceeddd9edf5
+  data.tar.gz: 45dde6bb1ceb82b3a381f2047f2bf09e33d1d8182214422537ee2a6dc97a0bdb01463e7f2eadeb4371007863f71a1566653081e53fb9db49620c1c77e9a4565c

data/README.md

@@ -80,26 +80,26 @@ 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
 
-- `if_version:` is optimistic locking. If another writer changed the document first, you get `Ndb::VersionConflict` (code `version_conflict`). Reload and try again.
-- 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`.
+ndb.update("calls", { status: "failed" }, { "$set" => { status: "retry" } }, many: true)   # => {"matched" => 3, "modified" => 3}
+ndb.update("counters", { name: "hits" }, { "$inc" => { n: 1 } }, upsert: true)
 
-```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.delete("calls", { call_id: "c2" })                  # => {"deleted" => 1}
+ndb.delete("calls", { status: "failed" }, many: true)
 ```
 
+- 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`).
+
 ## Expiry (TTL like Redis)
 
 The collection needs `expires_field`.
@@ -108,10 +108,10 @@ The collection needs `expires_field`.
 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.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, if_version: 2)
+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"}
 ```
@@ -275,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` |

data/lib/ndb/client.rb

@@ -50,19 +50,30 @@ module Ndb
       json(post(coll, "insert", body)).fetch("results")
     end
 
-    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))
+    # 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 delete(coll, id, if_version: nil)
-      change = { id: id }
-      change[:if_version] = if_version if if_version
-
-      json(post(coll, "delete", delete: change))
+    # 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
 
     # Makes a document expire, like EXPIRE in Redis: in: seconds or "30m", or
@@ -70,11 +81,10 @@ module Ndb
     # 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)
+    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]
-      body[:if_version] = if_version if if_version
 
       json(post(coll, "expire", body))
     end
@@ -143,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,15 @@ 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
@@ -50,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,
@@ -64,7 +71,13 @@ module Ndb
     "watch_lagged" => WatchLagged,
     "history_truncated" => HistoryTruncated,
     "ttl_not_enabled" => TtlNotEnabled,
-    "ttl_derived" => TtlDerived
+    "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.1"
+  VERSION = "0.1.2"
 end

metadata

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