x-uploads 1.0.0

data/lib/x/uploads/chunks.rb

@@ -0,0 +1,325 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require_relative "chunked_upload_failed"
+require_relative "json_classes"
+require_relative "missing_media_data"
+require_relative "multipart"
+require_relative "uploaded_media"
+require_relative "utils"
+require_relative "validator"
+
+module X
+  module Uploads
+    # Uploads a file in the chunks the X API requires for video and subtitles
+    #
+    # Internal to x-uploads: X::Uploads::MediaUpload calls it rather than mix its methods into itself, so a class that
+    # includes X::Uploads::MediaUpload gains none of them.
+    #
+    # @api private
+    module Chunks
+      extend self
+
+      # The message of the error raised for an initialize response that holds no media to append the chunks to
+      NO_MEDIA = "The response that initializes the upload holds no media to append the chunks to"
+      # The message of the error raised for a chunk that reads fewer bytes than the media held when it was measured
+      CHANGED = "%s held %d bytes when the upload was initialized, but chunk %d read %d of the %d it began with at " \
+        "byte %d: the media changed while it was uploaded"
+      # The fiber-local key x-core reads the guard it runs the save_tokens of a refresh inside from
+      REPORT_GUARD = :x_core_refresh_report_guard
+      private_constant :NO_MEDIA, :CHANGED, :REPORT_GUARD
+
+      # Raised in a worker to stop it, which the worker rescues to end at once
+      #
+      # It is not a StandardError, as Timeout::ExitException is not, so that a callback the client runs in the worker,
+      # as an on_response or a load_tokens that rescues the errors of its own store, cannot rescue it and let the upload
+      # go on after the call has ended, as Thread#kill, which cannot be rescued, did not.
+      class Stopped < Exception; end # rubocop:disable Lint/InheritException
+      private_constant :Stopped
+
+      # Upload media in chunks: initialize, append each chunk, and finalize
+      #
+      # MediaUpload.upload and MediaUpload.chunked_upload both upload with it, once each has checked its other
+      # arguments, so that upload calls no method a class that includes MediaUpload could define in place of its own.
+      # The chunk size is checked against the segments the API numbers before the upload is initialized.
+      #
+      # @api private
+      # @param client [Client] the X API client
+      # @param source [Source] the media
+      # @param media_type [String] the MIME type
+      # @param media_category [String] the media category
+      # @param chunk_size [Integer, nil] the chunk size in bytes, or nil for one derived from the size of the media
+      # @param concurrency [Integer] the number of chunks uploaded at once
+      # @param shared [Boolean, nil] whether the media is shared, or nil to send none
+      # @param additional_owners [Array<Integer, String>, nil] the identifiers of the users who may use the media, or
+      #   nil for none
+      # @return [UploadedMedia] the uploaded media, as the response that finalizes the upload describes it
+      # @raise [ArgumentError] if the chunk size would need more segments than the API numbers
+      # @raise [MissingMediaData] if the response that initializes the upload holds no media to append the chunks to
+      # @raise [ChunkedUploadFailed] if the upload is initialized, but a chunk cannot be appended, or it cannot be
+      #   finalized, or the response that finalizes it holds no media, with the media it initialized
+      # @example Upload a video in chunks
+      #   Uploads::Chunks.upload(client:, source:, media_type: "video/mp4", media_category: "tweet_video",
+      #     chunk_size: 4_194_304, concurrency: 4)
+      def upload(client:, source:, media_type:, media_category:, chunk_size:, concurrency:, shared:, additional_owners:)
+        chunk_size = Validator.validate_segments!(source, chunk_size)
+        media = init(client:, source:, media_type:, media_category:, shared:, additional_owners:)
+        ChunkedUploadFailed.__send__(:keeping, media) { complete(client:, source:, chunk_size:, media:, concurrency:) }
+      end
+
+      # Initialize a chunked upload
+      #
+      # The chunks that follow are appended to the media this returns, so a response that holds none, whether it has
+      # no body at all, a body without data, or data that names no media, raises here rather than leave the upload
+      # to fail on the first chunk, once the media it uploaded had been billed.
+      #
+      # @api private
+      # @param client [Client] the X API client
+      # @param source [Source] the media
+      # @param media_type [String] the MIME type
+      # @param media_category [String] the media category
+      # @param shared [Boolean, nil] whether the media is shared, or nil to send none
+      # @param additional_owners [Array<Integer, String>, nil] the identifiers of the users who may use the media, or
+      #   nil for none
+      # @return [Hash] the media the chunks are appended to
+      # @raise [MissingMediaData] if the response holds no media to append the chunks to
+      # @example Initialize the upload of a video
+      #   Uploads::Chunks.init(client:, source:, media_type: "video/mp4", media_category: "tweet_video")
+      def init(client:, source:, media_type:, media_category:, shared: nil, additional_owners: nil)
+        body = {media_type:, media_category:, total_bytes: source.size, shared:, additional_owners: additional_owners&.map(&:to_s)}.compact
+        response = client.post("media/upload/initialize", body, **JSON_CLASSES)
+        body = Utils.body_of(response)
+        media = body["data"]
+        raise MissingMediaData.new(NO_MEDIA, problems: Problem.all_from(body)) unless UploadedMedia.__send__(:documented?, media)
+
+        media
+      end
+
+      # Append the chunks of a file to a chunked upload, a few at a time
+      #
+      # Each worker reads its chunk from the media as it uploads it, so no more than concurrency chunks are held
+      # in memory at once. A chunk that fails stops the chunks not yet begun, and once the chunks already begun
+      # have finished, the first error is raised, unless save_tokens raised for the tokens of a refresh a chunk made,
+      # whose TokenReportFailed is raised in its place, whichever chunk failed first, since no other error holds the
+      # tokens. An exception raised in the caller while it waits, such as a timeout or an interrupt, stops every
+      # chunk, so that no thread goes on uploading once the caller has gone.
+      #
+      # @api private
+      # @param client [Client] the X API client
+      # @param source [Source] the media
+      # @param chunk_size [Integer] the chunk size in bytes
+      # @param media [Hash] the media object
+      # @param boundary [String] the multipart boundary
+      # @param concurrency [Integer] the number of chunks uploaded at once
+      # @return [void]
+      # @raise [TokenReportFailed] if save_tokens raises for the tokens of a refresh a chunk made, with the tokens
+      # @raise [StandardError] if a chunk fails otherwise, the error of the first that failed
+      # @example Append the chunks of a video
+      #   Uploads::Chunks.append(client:, source:, chunk_size: 4_194_304, media:, boundary:, concurrency: 4)
+      def append(client:, source:, chunk_size:, media:, boundary:, concurrency:)
+        queue = chunk_queue(source, chunk_size)
+        errors = Queue.new
+        media_id = media.fetch("id")
+        await([concurrency, queue.size].min, queue) { append_worker(queue, errors, client:, source:, chunk_size:, media_id:, boundary:) }
+        error = failure(errors)
+        raise error if error
+      end
+
+      # Append the chunks of a file to a chunked upload and finalize it
+      #
+      # @api private
+      # @param client [Client] the X API client
+      # @param source [Source] the media
+      # @param chunk_size [Integer] the chunk size in bytes
+      # @param media [Hash] the media the upload initialized
+      # @param concurrency [Integer] the number of chunks uploaded at once
+      # @return [UploadedMedia] the uploaded media, as the response that finalizes the upload describes it
+      # @raise [MissingMediaData] if the response that finalizes the upload holds no media or carries no body at all
+      # @example Upload the chunks of a video and finalize it
+      #   Uploads::Chunks.complete(client:, source:, chunk_size: 4_194_304, media:, concurrency: 4)
+      def complete(client:, source:, chunk_size:, media:, concurrency:)
+        append(client:, source:, chunk_size:, media:, boundary: SecureRandom.hex, concurrency:)
+        UploadedMedia.new(Utils.media_data(finalize(client:, media:), "that finalizes the upload"))
+      end
+
+      # Finalize a chunked upload, once its chunks are appended
+      #
+      # It is sent again after a server or network error, as a chunk is, rather than lose an upload whose every
+      # chunk was appended to a failure that may pass: the media can be finalized only by the upload that
+      # initialized it, which knows its identifier. A finalize the API acted on, but whose answer never arrived, may
+      # be refused when it is sent again, which raises as the failure it follows would have.
+      #
+      # @api private
+      # @param client [Client] the X API client
+      # @param media [Hash] the media the chunks were appended to
+      # @return [Hash, nil] the parsed response, or nil for a response that carries no body at all
+      # @example Finalize the upload of a video
+      #   Uploads::Chunks.finalize(client:, media: {"id" => "1880028106020515840"})
+      def finalize(client:, media:)
+        Utils.sending_again(client) { client.post("media/upload/#{media.fetch("id")}/finalize", **JSON_CLASSES) }
+      end
+
+      private
+
+      # Start the workers and wait for them, stopping them if the wait is cut short
+      #
+      # Every worker has finished when the wait ends on its own, so there is nothing left to stop. When an exception is
+      # raised in the waiting thread, the workers are stopped, which closes the connection of a request under way, and
+      # waited for, so that none outlives the call. A worker that is storing the tokens of a refresh it made finishes
+      # first, so that its save_tokens is not cut short, leaving the store with a refresh token X no longer accepts,
+      # while a timeout of its own still ends it. The workers are started inside the wait, so that one that cannot be
+      # started, as a thread the system refuses raises ThreadError, or an exception raised in the caller while they are
+      # started, stops those started before it as well.
+      #
+      # Each worker is started, and the workers are stopped, holding back an exception raised in the caller, which
+      # would otherwise leave a worker it struck as it was started, or as the others were stopped, uploading every
+      # chunk left. An exception a trap raises is not held back, so the chunks not yet begun are emptied first, and a
+      # worker it leaves unstopped ends once the chunk it began is uploaded. A worker reading a chunk from the media
+      # finishes reading it first, so that the file it reads is closed.
+      #
+      # @api private
+      # @param count [Integer] the number of workers to start
+      # @param queue [Thread::Queue] the index and offset of each chunk not yet begun
+      # @yieldreturn [Thread] a worker it started, a thread that uploads chunks
+      # @return [void]
+      def await(count, queue)
+        workers = [] #: Array[Thread]
+        begin
+          count.times { Thread.handle_interrupt(Object => :never) { workers << yield } }
+          workers.each(&:join)
+        ensure
+          Thread.handle_interrupt(Object => :never) { stop(workers, queue) }
+          workers.each(&:join)
+        end
+      end
+
+      # Empty the chunks not yet begun, then stop the workers
+      # @api private
+      # @param workers [Array<Thread>] the workers
+      # @param queue [Thread::Queue] the index and offset of each chunk not yet begun
+      # @return [void]
+      def stop(workers, queue)
+        queue.clear
+        workers.each { |worker| worker.raise(Stopped) }
+      end
+
+      # The error the chunks that failed raise, of those they recorded
+      #
+      # It is that of the first chunk that failed, unless save_tokens raised for the tokens of a refresh a chunk made:
+      # a TokenReportFailed is raised in place of any other error, since it alone holds tokens the store has yet to
+      # hold, and the last of them, if more than one refresh was made, since the refresh token of an earlier one is
+      # spent.
+      #
+      # @api private
+      # @param errors [Thread::Queue] the errors of failed chunks, in the order they failed
+      # @return [StandardError, nil] the error to raise, or nil if no chunk failed
+      def failure(errors)
+        failures = Array.new(errors.size) { errors.deq }
+        failures.reverse_each.find { |error| TokenReportFailed === error } || failures.first
+      end
+
+      # A closed queue of the index and byte offset of each chunk of the media, in order
+      # @api private
+      # @param source [Source] the media
+      # @param chunk_size [Integer] the chunk size in bytes
+      # @return [Thread::Queue] the queue
+      def chunk_queue(source, chunk_size)
+        queue = Queue.new
+        (0...source.size).step(chunk_size).each_with_index { |offset, index| queue << [index, offset] }
+        queue.close
+      end
+
+      # Start a thread that uploads chunks from a queue, emptying it if a chunk fails
+      #
+      # The thread is started holding every exception back, as a new thread holds back what the thread that starts it
+      # does, and takes them once it runs where it rescues Stopped, so that one stopped before it begins ends there
+      # rather than with Stopped, and a timeout of its own save_tokens still ends it.
+      #
+      # @api private
+      # @param queue [Thread::Queue] the index and offset of each chunk not yet begun
+      # @param errors [Thread::Queue] the errors of failed chunks, in the order they failed
+      # @param client [Client] the X API client
+      # @param source [Source] the media
+      # @param chunk_size [Integer] the chunk size in bytes
+      # @param media_id [String] the media ID
+      # @param boundary [String] the multipart boundary
+      # @return [Thread] the thread
+      def append_worker(queue, errors, client:, source:, chunk_size:, media_id:, boundary:)
+        Thread.new do
+          Thread.handle_interrupt(Object => :immediate) { append_chunks(queue, errors, client:, source:, chunk_size:, media_id:, boundary:) }
+        rescue Stopped
+          # A worker stopped before or between its requests ends as one stopped mid-request does
+        end
+      end
+
+      # Upload chunks from a queue until it is empty, emptying it if a chunk fails
+      # @api private
+      # @param queue [Thread::Queue] the index and offset of each chunk not yet begun
+      # @param errors [Thread::Queue] the errors of failed chunks, in the order they failed
+      # @param client [Client] the X API client
+      # @param source [Source] the media
+      # @param chunk_size [Integer] the chunk size in bytes
+      # @param media_id [String] the media ID
+      # @param boundary [String] the multipart boundary
+      # @return [void]
+      def append_chunks(queue, errors, client:, source:, chunk_size:, media_id:, boundary:)
+        Thread.current[REPORT_GUARD] = method(:saving)
+        while (index, offset = queue.deq)
+          upload_body = Multipart.body("media", chunk(source, chunk_size, index, offset), boundary:, segment_index: index)
+          upload_chunk(client:, media_id:, upload_body:, headers: Multipart.headers(boundary))
+        end
+      rescue => e
+        errors << e
+        queue.clear
+      end
+
+      # Run the save_tokens of a worker, holding a stop back until it returns
+      # @api private
+      # @yield passes the tokens of the refresh to save_tokens
+      # @return [Object] what the block returns
+      def saving(&) = Thread.handle_interrupt(Stopped => :never, &)
+
+      # Read a chunk of the media, of the bytes the upload declared it holds
+      #
+      # The size of the media is read once, so every chunk is read within the bytes the upload was initialized with,
+      # and a file that grows while it is uploaded appends none of what it grew by. A file that shrinks cannot fill
+      # the chunks it was measured for, so a chunk that reads short raises, rather than append fewer bytes than the
+      # upload declared.
+      #
+      # A stop of the worker is held back until the chunk is read. Ruby raises an exception raised in a thread once
+      # the file is opened, before anything holds the handle to close it, so a worker stopped as it opened the file
+      # would leave it open for as long as the process ran, and a file left open cannot be deleted on Windows.
+      #
+      # @api private
+      # @param source [Source] the media
+      # @param chunk_size [Integer] the chunk size in bytes
+      # @param index [Integer] the index of the chunk
+      # @param offset [Integer] the byte the chunk begins at
+      # @return [String] the bytes of the chunk
+      # @raise [EOFError] if the media holds fewer bytes than it did when it was measured
+      def chunk(source, chunk_size, index, offset)
+        length = [chunk_size, source.size - offset].min
+        bytes = Thread.handle_interrupt(Stopped => :never) { source.read(length, offset) }.to_s
+        return bytes if bytes.bytesize.eql?(length)
+
+        raise EOFError, format(CHANGED, source.description, source.size, index, bytes.bytesize, length, offset)
+      end
+
+      # Upload a single chunk, sending it again after a server or network error
+      #
+      # A chunk names the segment it is appended at, so one sent twice is appended once, and it is sent again as
+      # {Utils.sending_again} sends a request again.
+      #
+      # @api private
+      # @param client [Client] the X API client
+      # @param media_id [String] the media ID
+      # @param upload_body [String] the upload body
+      # @param headers [Hash] the request headers
+      # @return [void]
+      def upload_chunk(client:, media_id:, upload_body:, headers:)
+        Utils.sending_again(client) { client.post("media/upload/#{media_id}/append", upload_body, headers:, **JSON_CLASSES) }
+      end
+    end
+    private_constant :Chunks
+  end
+end

data/lib/x/uploads/error.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "x/core"
+
+module X
+  module Uploads
+    # Base error class for the failures of an upload, which every error x-uploads raises of its own descends from
+    #
+    # It descends from X::Error, so that rescuing the errors of the X API catches an upload failure as it did before.
+    # The errors that descend from it are named directly under X, as the errors of x-core are, so that this is the
+    # one name under X::Uploads a rescue reaches for.
+    #
+    # It catches the errors x-uploads raises of its own: media the API would refuse, raised before any request, and
+    # the failures after media was uploaded, which hold the media. It does not catch the X::Error of a request the
+    # API refused, or that got no response, before there was media to hold, such as the X::BadRequest of the request
+    # that initializes an upload, or of an image sent in a single request, nor an ArgumentError, which is not an
+    # X::Error: that of a mistake in the arguments of a call, and the one a request raises when the client was given
+    # no proxy_url and the proxy the environment names cannot be parsed, or is not an http or https URL with a host.
+    # Rescue X::Error to catch every failure of an
+    # upload but those.
+    #
+    # @api public
+    class Error < X::Error; end
+  end
+end

data/lib/x/uploads/gif.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative "source"
+
+module X
+  module Uploads
+    # Tells an animated GIF from a still one by reading its blocks, without decoding any image
+    #
+    # Internal to x-uploads: an upload tells with it whether a GIF is processed as a GIF or as an image, which X
+    # decides, so that it can change within 1.x as X does.
+    #
+    # @api private
+    module Gif
+      extend self
+
+      # Size in bytes of the header and logical screen descriptor
+      HEADER_SIZE = 13
+      # Byte that introduces an extension block
+      EXTENSION_INTRODUCER = 0x21
+      # Byte that introduces an image
+      IMAGE_SEPARATOR = 0x2C
+      # Size in bytes of an image descriptor, counting its separator
+      IMAGE_DESCRIPTOR_SIZE = 10
+      private_constant :HEADER_SIZE, :EXTENSION_INTRODUCER, :IMAGE_SEPARATOR, :IMAGE_DESCRIPTOR_SIZE
+
+      # Check whether a GIF holds more than one frame
+      #
+      # The GIF is read whole, so an upload asks it only of a GIF no larger than the API takes, which is 15 megabytes.
+      #
+      # @api private
+      # @param media [String, Pathname, IO, StringIO] the path to the GIF, or an IO open on it
+      # @return [Boolean] true if the GIF has a second frame
+      # @example Check whether a GIF is animated
+      #   Uploads::Gif.animated?("cat.gif") # => true
+      def animated?(media)
+        data = Source.for(media).content
+        position = skip_color_table(HEADER_SIZE, data.getbyte(10).to_i)
+        frames = 0
+        while (block = data.getbyte(position))
+          frames += 1 if block.eql?(IMAGE_SEPARATOR)
+          return true if frames > 1
+
+          position = after_block(data, position, block)
+        end
+        false
+      end
+
+      private
+
+      # The position after a block, or the end of the data after the last block
+      # @api private
+      # @param data [String] the GIF data
+      # @param position [Integer] the position of the block
+      # @param block [Integer] the byte that introduces the block
+      # @return [Integer] the position after the block
+      def after_block(data, position, block)
+        case block
+        when EXTENSION_INTRODUCER then skip_sub_blocks(data, position + 2)
+        when IMAGE_SEPARATOR
+          skip_sub_blocks(data, skip_color_table(position + IMAGE_DESCRIPTOR_SIZE, data.getbyte(position + 9).to_i) + 1)
+        else data.bytesize
+        end
+      end
+
+      # The position after a color table, if the flags say one follows
+      # @api private
+      # @param position [Integer] the position where a color table would start
+      # @param flags [Integer] the packed flags of the descriptor, zero when the data ends before them
+      # @return [Integer] the position after the color table
+      def skip_color_table(position, flags)
+        flags.anybits?(0x80) ? position + (3 << ((flags & 7) + 1)) : position
+      end
+
+      # The position after a run of data sub-blocks and its terminator
+      # @api private
+      # @param data [String] the GIF data
+      # @param position [Integer] the position of the first sub-block
+      # @return [Integer] the position after the terminator
+      def skip_sub_blocks(data, position)
+        while (size = data.getbyte(position).to_i).positive?
+          position += size + 1
+        end
+        position + 1
+      end
+    end
+    private_constant :Gif
+  end
+end

data/lib/x/uploads/invalid_media.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "error"
+
+module X
+  # Raised for media the API would refuse, before any request: a file that does not exist, and media that cannot be
+  # read, holds nothing, or is larger than the API takes
+  #
+  # The media of an upload is often given by a user, so it is told apart from a mistake in the arguments of a call,
+  # such as a media category that does not exist, which raises ArgumentError: code that uploads what a user gives
+  # rescues this, and X::InvalidMediaType, which descends from it, for media of a type the API does not take, without
+  # rescuing the ArgumentError of its own mistakes. One whose cause is an error of the system, such as Errno::EMFILE
+  # or Errno::EIO, says the machine could not read the media, not that the media is wrong.
+  #
+  # It descends from X::Uploads::Error, and so from X::Error, so rescuing the failures of an upload catches it.
+  #
+  # @api public
+  class InvalidMedia < Uploads::Error; end
+end

data/lib/x/uploads/invalid_media_type.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "invalid_media"
+
+module X
+  # Error raised when a file's MIME type cannot be determined or is unsupported
+  #
+  # It descends from X::InvalidMedia, so rescuing media the API would refuse catches it.
+  #
+  # @api public
+  class InvalidMediaType < InvalidMedia; end
+end

data/lib/x/uploads/json_classes.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module X
+  module Uploads
+    # The classes the uploaders parse responses into, whatever parsing classes a client defaults to
+    #
+    # The uploaders read the responses they receive, and return them, as Hashes and Arrays, so a client whose
+    # default_object_class is another class, such as OpenStruct, still uploads.
+    #
+    # @api private
+    JSON_CLASSES = {array_class: Array, object_class: Hash}.freeze
+    private_constant :JSON_CLASSES
+  end
+end

data/lib/x/uploads/media_processing_check_failed.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "timeout"
+require_relative "error"
+require_relative "uploaded_media"
+require_relative "media_processing_timeout"
+
+module X
+  # Error raised when media is uploaded, but a check of its processing fails
+  #
+  # An upload awaits the processing of media X processes, such as a video, once the media is uploaded,
+  # so the media is not lost to a check that fails, as one the API answers with a server error, or one the
+  # on_response hook of the client raises: the error holds the media, which can be awaited again with
+  # await_processing. The error that failed the check is the cause, whose
+  # message the message ends with. A TokenReportFailed, which a check raises when save_tokens raised for the tokens of
+  # a refresh it made, is raised as it is, rather than as this error, so that the rescue of it that stores the tokens
+  # it holds catches it around an upload as around any other request.
+  #
+  # @api public
+  class MediaProcessingCheckFailed < Uploads::Error
+    # Await processing, raising this error, which holds the media, if a check fails
+    #
+    # Internal to x-uploads: an upload awaits the processing of the media it uploaded through it, and calls it with
+    # __send__, since it is private. A MediaProcessingTimeout, which holds the media itself, a Timeout::Error, as
+    # Timeout.timeout raises around the upload, a TokenReportFailed, which holds the tokens of a refresh that
+    # save_tokens raised for, and an exception that is not a StandardError, such as an Interrupt, are raised as they
+    # are.
+    #
+    # @api private
+    # @param media [UploadedMedia] the uploaded media
+    # @yield awaits the processing
+    # @return [Object] what the block returns
+    # @raise [MediaProcessingCheckFailed] if the block raises a StandardError other than a MediaProcessingTimeout, a
+    #   Timeout::Error, or a TokenReportFailed, such as an error of the X API
+    # @raise [TokenReportFailed] if save_tokens raises for the tokens of a refresh the block made, with the tokens
+    # @raise [MediaProcessingTimeout] if the media is still processing once the processing timeout would pass
+    # @example Await the processing of an upload, keeping the media if a check fails
+    #   X::MediaProcessingCheckFailed.__send__(:keeping, media) { Uploads::MediaUpload.await_processing(media, client:) }
+    def self.keeping(media)
+      yield
+    rescue MediaProcessingTimeout, Timeout::Error, TokenReportFailed
+      raise
+    rescue
+      raise new(media:)
+    end
+    private_class_method :keeping
+
+    # The media that was uploaded, as the upload response describes it
+    # @api public
+    # @return [UploadedMedia, nil] the uploaded media, or nil if none was given
+    # @example Await the processing of the media again later
+    #   rescue X::MediaProcessingCheckFailed => e
+    #     client.await_media_processing(e.media)
+    attr_reader :media
+
+    # Initialize the error with the media that was uploaded
+    #
+    # The message is the one given, or else names the media by its identifier, when media that holds one was given.
+    #
+    # @api public
+    # @param message [String, nil] the message, or nil for one that names the media
+    # @param media [UploadedMedia, Hash{String => Object}, nil] the media that was uploaded, a Hash of which is held as
+    #   uploaded media
+    # @return [MediaProcessingCheckFailed] a new error
+    # @example Raise the error for media whose processing could not be checked
+    #   raise X::MediaProcessingCheckFailed.new(media: media)
+    # @example Raise the error with a message of its own, as a test stub may
+    #   raise X::MediaProcessingCheckFailed, "Processing could not be checked"
+    def initialize(message = nil, media: nil)
+      @media = media.is_a?(Hash) ? UploadedMedia.new(media) : media
+      super(message || ["Media", media&.[]("id"), "was uploaded, but its processing could not be checked"].compact.join(" "))
+    end
+
+    # The message, ending with why the processing could not be checked
+    #
+    # It ends with the message of the error that failed the check, which is the cause, if there is one, whether the
+    # message was given or named the media.
+    #
+    # @api public
+    # @return [String] the message
+    # @example Read why the processing could not be checked
+    #   error.message # => "Media 7 was uploaded, but its processing could not be checked: Service Unavailable"
+    def to_s = [super, cause&.message].compact.join(": ")
+  end
+end

data/lib/x/uploads/media_processing_failed.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "error"
+require_relative "uploaded_media"
+
+module X
+  # Error raised when X fails to process uploaded media, such as a video it cannot decode
+  # @api public
+  class MediaProcessingFailed < Uploads::Error
+    # The message of a failure X gives no reason for
+    DEFAULT_MESSAGE = "Media processing failed"
+    private_constant :DEFAULT_MESSAGE
+
+    # The uploaded media, as the processing status X reported describes it
+    #
+    # Its processing_info holds the state X reported, and the error, when X reported one.
+    #
+    # @api public
+    # @return [UploadedMedia, nil] the media, which reads as a Hash, or nil if none was given
+    # @example Read the state X reported
+    #   error.media.state # => "failed"
+    attr_reader :media
+
+    # Initialize the error with the reason X gives for the failure
+    #
+    # The message is the one given, or else the reason the processing status holds, or else "Media processing
+    # failed".
+    #
+    # @api public
+    # @param message [String, nil] the message, or nil for the reason the processing status holds
+    # @param media [UploadedMedia, Hash{String => Object}, nil] the media, as the processing status X reported
+    #   describes it, a Hash of which is held as uploaded media
+    # @return [MediaProcessingFailed] a new error
+    # @example Raise the error for a failed status
+    #   raise X::MediaProcessingFailed.new(media: status)
+    # @example Raise the error with a message of its own, as a test stub may
+    #   raise X::MediaProcessingFailed, "Unsupported video format"
+    def initialize(message = nil, media: nil)
+      @media = media.is_a?(Hash) ? UploadedMedia.new(media) : media
+      super(message || media&.dig("processing_info", "error", "message") || DEFAULT_MESSAGE)
+    end
+  end
+end