webpacker_uploader 0.3.0 → 0.4.0

data/Rakefile

@@ -1,6 +1,11 @@
+# frozen_string_literal: true
+
 require "bundler/gem_tasks"
 require "rake/testtask"
 
+require "yard"
+YARD::Rake::YardocTask.new
+
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
   t.libs << "lib"

data/lib/webpacker_uploader.rb

@@ -1,21 +1,31 @@
 # frozen_string_literal: true
 
 require "active_support/core_ext/object/blank"
-require "active_support/logger"
-require "active_support/tagged_logging"
 
 module WebpackerUploader
   extend self
 
+  # @private
   def instance=(instance)
     @instance = instance
   end
 
+  # @private
   def instance
     @instance ||= WebpackerUploader::Instance.new
   end
 
-  delegate :logger, :logger=, :configure, :config, :upload!, to: :instance
+  # @!attribute [rw] config
+  #   @see Instance#config
+  #   @!scope class
+  # @!method configure
+  #   @see Instance#configure
+  #   @!scope class
+  # @!method upload!
+  #   @return [void]
+  #   @see Instance#upload!
+  #   @!scope class
+  delegate :configure, :config, :upload!, to: :instance
 end
 
 require "webpacker_uploader/configuration"

data/lib/webpacker_uploader/configuration.rb

@@ -1,13 +1,33 @@
 # frozen_string_literal: true
 
+require "active_support/logger"
+require "active_support/tagged_logging"
+
+# This is the class which holds the configuration options.
+#
+# Options are set and retrieved using `WebpackerUploader.config`
+# and `WebpackerUploader.configure`.
 class WebpackerUploader::Configuration
-  attr_accessor :ignored_extensions, :log_output
-  attr_reader   :public_manifest_path, :public_path
+  # @return [Array] the file extentions ignored by the uploader.
+  attr_accessor :ignored_extensions
+
+  # @return [ActiveSupport::Logger] the logger to use.
+  attr_accessor :logger
+
+  # @return [Boolean] whether or not to log operations.
+  attr_accessor :log_output
+
+  # @return [Pathname] the path to manifest.json, defaults to Webpacker public manifest path.
+  attr_reader :public_manifest_path
+
+  # @return [Pathname] the public root path, defaults to Webpacker public root path.
+  attr_reader :public_path
 
   alias_method :log_output?, :log_output
 
   def initialize
     @ignored_extensions = []
+    @logger = ActiveSupport::TaggedLogging.new(ActiveSupport::Logger.new(STDOUT))
     @log_output = true
     @public_manifest_path = ::Webpacker.config.public_manifest_path
     @public_path = ::Webpacker.config.public_path

data/lib/webpacker_uploader/instance.rb

@@ -1,22 +1,50 @@
 # frozen_string_literal: true
 
 class WebpackerUploader::Instance
-  cattr_accessor(:logger) { ActiveSupport::TaggedLogging.new(ActiveSupport::Logger.new(STDOUT)) }
-
   attr_writer :config
 
+  # @private
   def manifest
     @manifest ||= WebpackerUploader::Manifest.new
   end
 
+  # Returns the global WebpackerUploader::Configuration object.
+  # Use this to set and retrieve specific configuration options.
+  #
+  # @return [WebpackerUploader::Configuration]
+  #
+  # @example Disable log output
+  #   WebpackerUploader.config.log_output = false
+  #
+  # @example Get the list of excluded file extension
+  #   puts WebpackerUploader.config.ignored_extensions
+  #
+  # @see WebpackerUploader::Configuration
   def config
     @config ||= WebpackerUploader::Configuration.new
   end
 
+  # Yields the global configuration to a block. Use this to
+  # configure the base gem features.
+  #
+  # @example
+  #   WebpackerUploader.configure do |config|
+  #     config.ignored_extensions = [".png", ".jpg", ".webp"]
+  #     config.log_output = false
+  #     config.public_manifest_path = "path/to/manifest.json"
+  #     config.public_path = "path/to/public/dir"
+  #   end
+  #
+  # @see WebpackerUploader::Configuration
   def configure
     yield config
   end
 
+  # Uploads assets using the supplied provider. Currently only AWS S3 is implemented.
+  #
+  # @return [void]
+  # @param provider [WebpackerUploader::Providers::Aws] A provider to use for file uploading.
+  # @param prefix [String] Used to prefix the remote file paths.
   def upload!(provider, prefix: nil)
     manifest.assets.each do |name, js_path|
       path = js_path[1..-1]
@@ -31,11 +59,11 @@ class WebpackerUploader::Instance
       file_path = config.public_path.join(path)
 
       if name.end_with?(*config.ignored_extensions)
-        logger.info("Skipping #{file_path}") if config.log_output?
+        config.logger.info("Skipping #{file_path}") if config.log_output?
       else
         content_type = WebpackerUploader::Mime.mime_type(path)
 
-        logger.info("Processing #{file_path} as #{content_type}") if config.log_output?
+        config.logger.info("Processing #{file_path} as #{content_type}") if config.log_output?
 
         provider.upload!(remote_path, file_path, content_type)
       end

data/lib/webpacker_uploader/manifest.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class WebpackerUploader::Manifest
+class WebpackerUploader::Manifest # @private
   attr_reader :assets
 
   def initialize

data/lib/webpacker_uploader/mime.rb

@@ -3,6 +3,12 @@
 require "mime-types"
 
 module WebpackerUploader::Mime
+  # Returns the mime type for the given file in the filesystem.
+  # If it's unable to detect the mime type, it returns +application/octet-stream+
+  # as a fallback.
+  #
+  # @param file_path [String] A file path in the local filesystem.
+  # @return [String] The file mime type.
   def mime_type(file_path)
     fallback = MIME::Types.type_for(file_path).first&.content_type || "application/octet-stream"
     Rack::Mime.mime_type(File.extname(file_path), fallback)

data/lib/webpacker_uploader/providers/aws.rb

@@ -3,18 +3,59 @@
 require "aws-sdk-s3"
 
 module WebpackerUploader
+  # Namespace for the upload providers.
   module Providers
+    # AWS provider uploads files to AWS S3. It uses the +aws-sdk-s3+ gem.
     class Aws
-      attr_reader :client
-      attr_reader :resource
-      attr_reader :bucket
+      attr_reader :client, :resource, :bucket # @private
 
+      # @param [Hash] options
+      #   * :region (String) The S3 region name.
+      #   * :bucket (String) The S3 bucket name.
+      #   * :credentials (Hash) credential options for the AWS provider:
+      #     * :profile_name (String) use a named profile configured in ~/.aws/credentials
+      #     * :instance_profile (Boolean) use an instance profile from an EC2
+      #     * :access_key_id (String) the AWS credentials access id.
+      #     * :secret_access_key (String) the AWS credentials secret access key.
+      #
+      # @example Initialize the using a named profile:
+      #
+      #   provider_options = {
+      #     credentials: { profile_name: "staging" },
+      #     region: "eu-central-1",
+      #     bucket: "application-assets-20200929124523451600000001"
+      #   }
+      #   provider = WebpackerUploader::Providers::Aws.new(provider_options)
+      #
+      # @example Initialize using IAM keys
+      #
+      #   provider_options = {
+      #     credentials: { access_key_id: "KEY_ID", secret_access_key: "ACCESS_KEY" },
+      #     region: "eu-central-1",
+      #     bucket: "application-assets-20200929124523451600000001"
+      #   }
+      #   provider = WebpackerUploader::Providers::Aws.new(provider_options)
+      #
+      # @example Initialize using an EC2 instance profile
+      #
+      #   provider_options = {
+      #     credentials: { instance_profile: true },
+      #     region: "eu-central-1",
+      #     bucket: "application-assets-20200929124523451600000001"
+      #   }
+      #   provider = WebpackerUploader::Providers::Aws.new(provider_options)
       def initialize(options)
         @client = ::Aws::S3::Client.new(credentials: credentials(options[:credentials]), region: options[:region])
         @resource = ::Aws::S3::Resource.new(client: @client)
         @bucket = @resource.bucket(options[:bucket])
       end
 
+      # Uploads a file to AWS S3.
+      #
+      # @param object_key [String] Is the remote path name for the S3 object.
+      # @param file [Pathname] Path of the local file.
+      # @param content_type [String] The content type that will be set to the S3 object.
+      # @return [void]
       def upload!(object_key, file, content_type = "")
         object = @bucket.object(object_key)
         object.upload_file(file, content_type: content_type)

data/lib/webpacker_uploader/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module WebpackerUploader
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/test/configuration_test.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class ConfigurationTest < Minitest::Test
+  def setup
+    @config = WebpackerUploader::Configuration.new
+  end
+
+  def teardown
+    WebpackerUploader.reset!
+  end
+
+  def test_default_config_options
+    assert_empty @config.ignored_extensions
+
+    assert_instance_of ActiveSupport::Logger, @config.logger
+
+    assert @config.log_output
+    assert @config.log_output?
+
+    public_manifest_path = Pathname.new(File.expand_path("test_app/public/packs/manifest.json", __dir__))
+    assert_equal public_manifest_path, @config.public_manifest_path
+
+    public_path = Pathname.new(File.expand_path("test_app/public/", __dir__))
+    assert_equal public_path, @config.public_path
+  end
+
+  def test_changing_config_options
+    @config.ignored_extensions = [".css", ".js"]
+    assert_equal [".css", ".js"], @config.ignored_extensions
+
+    @config.logger = Logger.new(STDOUT)
+    assert_instance_of Logger, @config.logger
+
+    @config.log_output = false
+    refute @config.log_output
+    refute @config.log_output?
+
+    @config.public_manifest_path = "test_app/manifest.json"
+    assert_equal "test_app/manifest.json", @config.public_manifest_path.to_s
+
+    @config.public_path = "test_app"
+    assert_equal "test_app", @config.public_path.to_s
+  end
+
+  def test_configure_block
+    WebpackerUploader.configure do |c|
+      c.ignored_extensions = [".js"]
+      c.logger = Logger.new(STDOUT)
+      c.log_output = false
+      c.public_manifest_path = "path/to/manifest.json"
+      c.public_path = "path/to/public/dir"
+    end
+
+    assert_equal [".js"], WebpackerUploader.config.ignored_extensions
+    assert_instance_of Logger, WebpackerUploader.config.logger
+    refute WebpackerUploader.config.log_output
+    refute WebpackerUploader.config.log_output?
+    assert_equal "path/to/manifest.json", WebpackerUploader.config.public_manifest_path.to_s
+    assert_equal "path/to/public/dir", WebpackerUploader.config.public_path.to_s
+
+    assert_raises(NoMethodError) do
+      WebpackerUploader.configure do |c|
+        c.unknown = true
+      end
+    end
+  end
+
+  def test_pathname_casting
+    WebpackerUploader.config do |c|
+      c.public_manifest_path = "path/to/manifest.json"
+      c.public_path = "path/to/public/dir"
+    end
+
+    assert_instance_of Pathname, WebpackerUploader.config.public_manifest_path
+    assert_instance_of Pathname, WebpackerUploader.config.public_path
+
+    WebpackerUploader.configure do |c|
+      c.public_manifest_path = Pathname.new("path/to/manifest.json")
+      c.public_path = Pathname.new("path/to/public/dir")
+    end
+
+    assert_instance_of Pathname, WebpackerUploader.config.public_manifest_path
+    assert_instance_of Pathname, WebpackerUploader.config.public_path
+  end
+end

data/test/manifest_test.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class ManifestTest < Minitest::Test
+  def setup
+    @manifest = ::WebpackerUploader::Manifest.new
+  end
+
+  def teardown
+    WebpackerUploader.reset!
+  end
+
+  def test_assets
+    assert_includes @manifest.assets, "application.css"
+    assert_includes @manifest.assets, "application.js"
+    assert_includes @manifest.assets, "application.png"
+    refute_includes @manifest.assets, "entrypoints"
+  end
+
+  def test_missing_manifest
+    WebpackerUploader.config.public_manifest_path = "missing.json"
+    @empty_manifest = WebpackerUploader::Manifest.new
+
+    assert_empty @empty_manifest.assets
+  end
+end

data/test/mime_test.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class MimeTest < Minitest::Test
+  def test_for_webp
+    # Rack < 3.x does not support this so we have a fallback mechanism in place
+    assert_equal "image/webp", WebpackerUploader::Mime.mime_type("image-dd6b1cd38bfa093df600.webp")
+  end
+
+  def test_for_sourcemap
+    assert_equal "application/octet-stream", WebpackerUploader::Mime.mime_type("application-dd6b1cd38bfa093df600.css.map")
+  end
+end

data/test/test_app/config/webpacker.yml

@@ -0,0 +1,103 @@
+# Note: You must restart bin/webpack-dev-server for changes to take effect
+
+default: &default
+  source_path: app/javascript
+  source_entry_path: packs
+  public_root_path: public
+  public_output_path: packs
+  cache_path: tmp/cache/webpacker
+  webpack_compile_output: false
+
+  # Additional paths webpack should lookup modules
+  # ['app/assets', 'engine/foo/app/assets']
+  additional_paths:
+    - app/assets
+    - /etc/yarn
+
+  # This configuration option is deprecated and is only here for testing, to
+  # ensure backwards-compatibility. Please use `additional_paths`.
+  resolved_paths:
+    - app/elm
+
+  # Reload manifest.json on all requests so we reload latest compiled packs
+  cache_manifest: false
+
+  # Extract and emit a css file
+  extract_css: false
+
+  static_assets_extensions:
+    - .jpg
+    - .jpeg
+    - .png
+    - .gif
+    - .tiff
+    - .ico
+    - .svg
+
+  extensions:
+    - .mjs
+    - .js
+    - .sass
+    - .scss
+    - .css
+    - .module.sass
+    - .module.scss
+    - .module.css
+    - .png
+    - .svg
+    - .gif
+    - .jpeg
+    - .jpg
+    - .elm
+
+development:
+  <<: *default
+  compile: true
+
+  # Reference: https://webpack.js.org/configuration/dev-server/
+  dev_server:
+    https: false
+    host: localhost
+    port: 3035
+    public: localhost:3035
+    hmr: false
+    # Inline should be set to true if using HMR
+    inline: true
+    overlay: true
+    disable_host_check: true
+    use_local_ip: false
+    pretty: false
+
+test:
+  <<: *default
+  compile: true
+
+  # Compile test packs to a separate directory
+  public_output_path: packs-test
+
+production:
+  <<: *default
+
+  # Production depends on precompilation of packs prior to booting for performance.
+  compile: false
+
+  # Extract and emit a css file
+  extract_css: true
+
+  # Cache manifest.json for performance
+  cache_manifest: true
+
+staging:
+  <<: *default
+
+  # Production depends on precompilation of packs prior to booting for performance.
+  compile: false
+
+  # Extract and emit a css file
+  extract_css: true
+
+  # Cache manifest.json for performance
+  cache_manifest: true
+
+  # Compile staging packs to a separate directory
+  public_output_path: packs-staging