diff --git a/CHANGELOG.md b/CHANGELOG.md index 22528e2..658973d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,9 @@ ## Main -Nothing so far +## 0.2.1 + +* Add square brackets setter for settings +* Explain integrations for Bridgetown, Hanami 2 and Rodbot ## 0.2.0 diff --git a/README.md b/README.md index 397ce28..a002731 100644 --- a/README.md +++ b/README.md @@ -37,6 +37,8 @@ And then install the bundle: bundle install --trust-policy MediumSecurity ``` +See [Integrations](#integrations) below for how to integrate Dry::Credentials into frameworks. + ## Usage Extend any class with `Dry::Credentials` to use the [default settings](#defaults): @@ -154,6 +156,109 @@ Setting | Default | Description `digest` | `"sha256"` | sign digest used if the cipher doesn't support AEAD `serializer` | `Marshal` | serializer responding to `dump` and `load` +## Integrations + +### Bridgetown + +The [bridgetown_credentials gem](https://github.com/svoop/bridgetown_credentials) integrates Dry::Credentials into your [Bridgetown](https://www.bridgetownrb.com) site. + +### Hanami 2 + +To use credentials in a [Hanami 2](https//hanami.org) app, first add this gem to the gemfile of the app and then create a provider `config/providers/credentials.rb`: + +```ruby +# frozen_string_literal: true + +Hanami.app.register_provider :credentials do + prepare do + require "dry-credentials" + + Dry::Credentials::Extension.new.then do |credentials| + credentials[:env] = Hanami.env + credentials.load! + register "credentials", credentials + end + end +end +``` + +You might want to add a Rake task `lib/tasks/credentials.rake` as well: + +```ruby +namespace :credentials do + desc "Edit (or create) the encrypted credentials file" + task :edit, [:env] => [:environment] do |_, args| + Hanami.app.prepare(:credentials) + Hanami.app['credentials'].edit! args[:env] + end +end +``` + +(As of Hanami 2.1, you have to [explicitly load such tasks in the Rakefile](https://github.com/hanami/hanami/issues/1375) yourself.) + +You can now create a new credentials file for the development environment: + +``` +rake credentials:edit +``` + +This prints the credentials key you have to set in `.env`: + +``` +DEVELOPMENT_CREDENTIALS_KEY=... +``` + +The credentials are now available anywhere you inject them: + +```ruby +module MyHanamiApp + class ApiKeyPrinter + include Deps[ + "credentials" + ] + + def call + puts credentials.api_key + end + end +end +``` + +You can use the credentials in other providers. Say, you want to pass the [ROM](https://rom-rb.org/) database URL (which contains the connection password) using credentials instead of settings. Simply replace `target["settings"].database_url` with `target["credentials"].database_url` and you're good to go: + +```ruby +Hanami.app.register_provider :persistence, namespace: true do + prepare do + require "rom" + + config = ROM::Configuration.new(:sql, target["credentials"].database_url) + + register "config", config + register "db", config.gateways[:default].connection + end + + (...) +end +``` + +Finally, if you have trouble using the credentials in slices, you might have to [share this app component](https://www.rubydoc.info/gems/hanami/Hanami/Config#shared_app_component_keys-instance_method) in `config/app.rb`: + +```ruby +module MyHanamiApp + class App < Hanami::App + config.shared_app_component_keys += ["credentials"] + end +end +``` + +### Ruby on Rails + +ActiveSupport implements [encrypted configuration](https://www.rubydoc.info/gems/activesupport/ActiveSupport/EncryptedConfiguration) which is used by `rails credentials:edit` [out of the box]((https://guides.rubyonrails.org/security.html#custom-credentials)). There's no benefit from introducing an additional dependency like Dry::Credentials. + +### Rodbot + +Dry::Credentials is integrated into [Rodbot](https://github.com/svoop/rodbot) out of the box, see [the README for more](https://github.com/svoop/rodbot/blob/main/README.md#credentials). + ## Development To install the development dependencies and then run the test suite: diff --git a/lib/dry/credentials/extension.rb b/lib/dry/credentials/extension.rb index 45b7419..a1ac411 100644 --- a/lib/dry/credentials/extension.rb +++ b/lib/dry/credentials/extension.rb @@ -55,6 +55,14 @@ def [](setting) @settings.send(setting) end + # Change settings + # + # @param setting [String] name of the setting + # @param value [Object] new value of the setting + def []=(setting, value) + @settings.send(setting, value) + end + end end end diff --git a/spec/lib/dry/credentials/extension_spec.rb b/spec/lib/dry/credentials/extension_spec.rb index 706cfa8..9811924 100644 --- a/spec/lib/dry/credentials/extension_spec.rb +++ b/spec/lib/dry/credentials/extension_spec.rb @@ -11,6 +11,13 @@ end end + describe :[]= do + it "writes the settings" do + subject.credentials[:serializer] = String + _(subject.credentials[:serializer]).must_equal String + end + end + describe :one_root do it "reads the credentials" do _(subject.credentials.one_root).must_equal 'ONE ROOT'