dotenv 2.7.6 → 3.2.0

data/lib/dotenv.rb

@@ -1,75 +1,133 @@
+require "dotenv/version"
 require "dotenv/parser"
 require "dotenv/environment"
 require "dotenv/missing_keys"
+require "dotenv/diff"
 
-# The top level Dotenv module. The entrypoint for the application logic.
+# Shim to load environment variables from `.env files into `ENV`.
 module Dotenv
-  class << self
-    attr_accessor :instrumenter
-  end
+  extend self
+
+  # An internal monitor to synchronize access to ENV in multi-threaded environments.
+  SEMAPHORE = Monitor.new
+  private_constant :SEMAPHORE
 
-  module_function
+  attr_accessor :instrumenter
 
-  def load(*filenames)
-    with(*filenames) do |f|
-      ignoring_nonexistent_files do
-        env = Environment.new(f, true)
-        instrument("dotenv.load", env: env) { env.apply }
+  # Loads environment variables from one or more `.env` files. See `#parse` for more details.
+  def load(*filenames, overwrite: false, ignore: true)
+    parse(*filenames, overwrite: overwrite, ignore: ignore) do |env|
+      instrument(:load, env: env) do |payload|
+        update(env, overwrite: overwrite)
       end
     end
   end
 
-  # same as `load`, but raises Errno::ENOENT if any files don't exist
+  # Same as `#load`, but raises Errno::ENOENT if any files don't exist
   def load!(*filenames)
-    with(*filenames) do |f|
-      env = Environment.new(f, true)
-      instrument("dotenv.load", env: env) { env.apply }
-    end
+    load(*filenames, ignore: false)
+  end
+
+  # same as `#load`, but will overwrite existing values in `ENV`
+  def overwrite(*filenames)
+    load(*filenames, overwrite: true)
+  end
+  alias_method :overload, :overwrite
+
+  # same as `#overwrite`, but raises Errno::ENOENT if any files don't exist
+  def overwrite!(*filenames)
+    load(*filenames, overwrite: true, ignore: false)
   end
+  alias_method :overload!, :overwrite!
+
+  # Parses the given files, yielding for each file if a block is given.
+  #
+  # @param filenames [String, Array<String>] Files to parse
+  # @param overwrite [Boolean] Overwrite existing `ENV` values
+  # @param ignore [Boolean] Ignore non-existent files
+  # @param block [Proc] Block to yield for each parsed `Dotenv::Environment`
+  # @return [Hash] parsed key/value pairs
+  def parse(*filenames, overwrite: false, ignore: true, &block)
+    filenames << ".env" if filenames.empty?
+    filenames = filenames.reverse if overwrite
 
-  # same as `load`, but will override existing values in `ENV`
-  def overload(*filenames)
-    with(*filenames) do |f|
-      ignoring_nonexistent_files do
-        env = Environment.new(f, false)
-        instrument("dotenv.overload", env: env) { env.apply! }
+    filenames.reduce({}) do |hash, filename|
+      begin
+        env = Environment.new(File.expand_path(filename), overwrite: overwrite)
+        env = block.call(env) if block
+      rescue Errno::ENOENT, Errno::EISDIR
+        raise unless ignore
       end
+
+      hash.merge! env || {}
     end
   end
 
-  # same as `overload`, but raises Errno::ENOENT if any files don't exist
-  def overload!(*filenames)
-    with(*filenames) do |f|
-      env = Environment.new(f, false)
-      instrument("dotenv.overload", env: env) { env.apply! }
+  # Save the current `ENV` to be restored later
+  def save
+    instrument(:save) do |payload|
+      @diff = payload[:diff] = Dotenv::Diff.new
     end
   end
 
-  # returns a hash of parsed key/value pairs but does not modify ENV
-  def parse(*filenames)
-    with(*filenames) do |f|
-      ignoring_nonexistent_files do
-        Environment.new(f, false)
-      end
+  # Restore `ENV` to a given state
+  #
+  # @param env [Hash] Hash of keys and values to restore, defaults to the last saved state
+  # @param safe [Boolean] Is it safe to modify `ENV`? Defaults to `true` in the main thread, otherwise raises an error.
+  def restore(env = @diff&.a, safe: Thread.current == Thread.main)
+    # No previously saved or provided state to restore
+    return unless env
+
+    diff = Dotenv::Diff.new(b: env)
+    return unless diff.any?
+
+    unless safe
+      raise ThreadError, <<~EOE.tr("\n", " ")
+        Dotenv.restore is not thread safe. Use `Dotenv.modify { }` to update ENV for the duration
+        of the block in a thread safe manner, or call `Dotenv.restore(safe: true)` to ignore
+        this error.
+      EOE
     end
+    instrument(:restore, diff: diff) { ENV.replace(env) }
   end
 
-  # Internal: Helper to expand list of filenames.
+  # Update `ENV` with the given hash of keys and values
   #
-  # Returns a hash of all the loaded environment variables.
-  def with(*filenames)
-    filenames << ".env" if filenames.empty?
-
-    filenames.reduce({}) do |hash, filename|
-      hash.merge!(yield(File.expand_path(filename)) || {})
+  # @param env [Hash] Hash of keys and values to set in `ENV`
+  # @param overwrite [Boolean|:warn] Overwrite existing `ENV` values
+  def update(env = {}, overwrite: false)
+    instrument(:update) do |payload|
+      diff = payload[:diff] = Dotenv::Diff.new do
+        ENV.update(env.transform_keys(&:to_s)) do |key, old_value, new_value|
+          # This block is called when a key exists. Return the new value if overwrite is true.
+          case overwrite
+          when :warn
+            # not printing the value since that could be a secret
+            warn "Warning: dotenv not overwriting ENV[#{key.inspect}]"
+            old_value
+          when true then new_value
+          when false then old_value
+          else raise ArgumentError, "Invalid value for overwrite: #{overwrite.inspect}"
+          end
+        end
+      end
+      diff.env
     end
   end
 
-  def instrument(name, payload = {}, &block)
-    if instrumenter
-      instrumenter.instrument(name, payload, &block)
-    else
-      yield
+  # Modify `ENV` for the block and restore it to its previous state afterwards.
+  #
+  # Note that the block is synchronized to prevent concurrent modifications to `ENV`,
+  # so multiple threads will be executed serially.
+  #
+  # @param env [Hash] Hash of keys and values to set in `ENV`
+  def modify(env = {}, &block)
+    SEMAPHORE.synchronize do
+      diff = Dotenv::Diff.new
+      update(env, overwrite: true)
+      block.call
+    ensure
+      restore(diff.a, safe: true)
     end
   end
 
@@ -79,8 +137,15 @@ module Dotenv
     raise MissingKeys, missing_keys
   end
 
-  def ignoring_nonexistent_files
-    yield
-  rescue Errno::ENOENT
+  private
+
+  def instrument(name, payload = {}, &block)
+    if instrumenter
+      instrumenter.instrument("#{name}.dotenv", payload, &block)
+    else
+      block&.call payload
+    end
   end
 end
+
+require "dotenv/rails" if defined?(Rails::Railtie)

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: dotenv
 version: !ruby/object:Gem::Version
-  version: 2.7.6
+  version: 3.2.0
 platform: ruby
 authors:
 - Brandon Keepers
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-07-11 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -39,19 +38,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rubocop
+  name: standard
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.40.0
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.40.0
+        version: '0'
 description: Loads environment variables from `.env`.
 email:
 - brandon@opensoul.org
@@ -64,11 +63,17 @@ files:
 - README.md
 - bin/dotenv
 - lib/dotenv.rb
+- lib/dotenv/autorestore.rb
 - lib/dotenv/cli.rb
+- lib/dotenv/diff.rb
 - lib/dotenv/environment.rb
 - lib/dotenv/load.rb
+- lib/dotenv/log_subscriber.rb
 - lib/dotenv/missing_keys.rb
 - lib/dotenv/parser.rb
+- lib/dotenv/rails-now.rb
+- lib/dotenv/rails.rb
+- lib/dotenv/replay_logger.rb
 - lib/dotenv/substitutions/command.rb
 - lib/dotenv/substitutions/variable.rb
 - lib/dotenv/tasks.rb
@@ -77,8 +82,9 @@ files:
 homepage: https://github.com/bkeepers/dotenv
 licenses:
 - MIT
-metadata: {}
-post_install_message: 
+metadata:
+  changelog_uri: https://github.com/bkeepers/dotenv/releases
+  funding_uri: https://github.com/sponsors/bkeepers
 rdoc_options: []
 require_paths:
 - lib
@@ -86,15 +92,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
-signing_key: 
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Loads environment variables from `.env`.
 test_files: []