calmlens 0.18.3 → 0.20.0

data/lib/calmlens/testing/test_inputs.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require_relative 'classification'
+require_relative 'test_input_scenario'
+require_relative 'test_image_grid'
+
+module CalmLens
+  # Signed test inputs: text codes, test images and media phrases that a project's moderation
+  # recognises as a declared scenario when they are signed with its secret test input key (shown in
+  # the portal's project settings), so CalmLens returns that scenario instead of classifying them.
+  # The formats match the JavaScript SDK's `calmlens/test-inputs` byte for byte.
+  #
+  # A scenario is a Hash with the API's keys, as Strings or Symbols (snake_case keys are converted
+  # to camelCase like other options):
+  # `{ 'regionalActions' => [{ 'region' => 'DE', 'action' => 'block' }], 'unassessedCategories' => ['profanity'],
+  # 'instances' => [{ 'category' => 'harassment', 'score' => 0.9, 'action' => 'block', 'qualifiers' => ['harassment-abuse'] }] }`.
+  # `instances` (at most 128) and each instance's `qualifiers` (unique qualifiers of its category, at
+  # most 64; input-type qualifiers such as `sexual-text` are automatic) are required; `score` (0 to
+  # 1) and `action` (`allow`, `limit`, `age-restrict` or `block`, on every instance or none) are
+  # optional. `unassessedCategories` lists categories reported as not assessed, none with instances;
+  # `regionalActions` gives up to one `limit`, `age-restrict` or `block` action for each of
+  # {REGIONS}. Values are Strings and Numerics. An absent list is left out of the signed scenario;
+  # an empty one is sent as `[]`. Anything else raises `sdk/invalid-argument`.
+  #
+  # @example
+  #   code = CalmLens::TestInputs.generate_text_code('harassment.insult', test_input_key)
+  #   png = CalmLens::TestInputs.paint_image('violence', test_input_key).png
+  #   phrase = CalmLens::TestInputs.generate_media_code('violence', test_input_key)
+  module TestInputs
+    # A painted test image: `width` by `height` pixels of 8-bit RGBA, row by row, in the binary
+    # String `rgba`, and the same image as binary PNG bytes in `png`.
+    Image = Struct.new(:width, :height, :rgba, :png, keyword_init: true)
+
+    # The regions a regional action can name.
+    REGIONS = %w[DE AT FR GB EU AU BR].freeze
+    # The signals {generate_text_code}, {paint_image} and {for_signal} accept: the categories and
+    # five named shortcuts.
+    SIGNALS = (MockClassification::CATEGORIES +
+               %w[sexual.involving-minors harassment.insult sexual.adult hate.regional-symbol violence.graphic]).freeze
+    # The signals {generate_media_code} accepts.
+    MEDIA_SIGNALS = (MockClassification::CATEGORIES + %w[violence.graphic]).freeze
+
+    one = ->(category, *qualifiers) { { 'instances' => [{ 'category' => category, 'qualifiers' => qualifiers }] } }
+    deep_freeze = lambda do |value|
+      value.each_value { |item| deep_freeze.call(item) } if value.is_a?(Hash)
+      value.each { |item| deep_freeze.call(item) } if value.is_a?(Array)
+      value.freeze
+    end
+    # Ready-made scenarios (deeply frozen): a clean input, a limited one, adult images and text,
+    # regional delivery, content restricted in Germany, and mixed instances in one category.
+    PRESETS = deep_freeze.call(
+      clean: { 'instances' => [] },
+      limited: one.call('harassment', 'harassment-abuse'),
+      adult_image: one.call('sexual', 'sexual-pornographic-media'),
+      adult_text: one.call('sexual', 'sexual-explicit-language'),
+      regional_delivery: { 'instances' => [], 'regionalActions' => [{ 'region' => 'DE', 'action' => 'block' },
+                                                                    { 'region' => 'GB', 'action' => 'age-restrict' },
+                                                                    { 'region' => 'FR', 'action' => 'limit' }] },
+      germany: one.call('hate', 'hate-symbol', 'hate-nazi-symbols-public-display'),
+      mixed: { 'instances' => [{ 'category' => 'harassment', 'qualifiers' => %w[harassment-abuse harassment-documentary] },
+                               { 'category' => 'harassment', 'qualifiers' => ['harassment-threat'] }] }
+    )
+
+    HEX_WORDS = %w[zero one two three four five six seven eight nine alpha bravo charlie delta echo foxtrot].freeze
+    private_constant :HEX_WORDS
+
+    module_function
+
+    # The scenario a signal (one of {SIGNALS}) stands for in a text input (`kind` `'text'`) or an
+    # image (`'image'`), as a new Hash. {generate_text_code} uses the text kind and {paint_image}
+    # the image kind.
+    # @param signal [String]
+    # @param kind [String] `'text'` or `'image'`
+    # @return [Hash{String => Object}]
+    # @raise [InvalidArgumentError] `sdk/invalid-argument` for an unknown signal or kind
+    def for_signal(signal, kind = 'text')
+      raise Internal.invalid("Test input kind must be text or image (got #{kind.inspect})") unless %w[text image].include?(kind)
+
+      preset = case signal
+               when 'harassment.insult' then PRESETS[:limited]
+               when 'sexual.adult' then PRESETS[kind == 'image' ? :adult_image : :adult_text]
+               when 'hate.regional-symbol' then PRESETS[:germany]
+               when 'sexual.involving-minors' then { 'instances' => [{ 'category' => 'sexual', 'qualifiers' => ['sexual-minors'] }] }
+               when 'violence.graphic'
+                 { 'instances' => [{ 'category' => 'violence', 'qualifiers' => %w[violence-injury violence-graphic] }] }
+               when *MockClassification::CATEGORIES then { 'instances' => [{ 'category' => signal, 'qualifiers' => [] }] }
+               else raise Internal.invalid("Unknown test signal #{signal.inspect}")
+               end
+      Marshal.load(Marshal.dump(preset))
+    end
+
+    # The signed text code for a scenario or a signal (one of {SIGNALS}): put it anywhere in a text
+    # input.
+    # @param input [Hash, String] a scenario or a signal
+    # @param test_input_key [String] the project's secret test input key from the portal
+    # @return [String]
+    # @raise [InvalidArgumentError] `sdk/invalid-argument` for an invalid key, scenario or signal
+    def generate_text_code(input, test_input_key)
+      text_code(scenario(input, 'text', test_input_key), test_input_key)
+    end
+
+    # Paints the signed test image for a scenario or a signal (one of {SIGNALS}): a grid that
+    # survives lossy formats and resizing. Upload its `png`, or encode its `rgba` in any format.
+    # @param input [Hash, String] a scenario or a signal
+    # @param test_input_key [String] the project's secret test input key from the portal
+    # @return [Image]
+    # @raise [InvalidArgumentError] `sdk/invalid-argument` for an invalid key, scenario or signal, or
+    #   a scenario too large for a test image
+    def paint_image(input, test_input_key)
+      checked = scenario(input, 'image', test_input_key)
+      signature = text_code(checked, test_input_key).split[1]
+      content = Scenario.canonical_json(checked).b
+      data = [content.bytesize].pack('n') + [signature].pack('H*') + content
+      width, rgba = Grid.paint(data, checked['instances'].map { |instance| instance['category'] })
+      Image.new(width: width, height: width, rgba: rgba, png: Png.png(width, width, rgba))
+    end
+
+    # The phrase that triggers a signal (one of {MEDIA_SIGNALS}) in audio or video: read it aloud,
+    # or show it as large, high-contrast text in a frame.
+    # @param signal [String]
+    # @param test_input_key [String] the project's secret test input key from the portal
+    # @return [String]
+    # @raise [InvalidArgumentError] `sdk/invalid-argument` for an invalid key or signal
+    def generate_media_code(signal, test_input_key)
+      raise Internal.invalid("Unsupported media test signal #{signal.inspect}") unless MEDIA_SIGNALS.include?(signal)
+
+      check_key(test_input_key)
+      words = tag(test_input_key, "calmlens-test:media:#{signal}").each_char.map { |digit| HEX_WORDS[digit.to_i(16)] }
+      ['Calm Lens test', *words, signal.tr('.-', '  '), 'end test'].join(' ')
+    end
+
+    # The checked scenario for an input or signal, in canonical form.
+    def scenario(input, kind, test_input_key)
+      check_key(test_input_key)
+      Scenario.validate(input.is_a?(String) ? for_signal(input, kind) : input)
+    end
+
+    def text_code(checked, test_input_key)
+      payload = [Scenario.canonical_json(checked)].pack('m0').tr('+/', '-_').delete('=')
+      raise Internal.invalid('Test scenario is too large') if payload.bytesize > 8000
+
+      "<!calmlens-test #{tag(test_input_key, "calmlens-test:v1:#{payload}")} #{payload}>"
+    end
+
+    def check_key(key)
+      return if key.is_a?(String) && key.match?(/\A[a-f0-9]{32}\z/)
+
+      raise Internal.invalid('The test input key must be 32 lowercase hexadecimal characters')
+    end
+
+    # The first 32 hex characters of HMAC-SHA256 with the key's ASCII bytes.
+    def tag(key, message) = OpenSSL::HMAC.hexdigest('SHA256', key, message)[0, 32]
+
+    private_class_method :scenario, :text_code, :check_key, :tag
+  end
+end

data/lib/calmlens/testing.rb

@@ -5,6 +5,7 @@ require 'securerandom'
 require 'uri'
 require_relative '../calmlens'
 require_relative 'testing/fake_api'
+require_relative 'testing/test_inputs'
 
 module CalmLens
   # An offline client for tests. Calls run the real client's validation, encoding, retries and
@@ -63,6 +64,7 @@ module CalmLens
                               retry explain wait_for_decision delete_content delete batch],
                    folders: %i[list retrieve create update delete move],
                    hash_lists: %i[list retrieve create update delete list_entries add_entry remove_entry],
+                   policies: %i[list retrieve create update apply_preset set_automatic_updates delete assign],
                    text: %i[classify], events: %i[list],
                    cdn: %i[serve] }.freeze
     private_constant :OPERATIONS
@@ -126,7 +128,7 @@ module CalmLens
       -> { lock.synchronize { last = [(Time.now.to_f * 1000).to_i, last + 1].max } }
     end
 
-    # @param project_id [String]
+    # @param project_id [String] `project-1` by default.
     # @param api_key [String] a key from {.create_api_key}; the default has no grants.
     # @param now [#call] returns the current time in epoch milliseconds. The default clock reads the
     #   system time but advances at least 1 ms per reading, so records made in a row have strictly
@@ -144,7 +146,8 @@ module CalmLens
     #   runs while the mock handles a request, so it must not call the mock.
     # @param max_retries [Integer] retries after a retryable failure; 0 by default, so a simulated
     #   failure reaches the caller.
-    # @param options [Hash] other {ServerClient#initialize} settings, except `api_key` and `transport`.
+    # @param options [Hash] other {ServerClient#initialize} settings, such as `part_size_bytes`, except
+    #   `api_key` and `transport`.
     #   Retries and decision checks wait no real time.
     def initialize(project_id: 'project-1', api_key: MockServerClient.create_api_key, base_url: 'https://api.calmlens.invalid/v1',
                    cdn_base_url: 'https://cdn.calmlens.invalid/v1', now: MockServerClient.monotonic_clock,
@@ -225,6 +228,9 @@ module CalmLens
         raise Internal.invalid('retry_after must be a whole number of seconds')
       end
       raise Internal.invalid('details must be a Hash') unless details.nil? || details.is_a?(Hash)
+      if !(failure.is_a?(String) && ErrorCodes::STATUSES.key?(failure)) && !(details.nil? && retry_after.nil?)
+        raise Internal.invalid('details and retry_after apply only to an API error code')
+      end
 
       name = operation && operation.to_s.split('.').map { |part| Internal.camelize(part) }.join('.')
       if name && !OPERATION_NAMES.include?(name)
@@ -338,6 +344,8 @@ module CalmLens
       path, query = Internal.split_url(request.url).last.split('?', 2)
       base = request.url.start_with?("#{cdn_base_url}/") ? URI(cdn_base_url).path : URI(base_url).path
       call = Thread.current[@call_key]
+      # The later parts of a content upload sent in parts count as assets.uploadPart.
+      call = { operation: 'assets.uploadPart' } if request.method == 'POST' && path.delete_prefix(base).match?(%r{\A/assets/[^/]+/part\z})
       @mock_lock.synchronize do
         record = Request.new(method: request.method, url: request.url, path: decode_path(path.delete_prefix(base)),
                              query: URI.decode_www_form(query.to_s).to_h, headers: request.headers.dup, body: body)

data/lib/calmlens/text.rb

@@ -3,6 +3,9 @@
 module CalmLens
   # Text moderation shortcuts. Reach it through {ServerClient#text}.
   class Text < Resource
+    # The prefix of this resource's operations in Internal::OPTION_KEYS.
+    OPERATIONS = 'text'
+
     # @api private
     def initialize(session, assets)
       super(session)
@@ -17,11 +20,9 @@ module CalmLens
     # @return [Hash] the asset; show it to everyone only when `classification.moderation.status` is
     #   `allowed` or `limited` (reduce the reach of `limited` content).
     def classify(options)
-      api, request = call(options) { |*split| split }
+      api, request = call(options, __method__) { |*split| split }
       text = api['text']
-      unless text.is_a?(String) && !text.strip.empty?
-        raise Internal.invalid('Text to classify must be a non-empty string', ErrorCodes::INVALID_UPLOAD_PAYLOAD)
-      end
+      raise Internal.invalid('Text to classify must be a non-empty string') unless text.is_a?(String) && !text.strip.empty?
 
       @assets.classify(without(api, 'text').merge('name' => api.fetch('name', 'text'),
                                                   'content' => { 'plainText' => text, 'type' => 'text/plain' },

data/lib/calmlens/transform_rules.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module CalmLens
+  # The CDN's rules for transforms: options checked against the image transform schema
+  # (Internal::TRANSFORM_OPTIONS_SCHEMA), and selectors read as the CDN reads them.
+  # @api private
+  module TransformRules
+    module_function
+
+    # Checks transform options against the image transform schema, as the CDN does, and returns
+    # the dotted keys it doesn't know and those whose values it refuses (or that are required and
+    # missing). nil options are left out of a selector, so they are not checked.
+    # @return [Array(Array<String>, Array<String>)] the unknown keys and the invalid keys
+    def check(options)
+      unknown = []
+      invalid = []
+      check_rule(Internal::TRANSFORM_OPTIONS_SCHEMA, options, '', unknown, invalid)
+      [unknown, invalid]
+    end
+
+    def check_rule(schema, value, key, unknown, invalid)
+      rule = schema.key?('oneOf') ? schema['oneOf'].find { |branch| rule_type?(branch['type'], value) } : schema
+      return invalid << key unless rule && rule_allows?(rule, value)
+      return unless rule['type'] == 'object'
+
+      path = ->(name) { key.empty? ? name : "#{key}.#{name}" }
+      entries = value.to_h { |name, item| [name.to_s, item] }
+      rule.fetch('required', []).each { |name| invalid << path.call(name) if entries[name].nil? }
+      entries.keys.sort.each do |name|
+        next if entries[name].nil?
+
+        child = rule.fetch('properties', {})[name]
+        child ? check_rule(child, entries[name], path.call(name), unknown, invalid) : unknown << path.call(name)
+      end
+    end
+
+    def rule_allows?(rule, value)
+      rule_type?(rule['type'], value) &&
+        (!rule.key?('enum') || rule['enum'].include?(value)) &&
+        (!rule.key?('minimum') || value >= rule['minimum']) &&
+        (!rule.key?('maximum') || value <= rule['maximum'])
+    end
+
+    def rule_type?(type, value)
+      case type
+      when 'object' then value.is_a?(Hash)
+      when 'string' then value.is_a?(String)
+      when 'boolean' then [true, false].include?(value)
+      when 'number' then value.is_a?(Integer) || (value.is_a?(Float) && value.finite?)
+      when 'integer' then value.is_a?(Integer) || (value.is_a?(Float) && value.finite? && value == value.floor)
+      else true
+      end
+    end
+
+    NUMBER = /\A-?(?:0|[1-9]\d*)(?:\.\d+)?\z/
+    LENS = /\A[a-z0-9-]{1,50}\z/
+
+    # Reads a CDN selector, the path text after the resource as sent (still percent-encoded), as the
+    # CDN does: an optional first `@lens`, then `key=value` options with dotted keys for nested ones (a
+    # bare key is `true`). Values are numbers, `true`, `false`, hex colours (`#` added) for colour
+    # options, or text. Raises ArgumentError on anything the CDN refuses as `asset/invalid-transform`.
+    # Used by the mock CDN.
+    # @return [Array(String, Hash)] the lens and the options, each nil when absent
+    def parse_selector(selector)
+      return [nil, nil] if selector.empty?
+      raise ArgumentError, "Invalid transform selector #{selector.inspect}" if selector.include?('/')
+
+      entries = selector.split(',', -1)
+      lens = nil
+      if entries.first.start_with?('@')
+        lens = selector_text(entries.shift.delete_prefix('@'), selector)
+        raise ArgumentError, "Invalid transform selector #{selector.inspect}" unless lens.match?(LENS)
+      end
+      return [lens, nil] if entries.empty?
+
+      options = {}
+      entries.each { |entry| add_selector_entry(options, entry, selector) }
+      [lens, options]
+    end
+
+    def add_selector_entry(options, entry, selector)
+      fail = -> { ArgumentError.new("Invalid transform selector #{selector.inspect}") }
+      raise fail.call if entry.empty? || entry.start_with?('@')
+
+      key, separator, text = entry.partition('=')
+      parts = key.split('.', -1)
+      raise fail.call unless parts.all? { |part| part.match?(Transforms::OPTION_NAME) }
+
+      value = separator.empty? || selector_value(key, selector_text(text, selector))
+      raise fail.call if value == ''
+
+      target = parts[0..-2].reduce(options) do |current, part|
+        raise fail.call unless current[part].nil? || current[part].is_a?(Hash)
+
+        current[part] ||= {}
+      end
+      raise fail.call if target.key?(parts.last)
+
+      target[parts.last] = value
+    end
+
+    def selector_value(key, text)
+      return text if text.empty?
+      return "##{text.downcase}" if Transforms::COLOUR_KEYS.include?(key) && Transforms::HEX_COLOUR.match?("##{text}")
+      return text.include?('.') ? Float(text) : Integer(text, 10) if text.match?(NUMBER)
+      return text == 'true' if %w[true false].include?(text)
+
+      text
+    end
+
+    # Percent-decodes selector text, refusing malformed escapes and text that isn't UTF-8.
+    def selector_text(text, selector)
+      decoded = text.b.gsub(/%(\h\h)/n) { Regexp.last_match(1).hex.chr }.force_encoding(Encoding::UTF_8)
+      raise ArgumentError, "Invalid transform selector #{selector.inspect}" if text.match?(/%(?!\h\h)/) || !decoded.valid_encoding?
+
+      decoded
+    end
+  end
+  private_constant :TransformRules
+end

data/lib/calmlens/transform_schema.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+# Generated by packages/sdk-contract/generate.ts from IMAGE_TRANSFORM_OPTIONS_SCHEMA; do not edit.
+# The rules each transform option is checked against; see packages/sdk-contract/README.md.
+
+require 'json'
+
+module CalmLens
+  module Internal
+    # The image transform options' schema, with only the rules the SDK checks.
+    TRANSFORM_OPTIONS_SCHEMA = JSON.parse(<<~JSON).freeze
+      {
+        "type": "object",
+        "properties": {
+          "format": {
+            "type": "string",
+            "enum": [
+              "jpg",
+              "png",
+              "webp",
+              "avif",
+              "gif"
+            ]
+          },
+          "width": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 10000
+          },
+          "height": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 10000
+          },
+          "dpr": {
+            "type": "number",
+            "minimum": 1,
+            "maximum": 3
+          },
+          "anim": {
+            "type": "boolean"
+          },
+          "background": {
+            "type": "string"
+          },
+          "blur": {
+            "type": "number"
+          },
+          "redact": {
+            "type": "object",
+            "properties": {
+              "text": {
+                "type": "boolean"
+              },
+              "personalInformation": {
+                "type": "boolean"
+              },
+              "faces": {
+                "type": "boolean"
+              }
+            }
+          },
+          "border": {
+            "type": "object",
+            "properties": {
+              "color": {
+                "type": "string"
+              },
+              "width": {
+                "type": "number"
+              }
+            }
+          },
+          "brightness": {
+            "type": "number"
+          },
+          "contrast": {
+            "type": "number"
+          },
+          "quality": {
+            "oneOf": [
+              {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 100
+              },
+              {
+                "type": "string",
+                "enum": [
+                  "low",
+                  "medium",
+                  "high"
+                ]
+              }
+            ]
+          },
+          "fit": {
+            "type": "string",
+            "enum": [
+              "scale-down",
+              "contain",
+              "pad",
+              "squeeze",
+              "cover",
+              "crop"
+            ]
+          },
+          "flip": {
+            "type": "string",
+            "enum": [
+              "h",
+              "v",
+              "hv"
+            ]
+          },
+          "gamma": {
+            "type": "number"
+          },
+          "segment": {
+            "type": "string",
+            "enum": [
+              "foreground"
+            ]
+          },
+          "gravity": {
+            "oneOf": [
+              {
+                "type": "string",
+                "enum": [
+                  "face",
+                  "left",
+                  "right",
+                  "top",
+                  "bottom",
+                  "center",
+                  "auto",
+                  "entropy"
+                ]
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "mode": {
+                    "type": "string",
+                    "enum": [
+                      "remainder",
+                      "box-center"
+                    ]
+                  },
+                  "x": {
+                    "type": "number"
+                  },
+                  "y": {
+                    "type": "number"
+                  }
+                },
+                "required": [
+                  "mode"
+                ]
+              }
+            ]
+          },
+          "rotate": {
+            "type": "integer",
+            "enum": [
+              0,
+              90,
+              180,
+              270
+            ]
+          },
+          "saturation": {
+            "type": "number"
+          },
+          "sharpen": {
+            "type": "number"
+          },
+          "trim": {
+            "oneOf": [
+              {
+                "type": "string",
+                "enum": [
+                  "border"
+                ]
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "top": {
+                    "type": "number"
+                  },
+                  "bottom": {
+                    "type": "number"
+                  },
+                  "left": {
+                    "type": "number"
+                  },
+                  "right": {
+                    "type": "number"
+                  },
+                  "width": {
+                    "type": "number"
+                  },
+                  "height": {
+                    "type": "number"
+                  },
+                  "border": {
+                    "oneOf": [
+                      {
+                        "type": "boolean"
+                      },
+                      {
+                        "type": "object",
+                        "properties": {
+                          "color": {
+                            "type": "string"
+                          },
+                          "tolerance": {
+                            "type": "number"
+                          },
+                          "keep": {
+                            "type": "number"
+                          }
+                        }
+                      }
+                    ]
+                  }
+                }
+              }
+            ]
+          }
+        }
+      }
+    JSON
+  end
+end