fileboy 0.2.0 → 0.3.0

data/lib/fileboy/file_data.rb

@@ -2,10 +2,13 @@ require "time"
 
 module Fileboy
   # The details of one stored file, as returned by an upload, `fetch_file_data` or the management calls.
-  # `labels` lists the labels pointing at the file and is only filled by the management calls.
+  # `labels` lists the labels pointing at the file and `share_page` says whether its share page
+  # (https://fileboy.io/f/{id}) is on. Both are only filled by the management calls.
+  # `folder_id` and `folder_path` (like "/Products/Shoes") say which folder the file is in, and
+  # are nil at the root. Uploads and the management calls fill them in.
   FileData = Struct.new(
     :id, :name, :original_filename, :mime, :metadata, :file_size, :content_hash, :signed,
-    :dies_at, :created_at, :labels,
+    :dies_at, :created_at, :labels, :folder_id, :folder_path, :share_page,
     keyword_init: true
   ) do
     # Build from the `data` object of an API response.
@@ -21,19 +24,34 @@ module Fileboy
         signed: data["signed"],
         dies_at: parse_time(data["diesAt"]),
         created_at: parse_time(data["createdAt"]),
-        labels: data["labels"] || []
+        labels: data["labels"] || [],
+        folder_id: data["folderId"],
+        folder_path: data["folderPath"],
+        share_page: data["sharePage"] == true
       )
     end
 
     def self.parse_time(value)
       value.nil? || value == "" ? nil : Time.parse(value)
     end
+
+    # The strings of a JSON list, [] for anything else.
+    def self.string_list(value)
+      value.is_a?(Array) ? value.select { |v| v.is_a?(String) } : []
+    end
+
+    # The string values of a JSON object, {} for anything else.
+    def self.string_map(value)
+      value.is_a?(Hash) ? value.select { |_k, v| v.is_a?(String) } : {}
+    end
   end
 
   # The details of one video, as returned by `upload_video`.
-  Video = Struct.new(:id, :name, :raw_file_id, keyword_init: true) do
+  Video = Struct.new(:id, :name, :raw_file_id, :description, :tags, :metadata, keyword_init: true) do
     def self.from_api(data)
-      new(id: data["id"], name: data["name"], raw_file_id: data["rawFileId"])
+      new(id: data["id"], name: data["name"], raw_file_id: data["rawFileId"],
+          description: data["description"] || "", tags: FileData.string_list(data["tags"]),
+          metadata: FileData.string_map(data["metadata"]))
     end
   end
 
@@ -68,7 +86,7 @@ module Fileboy
   # "failed". `urls` is nil until ready, else a hash with :manifest, :hls, :dash and :poster.
   ManagedVideo = Struct.new(
     :id, :name, :created_at, :status, :status_message, :duration, :width, :height, :play_count,
-    :last_played_at, :urls,
+    :last_played_at, :urls, :description, :tags, :metadata,
     keyword_init: true
   ) do
     def self.from_api(data)
@@ -78,7 +96,9 @@ module Fileboy
         status: data["status"], status_message: data["statusMessage"], duration: data["duration"],
         width: data["width"], height: data["height"], play_count: data["playCount"],
         last_played_at: FileData.parse_time(data["lastPlayedAt"]),
-        urls: urls && urls.each_with_object({}) { |(k, v), memo| memo[k.to_sym] = v }
+        urls: urls && urls.each_with_object({}) { |(k, v), memo| memo[k.to_sym] = v },
+        description: data["description"] || "", tags: FileData.string_list(data["tags"]),
+        metadata: FileData.string_map(data["metadata"])
       )
     end
   end
@@ -91,6 +111,73 @@ module Fileboy
     end
   end
 
+  # A folder. `path` is where it is, like "/Products/Shoes", and `parent_id` is nil at the root.
+  # `file_count` and `folder_count` count what is directly inside it. `ancestors` are the folders
+  # above it from the top, as {FolderRef}s, and are only filled in when one folder is fetched,
+  # created or updated (nil in lists).
+  Folder = Struct.new(
+    :id, :name, :path, :parent_id, :file_count, :folder_count, :created_at, :ancestors,
+    keyword_init: true
+  ) do
+    def self.from_api(data)
+      ancestors = data["ancestors"]
+      new(
+        id: data["id"], name: data["name"], path: data["path"], parent_id: data["parentId"],
+        file_count: data["fileCount"] || 0, folder_count: data["folderCount"] || 0,
+        created_at: FileData.parse_time(data["createdAt"]),
+        ancestors: ancestors&.map { |a| FolderRef.new(id: a["id"], name: a["name"]) }
+      )
+    end
+  end
+  FolderRef = Struct.new(:id, :name, keyword_init: true)
+
+  # The result of `move_files`. `folder` is the {Folder} the files are in now, nil for the root.
+  # `not_found` holds unknown ids and other apps' files.
+  MoveFilesResult = Struct.new(:moved, :not_found, :folder, keyword_init: true) do
+    def self.from_api(data)
+      new(
+        moved: data["moved"] || [], not_found: data["notFound"] || [],
+        folder: data["folder"] && Folder.from_api(data["folder"])
+      )
+    end
+  end
+
+  # The result of `delete_folder`: how many folders and files were deleted or moved up a level.
+  FolderDeleteResult = Struct.new(
+    :deleted_folders, :deleted_files, :moved_files, :moved_folders,
+    keyword_init: true
+  ) do
+    def self.from_api(data)
+      new(
+        deleted_folders: data["deletedFolders"] || 0, deleted_files: data["deletedFiles"] || 0,
+        moved_files: data["movedFiles"] || 0, moved_folders: data["movedFolders"] || 0
+      )
+    end
+  end
+
+  # An expiring link to one file, made with `create_file_link`. `url` works until `expires_at` or
+  # until the link is revoked, whatever the file's own read settings. `status` is "active",
+  # "expired" or "revoked"; `created_via` is "api" or "dashboard". Times are `Time` or nil.
+  FileLink = Struct.new(
+    :id, :file_id, :url, :status, :expires_at, :revoked_at, :transform, :download, :filename, :note,
+    :created_via, :created_at, :last_used_at, :use_count,
+    keyword_init: true
+  ) do
+    def self.from_api(data)
+      new(
+        id: data["id"], file_id: data["fileId"], url: data["url"], status: data["status"],
+        expires_at: FileData.parse_time(data["expiresAt"]), revoked_at: FileData.parse_time(data["revokedAt"]),
+        transform: data["transform"].to_s, download: data["download"] == true, filename: data["filename"].to_s,
+        note: data["note"].to_s, created_via: data["createdVia"], created_at: FileData.parse_time(data["createdAt"]),
+        last_used_at: FileData.parse_time(data["lastUsedAt"]), use_count: data["useCount"] || 0
+      )
+    end
+
+    def active?
+      status == "active"
+    end
+  end
+
   # The result of `delete_files`. `failed` is a list of {FailedDelete}.
   BulkDeleteResult = Struct.new(:deleted, :not_found, :failed, keyword_init: true) do
     def self.from_api(data)
@@ -102,7 +189,8 @@ module Fileboy
   end
   FailedDelete = Struct.new(:id, :message, keyword_init: true)
 
-  # Plan limits. A nil limit means none is set.
+  # The limits set on the app, which Fileboy sets from your plan (or an agreement). A nil limit
+  # means none is set on the app, not unlimited; the dashboard then shows the plan's standard limit.
   UsageLimits = Struct.new(:files, :videos, :storage_bytes, keyword_init: true)
 
   # What the app stores. `storage_bytes` counts files, image copies, video renditions and posters.
@@ -115,4 +203,101 @@ module Fileboy
       )
     end
   end
+
+  # Where a photo was taken, in decimal degrees (negative is south or west). Personal data.
+  ExifGps = Struct.new(:latitude, :longitude, :altitude, keyword_init: true)
+
+  EXIF_FIELDS = {
+    "make" => :make, "model" => :model, "lensMake" => :lens_make, "lensModel" => :lens_model,
+    "focalLength" => :focal_length, "focalLength35mm" => :focal_length_35mm, "aperture" => :aperture,
+    "exposureTime" => :exposure_time, "shutterSpeed" => :shutter_speed, "iso" => :iso,
+    "exposureCompensation" => :exposure_compensation, "exposureProgram" => :exposure_program,
+    "meteringMode" => :metering_mode, "flashFired" => :flash_fired, "whiteBalance" => :white_balance,
+    "dateTaken" => :date_taken, "timezone" => :timezone, "orientation" => :orientation, "width" => :width,
+    "height" => :height, "software" => :software, "colorSpace" => :color_space,
+    "colorProfile" => :color_profile, "title" => :title, "description" => :description, "artist" => :artist,
+    "copyright" => :copyright, "rating" => :rating, "city" => :city, "state" => :state, "country" => :country,
+    "sublocation" => :sublocation, "bodySerialNumber" => :body_serial_number,
+    "lensSerialNumber" => :lens_serial_number, "cameraOwnerName" => :camera_owner_name
+  }.freeze
+
+  # The normalised metadata of a photo. A field is nil when the file does not say. `date_taken` is
+  # the ISO 8601 text the file records, with an offset only when it has one (`timezone`). `gps`, the
+  # place names, the serial numbers and `camera_owner_name` are personal data.
+  ExifFields = Struct.new(*EXIF_FIELDS.values, :keywords, :gps, keyword_init: true) do
+    def self.from_api(data)
+      values = EXIF_FIELDS.to_h { |camel, snake| [snake, data[camel]] }
+      gps = data["gps"]
+      values[:gps] = gps && ExifGps.new(latitude: gps["latitude"], longitude: gps["longitude"], altitude: gps["altitude"])
+      new(**values, keywords: data["keywords"] || [])
+    end
+  end
+
+  # A file's EXIF, IPTC and XMP metadata, from {Client#fetch_file_exif}. `status` is "found",
+  # "none" (an image with no metadata) or "unsupported" (not an image type that is read). `raw` has
+  # every tag read, by source: "exif", "iptc" and "xmp".
+  FileExif = Struct.new(:file_id, :status, :format, :extracted_at, :location_removed, :personal_data, :fields,
+                        :raw, :warnings, keyword_init: true) do
+    def self.from_api(data)
+      raw = data["raw"] || {}
+      new(
+        file_id: data["fileId"], status: data["status"], format: data["format"],
+        extracted_at: FileData.parse_time(data["extractedAt"]), location_removed: data["locationRemoved"] == true,
+        personal_data: data["personalData"] != false, fields: ExifFields.from_api(data["fields"] || {}),
+        raw: %w[exif iptc xmp].to_h { |k| [k, raw[k] || {}] }, warnings: data["warnings"] || []
+      )
+    end
+  end
+
+  # The kinds stored files are counted under. Every stored file is exactly one kind.
+  STORAGE_KINDS = %w[
+    images files videoOriginals videoRenditions videoPosters videoCaptions imageTransforms otherGenerated
+  ].freeze
+
+  # How many stored files of one kind there are and their size in bytes.
+  StorageKindUsage = Struct.new(:count, :bytes, keyword_init: true)
+
+  # A video and what it stores, in bytes. `storage_bytes` is all of its parts together.
+  StorageVideo = Struct.new(
+    :id, :name, :created_at, :status, :storage_bytes, :original_bytes, :rendition_bytes, :poster_bytes,
+    :caption_bytes,
+    keyword_init: true
+  ) do
+    def self.from_api(data)
+      new(
+        id: data["id"], name: data["name"], created_at: FileData.parse_time(data["createdAt"]), status: data["status"],
+        storage_bytes: data["storageBytes"] || 0, original_bytes: data["originalBytes"] || 0,
+        rendition_bytes: data["renditionBytes"] || 0, poster_bytes: data["posterBytes"] || 0,
+        caption_bytes: data["captionBytes"] || 0
+      )
+    end
+  end
+
+  # The app's stored bytes on one UTC day (`date` is "YYYY-MM-DD"), with bytes by kind.
+  StorageSnapshot = Struct.new(:date, :storage_bytes, :kinds, keyword_init: true)
+
+  # What the app stores: by kind (a hash keyed by the API's kind names, every kind present), its
+  # biggest files and videos, and a daily total, oldest first. `storage_limit` is the limit set on the
+  # app in bytes, as {Client#fetch_usage} returns it; nil means none is set on the app, not unlimited.
+  StorageUsage = Struct.new(
+    :storage_bytes, :storage_limit, :kinds, :largest_files, :largest_videos, :history,
+    keyword_init: true
+  ) do
+    def self.from_api(data)
+      kinds = STORAGE_KINDS.to_h { |k| [k, StorageKindUsage.new(count: 0, bytes: 0)] }
+      (data["kinds"] || {}).each do |name, value|
+        kinds[name] = StorageKindUsage.new(count: value["count"] || 0, bytes: value["bytes"] || 0)
+      end
+      new(
+        storage_bytes: data["storageBytes"] || 0,
+        storage_limit: (data["limits"] || {})["storageBytes"],
+        kinds: kinds,
+        largest_files: (data["largestFiles"] || []).map { |f| FileData.from_api(f) },
+        largest_videos: (data["largestVideos"] || []).map { |v| StorageVideo.from_api(v) },
+        history: (data["history"] || []).map do |h|
+          StorageSnapshot.new(date: h["date"], storage_bytes: h["storageBytes"] || 0, kinds: h["kinds"] || {})
+        end
+      )
+    end
+  end
 end

data/lib/fileboy/signing.rb

@@ -0,0 +1,198 @@
+require "openssl"
+require "resolv"
+
+module Fileboy
+  # Signed (expiring) URLs for apps that require signed reads. Make them on your server with the
+  # app's private key:
+  #
+  #   url = Fileboy.client.sign_url(Fileboy.client.build_image_url(id, transforms: { resize: [400, 400] }),
+  #                                 expires_in: 600)
+  #
+  # The format is described at https://fileboy.io/docs/delivery/signed-urls and pinned by
+  # packages/sdk-fixtures/signing.json, which every Fileboy SDK and the API test against.
+  module Signing
+    VERSION = "FBS1".freeze
+    DEFAULT_EXPIRES_IN = 3600
+    SIGNATURE_PARAMS = %w[fb_exp fb_sig fb_ip].freeze
+    UUID = /\A[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\z/
+
+    module_function
+
+    # Percent-encode every UTF-8 byte except A-Z a-z 0-9 - . _ ~ with uppercase hex.
+    def escape(value)
+      value.to_s.dup.force_encoding(Encoding::BINARY).each_byte.map do |byte|
+        if (byte >= 0x41 && byte <= 0x5a) || (byte >= 0x61 && byte <= 0x7a) || (byte >= 0x30 && byte <= 0x39) || [0x2d, 0x2e, 0x5f, 0x7e].include?(byte)
+          byte.chr
+        else
+          format("%%%02X", byte)
+        end
+      end.join
+    end
+
+    # The exact string that gets signed.
+    def canonical_string(scope:, id:, expires:, transform: "", filename: "", ip: "")
+      [
+        VERSION,
+        "scope=#{escape(scope)}",
+        "id=#{escape(id)}",
+        "transform=#{escape(transform)}",
+        "filename=#{escape(filename)}",
+        "exp=#{expires}",
+        "ip=#{escape(ip)}"
+      ].join("\n")
+    end
+
+    # The fb_sig value for some claims.
+    def sign_claims(private_key, **claims)
+      digest = OpenSSL::HMAC.digest("SHA256", private_key, canonical_string(**claims))
+      [digest].pack("m0").tr("+/", "-_").delete("=")
+    end
+
+    # Sign a Fileboy URL so it works when the app requires signed reads. The URL is kept as
+    # written; fb_exp (and fb_ip) and fb_sig are added to its query.
+    #
+    # @param url [String] the URL of a file, image or video
+    # @param private_key [String]
+    # @param expires_in [Integer] seconds from now, default one hour
+    # @param expires_at [Time, Integer] an exact expiry, wins over expires_in
+    # @param ip [String, nil] only requests from this address or CIDR range can use the URL
+    # @param now [Time] replaces the current time, for tests
+    def sign_url(url, private_key, expires_in: DEFAULT_EXPIRES_IN, expires_at: nil, ip: nil, now: Time.now)
+      raise ConfigurationError, "Signing needs the app's private key" if private_key.to_s.empty?
+
+      expires = resolve_expiry(expires_in, expires_at, now)
+      ip = nil if ip == ""
+      check_ip!(ip) if ip
+      claims, query = claims_from_url(url)
+      signature = sign_claims(private_key, **claims, expires: expires, ip: ip.to_s)
+
+      without_fragment, hash, fragment = url.partition("#")
+      base = without_fragment.split("?", 2).first
+      signed_query = query.empty? ? "" : "#{query}&"
+      signed_query += "fb_exp=#{expires}"
+      signed_query += "&fb_ip=#{escape(ip)}" if ip
+      signed_query += "&fb_sig=#{signature}"
+      "#{base}?#{signed_query}#{hash}#{fragment}"
+    end
+
+    # The query string that unlocks every URL of one video: manifests, segments, poster, captions
+    # and data. Make it last at least as long as the video takes to watch.
+    def sign_video_query(video_id, private_key, expires_in: DEFAULT_EXPIRES_IN, expires_at: nil, ip: nil, now: Time.now)
+      raise ConfigurationError, "Signing needs the app's private key" if private_key.to_s.empty?
+      raise InvalidArgumentError, "#{video_id.inspect} is not a video id" unless UUID.match?(video_id.to_s)
+
+      expires = resolve_expiry(expires_in, expires_at, now)
+      ip = nil if ip == ""
+      check_ip!(ip) if ip
+      signature = sign_claims(private_key, scope: "video", id: video_id.downcase, expires: expires, ip: ip.to_s)
+      "fb_exp=#{expires}#{ip ? "&fb_ip=#{escape(ip)}" : ""}&fb_sig=#{signature}"
+    end
+
+    # What a URL refers to, and what is left of its query once any signature is removed. Mirrors
+    # the server's own reading of the URL.
+    def claims_from_url(url)
+      without_fragment = url.partition("#").first
+      raw_path, _, raw_query = without_fragment.partition("?")
+      raw_path = raw_path.sub(%r{\A[A-Za-z][A-Za-z0-9+.-]*://[^/]*}, "")
+      path = percent_decode(raw_path) or unsupported!(url)
+      segs = path.gsub(%r{\A/+|/+\z}, "").split("/", -1)
+      unsupported!(url) if segs.any?(&:empty?)
+
+      a, b, c, d = segs
+      claims =
+        if segs.length == 2 && %w[files images].include?(a) then { scope: "file", id: b }
+        elsif segs.length == 3 && %w[files images].include?(a) && b == "get" then { scope: "file", id: c }
+        elsif segs.length == 4 && %w[files images].include?(a) && b == "get" then { scope: "file", id: c, filename: d }
+        elsif segs.length == 3 && a == "files" && b == "data" then { scope: "file-data", id: c }
+        elsif segs.length == 3 && a == "files" && c == "data" then { scope: "file-data", id: b }
+        elsif segs.length >= 3 && a == "videos" then { scope: "video", id: b }
+        # A share page, on the website: https://fileboy.io/f/{id}
+        elsif segs.length == 2 && a == "f" then { scope: "share", id: b }
+        elsif segs.length == 3 && a == "files" && c == "share" then { scope: "share", id: b }
+        else unsupported!(url)
+        end
+      unsupported!(url) unless valid_id?(claims[:id], %w[video share].include?(claims[:scope]))
+      claims[:id] = claims[:id].downcase unless claims[:id].include?("+")
+
+      kept = []
+      unless raw_query.empty?
+        raw_query.split("&", -1).each do |pair|
+          # partition, not split: an empty component ("a&&b", a trailing "&") gives "" and is kept
+          key = pair.partition("=").first
+          name = percent_decode(key, plus: true)
+          next if name && SIGNATURE_PARAMS.include?(name)
+
+          kept << pair
+        end
+      end
+
+      if claims[:scope] == "file"
+        # the server reads the query with semicolons as data, and the first transform wins
+        raw_query.gsub(";", "%3B").split("&", -1).each do |pair|
+          next if pair.empty?
+
+          key, _, value = pair.partition("=")
+          name = percent_decode(key, plus: true)
+          decoded = percent_decode(value, plus: true)
+          if name.nil? || decoded.nil?
+            raise InvalidArgumentError, "Cannot sign #{url}: its query string is malformed"
+          end
+          if name == "transform"
+            claims[:transform] = decoded
+            break
+          end
+        end
+      end
+      [claims, kept.join("&")]
+    end
+
+    def percent_decode(string, plus: false)
+      return nil if string =~ /%(?![0-9A-Fa-f]{2})/
+
+      string = string.tr("+", " ") if plus
+      decoded = string.gsub(/%([0-9A-Fa-f]{2})/) { Regexp.last_match(1).hex.chr }.dup.force_encoding(Encoding::BINARY)
+      decoded.force_encoding(Encoding::UTF_8)
+      decoded.valid_encoding? ? decoded : nil
+    end
+
+    def valid_id?(id, uuid_only)
+      if id.include?("+")
+        parts = id.split("+", -1)
+        return !uuid_only && parts.length == 2 && !parts[0].empty? && !parts[1].empty?
+      end
+      UUID.match?(id)
+    end
+
+    def resolve_expiry(expires_in, expires_at, now)
+      expires =
+        if expires_at
+          expires_at.respond_to?(:to_f) ? expires_at.to_f : expires_at
+        else
+          now.to_f + expires_in.to_f
+        end
+      expires = expires.floor
+      raise InvalidArgumentError, "The expiry must be a time in the future" unless expires.positive?
+
+      expires
+    end
+
+    def check_ip!(spec)
+      address, prefix = spec.split("/", 2)
+      v4 = Resolv::IPv4::Regex.match?(address)
+      v6 = !v4 && Resolv::IPv6::Regex.match?(address) && !address.include?("%")
+      ok = v4 || v6
+      if ok && !prefix.nil?
+        ok = prefix.match?(/\A[0-9]{1,3}\z/) && prefix.to_i <= (v4 ? 32 : 128)
+      end
+      raise InvalidArgumentError, "Invalid ip address or range: #{spec}" unless ok && !spec.end_with?("/")
+    end
+
+    def unsupported!(url)
+      raise InvalidArgumentError,
+            "Cannot sign #{url}: it is not the URL of a Fileboy file, image, video or share page " \
+            "(for example /files/get/{id}, /images/get/{id}, /videos/{id}/manifest or /f/{id})"
+    end
+
+    private_class_method :percent_decode, :valid_id?, :resolve_expiry, :check_ip!, :unsupported!
+  end
+end