calmlens 0.19.0 → 0.21.0

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 `transform/invalid`.
+    # 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

data/lib/calmlens/transforms.rb

@@ -42,6 +42,7 @@ module CalmLens
     def serialize(value)
       raise Internal.invalid('Transform options must be a Hash') unless value.is_a?(Hash)
 
+      assert_valid(value)
       pairs = []
       sorted_options(value).each { |key, item| append_pairs(pairs, key, item) }
       raise Internal.invalid('A transform needs at least one option') if pairs.empty?
@@ -49,6 +50,21 @@ module CalmLens
       pairs.join(',')
     end
 
+    # Raises `sdk/invalid-argument` naming each transform option the CDN would refuse, with
+    # `details` `{'unknownKeys', 'invalidKeys'}`.
+    def assert_valid(options)
+      unknown, invalid = TransformRules.check(options)
+      return if unknown.empty? && invalid.empty?
+
+      problems = []
+      problems << "unknown option#{'s' if unknown.size > 1} #{unknown.join(', ')}" unless unknown.empty?
+      problems << "invalid value#{'s' if invalid.size > 1} for #{invalid.join(', ')}" unless invalid.empty?
+      raise InvalidArgumentError.new(SdkErrorCodes::INVALID_ARGUMENT,
+                                     "Transform options are invalid: #{problems.join('; ')}. Pass the options " \
+                                     "themselves, such as { width: 640, format: 'webp' }.",
+                                     details: { 'unknownKeys' => unknown, 'invalidKeys' => invalid })
+    end
+
     def sorted_options(options, prefix = '')
       options.map do |key, item|
         name = key.to_s

data/lib/calmlens/upload_mime_types.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# Generated by packages/sdk-contract/generate.ts from packages/shared/src/UploadMimeTypes.ts; do not edit.
+# After lower-casing and dropping parameters, a type in REJECTED is refused; otherwise one
+# that starts with a PREFIXES entry, ends with a SUFFIXES entry or is in TYPES is accepted,
+# and any other type is refused with upload/unsupported-type.
+
+module CalmLens
+  module Internal
+    UPLOAD_MIME_REJECTED = [
+      'application/octet-stream',
+      'multipart/form-data',
+      'multipart/mixed',
+      'multipart/alternative',
+      'multipart/related',
+      'multipart/signed',
+      'multipart/encrypted'
+    ].freeze
+    UPLOAD_MIME_PREFIXES = [
+      'image/',
+      'video/',
+      'audio/',
+      'text/'
+    ].freeze
+    UPLOAD_MIME_SUFFIXES = [
+      '+json',
+      '+xml'
+    ].freeze
+    UPLOAD_MIME_TYPES = [
+      'application/pdf',
+      'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+      'application/msword',
+      'application/rtf',
+      'application/vnd.oasis.opendocument.text',
+      'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+      'application/vnd.ms-excel.sheet.macroenabled.12',
+      'application/vnd.ms-excel',
+      'application/vnd.oasis.opendocument.spreadsheet',
+      'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+      'application/vnd.ms-powerpoint.presentation.macroenabled.12',
+      'application/vnd.ms-powerpoint',
+      'application/vnd.oasis.opendocument.presentation',
+      'application/javascript',
+      'application/json',
+      'application/x-javascript',
+      'application/x-yaml',
+      'application/xml',
+      'application/yaml'
+    ].freeze
+  end
+end

data/lib/calmlens/upload_tokens.rb

@@ -26,7 +26,7 @@ module CalmLens
     # Signs a single-use token. Hand it to the browser as its bearer token; give each upload its own.
     # @option options [String] :upload_preset_id the preset the token may upload through
     # @option options [String] :external_id the external ID the uploaded asset gets (not empty)
-    # @option options [Integer] :expires_in_seconds lifetime, 1 to 3600 (default 600)
+    # @option options [Integer] :expires_in lifetime in seconds, 1 to 3600 (default 600)
     # @return [Hash] `{'token' => String, 'expiresAt' => Integer}` (milliseconds since the Unix epoch)
     def sign(options)
       call(options, __method__) { UploadTokens.sign_at(@api_key, options, now: (Time.now.to_f * 1000).to_i, nonce: SecureRandom.uuid) }
@@ -39,9 +39,9 @@ module CalmLens
       api, = Internal.options(options)
       preset_id = api['uploadPresetId']
       Internal.segment(preset_id)
-      ttl = api.fetch('expiresInSeconds', DEFAULT_TTL_SECONDS)
+      ttl = api.fetch('expiresIn', DEFAULT_TTL_SECONDS)
       unless ttl.is_a?(Integer) && ttl.between?(1, MAX_TTL_SECONDS)
-        raise Internal.invalid("expiresInSeconds must be a whole number from 1 to #{MAX_TTL_SECONDS}")
+        raise Internal.invalid("expiresIn must be a whole number from 1 to #{MAX_TTL_SECONDS}")
       end
 
       external_id = api['externalId']

data/lib/calmlens/version.rb

@@ -2,5 +2,5 @@
 
 module CalmLens
   # The gem version. The gemspec and the User-Agent header read it from here.
-  VERSION = '0.19.0'
+  VERSION = '0.21.0'
 end

data/lib/calmlens/webhooks.rb

@@ -15,25 +15,34 @@ module CalmLens
   WEBHOOK_SIGNATURE_TOLERANCE_SECONDS = 300
 
   # A verified webhook delivery. The body has the shape of an {Events#list} item:
-  # `{id, projectId, type, severity, title, description, assetId, asset, facts, createdAt}`.
+  # `{id, projectId, actor, type, severity, title, description, assetId, assetSequence, asset, facts, createdAt}`.
   # Fields CalmLens adds later are kept in {#payload}, as are unknown asset and fact fields.
   #
   # @!attribute id [String] the event ID.
   # @!attribute project_id [String]
+  # @!attribute actor [Hash, nil] who caused the event: `{'type', 'id'}`, with `type` `user`, `api-key`,
+  #   `automated` or `system`, and `id` the user's or API key's ID, or nil when it was not recorded.
   # @!attribute type [String] such as `asset.allowed`. New types may appear: ignore unknown ones.
   # @!attribute severity [String, nil] `low` or `high`.
   # @!attribute title [String, nil]
   # @!attribute description [String, nil]
   # @!attribute asset_id [String, nil]
+  # @!attribute asset_sequence [Integer, nil] increases with each event about the same asset; nil for
+  #   events not about an asset. Deliveries can arrive out of order: see {#newer_than?}.
   # @!attribute asset [Hash, nil] the asset's status when the event was created.
   # @!attribute facts [Array<Hash>] `{'key', 'value', 'url'?}` entries registered for the event type.
   # @!attribute created_at [Integer] milliseconds since the epoch.
   # @!attribute payload [Hash{String => Object}] the delivery body as received, with every field.
-  WebhookEvent = Struct.new(:id, :project_id, :type, :severity, :title, :description, :asset_id, :asset, :facts,
-                            :created_at, :payload, keyword_init: true) do
+  WebhookEvent = Struct.new(:id, :project_id, :actor, :type, :severity, :title, :description, :asset_id, :asset_sequence, :asset,
+                            :facts, :created_at, :payload, keyword_init: true) do
     # @return [Boolean] true for a test send from the portal or CLI.
     def test? = Webhooks.test_event?(self)
 
+    # @param last_sequence [Integer, nil] the highest `assetSequence` applied for this event's asset
+    # @return [Boolean] whether to apply this event after it.
+    # @see Webhooks.newer_asset_event?
+    def newer_than?(last_sequence) = Webhooks.newer_asset_event?(self, last_sequence)
+
     # @return [Hash{String => Object}] the delivery body as received, with every field.
     def to_payload = payload
   end
@@ -79,16 +88,34 @@ module CalmLens
       facts.is_a?(Array) && facts.any? { |fact| fact.is_a?(Hash) && fact['key'] == 'test' && fact['value'] == true }
     end
 
+    # Whether to apply `event` after `last_sequence`, the highest `assetSequence` you have applied
+    # for its asset (nil when none). Deliveries can arrive out of order: an event about an asset is
+    # newer only with a higher `assetSequence`, so a retried or repeated delivery of an earlier one
+    # returns false. Events that aren't about an asset have no sequence and are always new. Store
+    # the highest `assetSequence` applied per `assetId` and ignore lower ones.
+    # @param event [WebhookEvent, Hash] a parsed delivery, or a delivery body with string keys
+    # @param last_sequence [Integer, nil]
+    # @return [Boolean]
+    def newer_asset_event?(event, last_sequence)
+      sequence = event.is_a?(Hash) ? event['assetSequence'] : event.asset_sequence
+      sequence.nil? || last_sequence.nil? || sequence > last_sequence
+    end
+
     # Converts an event from {Events#list} to the JSON body of its webhook delivery, which has the
-    # same fields: `description`, `assetId` and `asset` are nil when absent.
+    # same fields: `description`, `assetId`, `assetSequence` and `asset` are nil when absent, and
+    # `actor` is left out when the event has none.
     # @param event [Hash] an event with string keys, as {Events#list} returns it
-    # @return [Hash] `{ 'id', 'projectId', 'type', 'severity', 'title', 'description', 'assetId', 'asset', 'facts', 'createdAt' }`
+    # @return [Hash] `{ 'id', 'projectId', 'actor', 'type', 'severity', 'title', 'description', 'assetId',
+    #   'assetSequence', 'asset', 'facts', 'createdAt' }`
     def to_payload(event)
       raise Internal.invalid('event must be a Hash') unless event.is_a?(Hash)
 
-      { 'id' => event['id'], 'projectId' => event['projectId'], 'type' => event['type'], 'severity' => event['severity'],
-        'title' => event['title'], 'description' => event['description'], 'assetId' => event['assetId'],
-        'asset' => event['asset'], 'facts' => event['facts'], 'createdAt' => event['createdAt'] }
+      payload = { 'id' => event['id'], 'projectId' => event['projectId'] }
+      payload['actor'] = event['actor'] if event.key?('actor')
+      payload.merge('type' => event['type'], 'severity' => event['severity'], 'title' => event['title'],
+                    'description' => event['description'], 'assetId' => event['assetId'],
+                    'assetSequence' => event['assetSequence'], 'asset' => event['asset'], 'facts' => event['facts'],
+                    'createdAt' => event['createdAt'])
     end
 
     # Checks a delivery's signature and freshness in constant time. Pass the `signature` and
@@ -149,9 +176,10 @@ module CalmLens
       body = JSON.parse(payload.dup.force_encoding(Encoding::UTF_8))
       raise WebhookVerificationError.new(SdkErrorCodes::INVALID_WEBHOOK_PAYLOAD, 'Webhook body is not a CalmLens event') unless event?(body)
 
-      WebhookEvent.new(id: body['id'], project_id: body['projectId'], type: body['type'], severity: body['severity'],
+      WebhookEvent.new(id: body['id'], project_id: body['projectId'], actor: body['actor'], type: body['type'], severity: body['severity'],
                        title: body['title'], description: body['description'], asset_id: body['assetId'],
-                       asset: body['asset'], facts: body.fetch('facts', []), created_at: body['createdAt'], payload: body)
+                       asset_sequence: body['assetSequence'], asset: body['asset'], facts: body.fetch('facts', []),
+                       created_at: body['createdAt'], payload: body)
     rescue JSON::ParserError, EncodingError => e
       raise WebhookVerificationError.new(SdkErrorCodes::INVALID_WEBHOOK_PAYLOAD, 'Webhook body is not JSON'), cause: e
     end
@@ -163,9 +191,17 @@ module CalmLens
                           body['projectId'].is_a?(String) && body['createdAt'].is_a?(Numeric)
 
       optional = ->(key, *types) { !body.key?(key) || types.any? { |type| type.nil? ? body[key].nil? : body[key].is_a?(type) } }
-      asset = body['asset']
       optional.call('severity', String) && optional.call('title', String) && optional.call('description', String, nil) &&
-        optional.call('assetId', String, nil) && (asset.nil? || (asset.is_a?(Hash) && asset['id'].is_a?(String))) &&
+        optional.call('assetId', String, nil) && optional.call('assetSequence', Numeric, nil) && nested?(body)
+    end
+
+    # The nested fields, when present: `actor` is `{type, id}` with a String type and a String or null
+    # ID, `asset` has a String `id` and `facts` lists `{key, value, url?}` entries.
+    def nested?(body)
+      actor = body.fetch('actor', { 'type' => '' })
+      asset = body['asset']
+      actor.is_a?(Hash) && actor['type'].is_a?(String) && (actor['id'].nil? || actor['id'].is_a?(String)) &&
+        (asset.nil? || (asset.is_a?(Hash) && asset['id'].is_a?(String))) &&
         (!body.key?('facts') || (body['facts'].is_a?(Array) && body['facts'].all? { |fact| fact?(fact) }))
     end
 
@@ -191,7 +227,7 @@ module CalmLens
       raise Internal.invalid("Webhook payload must be the raw body String, not a #{payload.class}. " \
                              'Read request.raw_post (Rails) or request.body.read (Rack, Sinatra) before parsing.')
     end
-    private_class_method :decode_event, :event?, :fact?, :header, :raw_body
+    private_class_method :decode_event, :event?, :nested?, :fact?, :header, :raw_body
   end
 
   # @see Webhooks.signature_header
@@ -214,4 +250,13 @@ module CalmLens
 
   # @see Webhooks.test_event?
   def self.test_webhook_event?(...) = Webhooks.test_event?(...)
+
+  # @see Webhooks.newer_asset_event?
+  def self.newer_asset_event?(...) = Webhooks.newer_asset_event?(...)
+
+  # @see EventFacts.value
+  def self.get_event_fact(...) = EventFacts.value(...)
+
+  # @see EventFacts.values
+  def self.get_event_facts(...) = EventFacts.values(...)
 end

data/lib/calmlens.rb

@@ -9,8 +9,11 @@ require_relative 'calmlens/version'
 require_relative 'calmlens/error_codes'
 require_relative 'calmlens/errors'
 require_relative 'calmlens/option_keys'
+require_relative 'calmlens/transform_schema'
+require_relative 'calmlens/upload_mime_types'
 require_relative 'calmlens/internal'
 require_relative 'calmlens/transforms'
+require_relative 'calmlens/transform_rules'
 require_relative 'calmlens/response'
 require_relative 'calmlens/transport'
 require_relative 'calmlens/upload_body'