calmlens 0.1.1 → 0.18.0

data/lib/calmlens/testing/mock_decision.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require_relative 'classification'
+
+module CalmLens
+  # A moderation decision for {MockServerClient}'s `moderate:` option or
+  # {MockServerClient#complete_processing}, started with {.of}: flag the categories it found, with
+  # their scores and qualifiers, and mark the categories it couldn't assess. Each call checks its
+  # names and scores and raises `sdk/invalid-argument` for one CalmLens doesn't have.
+  #
+  # @example
+  #   CalmLens::MockDecision.of('blocked').flag('violence', 0.9, 'violence-threat' => 0.9).not_evaluated('profanity')
+  class MockDecision
+    # Where the mock's moderation leaves an upload: `pending` (still processing), `failed`
+    # (processing failed, retryable), or a decision with that moderation status (`purged` also
+    # removes the content).
+    STATUSES = %w[pending failed allowed limited age-restricted blocked purged].freeze
+    # The policy action that gives each decided status.
+    STATUS_ACTIONS = { 'allowed' => 'allow', 'limited' => 'limit', 'age-restricted' => 'age-restrict', 'blocked' => 'block',
+                       'purged' => 'purge' }.freeze
+    private_constant :STATUS_ACTIONS
+
+    # @return [String]
+    attr_reader :status
+
+    # Starts a decision with this status.
+    # @param status [String] one of {STATUSES}
+    # @return [MockDecision]
+    def self.of(status) = new(status)
+
+    # A `moderate:` answer or {MockServerClient#complete_processing} decision as a checked decision.
+    # @api private
+    def self.from(value)
+      return value if value.is_a?(MockDecision)
+      return new(value) if value.is_a?(String)
+
+      raise Internal.invalid("A decision must be a status or a CalmLens::MockDecision (got #{value.inspect})")
+    end
+
+    # @param status [String] one of {STATUSES}
+    # @raise [InvalidArgumentError] for an unknown status
+    def initialize(status)
+      raise Internal.invalid("status must be one of #{STATUSES.join(', ')} (got #{status.inspect})") unless STATUSES.include?(status)
+
+      @status = status
+      @flags = {}
+      @not_evaluated = []
+    end
+
+    # Records findings in `category` with its `score` (0 to 1) and, optionally, scores for its
+    # qualifiers, such as `{ 'violence-threat' => 0.9 }`. The policy acts on a category at 0.5 and
+    # above, so `flaggedCategories` lists it there unless the status is `allowed`.
+    # @param category [String]
+    # @param score [Numeric]
+    # @param qualifiers [Hash{String => Numeric}]
+    # @return [self]
+    # @raise [InvalidArgumentError] for an unknown category or qualifier, a score outside 0 to 1, a
+    #   category already in the decision, or a `pending` or `failed` decision
+    def flag(category, score, qualifiers = {})
+      category = check_category(category)
+      raise Internal.invalid("#{category}'s score must be from 0 to 1") unless score?(score)
+
+      checked = qualifiers.to_h do |qualifier, qualifier_score|
+        qualifier = qualifier.to_s
+        known = MockClassification::QUALIFIERS[category].include?(qualifier)
+        raise Internal.invalid("#{qualifier} is not a qualifier of #{category}") unless known
+        raise Internal.invalid("#{qualifier}'s score must be from 0 to 1") unless score?(qualifier_score)
+
+        [qualifier, qualifier_score]
+      end
+      @flags[category] = { score: score, qualifiers: checked }
+      self
+    end
+
+    # Marks `category` as not assessed (`not-evaluated` for reason `not-supported`).
+    # @param category [String]
+    # @return [self]
+    # @raise [InvalidArgumentError] like {#flag}
+    def not_evaluated(category)
+      @not_evaluated << check_category(category)
+      self
+    end
+
+    # The report a decided asset gets, as the API sends it: every category (unflagged ones
+    # evaluated with score 0), the policy's actions and `flaggedCategories`.
+    # @return [Hash{String => Object}, nil] `categories`, `score` and `policy`; nil for `pending` and `failed`
+    def report
+      return if undecided?
+
+      evaluated = (MockClassification::CATEGORIES - @not_evaluated).map { |category| [category, @flags.dig(category, :score) || 0] }
+      { 'raw' => { 'categories' => MockClassification::CATEGORIES.to_h { |category| [category, category_report(category)] } },
+        'categories' => evaluated.to_h { |category, value| [category, { 'score' => value, 'action' => action(value) }] },
+        'explanationComplete' => true, 'source' => 'policy', 'automatedAction' => STATUS_ACTIONS[@status],
+        'regions' => [], 'flaggedCategories' => evaluated.reject { |_, value| action(value) == 'allow' }.map(&:first) }
+    end
+
+    def inspect = "#<#{self.class.name} #{@status}>"
+
+    private
+
+    def undecided? = %w[pending failed].include?(@status)
+
+    def check_category(category)
+      category = category.to_s
+      raise Internal.invalid("#{category} is not a CalmLens category") unless MockClassification::CATEGORIES.include?(category)
+      raise Internal.invalid("a #{@status} decision has no findings") if undecided?
+      raise Internal.invalid("#{category} is already in this decision") if @flags.key?(category) || @not_evaluated.include?(category)
+
+      category
+    end
+
+    def score?(score) = score.is_a?(Numeric) && score.real? && score.finite? && score >= 0 && score <= 1
+
+    def action(score) = @status != 'allowed' && score >= 0.5 ? STATUS_ACTIONS[@status] : 'allow'
+
+    # The API's likelihood for a score (ClassificationCategories.ts, scoreToLikelihood).
+    def likelihood(score)
+      if score >= 0.8 then 'very-likely'
+      elsif score >= 0.6 then 'likely'
+      elsif score >= 0.4 then 'possible'
+      elsif score >= 0.2 then 'unlikely'
+      else 'very-unlikely'
+      end
+    end
+
+    def category_report(category)
+      return { 'status' => 'not-evaluated', 'reason' => 'not-supported' } if @not_evaluated.include?(category)
+
+      flag = @flags.fetch(category, { score: 0, qualifiers: {} })
+      result = { 'status' => 'evaluated', 'likelihood' => likelihood(flag[:score]), 'score' => flag[:score] }
+      unless flag[:qualifiers].empty?
+        result['qualifiers'] = flag[:qualifiers].to_h do |qualifier, some|
+          [qualifier, { 'status' => 'evaluated', 'someScore' => some, 'likelihood' => likelihood(some) }]
+        end
+      end
+      result
+    end
+  end
+
+  # What {MockServerClient}'s `moderate:` callback receives for each asset the mock moderates.
+  #
+  # - `asset` [Hash] the asset as stored, still processing (a copy).
+  # - `content` [Content] the uploaded bytes and, for a `plaintext-document`, their text.
+  # - `trigger` [String] why the mock is moderating it: `upload` (`assets.create`, `assets.classify`,
+  #   `text.classify` or a final part), `retry` (`assets.retry`), `rerun` (`assets.explain` with
+  #   `rerun: true`) or `complete` ({MockServerClient#complete_processing} without a decision).
+  # - `queued` [Boolean] true when the API would queue the work rather than answer with the
+  #   decision: queued uploads, retries, reruns and `complete`.
+  MockModerationInput = Struct.new(:asset, :content, :trigger, :queued, keyword_init: true) do
+    # @return [Boolean]
+    def queued? = queued
+  end
+
+  # The content of a {MockModerationInput}: `bytes` is the uploaded bytes (binary; nil without
+  # stored content, such as a website or removed content, and multipart parts joined in order),
+  # and `text` is them decoded as UTF-8 for a `plaintext-document` (else nil).
+  MockModerationInput::Content = Struct.new(:bytes, :text, keyword_init: true)
+end

data/lib/calmlens/testing/placeholder.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require 'zlib'
+
+module CalmLens
+  module Testing
+    # Renders a ThumbHash as the small PNG the CDN serves for an asset's `placeholder` resource,
+    # byte for byte like the CDN's renderer: the ThumbHash decoded to RGBA, stored uncompressed.
+    # @api private
+    module Placeholder
+      module_function
+
+      # @param hash [String] the base64 ThumbHash
+      # @return [String] PNG bytes
+      def png(hash)
+        width, height, rgba = rgba(hash.unpack1('m0').bytes)
+        encode(width, height, rgba)
+      end
+
+      # Decodes ThumbHash bytes to its width, height and RGBA pixels (RGB not premultiplied).
+      def rgba(hash)
+        header = hash[0] | (hash[1] << 8) | (hash[2] << 16)
+        alpha = (header >> 23) == 1
+        landscape = ((hash[3] | (hash[4] << 8)) >> 15) == 1
+        short = alpha ? 5 : 7
+        lx = [3, landscape ? short : hash[3] & 7].max
+        ly = [3, landscape ? hash[3] & 7 : short].max
+        channels = channels(hash, header, alpha, lx, ly)
+        ratio = aspect_ratio(hash)
+        width = (ratio > 1 ? 32 : 32 * ratio).round
+        height = (ratio > 1 ? 32 / ratio : 32).round
+        pixels = []
+        height.times do |y|
+          width.times do |x|
+            fx = Array.new([lx, alpha ? 5 : 3].max) { |cx| Math.cos(Math::PI / width * (x + 0.5) * cx) }
+            fy = Array.new([ly, alpha ? 5 : 3].max) { |cy| Math.cos(Math::PI / height * (y + 0.5) * cy) }
+            pixels.concat(pixel(channels, fx, fy, lx, ly, alpha))
+          end
+        end
+        [width, height, pixels]
+      end
+
+      # The DC values and AC coefficients of the luminance, colour and alpha channels.
+      def channels(hash, header, alpha, lum_cols, lum_rows)
+        header16 = hash[3] | (hash[4] << 8)
+        index = 0
+        start = alpha ? 6 : 5
+        decode = lambda do |cols, rows, scale|
+          values = []
+          each_term(cols, rows) do
+            values << (((((hash[start + (index >> 1)] >> ((index & 1) << 2)) & 15) / 7.5) - 1) * scale)
+            index += 1
+          end
+          values
+        end
+        { l_dc: (header & 63) / 63.0, p_dc: (((header >> 6) & 63) / 31.5) - 1, q_dc: (((header >> 12) & 63) / 31.5) - 1,
+          a_dc: alpha ? (hash[5] & 15) / 15.0 : 1.0,
+          l: decode.call(lum_cols, lum_rows, ((header >> 18) & 31) / 31.0), p: decode.call(3, 3, ((header16 >> 3) & 63) / 63.0 * 1.25),
+          q: decode.call(3, 3, ((header16 >> 9) & 63) / 63.0 * 1.25), a: alpha ? decode.call(5, 5, (hash[5] >> 4) / 15.0) : [] }
+      end
+
+      # Yields the index of each AC coefficient of an `nx` by `ny` channel with its cosine indexes.
+      def each_term(cols, rows)
+        index = 0
+        rows.times do |cy|
+          cx = cy.zero? ? 1 : 0
+          while cx * rows < cols * (rows - cy)
+            yield index, cx, cy
+            index += 1
+            cx += 1
+          end
+        end
+      end
+
+      def pixel(channels, cos_x, cos_y, lum_cols, lum_rows, alpha)
+        l = channels[:l_dc]
+        each_term(lum_cols, lum_rows) { |j, cx, cy| l += channels[:l][j] * cos_x[cx] * cos_y[cy] * 2 }
+        p = channels[:p_dc]
+        q = channels[:q_dc]
+        each_term(3, 3) do |j, cx, cy|
+          f = cos_x[cx] * cos_y[cy] * 2
+          p += channels[:p][j] * f
+          q += channels[:q][j] * f
+        end
+        a = channels[:a_dc]
+        each_term(5, 5) { |j, cx, cy| a += channels[:a][j] * cos_x[cx] * cos_y[cy] * 2 } if alpha
+        b = l - (2 / 3.0 * p)
+        r = ((3 * l) - b + q) / 2
+        [r, r - q, b, a].map { |value| [0, 255 * [1, value].min].max.to_i }
+      end
+
+      def aspect_ratio(hash)
+        short = hash[2].anybits?(128) ? 5 : 7
+        sides = hash[4].anybits?(128) ? [short, hash[3] & 7] : [hash[3] & 7, short]
+        sides[0].to_f / sides[1]
+      end
+
+      # An uncompressed PNG: one stored deflate block per scanline.
+      def encode(width, height, rgba)
+        row = (width * 4) + 1
+        lines = Array.new(height) { |y| "\0".b + rgba[y * width * 4, width * 4].pack('C*') }
+        data = "\x78\x01".b
+        lines.each_with_index { |line, y| data << [y + 1 < height ? 0 : 1, row, row ^ 0xffff].pack('Cvv') << line }
+        data << [Zlib.adler32(lines.join)].pack('N')
+        chunk = ->(type, body) { [body.bytesize].pack('N') + type.b + body + [Zlib.crc32(type.b + body)].pack('N') }
+        "\x89PNG\r\n\x1a\n".b + chunk.call('IHDR', [width, height, 8, 6, 0, 0, 0].pack('NNC5')) +
+          chunk.call('IDAT', data) + chunk.call('IEND', ''.b)
+      end
+    end
+  end
+end

data/lib/calmlens/testing.rb

@@ -11,26 +11,42 @@ module CalmLens
   # error handling, then reach an in-memory stand-in for the API and CDN instead of the network.
   #
   # By default the stand-in is stateful: uploads create assets you can retrieve, list, filter,
-  # move and delete, folders behave like the API's, the CDN serves stored bytes, and errors use
-  # the API's codes, HTTP statuses and body shape. It does not classify content: assets moderated
-  # synchronously get `analyzed_outcome` and queued ones `queued_outcome`. Content is kept only with
-  # `keepContentAfterProcessing: true`; otherwise it is removed once processing is `done`, as in the API.
+  # search, move and delete, folders and hash lists behave like the API's, the CDN serves stored bytes, and errors use
+  # the API's codes, HTTP statuses and body shape. It does not classify content: the `moderate:`
+  # callback decides each upload, retry and rerun with a status or a {MockDecision}, and the events
+  # feed gets the pipeline's `asset.uploaded`, `asset.classified`, `asset.<status>` and `asset.failed`
+  # events. Without it, queued uploads stay `pending` until {#complete_processing} and the rest are
+  # `allowed`. Content is kept only with `keepContentAfterProcessing: true`; otherwise it is removed
+  # once classification is `completed`, as in the API.
+  # A `purged` outcome removes the content with reason `policy`. The CDN answers like the real one:
+  # `asset/not-available` (403) for blocked, purged, failed or removed content,
+  # `viewer/age-confirmation-required` (403) for an age-restricted asset without
+  # `viewer_claims: {age_confirmed: true}`, whatever the key, and `asset/api-key-missing-permission` (403)
+  # for a private asset unless `api_key` comes from {.create_api_key} with an `assets:download`
+  # grant. The default key has no grants. {#decide} applies a reviewer's decision, and
+  # {Assets#wait_for_decision} takes no real time: a pending asset times out at once.
+  # Filters join comparisons with `;` (and), which binds tighter than `,` (or), and group them with
+  # `( … )`; list cursors resume after the last item returned. {Assets#search} is the API's keyword
+  # search: every query word (case-insensitive, up to 8) must appear in a searchable field, and
+  # results carry the API's `score` and `matchedFields`, ranked by score and then newest first.
   #
   # To script exact responses, enqueue them: queued responses and errors are used first, in order,
   # before the stand-in answers.
   #
   # @example
-  #   mock = CalmLens::MockServerClient.new
-  #   asset = mock.assets.moderate(name: 'note', content: {plain_text: 'hi', type: 'text/plain'})
-  #   mock.assets.retrieve(asset_id: asset['id']).dig('moderation', 'status') # => "approved"
+  #   mock = CalmLens::MockServerClient.new(moderate: ->(input) { input.content.text&.include?('spam') ? 'blocked' : 'allowed' })
+  #   asset = mock.assets.classify(name: 'note', content: {plain_text: 'hi', type: 'text/plain'})
+  #   mock.assets.retrieve(asset_id: asset['id']).dig('classification', 'moderation', 'status') # => "allowed"
   #   mock.enqueue(status: 503, body: {code: 'server/unavailable', message: 'Try again'})
   class MockServerClient < ServerClient
     # A request the mock received.
     #
-    # `path` is relative to `base_url` for API calls (`/projects/<id>/assets`) and to
-    # `cdn_base_url` for CDN requests. `query` holds the decoded query string. `body` is the bytes
-    # sent: JSON text, or the uploaded content (streams are read), or nil.
-    Request = Struct.new(:method, :url, :path, :query, :headers, :body, keyword_init: true) do
+    # `path` is relative to `base_url` for API calls (`/projects/<id>/assets`, without `/v1`) and to
+    # `cdn_base_url` for CDN requests, with each segment decoded. `query` holds the decoded query
+    # string. `body` is the bytes sent: JSON text, or the uploaded content (streams are read), or
+    # nil. `status` is the HTTP status the mock answered with, or nil when the request failed
+    # without a response.
+    Request = Struct.new(:method, :url, :path, :query, :headers, :body, :status, keyword_init: true) do
       # @return [Object] the body parsed as JSON.
       def json = body && JSON.parse(body)
     end
@@ -38,33 +54,193 @@ module CalmLens
     # @return [Testing::State] the stored assets, folders, content and events.
     attr_reader :state
 
+    # The prefix of mock API keys made by {.create_api_key}.
+    API_KEY_PREFIX = 'sk_test_'
+    # Simulated failures for {#fail_next_request}, besides API error codes and exceptions.
+    REQUEST_FAILURES = %w[transport-error timeout].freeze
+    # The methods {#fail_next_request} can target, by resource. Iterators are their list calls.
+    OPERATIONS = { assets: %i[search list retrieve list_children update create classify upload_part create_signed_url move
+                              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],
+                   text: %i[classify], events: %i[list],
+                   cdn: %i[serve] }.freeze
+    private_constant :OPERATIONS
+    # The operation names {#fail_next_request} accepts, in their camelCase form.
+    OPERATION_NAMES = (OPERATIONS.flat_map do |resource, methods|
+      methods.map { |name| "#{Internal.camelize(resource)}.#{Internal.camelize(name)}" }
+    end + %w[ensureLens ensureLenses]).freeze
+    private_constant :OPERATION_NAMES
+
+    # A mock API key carrying permission grants, such as
+    # `[{ actions: ['assets:download'], folderId: nil, includeSubfolders: true }]` for CDN reads of
+    # private and age-restricted assets.
+    # @param grants [Array<Hash>] snake_case keys are converted.
+    # @return [String]
+    def self.create_api_key(grants = [])
+      API_KEY_PREFIX + [JSON.generate(Internal.normalize(grants))].pack('m0').tr('+/', '-_').delete('=')
+    end
+
+    # The grants a key from {.create_api_key} carries; none for any other key.
+    # @api private
+    def self.grants_of(api_key)
+      return [] unless api_key.start_with?(API_KEY_PREFIX)
+
+      encoded = api_key.delete_prefix(API_KEY_PREFIX).tr('-_', '+/')
+      grants = JSON.parse("#{encoded}#{'=' * (-encoded.size % 4)}".unpack1('m0'))
+      grants.is_a?(Array) ? grants.grep(Hash) : []
+    rescue ArgumentError, JSON::ParserError
+      []
+    end
+
+    # Signs an upload token like {UploadTokens#sign}, with the same checks, at a fixed time and with
+    # a fixed nonce, so tests can compare exact tokens.
+    # @param api_key [String]
+    # @param options [Hash] the options of {UploadTokens#sign}
+    # @param now [Integer] the signing time in milliseconds since the Unix epoch
+    # @param nonce [String]
+    # @return [Hash] `{'token', 'expiresAt'}`
+    def self.sign_upload_token(api_key, options, now:, nonce:)
+      UploadTokens.sign_at(api_key, options, now: now, nonce: nonce)
+    rescue KeyError, TypeError, ArgumentError, JSON::GeneratorError, EncodingError => e
+      raise InvalidArgumentError.new(SdkErrorCodes::INVALID_ARGUMENT, e.message), cause: e
+    end
+
+    BASE62 = [*'0'..'9', *'A'..'Z', *'a'..'z'].join.freeze
+    private_constant :BASE62
+
+    # A new ID like the API's: `prefix`, `_` and 20 base62 characters from a CSPRNG (bytes 248 to
+    # 255 are drawn again, so every character is equally likely).
+    # @api private
+    def self.new_id(prefix)
+      body = +''
+      SecureRandom.random_bytes(40).each_byte { |byte| body << BASE62[byte % 62] if byte < 248 } while body.size < 20
+      "#{prefix}_#{body[0, 20]}"
+    end
+
+    # A clock in epoch milliseconds that follows the system time but never repeats or goes back.
+    # @api private
+    def self.monotonic_clock
+      last = 0
+      lock = Mutex.new
+      -> { lock.synchronize { last = [(Time.now.to_f * 1000).to_i, last + 1].max } }
+    end
+
     # @param project_id [String]
-    # @param now [#call] returns the current time in epoch milliseconds.
-    # @param create_id [#call] returns a new ID.
-    # @param queued_outcome [String] the outcome of assets created with {Assets#create}: `pending`
-    #   (processing, moderation pending), `approved` or `rejected` (processing done with that
-    #   decision) or `failed` (processing failed, retryable).
-    # @param analyzed_outcome [String, Hash, #call] the result of {Assets#moderate}: an outcome, fields
-    #   to deep-merge into the asset (`{'moderation' => {'status' => 'rejected', 'action' => 'hide'}}`;
-    #   the outcome follows `moderation.status`, or is `failed` when `processing.status` is `failed`,
-    #   and is `approved` otherwise), or a callable that receives a copy of the asset and returns either.
+    # @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
+    #   increasing `createdAt` and order predictably. A clock you pass is used as is.
+    # @param create_id [#call] receives the prefix of the kind of object (`asset`, `fldr`, `hl`, `hle`, `lens`,
+    #   `evt` or `rev`) and returns a new ID. The default is like the API's: the prefix, `_` and 20 random base62
+    #   characters, such as `asset_5Gm2Rk8XqT3wLp9VbN4c`.
+    # @param moderate [#call, nil] decides each asset the mock moderates. It receives a
+    #   {MockModerationInput} (the stored asset, its content, the trigger and whether the API would
+    #   queue the work) and returns a status from {MockDecision::STATUSES} or a {MockDecision}. It is
+    #   called on uploads (`assets.create`, `assets.classify`, `text.classify` and a final part:
+    #   trigger `upload`), `assets.retry` (`retry`), `assets.explain` with `rerun: true` (`rerun`) and
+    #   {#complete_processing} without a decision (`complete`). `pending` leaves the asset processing.
+    #   Without it, queued work other than `complete` stays `pending` and the rest is `allowed`. It
+    #   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`.
-    #   Retries wait no time unless a queued response sets `Retry-After`.
-    def initialize(project_id: 'project-1', base_url: 'https://api.calmlens.invalid/v1',
-                   cdn_base_url: 'https://cdn.calmlens.invalid/v1', now: -> { (Time.now.to_f * 1000).to_i },
-                   create_id: -> { SecureRandom.uuid }, queued_outcome: 'pending', analyzed_outcome: 'approved',
-                   **options)
+    #   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,
+                   create_id: ->(prefix) { MockServerClient.new_id(prefix) }, moderate: nil, max_retries: 0, **options)
+      raise Internal.invalid('moderate must respond to call') unless moderate.nil? || moderate.respond_to?(:call)
+
       @mock_lock = Mutex.new
       @queue = []
       @received = []
-      super(api_key: 'mock-key', project_id: project_id, base_url: base_url, cdn_base_url: cdn_base_url,
-            retry_base_delay: 0, **options, transport: method(:receive))
+      @failures = []
+      @call_key = :"calmlens_mock_call_#{object_id}"
+      super(api_key: api_key, project_id: project_id, base_url: base_url, cdn_base_url: cdn_base_url, max_retries: max_retries,
+            **options, transport: method(:receive))
       @fake = Testing::FakeAPI.new(project_id: project_id, base_url: self.base_url, cdn_base_url: self.cdn_base_url,
-                                   now: now, create_id: create_id, queued_outcome: queued_outcome,
-                                   analyzed_outcome: analyzed_outcome)
+                                   now: now, create_id: create_id, moderate: moderate, grants: MockServerClient.grants_of(api_key))
       @state = @fake.state
+      # Like the API, the stand-in checks upload sizes itself, in the API's order.
+      @session.defer_upload_checks = true
+      OPERATIONS.each { |resource, methods| track(public_send(resource), Internal.camelize(resource), methods) }
+      # Retries and decision checks advance this clock instead of sleeping.
+      @waited = 0.0
+      @session.use_clock(monotonic: -> { @mock_lock.synchronize { @waited } },
+                         pause: ->(seconds) { @mock_lock.synchronize { @waited += seconds } })
+    end
+
+    # Applies a reviewer's decision to a stored asset, as the portal or API would: the moderation
+    # status changes (`purged` also removes the content), the review joins `manualReviews`, and an
+    # `asset.<decision>` event with a `decided-by: reviewer` fact joins the events feed.
+    # @param asset_id [String]
+    # @param decision [String] `allowed`, `limited`, `age-restricted`, `blocked` or `purged`
+    # @return [Hash] the asset
+    # @raise [APIError] `asset/not-found` for an unknown asset
+    # @raise [InvalidArgumentError] for any other decision, such as `pending` or `failed`
+    def decide(asset_id, decision)
+      @mock_lock.synchronize { @fake.decide(asset_id, decision) } || raise(not_found)
+    end
+
+    # Finishes processing an asset as the moderation pipeline would: with `decision`, or else what
+    # `moderate:` answers for the `complete` trigger (`allowed` without it). A decision adds the
+    # `asset.classified` and automated `asset.<status>` events (or `asset.failed`); `pending` leaves
+    # the asset processing. It records no manual review.
+    # @param asset_id [String]
+    # @param decision [String, MockDecision, nil] a status from {MockDecision::STATUSES} or a {MockDecision}
+    # @return [Hash] the asset
+    # @raise [APIError] `asset/not-found` for an unknown asset
+    # @raise [InvalidArgumentError] when the asset isn't processing, or for an unknown decision
+    def complete_processing(asset_id, decision = nil)
+      @mock_lock.synchronize { @fake.complete_processing(asset_id, decision) } || raise(not_found)
+    end
+
+    # Changes the grants of the mock's API key, as editing the key in the portal would: later
+    # requests, such as {CDN#serve}, use them. The key itself stays the same, so idempotency keys it
+    # used still replay.
+    # @param grants [Array<Hash>] like {.create_api_key}'s
+    def api_key_grants=(grants)
+      normalized = JSON.parse(JSON.generate(Internal.normalize(grants)))
+      @mock_lock.synchronize { @fake.grants = normalized }
+    end
+
+    # Makes the next request (or the next one `operation` sends) fail instead of running, as if it
+    # never completed. Each queued failure fails one request, so a client retry takes the next
+    # queued failure or reaches the API. Queue several to fail several requests in a row.
+    # @param failure [String, Exception] `transport-error` (`sdk/transport-error`), `timeout`
+    #   (`sdk/timeout`), an API error code such as `upload/limit-exceeded` (answered with its HTTP
+    #   status), or an exception for the transport to raise.
+    # @param operation [String, nil] a method such as `assets.create`, `assets.upload_part`,
+    #   `cdn.serve` or `ensure_lens` (JavaScript names such as `assets.uploadPart` work too).
+    # @param details [Hash, nil] the API error's `details`, for an API error code.
+    # @param retry_after [Integer, nil] whole seconds for the API error's `Retry-After` header.
+    # @return [self]
+    # @raise [InvalidArgumentError] for an unknown failure or operation, or a `retry_after` that isn't
+    #   a whole number of seconds
+    def fail_next_request(failure = 'transport-error', operation: nil, details: nil, retry_after: nil)
+      unless failure.is_a?(Exception) || REQUEST_FAILURES.include?(failure) || ErrorCodes::STATUSES.key?(failure)
+        raise Internal.invalid("Unknown failure #{failure.inspect}: use #{REQUEST_FAILURES.join(', ')}, an API error code or an exception")
+      end
+      unless retry_after.nil? || (retry_after.is_a?(Integer) && retry_after >= 0)
+        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)
+
+      name = operation && operation.to_s.split('.').map { |part| Internal.camelize(part) }.join('.')
+      if name && !OPERATION_NAMES.include?(name)
+        raise Internal.invalid("Unknown operation #{operation.inspect}: use one of #{OPERATION_NAMES.join(', ')}")
+      end
+
+      @mock_lock.synchronize { @failures << { failure: failure, operation: name, details: details, retry_after: retry_after } }
+      self
     end
 
+    # @see ServerClient#ensure_lenses
+    def ensure_lenses(options) = operation('ensureLenses') { super }
+
+    # @see ServerClient#ensure_lens
+    def ensure_lens(options) = operation('ensureLens') { super }
+
     # Queues a JSON response for the next request.
     # @param status [Integer]
     # @param body [Object] encoded as JSON
@@ -93,18 +269,28 @@ module CalmLens
     end
 
     # Adds an event to the mock's events feed. Fields you omit (`id`, `projectId`, `createdAt`,
-    # `severity`, `title`, `facts`) are filled in.
+    # `severity`, `title`, `facts`, and nil `description` and `assetId`) are filled in. An event
+    # with the `asset_id` of a stored asset carries that asset's snapshot as it is now, unless you
+    # pass `asset`.
     # @param event [Hash] at least `type:`; snake_case keys are converted.
     # @return [Hash] the stored event
     def enqueue_event(event)
-      @mock_lock.synchronize { JSON.parse(JSON.generate(@fake.add_event(Internal.normalize(event)))) }
+      @mock_lock.synchronize { JSON.parse(JSON.generate(@fake.enqueue_event(Internal.normalize(event)))) }
     end
 
-    # @return [Array<Request>] copies of every request received so far, oldest first.
+    # @return [Array<Request>] copies of every request received since the mock was created or
+    #   {#clear_requests} last ran, oldest first.
     def requests
       @mock_lock.synchronize { @received.map { |request| Request.new(**Marshal.load(Marshal.dump(request.to_h))) } }
     end
 
+    # Forgets the requests recorded so far.
+    # @return [self]
+    def clear_requests
+      @mock_lock.synchronize { @received.clear }
+      self
+    end
+
     # @return [Integer] queued responses and errors not used yet.
     def remaining_responses
       @mock_lock.synchronize { @queue.size }
@@ -114,22 +300,79 @@ module CalmLens
 
     private
 
+    def not_found = APIError.class_for(404).new(ErrorCodes::ASSET_NOT_FOUND, 'Asset not found', status: 404)
+
+    # Wraps a resource's methods so requests know which call sent them, for {#fail_next_request}.
+    def track(resource, prefix, methods)
+      mock = self
+      resource.singleton_class.prepend(Module.new do
+        methods.each do |name|
+          define_method(name) do |*args, **options, &block|
+            mock.send(:operation, "#{prefix}.#{Internal.camelize(name)}") { super(*args, **options, &block) }
+          end
+        end
+      end)
+    end
+
+    # Runs a call; calls it makes (text.classify through assets.classify) count as the outer one.
+    def operation(name)
+      return yield if Thread.current[@call_key]
+
+      begin
+        Thread.current[@call_key] = { operation: name }
+        yield
+      ensure
+        Thread.current[@call_key] = nil
+      end
+    end
+
+    # The next queued failure for this request, which it uses up.
+    def failure_for(call)
+      index = @failures.index { |pending| pending[:operation].nil? || pending[:operation] == call&.dig(:operation) }
+      index && @failures.delete_at(index)
+    end
+
     # Returns the response rather than yielding it: the client accepts either from a transport.
     def receive(request, &)
       body = request.body.respond_to?(:read) ? read_stream(request.body) : request.body&.b
       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]
       @mock_lock.synchronize do
-        @received << Request.new(method: request.method, url: request.url, path: path.delete_prefix(base),
-                                 query: URI.decode_www_form(query.to_s).to_h, headers: request.headers.dup,
-                                 body: body)
-        queued = @queue.shift
-        raise queued if queued.is_a?(Exception)
-
-        queued || @fake.handle(request.method, request.url, request.headers, body)
+        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)
+        @received << record
+        response = answer(request, body, failure_for(call))
+        record.status = response.status
+        response
       end
     end
 
+    def answer(request, body, failure)
+      return fail_request(failure) if failure
+
+      queued = @queue.shift
+      raise queued if queued.is_a?(Exception)
+
+      queued || @fake.handle(request.method, request.url, request.headers, body)
+    end
+
+    # Each segment of a request path, percent-decoded.
+    def decode_path(path)
+      path.split('/', -1).map do |segment|
+        segment.b.gsub(/%(\h\h)/) { Regexp.last_match(1).hex.chr }.force_encoding(Encoding::UTF_8)
+      end.join('/')
+    end
+
+    def fail_request(pending)
+      failure = pending[:failure]
+      raise failure if failure.is_a?(Exception)
+      raise Errno::ECONNRESET, 'Simulated network failure' if failure == 'transport-error'
+      raise Net::ReadTimeout, 'Simulated timeout' if failure == 'timeout'
+
+      @fake.error(failure, details: pending[:details] && JSON.parse(JSON.generate(pending[:details])), retry_after: pending[:retry_after])
+    end
+
     def read_stream(io)
       buffer = String.new(encoding: Encoding::BINARY)
       while (chunk = io.read(64 * 1024))