bynn-decisionnode 0.4.1

data/lib/decisionnode/keys.rb

@@ -0,0 +1,383 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "uri"
+
+class DecisionNode
+  # The query rules the API checks as it reads `GET /v1/usage` and
+  # `GET /v1/keys`, each raised as its 400 `api_usage_error` with the API's
+  # message, and the query built from what is given.
+  module KeyFilters
+    GRANULARITIES = %w[none hour day month].freeze
+    GROUPS = %w[model channel].freeze
+    SCOPES = %w[full decide keys].freeze
+    STATUSES = %w[active expired revoked all].freeze
+    USAGE_LIMIT_MAX = 1_000
+    KEYS_LIMIT_MAX = 200
+    MAX_KEY_IDS = 100
+    KEY_ID_RULE = /\Akey_[0-9a-f]{32}\z/
+    LABEL_NAME_RULE = /\A[a-z0-9_.-]{1,32}\z/
+    LABEL_VALUE_CHARS = 64
+    DEVICE_ID_CHARS = 128
+    IDEMPOTENCY_KEY_CHARS = 255
+    KEY_NAME_CHARS = 48
+    KEY_MAX_LABELS = 16
+    SPEND_CAP_MAX_USD = 1_000
+    MAX_REVOKE_DEVICES = 1_000
+    ECHO_CHARS = 64
+    DEVICE_ID_RULE = "device_id is 1 to 128 printable ASCII characters, not starting with a space."
+
+    module_function
+
+    # A usage read's period and breakdowns, each only when given.
+    def period(start, finish, granularity, group_by)
+      Checks.usage("granularity is none, hour, day or month.") unless granularity.nil? || GRANULARITIES.include?(granularity.to_s)
+      Checks.usage("group_by is model or channel.") unless group_by.nil? || GROUPS.include?(group_by.to_s)
+
+      [["start", start], ["end", finish], ["granularity", granularity], ["group_by", group_by]].reject { |_, v| v.nil? }
+    end
+
+    # Each label as `label=name:value`, sorted by name, so a Hash sends the
+    # same query every time.
+    def labels(labels)
+      return [] if labels.nil?
+      raise ArgumentError, "labels must be a Hash of label names to values" unless labels.is_a?(Hash)
+
+      labels.map { |name, value| [name.is_a?(Symbol) ? name.to_s : name, value] }.sort_by { |name, _| name.to_s }.map do |name, value|
+        unless name.is_a?(String) && name.match?(LABEL_NAME_RULE) && value.is_a?(String) &&
+               value.length.between?(1, LABEL_VALUE_CHARS) && !value.match?(/\p{Cc}/)
+          Checks.usage("A label filter is name:value, as labels are written.")
+        end
+        ["label", "#{name}:#{value}"]
+      end
+    end
+
+    def device_ok?(device_id)
+      device_id.is_a?(String) && device_id.length.between?(1, DEVICE_ID_CHARS) &&
+        device_id.each_char.all? { |c| c.ord.between?(0x20, 0x7E) } && !device_id.start_with?(" ")
+    end
+
+    def device(device_id)
+      return [] if device_id.nil?
+
+      Checks.usage(DEVICE_ID_RULE) unless device_ok?(device_id)
+      [["device_id", device_id]]
+    end
+
+    def status(status)
+      return [] if status.nil?
+
+      Checks.usage("status is active, expired, revoked or all.") unless STATUSES.include?(status.to_s)
+      [["status", status]]
+    end
+
+    def page(limit, most, cursor)
+      out = []
+      unless limit.nil?
+        Checks.usage("limit is a whole number from 1 to #{most}.") unless limit.is_a?(Integer) && limit.between?(1, most)
+        out << ["limit", limit]
+      end
+      out << ["cursor", cursor] unless cursor.nil?
+      out
+    end
+
+    # `GET /v1/usage`'s query, checked in the API's order; the period's own
+    # rules and the cursor are the server's.
+    def usage_list(start, finish, granularity, group_by, labels, device_id, key_ids, scope, status, include_empty, limit, cursor)
+      query = period(start, finish, granularity, group_by) + labels(labels) + device(device_id)
+      Array(key_ids).each_with_index do |key_id, i|
+        Checks.usage("key_id is a key's id, key_ and 32 hex digits.") unless key_id.is_a?(String) && key_id.match?(KEY_ID_RULE)
+        Checks.usage("At most 100 key_id filters.") if i == MAX_KEY_IDS
+        query << ["key_id", key_id]
+      end
+      unless scope.nil?
+        Checks.usage("scope is full, decide or keys.") unless SCOPES.include?(scope.to_s)
+        query << ["scope", scope]
+      end
+      query.concat(status(status))
+      unless include_empty.nil?
+        Checks.usage("include_empty is true or false.") unless [true, false].include?(include_empty)
+        query << ["include_empty", include_empty.to_s]
+      end
+      query + page(limit, USAGE_LIMIT_MAX, cursor)
+    end
+
+    # `GET /v1/keys`'s query, checked as the API reads it; the cursor is the
+    # server's.
+    def keys_list(labels, device_id, status, limit, cursor)
+      labels(labels) + device(device_id) + status(status) + page(limit, KEYS_LIMIT_MAX, cursor)
+    end
+
+    # A caller's own Idempotency-Key: 1 to 255 printable ASCII characters.
+    def idempotency_key!(key)
+      return if key.is_a?(String) && key.length.between?(1, IDEMPOTENCY_KEY_CHARS) && key.each_char.all? { |c| c.ord.between?(0x20, 0x7E) }
+
+      Checks.usage("Idempotency-Key must be sent once, as 1 to 255 printable ASCII characters.")
+    end
+
+    # How a key's 422 entry echoes an input, as the API does: a String cut to
+    # its first 64 characters, with "..." only when it was longer; a Hash or
+    # an Array never (nil); anything else as it is.
+    def echoed(value)
+      case value
+      when String then value.length > ECHO_CHARS ? "#{value[0, ECHO_CHARS]}..." : value
+      when Hash, Array then nil
+      else value
+      end
+    end
+
+    def key_entry(loc, msg, value)
+      Checks.entry("value_error", ["body"] + loc, msg, echoed(value))
+    end
+
+    # A key's name, trimmed, 1 to 48 characters; its characters are the
+    # server's to judge.
+    def name_entries(name)
+      trimmed = name.is_a?(String) ? name.gsub(/\A[[:space:]]+|[[:space:]]+\z/, "") : ""
+      return [key_entry(["name"], "Give the key a name.", name)] if trimmed.empty?
+      return [key_entry(["name"], "Key names are at most 48 characters.", name)] if trimmed.length > KEY_NAME_CHARS
+
+      []
+    end
+
+    def labels_entries(labels)
+      return [key_entry(["labels"], "labels is an object of names to values.", labels)] unless labels.is_a?(Hash)
+      return [key_entry(["labels"], "A key has at most 16 labels.", labels)] if labels.size > KEY_MAX_LABELS
+
+      labels.each do |name, value|
+        name = name.to_s if name.is_a?(Symbol)
+        unless name.is_a?(String) && name.match?(LABEL_NAME_RULE)
+          return [key_entry(["labels"], "A label's name is 1 to 32 of a-z, 0-9, _ . and -.", labels)]
+        end
+        unless value.is_a?(String) && value.length.between?(1, LABEL_VALUE_CHARS) && !value.match?(/\p{Cc}/)
+          return [key_entry(["labels", name], "A label's value is 1 to 64 characters of text.", labels)]
+        end
+      end
+      []
+    end
+
+    # `daily_spend_cap`: `{"usd"}` from 0.01 to 1,000 in whole cents.
+    def cap_entries(cap)
+      usd = cap.is_a?(Hash) ? (cap.key?("usd") ? cap["usd"] : cap[:usd]) : nil
+      ok = usd.is_a?(Numeric) && usd.to_f.finite?
+      cents = ok ? (usd * 100).round : 0
+      return [] if ok && ((usd * 100) - cents).abs < 1e-6 && cents >= 1 && usd <= SPEND_CAP_MAX_USD
+
+      [key_entry(["daily_spend_cap"], "daily_spend_cap.usd is from 0.01 to 1000, in cents, or null.", cap)]
+    end
+
+    # A key's create (`clears` false) or update body, the fields given only,
+    # checked in the body's order: the first fault is the API's 422 entry. A
+    # limit's ceiling, the expiry's window and a name's characters are the
+    # server's.
+    def key_fields!(body, clears:)
+      entries = body.key?("name") ? name_entries(body["name"]) : []
+      if entries.empty?
+        entries << key_entry(["device_id"], DEVICE_ID_RULE, body["device_id"]) if body.key?("device_id") && !device_ok?(body["device_id"])
+        entries.concat(labels_entries(body["labels"])) if body.key?("labels") && !(clears && body["labels"].nil?)
+        if body.key?("limits") && !(clears && body["limits"].nil?) && !body["limits"].is_a?(Hash)
+          entries << key_entry(["limits"], "limits is an object, or null.", body["limits"])
+        end
+        entries.concat(cap_entries(body["daily_spend_cap"])) if body.key?("daily_spend_cap") && !(clears && body["daily_spend_cap"].nil?)
+      end
+      raise Checks.invalid(entries.first(1)) unless entries.empty?
+    end
+
+    # A bulk revoke's labels (at least one) and `device_ids` (at most 1,000).
+    def revoke_by_labels!(labels, device_ids)
+      entries = labels_entries(labels)
+      if entries.empty? && labels.empty?
+        entries = [key_entry(["labels"], "A bulk revoke names at least one label: every key it revokes has them all.", labels)]
+      end
+      if entries.empty? && !device_ids.nil?
+        if !device_ids.is_a?(Array) || device_ids.size > MAX_REVOKE_DEVICES
+          entries = [key_entry(["device_ids"], "device_ids is a list of at most 1,000 device ids.", device_ids)]
+        elsif (bad = device_ids.find { |d| !device_ok?(d) })
+          entries = [key_entry(["device_id"], DEVICE_ID_RULE, bad)]
+        end
+      end
+      raise Checks.invalid(entries) unless entries.empty?
+    end
+
+    def path(path, query)
+      return path if query.empty?
+
+      "#{path}?#{query.map { |k, v| "#{k}=#{URI.encode_uri_component(v.to_s)}" }.join('&')}"
+    end
+
+    def segment(id)
+      raise ArgumentError, "a key id is required" if id.nil? || id.to_s.empty?
+
+      URI.encode_uri_component(id.to_s)
+    end
+  end
+  private_constant :KeyFilters
+
+  # Per-key usage: what each key used and cost over a period. A Full access
+  # key reads every key of its workspace, a Manage device keys key its
+  # Decisions-only keys. Every call returns the API's object as sent, a Hash
+  # with the API's field names, and retries as any read.
+  class KeyUsage
+    def initialize(client)
+      @client = client
+    end
+
+    def inspect
+      "#<#{self.class.name}>"
+    end
+
+    # One key's usage (`GET /v1/keys/{key_id}/usage`). `start:` and `end:`
+    # are RFC 3339 times, rounded to the hour by the API; left out, the UTC
+    # month so far. `granularity:` ("none", "hour", "day" or "month") adds
+    # `buckets`, and `group_by:` ("model" or "channel") `by_model` or
+    # `by_channel`.
+    def key(key_id, start: nil, end: nil, granularity: nil, group_by: nil)
+      query = KeyFilters.period(start, binding.local_variable_get(:end), granularity, group_by)
+      get(KeyFilters.path("/v1/keys/#{KeyFilters.segment(key_id)}/usage", query))
+    end
+
+    # One page of every key's usage over a period (`GET /v1/usage`):
+    # `{period, as_of, items, next_cursor}`. `labels:` keeps the keys that
+    # have them all, `key_ids:` (at most 100) the keys named, `scope:`
+    # ("full", "decide" or "keys") and `status:` ("active", "expired",
+    # "revoked" or "all") the keys of that kind or state; `include_empty:`
+    # lists keys with no usage too. Pass `next_cursor` as `cursor:` for the
+    # next page, until it is nil.
+    def list(start:, end:, granularity: nil, group_by: nil, labels: nil, device_id: nil, key_ids: nil, scope: nil,
+             status: nil, include_empty: nil, limit: nil, cursor: nil)
+      query = KeyFilters.usage_list(start, binding.local_variable_get(:end), granularity, group_by, labels, device_id,
+                                    key_ids, scope, status, include_empty, limit, cursor)
+      get(KeyFilters.path("/v1/usage", query))
+    end
+
+    # Every key's usage over the period: #list's pages, `next_cursor`
+    # followed until it is nil, their `items` in order. A page can hold fewer
+    # keys than `limit`, so only the cursor says when the list is done.
+    def all(start:, end:, granularity: nil, group_by: nil, labels: nil, device_id: nil, key_ids: nil, scope: nil,
+            status: nil, include_empty: nil, limit: nil)
+      finish = binding.local_variable_get(:end)
+      items = []
+      cursor = nil
+      loop do
+        page = list(start: start, end: finish, granularity: granularity, group_by: group_by, labels: labels,
+                    device_id: device_id, key_ids: key_ids, scope: scope, status: status,
+                    include_empty: include_empty, limit: limit, cursor: cursor)
+        items.concat(Array(page.is_a?(Hash) ? page["items"] : nil))
+        cursor = page.is_a?(Hash) ? page["next_cursor"] : nil
+        return items if cursor.nil? || cursor.to_s.empty?
+      end
+    end
+
+    private
+
+    def get(path)
+      @client.__send__(:request, "GET", path, nil).first
+    end
+  end
+
+  # Decisions-only keys for devices, made, listed, changed and revoked with a
+  # Manage device keys key. Every call returns the API's object as sent, a
+  # Hash with the API's field names.
+  #
+  # #create sends an Idempotency-Key: the one given (one per enrollment, so a
+  # retried enrollment gets the same key and secret back), else a new UUID
+  # per call, the same on every attempt of it. It retries as every call does,
+  # and also on a 409 `idempotency_in_progress` after its Retry-After; a 409
+  # `idempotency_key_reused` is raised. The other calls retry as any call.
+  class Keys
+    # The value of an argument not given, so a field given as nil is sent as
+    # null, which clears it.
+    UNSET = Object.new.freeze
+    private_constant :UNSET
+
+    def initialize(client)
+      @client = client
+    end
+
+    def inspect
+      "#<#{self.class.name}>"
+    end
+
+    # Makes a Decisions-only key (`POST /v1/keys`): `{key, secret}`. The
+    # secret is shown in this answer only (and again to a retry with the same
+    # `idempotency_key:` within 24 hours); hand it to the device and never
+    # log it. Each field is sent only when given. The name, `device_id`,
+    # labels, the shape of `limits` and the spend cap are checked first, each
+    # fault the API's 422 ValidationError, then the `idempotency_key`.
+    def create(name, device_id: nil, labels: nil, limits: nil, daily_spend_cap: nil, expires_at: nil,
+               may_search_collections: nil, idempotency_key: nil)
+      body = { "name" => name }
+      { "device_id" => device_id, "labels" => labels, "limits" => limits, "daily_spend_cap" => daily_spend_cap,
+        "expires_at" => expires_at, "may_search_collections" => may_search_collections }.each do |field, value|
+        body[field] = value unless value.nil?
+      end
+      KeyFilters.key_fields!(body, clears: false)
+      KeyFilters.idempotency_key!(idempotency_key) unless idempotency_key.nil?
+      parsed, = @client.__send__(:request, "POST", "/v1/keys", body, policy: :idempotent,
+                                                                 extra_headers: { "Idempotency-Key" => idempotency_key || SecureRandom.uuid })
+      parsed
+    end
+
+    # One page of the workspace's Decisions-only keys, newest first:
+    # `{items, next_cursor}`. `labels:` keeps the keys that have them all,
+    # `status:` is "active" (the API's default), "expired", "revoked" or
+    # "all", and `limit:` 1 to 200. Pass `next_cursor` as `cursor:` for the
+    # next page, until it is nil.
+    def list(labels: nil, device_id: nil, status: nil, limit: nil, cursor: nil)
+      call("GET", KeyFilters.path("/v1/keys", KeyFilters.keys_list(labels, device_id, status, limit, cursor)))
+    end
+
+    # Every key #list finds: its pages, `next_cursor` followed until it is
+    # nil, their `items` in order.
+    def all(labels: nil, device_id: nil, status: nil, limit: nil)
+      items = []
+      cursor = nil
+      loop do
+        page = list(labels: labels, device_id: device_id, status: status, limit: limit, cursor: cursor)
+        items.concat(Array(page.is_a?(Hash) ? page["items"] : nil))
+        cursor = page.is_a?(Hash) ? page["next_cursor"] : nil
+        return items if cursor.nil? || cursor.to_s.empty?
+      end
+    end
+
+    # Changes a key (`PATCH /v1/keys/{id}`), sending only the fields given:
+    # `labels:` replaces the key's whole set, and nil clears `labels`,
+    # `limits`, `daily_spend_cap` or `expires_at`. A key's `device_id` never
+    # changes. Returns the key.
+    def update(key_id, name: UNSET, labels: UNSET, limits: UNSET, daily_spend_cap: UNSET, expires_at: UNSET,
+               may_search_collections: UNSET)
+      body = { "name" => name, "labels" => labels, "limits" => limits, "daily_spend_cap" => daily_spend_cap,
+               "expires_at" => expires_at, "may_search_collections" => may_search_collections }
+             .reject { |_, value| value.equal?(UNSET) }
+      KeyFilters.key_fields!(body, clears: true)
+      Checks.usage("Nothing to change.") if body.empty?
+
+      call("PATCH", "/v1/keys/#{KeyFilters.segment(key_id)}", body)
+    end
+
+    # Revokes a key at once (`DELETE /v1/keys/{id}`): `{id, revoked}`. The
+    # next call with it gets a 401; a revocation cannot be undone.
+    def revoke(key_id)
+      call("DELETE", "/v1/keys/#{KeyFilters.segment(key_id)}")
+    end
+
+    # Revokes every active key that has all of `labels` (and, with
+    # `device_ids:`, is one of those devices), at most 10,000 a call
+    # (`POST /v1/keys/revoke`): `{revoked, more}`. Call it again while `more`
+    # is true. With `dry_run: true` it revokes nothing and answers
+    # `{would_revoke, more}`.
+    def revoke_by_labels(labels, device_ids: nil, dry_run: nil)
+      KeyFilters.revoke_by_labels!(labels, device_ids)
+      body = { "labels" => labels }
+      body["device_ids"] = device_ids unless device_ids.nil?
+      body["dry_run"] = dry_run unless dry_run.nil?
+      call("POST", "/v1/keys/revoke", body)
+    end
+
+    private
+
+    def call(method, path, body = nil)
+      @client.__send__(:request, method, path, body).first
+    end
+  end
+end

data/lib/decisionnode/questions.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+class DecisionNode
+  # Question builders. Each returns the question's wire form as a plain Hash,
+  # so a builder and a Hash copied from the API documentation are interchangeable.
+  #
+  #   DecisionNode.truth("Escalate to a human now?")
+  #
+  # or, to call them without the prefix:
+  #
+  #   include DecisionNode::Questions
+  #   truth("Escalate to a human now?")
+  #
+  # Instructions, descriptions and levels take a string or any JSON value.
+  module Questions
+    module_function
+
+    # A yes-or-no question answered as a probability.
+    # The criteria are left out when neither side is given.
+    def truth(instructions = nil, if_true: nil, if_false: nil)
+      question = { "type" => "truth" }
+      question["instructions"] = instructions unless instructions.nil?
+      criteria = {}
+      criteria["true"] = if_true unless if_true.nil?
+      criteria["false"] = if_false unless if_false.nil?
+      question["criteria"] = criteria unless criteria.empty?
+      question
+    end
+
+    # One option of a set. `options` is a Hash of name to description, or an
+    # Array of names (each description nil). Names are sent exactly as given.
+    def choice(instructions = nil, options = nil)
+      criteria =
+        case options
+        when nil then {}
+        when Array then options.each_with_object({}) { |name, h| h[name.to_s] = nil }
+        when Hash then options.each_with_object({}) { |(name, desc), h| h[name.to_s] = desc }
+        else raise ArgumentError, "options must be a Hash of name to description or an Array of names"
+        end
+      question = { "type" => "choice" }
+      question["instructions"] = instructions unless instructions.nil?
+      question["criteria"] = criteria
+      question
+    end
+
+    # A place on an ordered scale. `levels` is listed from low to high.
+    def score(instructions = nil, levels = nil)
+      question = { "type" => "score" }
+      question["instructions"] = instructions unless instructions.nil?
+      question["criteria"] = levels.nil? ? [] : levels.to_a
+      question
+    end
+
+    # A value on a grid of numbers from `min` to `max` in steps of `step`.
+    # An argument left out is left out of the wire form, so the server's
+    # defaults apply: 0, 255 and 1.
+    #
+    #   number("How many cars are visible?", min: 0, max: 50)
+    #   number("Rating?", min: 0, max: 5, step: 0.5)
+    def number(instructions = nil, min: nil, max: nil, step: nil)
+      question = { "type" => "number" }
+      question["instructions"] = instructions unless instructions.nil?
+      question["min"] = min unless min.nil?
+      question["max"] = max unless max.nil?
+      question["step"] = step unless step.nil?
+      question
+    end
+
+    # One spot in an image, answered with its `x` and `y`. `image` is the id
+    # of the image to look in (a string), needed when the request has two or
+    # more; a reference by number ("Picture 2") goes in the instructions.
+    # `units` is "pixels" (the API's default) or "normalized". `max` (an
+    # Integer from 2 to 16) asks for up to that many spots, one per thing the
+    # instructions describe, answered as a PointsAnswer. Each is left out of
+    # the wire form when not given.
+    #
+    #   point("Point to the yellow package closest to the robot arm.")
+    #   point("Each person standing on the platform.", max: 6)
+    def point(instructions = nil, image: nil, units: nil, max: nil)
+      place("point", instructions, image, units, max)
+    end
+
+    # A rectangle in an image, answered with its top-left (`x1`, `y1`) and
+    # bottom-right (`x2`, `y2`) corners. `image`, `units` and `max` as for
+    # #point; with `max` the answer is a BoxesAnswer.
+    #
+    #   box("Draw a box around the damaged package.", image: "belt")
+    #   box("Every car in the lot.", image: "lot", max: 8)
+    def box(instructions = nil, image: nil, units: nil, max: nil)
+      place("box", instructions, image, units, max)
+    end
+
+    def place(type, instructions, image, units, most)
+      question = { "type" => type }
+      question["instructions"] = instructions unless instructions.nil?
+      question["image"] = image unless image.nil?
+      question["units"] = units unless units.nil?
+      question["max"] = most unless most.nil?
+      question
+    end
+    private_class_method :place
+  end
+
+  class << self
+    # See Questions.truth.
+    def truth(instructions = nil, if_true: nil, if_false: nil)
+      Questions.truth(instructions, if_true: if_true, if_false: if_false)
+    end
+
+    # See Questions.choice.
+    def choice(instructions = nil, options = nil)
+      Questions.choice(instructions, options)
+    end
+
+    # See Questions.score.
+    def score(instructions = nil, levels = nil)
+      Questions.score(instructions, levels)
+    end
+
+    # See Questions.number.
+    def number(instructions = nil, min: nil, max: nil, step: nil)
+      Questions.number(instructions, min: min, max: max, step: step)
+    end
+
+    # See Questions.point.
+    def point(instructions = nil, image: nil, units: nil, max: nil)
+      Questions.point(instructions, image: image, units: units, max: max)
+    end
+
+    # See Questions.box.
+    def box(instructions = nil, image: nil, units: nil, max: nil)
+      Questions.box(instructions, image: image, units: units, max: max)
+    end
+  end
+end