x-uploads 1.0.0

data/lib/x/uploads/metadata.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "x/core"
+require_relative "json_classes"
+require_relative "missing_media_data"
+require_relative "utils"
+require_relative "validator"
+
+module X
+  module Uploads
+    # Describes uploaded media with alt text, and uploaded videos with subtitles
+    # @api public
+    module Metadata
+      extend self
+
+      # The media category of a video attached to a post, which subtitles default to, named as the uploaders name it
+      SUBTITLED_MEDIA_CATEGORY = "tweet_video"
+      private_constant :SUBTITLED_MEDIA_CATEGORY
+
+      # Describe uploaded media with alt text, for people who cannot see it
+      #
+      # Alt text added twice is added once, so it is sent again after a server or network error, up to the
+      # max_retries of the client, even after a timeout, which a client sends no read again after: X bills a metadata
+      # request each time it is sent, so one whose answer was lost may be billed twice.
+      #
+      # It returns the media it described, as uploaded media, so that a call can be chained to the upload it
+      # describes. The response holds nothing more than the media identifier and the alt text that was sent.
+      #
+      # @api public
+      # @param media [UploadedMedia, Hash, #media_key, String, Integer] the uploaded media, media that has a media key,
+      #   such as X::Media, the media key, or the media identifier
+      # @param text [String] the alt text, of 1 to 1,000 characters
+      # @param client [Client] the X API client
+      # @return [UploadedMedia] the media given, if it is uploaded media, or else uploaded media built from the upload
+      #   response, the media key, or the media identifier given
+      # @raise [ArgumentError] if the alt text is empty or longer than the API takes, before a request
+      # @raise [ArgumentError] if the media given is nil, holds no identifier, or is neither media, a media key, nor a
+      #   media identifier, or its media key names none
+      # @raise [ArgumentError] if the client was given no proxy_url and the proxy the environment names for the request
+      #   cannot be parsed, or is not an http or https URL with a host, with a message that names the variables read and
+      #   leaves out the value
+      # @raise [MissingMediaData] if the response holds no metadata or carries no body at all
+      # @example Describe an uploaded image
+      #   Uploads::Metadata.add_alt_text(media, "A cat asleep on a keyboard", client: client)
+      # @example Describe an image as it is uploaded, and attach it to a post
+      #   media = Uploads::Metadata.add_alt_text(Uploads::MediaUpload.upload("cat.jpg", client:), "A cat", client:)
+      #   client.post("tweets", {text: "Look at this cat", media: {media_ids: [media.media_id.to_s]}})
+      def add_alt_text(media, text, client:)
+        Validator.validate_alt_text!(text)
+        body = {id: Utils.media_id(media), metadata: {alt_text: {text:}}}
+        Utils.described(Utils.sending_again(client) { client.post("media/metadata", body, **JSON_CLASSES) }, media)
+      end
+
+      # Attach uploaded subtitles to an uploaded video
+      #
+      # Subtitles attached twice are attached once, as the track of their language, so they are sent again after a
+      # server or network error, as alt text is, up to the max_retries of the client.
+      #
+      # It returns the video it subtitled, as uploaded media, so that a call can be chained to the upload of the
+      # video. The response holds nothing more than the identifiers, the category, and the track that were sent.
+      #
+      # @api public
+      # @param video [UploadedMedia, Hash, #media_key, String, Integer] the uploaded video, media that has a media
+      #   key, such as X::Media, or its media identifier
+      # @param subtitles [UploadedMedia, Hash, #media_key, String, Integer] the uploaded .srt or .vtt file, media
+      #   that has a media key, or its media identifier
+      # @param language_code [String] the two-letter language code of the subtitles, in any case, such as EN
+      # @param client [Client] the X API client
+      # @param display_name [String, nil] the name of the language shown to viewers, such as English
+      # @param media_category [String, Symbol] the category the video was uploaded as, tweet_video, the default, or
+      #   amplify_video, in any case, as the uploaders take it, or as the subtitles endpoint names it, TweetVideo or
+      #   AmplifyVideo
+      # @return [UploadedMedia] the video given, if it is uploaded media, or else uploaded media built from the upload
+      #   response, the media key, or the media identifier given
+      # @raise [ArgumentError] if the media category is neither tweet_video nor amplify_video, or the language code is
+      #   not two letters
+      # @raise [ArgumentError] if the video or the subtitles are nil, hold no identifier, are neither media, a media
+      #   key, nor a media identifier, have a media key that names none, or an identifier the API does not take
+      # @raise [ArgumentError] if the client was given no proxy_url and the proxy the environment names for the request
+      #   cannot be parsed, or is not an http or https URL with a host, with a message that names the variables read and
+      #   leaves out the value
+      # @raise [MissingMediaData] if the response holds no metadata or carries no body at all
+      # @example Upload a video and its English subtitles
+      #   video = Uploads::MediaUpload.upload("cat.mp4", client: client)
+      #   subtitles = Uploads::MediaUpload.upload("cat.srt", client: client)
+      #   Uploads::Metadata.add_subtitles(video, subtitles, "EN", client: client, display_name: "English")
+      # @example Subtitle an Amplify video
+      #   video = Uploads::MediaUpload.upload("cat.mp4", client: client, media_category: :amplify_video)
+      #   Uploads::Metadata.add_subtitles(video, subtitles, "EN", client: client, media_category: :amplify_video)
+      def add_subtitles(video, subtitles, language_code, client:, display_name: nil, media_category: SUBTITLED_MEDIA_CATEGORY)
+        track = {id: Utils.media_id(subtitles), language_code: Validator.validate_language_code!(language_code), display_name:}.compact
+        body = {id: Utils.media_id(video), media_category: Utils.subtitled_media_category(media_category), subtitles: track}
+        Utils.described(Utils.sending_again(client) { client.post("media/subtitles", body, **JSON_CLASSES) }, video)
+      end
+    end
+  end
+end

data/lib/x/uploads/missing_media_data.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "x/core"
+require_relative "error"
+
+module X
+  # Raised when a response of an upload holds none of the data it describes the media with
+  #
+  # The API answers an upload, a status check, and a change of metadata with what it acted on, under the data of
+  # the response. A response that succeeded without it holds nothing an upload can go on, so the uploaders raise
+  # this rather than fail later on what is missing. So does one whose media is not what the API documents, such as an
+  # identifier that is not one, or processing information of another type, as a gateway in front of the API might
+  # answer with, rather than fail as it is read. A response that holds problems in place of the data, as one for
+  # media X does not know of does, names the reason in them, which the error holds, and names in its message.
+  #
+  # It descends from X::Uploads::Error, and so from X::Error, so rescuing the failures of an upload catches it.
+  #
+  # @api public
+  class MissingMediaData < Uploads::Error
+    # The problems the response reported in place of the data
+    # @api public
+    # @return [Array<Problem>] the problems, frozen, empty for a response that reported none
+    # @example Tell media X does not know of
+    #   error.problems.any?(&:not_found?)
+    attr_reader :problems
+
+    # Initialize the error with the reason X gave for holding no data
+    #
+    # The message is the one given, then the detail, or else the message or the title, of the first problem the
+    # response reported, as "The response of the status check holds no media: Could not find media".
+    #
+    # @api public
+    # @param message [String, nil] the message, or nil for the reason alone
+    # @param problems [Array<Problem>] the problems the response reported in place of the data
+    # @return [MissingMediaData] a new error
+    # @example Raise the error for a response that holds problems in place of media
+    #   raise X::MissingMediaData.new("The response holds no media", problems: X::Problem.all_from(response))
+    # @example Raise the error with a message alone, as a test stub may
+    #   raise X::MissingMediaData, "The response holds no media"
+    def initialize(message = nil, problems: [])
+      @problems = problems.dup.freeze
+      reason = problems.first&.then { |problem| problem.detail || problem.message || problem.title }
+      parts = [message, reason].compact
+      super((parts.join(": ") unless parts.empty?))
+    end
+  end
+end

data/lib/x/uploads/multipart.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require_relative "json_classes"
+
+module X
+  module Uploads
+    # Builds the multipart form requests of the uploads
+    #
+    # Internal to x-uploads: the uploaders call it rather than mix its methods into themselves, so a class that
+    # includes an uploader gains none of them.
+    #
+    # @api private
+    module Multipart
+      extend self
+
+      # The headers of a multipart form request
+      #
+      # @api private
+      # @param boundary [String] the multipart boundary
+      # @return [Hash{String => String}] the content type, which names the boundary
+      # @example The headers of a request
+      #   Uploads::Multipart.headers("boundary") # => {"Content-Type" => "multipart/form-data; boundary=boundary"}
+      def headers(boundary) = {"Content-Type" => "multipart/form-data; boundary=#{boundary}"}
+
+      # Post a multipart form request, with a boundary of its own
+      #
+      # @api private
+      # @param client [Client] the X API client
+      # @param url [String] the endpoint, relative to the base URL of the client
+      # @param name [String] the name of the field that holds the content
+      # @param content [String] the content to upload
+      # @param fields [Hash{Symbol => Object}] the form fields that come before the content, less any that are nil
+      # @return [Hash, nil] the parsed response, or nil for a response with no body
+      # @example Update a profile image
+      #   Uploads::Multipart.post(client, "../1.1/account/update_profile_image.json", "image", png)
+      def post(client, url, name, content, **fields)
+        boundary = SecureRandom.hex
+        client.post(url, body(name, content, boundary:, **fields), headers: headers(boundary), **JSON_CLASSES)
+      end
+
+      # The body of a multipart form request: any form fields, then the content uploaded
+      #
+      # @api private
+      # @param name [String] the name of the field that holds the content
+      # @param content [String] the content to upload
+      # @param boundary [String] the multipart boundary
+      # @param fields [Hash{Symbol => Object}] the form fields that come before the content, less any that are nil
+      # @return [String] the multipart body
+      # @example The body of one chunk of a video
+      #   Uploads::Multipart.body("media", chunk, boundary: "boundary", segment_index: 0)
+      def body(name, content, boundary:, **fields)
+        fields.compact.map { |field, value| "--#{boundary}\r\nContent-Disposition: form-data; name=\"#{field}\"\r\n\r\n#{value}\r\n" }.join +
+          "--#{boundary}\r\n" \
+          "Content-Disposition: form-data; name=\"#{name}\"\r\n" \
+          "Content-Type: application/octet-stream\r\n\r\n" \
+          "#{content}\r\n" \
+          "--#{boundary}--\r\n"
+      end
+    end
+    private_constant :Multipart
+  end
+end

data/lib/x/uploads/signature.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module X
+  module Uploads
+    # Reads the media type of media from the bytes it begins with
+    #
+    # Media is typed by its signature, the bytes every file of a type begins with, before the name of its file, so
+    # that a file named as what it is not is typed as what it is. Only a type the API documents for an upload of a
+    # media category it documents is read, so a glTF 3D model, which no category takes, is not among them, and only
+    # one whose signature names it on its own, so SubRip subtitles, which begin with nothing a text file could not,
+    # are not among them either.
+    #
+    # Internal to x-uploads: X::Uploads::MediaUpload reads a signature with it.
+    #
+    # @api private
+    module Signature
+      extend self
+
+      # The brands an MP4 video names after the box type it begins with, which files of other types share with it: a
+      # HEIF or AVIF image, and M4A audio, begin with that box type too, and name a brand of their own. The 3GPP and
+      # 3GPP2 videos of phones, and the F4V, XAVC, and mobile MP4 videos of cameras and encoders, are MP4 files that
+      # name a brand of their own too.
+      MP4_BRANDS = ["isom", "iso2", "iso3", "iso4", "iso5", "iso6", "iso7", "iso8", "iso9", "mp41", "mp42", "avc1", "M4V ",
+        "M4VH", "M4VP", "dash", "MSNV", "3gp4", "3gp5", "3gp6", "3g2a", "f4v ", "XAVC", "mmp4"].freeze
+
+      # The media type each signature names, by the bytes that must appear at each offset, most specific first,
+      # since the first signature that matches names the type: the brand of a QuickTime file or an MP4 video follows
+      # the box type the two share, a WebP file is a RIFF file whose form is named eight bytes in, and an MPEG transport
+      # stream, which begins with no header, is one whose first packets each begin with its sync byte, which a
+      # transport stream of 188-byte packets begins with and one of the 192-byte packets of an M2TS file holds four
+      # bytes in, after a timestamp. A signature of
+      # bytes above ASCII is packed from them, since a String literal of those bytes is not the UTF-8 this file is.
+      SIGNATURES = {
+        {0 => "GIF87a".b} => "image/gif",
+        {0 => "GIF89a".b} => "image/gif",
+        {0 => [0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A].pack("C*")} => "image/png", # \x89PNG\r\n\x1A\n
+        {0 => [0xFF, 0xD8, 0xFF].pack("C*")} => "image/jpeg",
+        {0 => "BM".b} => "image/bmp",
+        {0 => "II*\x00".b} => "image/tiff",
+        {0 => "MM\x00*".b} => "image/tiff",
+        {0 => "RIFF".b, 8 => "WEBP".b} => "image/webp",
+        {4 => "ftypqt  ".b} => "video/quicktime",
+        **MP4_BRANDS.to_h { |brand| [{4 => "ftyp#{brand}".b}, "video/mp4"] },
+        {0 => [0xEF, 0xBB, 0xBF].pack("C*") + "WEBVTT"} => "text/vtt", # a byte order mark before the header
+        {0 => "WEBVTT".b} => "text/vtt",
+        {0 => "G".b, 188 => "G".b, 376 => "G".b} => "video/mp2t",
+        {4 => "G".b, 196 => "G".b, 388 => "G".b} => "video/mp2t"
+      }.freeze
+
+      # The bytes of the EBML header a Matroska file begins with, which a WebM file, being Matroska, begins with too
+      EBML = [0x1A, 0x45, 0xDF, 0xA3].pack("C*")
+      # The DocType element of the EBML header of a WebM file: its identifier, the length of its value, and "webm", which
+      # a Matroska file that is not WebM names "matroska" in place of. The header is the first thing in the file, so
+      # its DocType is among the bytes a signature is read from.
+      WEBM_DOC_TYPE = [0x42, 0x82, 0x84].pack("C*") + "webm".b
+      private_constant :MP4_BRANDS, :SIGNATURES, :EBML, :WEBM_DOC_TYPE
+
+      # The media type the signature of media names
+      #
+      # A Matroska file is WebM, which the API documents, only when its EBML header names webm as its DocType; the API
+      # documents no type for any other Matroska file, such as an .mkv video, so its signature names none.
+      #
+      # @api private
+      # @param bytes [String] the bytes the media begins with, as {Source#sniff} reads them
+      # @return [String, nil] the media type, or nil if no signature names one
+      # @example Read the media type of a PNG image
+      #   Uploads::Signature.media_type("\x89PNG\r\n\x1A\n".b) # => "image/png"
+      def media_type(bytes)
+        return matroska_type(bytes) if matroska?(bytes)
+
+        SIGNATURES.find { |magic, _| matches?(bytes, magic) }&.last
+      end
+
+      # Whether media begins with the EBML header of Matroska
+      #
+      # WebM is Matroska, so a WebM file begins with it too.
+      #
+      # @api private
+      # @param bytes [String] the bytes the media begins with, as {Source#sniff} reads them
+      # @return [Boolean] true if the media is Matroska
+      # @example Tell a Matroska file
+      #   Uploads::Signature.matroska?("\x1A\x45\xDF\xA3...".b) # => true
+      def matroska?(bytes) = bytes.start_with?(EBML)
+
+      private
+
+      # The media type of a Matroska file, which is WebM when its DocType is webm
+      # @api private
+      # @param bytes [String] the bytes the media begins with, an EBML header first
+      # @return [String, nil] video/webm, or nil for a Matroska file that is not WebM
+      def matroska_type(bytes) = ("video/webm" if bytes.include?(WEBM_DOC_TYPE))
+
+      # Whether media begins with the bytes of a signature
+      # @api private
+      # @param bytes [String] the bytes the media begins with
+      # @param magic [Hash{Integer => String}] the bytes the signature expects at each offset
+      # @return [Boolean] true if the media matches the signature
+      def matches?(bytes, magic)
+        magic.all? { |offset, expected| bytes.byteslice(offset, expected.bytesize).eql?(expected) }
+      end
+    end
+    private_constant :Signature
+  end
+end