AssetBomRemoval::Rails

This gem hooks into Rails assets:precompile task and removes the UTF8 Byte Order Mark (BOM) from any CSS files compressed by Sass.

What is a BOM?

The BOM is a sequence of bytes at the start of a unicode text file that are used to tell the computer how to interpret the contents. The BOM is required for UTF-16 because you can write the bytes for each character in big or little endian form. This gem does not remove the UTF-16 BOM. The BOM is optional for UTF-8 files as the standard says there is only one way to write the bytes for each character. Adding it to a file is a hint to the computer for how to interpret the file, but can be safely removed without changing how the file will be interpreted.

Why remove it?

We do this because we want to use SRI on our assets to let users know that neither the assets nor the html have been intercepted and changed between our server and their browser. Unfortunately a bug in Firefox versions < 52 means it calculates the hash incorrectly when the CSS asset has a UTF-8 BOM and refuses to load the asset.

The BOM is generated by SASS versions > 3.4 when the CSS file includes utf-8 characters and in the versions of rails, sass, sprockets, sass-rails, and sprockets-rails we use it is impossible to configure Sass to stop doing this (as mentioned in the sass-rails readme from version 4.0+).

Installation

Add this line to your application's Gemfile:

gem 'asset_bom_removal-rails'

And then execute:

$ bundle

Or install it yourself as:

$ gem install asset_bom_removal-rails

Usage

The gem hooks itself into rails assets pipeline so when you run assets:precompile it will be used. When a css file is compiled with this gem in the app any BOM added by sass will be removed before the compiled CSS is passed to the rest of the asset pipeline to be persisted and added to the manifest.

It should only affect production environments because sass is (by default) only configured to use :compressed style (and thus generate BOMs) in production mode. In development it uses :expanded which does not trigger the BOM insertion.

It replaces the default css_compressor (as configured in rails via config.assets.css_compressor) with a version that strips the BOM. It won't do it if the css_compressor is configured and is not :sass or :scss.

Development

After checking out the repo, run bundle install to install dependencies. Then, run rake spec to run the tests.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/alphagov/asset_bom_removal-rails.

License

The gem is available as open source under the terms of the MIT License.

alphagov / asset_bom_removal-rails Goto Github PK