file_hutch 0.1.0

data/lib/file_hutch/project.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module FileHutch
+  class Project < Resource
+    attribute :name, :team_id, :storage_ready
+    time_attribute :created_at
+
+    def storage_ready? = storage_ready == true
+    def storage_connection = self["active_storage_connection"]
+    def storage_mode = storage_connection && storage_connection["mode"]
+    def storage_provider = storage_connection && storage_connection["provider"]
+
+    def upload_policies
+      (self["upload_policies"] || []).map { |p| UploadPolicy.new(p, client: client) }
+    end
+
+    def upload_policy(name) = upload_policies.find { |p| p.name == name.to_s || p.id == name.to_s }
+
+    def transforms
+      (self["transforms"] || []).map { |t| Transform.new(t, client: client) }
+    end
+
+    def transform(name) = transforms.find { |t| t.name == name.to_s || t.id == name.to_s }
+  end
+
+  # A named image size defined in the project. Applications reference the name;
+  # nothing here is provider-specific.
+  class Transform < Resource
+    attribute :name, :width, :height, :fit, :quality, :format
+    time_attribute :created_at
+  end
+
+  class UploadPolicy < Resource
+    attribute :name, :allowed_content_types, :maximum_size, :visibility
+    time_attribute :created_at
+
+    def public? = visibility == "public"
+    def private? = visibility == "private"
+    def allowed_content_types = self["allowed_content_types"] || []
+
+    def allows_content_type?(content_type)
+      return true if allowed_content_types.empty?
+      ct = content_type.to_s.downcase
+      allowed_content_types.any? { |p| p == ct || (p.end_with?("/*") && ct.start_with?(p.delete_suffix("*"))) }
+    end
+
+    def allows_byte_size?(size) = size.to_i.positive? && size.to_i <= maximum_size.to_i
+  end
+end

data/lib/file_hutch/rails/attachable.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module FileHutch
+  # `has_file_hutch_file` for Active Record. The model stores one string column,
+  # `<name>_file_id`, holding an FileHutch file id. Nothing about storage leaks in.
+  #
+  #   class User < ApplicationRecord
+  #     has_file_hutch_file :avatar, policy: "avatars"
+  #   end
+  #
+  #   user.avatar = params[:avatar]            # uploaded IO: uploaded to storage on save
+  #   user.avatar = "file_…"                   # id from a browser direct upload: verified on save
+  #   user.avatar                              # => FileHutch::File or nil
+  #   user.avatar_url                          # public URL (public policies)
+  #   user.avatar_signed_url(expires_in: 600)  # works for private files
+  #   user.avatar_transform_url("thumb")       # a named transform from the dashboard
+  #   user.purge_avatar                        # deletes remotely, clears the column
+  #
+  # Options: column: (default "<name>_file_id"), dependent: :delete (default; delete the file when the
+  # record is destroyed or the file is replaced) or false, verify: true (default; a raw id assigned
+  # from a form is fetched on validation and must be a ready file uploaded under this policy).
+  module Attachable
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def has_file_hutch_file(name, policy:, column: "#{name}_file_id", dependent: :delete, verify: true)
+        include Attachable unless include?(Attachable)
+        name = name.to_sym
+        column = column.to_s
+        file_hutch_files[name] = { policy: policy.to_s, column: column, dependent: dependent, verify: verify }
+
+        validate { file_hutch_validate(name) }
+        before_save { file_hutch_upload_staged(name) }
+        after_save { file_hutch_delete_replaced(name) }
+        after_destroy { file_hutch_delete_on_destroy(name) } if dependent == :delete
+
+        define_method(name) { file_hutch_file(name) }
+        define_method(:"#{name}=") { |value| file_hutch_assign(name, value) }
+        define_method(:"#{name}?") { self[column].present? }
+        define_method(:"#{name}_url") { file_hutch_file(name)&.url }
+        define_method(:"#{name}_signed_url") { |expires_in: nil, disposition: nil| file_hutch_file(name)&.signed_url(expires_in: expires_in, disposition: disposition) }
+        define_method(:"#{name}_transform_url") { |transform, expires_in: nil| file_hutch_file(name)&.transform_url(transform, expires_in: expires_in) }
+        define_method(:"purge_#{name}") { file_hutch_purge(name) }
+      end
+
+      def file_hutch_files
+        @file_hutch_files ||= superclass.respond_to?(:file_hutch_files) ? superclass.file_hutch_files.dup : {}
+      end
+    end
+
+    def reload(*)
+      @file_hutch_cache = nil
+      super
+    end
+
+    private
+
+    def file_hutch_option(name, key) = self.class.file_hutch_files.fetch(name).fetch(key)
+    def file_hutch_cache = @file_hutch_cache ||= {}
+    def file_hutch_staged = @file_hutch_staged ||= {}
+    def file_hutch_replaced = @file_hutch_replaced ||= {}
+
+    def file_hutch_file(name)
+      id = self[file_hutch_option(name, :column)]
+      return nil if id.blank?
+      cached = file_hutch_cache[name]
+      return cached if cached && cached.id == id
+      file_hutch_cache[name] = FileHutch.client.file(id)
+    rescue FileHutch::NotFoundError
+      nil
+    end
+
+    def file_hutch_assign(name, value)
+      column = file_hutch_option(name, :column)
+      previous = self[column]
+      file_hutch_staged.delete(name)
+      file_hutch_cache.delete(name)
+
+      case value
+      when nil, ""
+        self[column] = nil
+      when FileHutch::File
+        file_hutch_cache[name] = value
+        self[column] = value.id
+      when String
+        raise ArgumentError, "#{value.inspect} is not an FileHutch file id" unless FileHutch::File.id?(value)
+        self[column] = value
+      else
+        raise ArgumentError, "cannot attach #{value.class} to #{name}" unless value.respond_to?(:read) || value.respond_to?(:tempfile) || value.is_a?(Pathname)
+        file_hutch_staged[name] = value
+        self[column] = nil
+      end
+
+      file_hutch_remember_replaced(name, previous) if previous.present? && previous != self[column]
+      value
+    end
+
+    def file_hutch_remember_replaced(name, previous_id)
+      file_hutch_replaced[name] = previous_id if file_hutch_option(name, :dependent) == :delete
+    end
+
+    def file_hutch_validate(name)
+      column = file_hutch_option(name, :column)
+      staged = file_hutch_staged[name]
+      if staged
+        policy = file_hutch_policy(name)
+        if policy
+          type = staged.respond_to?(:content_type) ? staged.content_type : nil
+          size = staged.respond_to?(:size) ? staged.size : nil
+          errors.add(name, :file_hutch_content_type, message: "type #{type} is not allowed") if type && !policy.allows_content_type?(type)
+          errors.add(name, :file_hutch_too_large, message: "is larger than #{policy.maximum_size} bytes") if size && !policy.allows_byte_size?(size)
+        end
+        return
+      end
+
+      id = self[column]
+      return unless file_hutch_option(name, :verify) && id.present? && attribute_changed?(column) && file_hutch_cache[name].nil?
+
+      file = FileHutch.client.file(id)
+      if !file.ready?
+        errors.add(name, :file_hutch_not_ready, message: "upload is #{file.status}")
+      elsif file.policy != file_hutch_option(name, :policy)
+        errors.add(name, :file_hutch_wrong_policy, message: "was uploaded under the #{file.policy} policy")
+      else
+        file_hutch_cache[name] = file
+      end
+    rescue FileHutch::NotFoundError
+      errors.add(name, :file_hutch_not_found, message: "does not exist")
+    end
+
+    # Policies are fetched once per process; a miss (or an outage) skips local checks. The server still enforces them.
+    def file_hutch_policy(name)
+      Attachable.policy(file_hutch_option(name, :policy))
+    end
+
+    def file_hutch_upload_staged(name)
+      source = file_hutch_staged.delete(name) or return
+      file = FileHutch.client.upload(source, policy: file_hutch_option(name, :policy))
+      file_hutch_cache[name] = file
+      self[file_hutch_option(name, :column)] = file.id
+    end
+
+    def file_hutch_delete_replaced(name)
+      id = file_hutch_replaced.delete(name) or return
+      return if id == self[file_hutch_option(name, :column)]
+      Attachable.delete_quietly(id)
+    end
+
+    def file_hutch_delete_on_destroy(name)
+      id = self[file_hutch_option(name, :column)]
+      Attachable.delete_quietly(id) if id.present?
+    end
+
+    def file_hutch_purge(name)
+      column = file_hutch_option(name, :column)
+      id = self[column]
+      Attachable.delete_quietly(id) if id.present?
+      file_hutch_cache.delete(name)
+      update_column(column, nil) if persisted?
+      self[column] = nil
+      true
+    end
+
+    class << self
+      def delete_quietly(id)
+        FileHutch.client.delete_file(id)
+      rescue FileHutch::NotFoundError, FileHutch::InvalidStateError
+        true
+      end
+
+      def policy(name)
+        policies[name] ||= FileHutch.client.project.upload_policy(name)
+      rescue FileHutch::Error => e
+        FileHutch.config.logger&.warn { "[file_hutch] could not load upload policies: #{e.message}" }
+        nil
+      end
+
+      def policies = @policies ||= {}
+      def reset_policies! = @policies = {}
+    end
+  end
+end

data/lib/file_hutch/rails/engine.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module FileHutch
+  # Mount at /file_hutch to give browsers a direct-upload endpoint that never
+  # exposes the API key:
+  #
+  #   mount FileHutch::Engine => "/file_hutch"
+  #
+  #   POST /file_hutch/uploads              {policy, filename, content_type, byte_size}
+  #   POST /file_hutch/uploads/:id/complete
+  #
+  # Both require FileHutch.config.authorize_direct_upload to return true.
+  class Engine < ::Rails::Engine
+    isolate_namespace FileHutch
+
+    initializer "file_hutch.active_record" do
+      ActiveSupport.on_load(:active_record) { extend FileHutch::Attachable::ClassMethods }
+    end
+
+    initializer "file_hutch.assets" do |app|
+      app.config.assets.precompile += %w[file_hutch/direct_upload_controller.js] if app.config.respond_to?(:assets) && app.config.assets.respond_to?(:precompile)
+    end
+
+    initializer "file_hutch.logger" do
+      FileHutch.config.logger ||= ::Rails.logger
+    end
+  end
+end

data/lib/file_hutch/rails.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require "rails"
+require_relative "rails/attachable"
+require_relative "rails/engine"

data/lib/file_hutch/resource.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module FileHutch
+  # Thin, immutable wrapper over an API JSON object.
+  class Resource
+    attr_reader :attributes, :client
+
+    def initialize(attributes, client: nil)
+      @attributes = (attributes || {}).transform_keys(&:to_s).freeze
+      @client = client
+    end
+
+    def [](key) = attributes[key.to_s]
+    def id = self["id"]
+    def to_h = attributes.dup
+    def to_param = id
+    def to_s = id.to_s
+    def as_json(*) = to_h
+    def to_json(*args) = to_h.to_json(*args)
+    def ==(other) = other.class == self.class && other.attributes == attributes
+    alias eql? ==
+    def hash = [ self.class, attributes ].hash
+    def inspect = "#<#{self.class.name} #{attributes.map { |k, v| "#{k}=#{v.inspect}" }.join(' ')}>"
+
+    def self.attribute(*names)
+      names.each { |name| define_method(name) { self[name] } }
+    end
+
+    def self.time_attribute(*names)
+      names.each do |name|
+        define_method(name) do
+          value = self[name]
+          value && Time.iso8601(value)
+        end
+      end
+    end
+
+    private
+
+    def client!
+      client || FileHutch.client
+    end
+  end
+end

data/lib/file_hutch/upload.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module FileHutch
+  # Direct-upload instructions from POST /api/v1/uploads plus the pending file.
+  class Upload < Resource
+    attribute :file_id, :method, :url, :headers
+    time_attribute :expires_at
+
+    def initialize(attributes, file: nil, client: nil)
+      super(attributes, client: client)
+      @file = file
+    end
+
+    attr_reader :file
+
+    def headers = self["headers"] || {}
+    def expired? = expires_at && expires_at <= Time.now
+
+    # PUTs the bytes straight to storage. `source` is an IO or a String of bytes.
+    def put(source)
+      client!.put_to_storage(self, source)
+      self
+    end
+
+    # Tells FileHutch the bytes are in place; returns the ready file.
+    def complete = client!.complete_upload(id)
+  end
+end

data/lib/file_hutch/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module FileHutch
+  VERSION = "0.1.0"
+end

data/lib/file_hutch/webhook.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module FileHutch
+  # Verifies the signature FileHutch puts on every webhook delivery:
+  #
+  #   FileHutch-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<body>")>
+  #
+  #   event = FileHutch::Webhook.construct_event(request.raw_post, request.headers["FileHutch-Signature"], secret)
+  #   case event["type"]
+  #   when "file.created" then Document.find_by(file_hutch_file_id: event["data"]["file"]["id"])&.ready!
+  #   end
+  module Webhook
+    HEADER = "FileHutch-Signature"
+    DEFAULT_TOLERANCE = 300
+
+    # Returns the parsed event. Raises SignatureVerificationError if the body was
+    # not signed with `secret` in the last `tolerance` seconds.
+    def self.construct_event(payload, signature_header, secret, tolerance: DEFAULT_TOLERANCE, now: Time.now)
+      verify!(payload, signature_header, secret, tolerance: tolerance, now: now)
+      JSON.parse(payload)
+    end
+
+    def self.verify!(payload, signature_header, secret, tolerance: DEFAULT_TOLERANCE, now: Time.now)
+      raise SignatureVerificationError, "webhook secret is missing" if secret.to_s.empty?
+
+      parts = signature_header.to_s.split(",").filter_map do |part|
+        key, value = part.split("=", 2)
+        [ key, value ] if value
+      end.to_h
+      timestamp = parts["t"].to_i
+      given = parts["v1"].to_s
+      raise SignatureVerificationError, "missing or malformed #{HEADER} header" if timestamp.zero? || given.empty?
+      raise SignatureVerificationError, "signature timestamp is outside the #{tolerance}s tolerance" if (now.to_i - timestamp).abs > tolerance
+
+      expected = compute_signature(timestamp, payload, secret)
+      raise SignatureVerificationError, "signature does not match" unless secure_compare(expected, given)
+
+      true
+    end
+
+    def self.compute_signature(timestamp, payload, secret)
+      OpenSSL::HMAC.hexdigest("SHA256", secret, "#{timestamp.to_i}.#{payload}")
+    end
+
+    def self.secure_compare(a, b)
+      return false unless a.bytesize == b.bytesize
+
+      OpenSSL.fixed_length_secure_compare(a, b)
+    end
+    private_class_method :secure_compare
+  end
+end

data/lib/file_hutch.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "json"
+require "stringio"
+require "openssl"
+require "digest"
+require "net/http"
+require "uri"
+require "time"
+
+require_relative "file_hutch/version"
+require_relative "file_hutch/errors"
+require_relative "file_hutch/configuration"
+require_relative "file_hutch/resource"
+require_relative "file_hutch/file"
+require_relative "file_hutch/upload"
+require_relative "file_hutch/project"
+require_relative "file_hutch/client"
+require_relative "file_hutch/webhook"
+require_relative "file_hutch/cli"
+
+# FileHutch: file infrastructure for apps that aren't Netflix.
+#
+#   FileHutch.configure { |c| c.api_key = ENV["FILE_HUTCH_API_KEY"] }
+#   file = FileHutch.upload("report.pdf", policy: "documents")   # => FileHutch::File (ready)
+#   file.signed_url(expires_in: 3600)
+#   FileHutch::File.find(file.id).delete
+#
+# Your application persists `file.id` ("file_…") and nothing else about storage.
+module FileHutch
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+    alias config configuration
+
+    def configure
+      yield configuration
+      reset_client!
+      configuration
+    end
+
+    # The shared client built from FileHutch.configuration.
+    def client
+      @client ||= Client.new(configuration)
+    end
+
+    def client=(client)
+      @client = client
+    end
+
+    def reset_client!
+      @client = nil
+    end
+
+    # Convenience delegators for one-project apps.
+    def upload(source, **options) = client.upload(source, **options)
+    def file(id) = client.file(id)
+    def project = client.project
+  end
+end
+
+require_relative "file_hutch/rails" if defined?(::Rails::Railtie)

data/lib/generators/file_hutch/attachment/attachment_generator.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module FileHutch
+  module Generators
+    # bin/rails generate file_hutch:attachment User avatar
+    # Adds users.avatar_file_id (string). Pair with `has_file_hutch_file :avatar, policy: "…"`.
+    class AttachmentGenerator < ::Rails::Generators::NamedBase
+      include ::ActiveRecord::Generators::Migration
+
+      source_root ::File.expand_path("templates", __dir__)
+      argument :attachment, type: :string, banner: "attachment_name"
+
+      def create_migration_file
+        migration_template "migration.rb.tt", "db/migrate/add_#{column_name}_to_#{table_name}.rb"
+      end
+
+      def show_macro
+        say %(Add to #{class_name}:  has_file_hutch_file :#{attachment}, policy: "#{attachment.pluralize}"), :green
+      end
+
+      private
+
+      def column_name = "#{attachment.underscore}_file_id"
+      def migration_class_name = "Add#{column_name.camelize}To#{table_name.camelize}"
+    end
+  end
+end

data/lib/generators/file_hutch/attachment/templates/migration.rb.tt

@@ -0,0 +1,6 @@
+class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    # Holds an FileHutch file id ("file_…"). Never a URL, never a storage key.
+    add_column :<%= table_name %>, :<%= column_name %>, :string
+  end
+end

data/lib/generators/file_hutch/install/install_generator.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module FileHutch
+  module Generators
+    # bin/rails generate file_hutch:install
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root ::File.expand_path("templates", __dir__)
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/file_hutch.rb"
+      end
+
+      def mount_engine
+        route 'mount FileHutch::Engine => "/file_hutch"'
+      end
+
+      def pin_javascript
+        return unless ::File.exist?(::File.join(destination_root, "config/importmap.rb"))
+        append_to_file "config/importmap.rb", %(pin "file_hutch/direct_upload_controller", to: "file_hutch/direct_upload_controller.js"\n)
+      end
+
+      def show_next_steps
+        say ""
+        say "FileHutch installed.", :green
+        say "  1. Set FILE_HUTCH_API_KEY (Dashboard → API keys) and, if not production, FILE_HUTCH_URL."
+        say "  2. Add a column and macro:  bin/rails g file_hutch:attachment User avatar  then  has_file_hutch_file :avatar, policy: \"avatars\""
+        say "  3. For browser uploads, set FileHutch.config.authorize_direct_upload in the initializer and register the"
+        say "     Stimulus controller:  application.register(\"filehutch-direct-upload\", DirectUploadController)"
+      end
+    end
+  end
+end

data/lib/generators/file_hutch/install/templates/initializer.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+FileHutch.configure do |config|
+  # Project-scoped API key from the FileHutch dashboard. Keep it out of the repo.
+  config.api_key = ENV["FILE_HUTCH_API_KEY"]
+
+  # Leave the default for FileHutch cloud; point at your own instance otherwise.
+  config.url = ENV.fetch("FILE_HUTCH_URL", FileHutch::Configuration::DEFAULT_URL)
+
+  # Browser-direct uploads (POST /file_hutch/uploads) are off until you decide who may
+  # upload, and against which policies. `controller` is the request's controller.
+  # config.authorize_direct_upload = ->(controller, policy) do
+  #   controller.current_user.present? && %w[avatars documents].include?(policy)
+  # end
+
+  # The direct-upload controller inherits from this so your auth helpers are available.
+  # config.direct_upload_parent_controller = "ApplicationController"
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: file_hutch
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Andy Leverenz
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Talk to the FileHutch file control plane from Ruby. Server-side and browser-direct
+  uploads, signed URLs, and a has_file_hutch_file macro for Active Record that stores
+  only opaque file ids.
+email:
+- andy@justalever.com
+executables:
+- file_hutch
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- app/assets/javascripts/file_hutch/direct_upload_controller.js
+- app/controllers/file_hutch/direct_uploads_controller.rb
+- config/routes.rb
+- exe/file_hutch
+- lib/file_hutch.rb
+- lib/file_hutch/cli.rb
+- lib/file_hutch/client.rb
+- lib/file_hutch/configuration.rb
+- lib/file_hutch/errors.rb
+- lib/file_hutch/file.rb
+- lib/file_hutch/project.rb
+- lib/file_hutch/rails.rb
+- lib/file_hutch/rails/attachable.rb
+- lib/file_hutch/rails/engine.rb
+- lib/file_hutch/resource.rb
+- lib/file_hutch/upload.rb
+- lib/file_hutch/version.rb
+- lib/file_hutch/webhook.rb
+- lib/generators/file_hutch/attachment/attachment_generator.rb
+- lib/generators/file_hutch/attachment/templates/migration.rb.tt
+- lib/generators/file_hutch/install/install_generator.rb
+- lib/generators/file_hutch/install/templates/initializer.rb
+homepage: https://github.com/filehutch/filehutch-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/filehutch/filehutch-ruby
+  source_code_uri: https://github.com/filehutch/filehutch-ruby
+  changelog_uri: https://github.com/filehutch/filehutch-ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: 'Ruby and Rails client for FileHutch: uploads, private files, and delivery
+  without file plumbing.'
+test_files: []