add support for named appends

[oreoshake]

Fixes #250

All PRs:

• Has tests
• Documentation updated

@reedloden was this what you had in mind?

This allows you to define blocks of code that produce a hash of additions to be added to the CSP for a given request. The current request object is passed to the block. The result of the hash is passed to append_content_security_policy_directives.

The use case usually is related to loosening a policy's restrictions. While we do provide SecureHeaders::Configuration.override blocks, something like this may be useful with override_content_security_policy_directives as well. I think that the demand for override support like this is pretty rare so I'll wait until there's a need. One example I can think of would be needing to override a directive with 'none', but chances are anything that needs to be set to none would be set in the default config.

Example use:

def show
  if include_widget?
    @widget = widget.render
    use_content_security_policy_named_append(:widget_partial)
  end
end


SecureHeaders::Configuration.named_append(:widget_partial) do |request|
  if request.controller_instance.current_user.in_test_bucket?
    { child_src: %w(beta.thirdpartyhost.com) }
  else
    { child_src: %w(thirdpartyhost.com) }
  end
end

Blocked by #281 - This feature needs to be aware of the csp/csp_report_only config separation and needs to support the target attribute.

[coveralls]

Coverage decreased (-0.03%) to 97.579% when pulling 7abe764 on named-appends into a1d74cf on master.

[coveralls]

Coverage decreased (-0.03%) to 97.579% when pulling 7abe764 on named-appends into a1d74cf on master.

[coveralls]

Coverage decreased (-0.03%) to 97.579% when pulling 7abe764 on named-appends into a1d74cf on master.

[oreoshake]

I disabled @coveralls comments for now.