mongo 2.18.2 → 2.18.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44bd3e615b9e0e11f3803eae60a44b56fe5be326b7dd8f78b3c5aa42fbf7e621
-  data.tar.gz: 124bfd17f02e5b929e8b40dc797146770096270a83f7ea2389890efe83af1fbe
+  metadata.gz: 0c36a5a34e34ad90dc310f1151d98257f36c6c2bbea07282963f631f06a450eb
+  data.tar.gz: 220b2abd528a4f540d08cf08e78e256be845ae5b9bcf41f52f92ce9c98e554b5
 SHA512:
-  metadata.gz: 675df13e076a6a8b94e187e493cefb8fe4e1697cafdb4241898519f55b5abf3cceff7db1e9424bc2defdcba5a218e1bd8b149572ab891319c7c8a42f9699706a
-  data.tar.gz: 7593ef22c16038dc53e7e4e04c615dbc39c083bdffb6ef7d99f583d64613909079c7edb2b5e367117e0b3dca19a0a57ba3eb0ac92701bde48d750557a17cf567
+  metadata.gz: 8fd8cdeee661a65f74b3825db234492357bb82f3b4ec595f0df9477e0b03f62ac093c33d31a0ff7b766868556662b32ee74c3ff87be379cda4bc5363e2e37b0e
+  data.tar.gz: 2d202097305e6b8fa1fba5541fe8d6d630f1beb96cef753294d16ccfbaa1d114547208868d16fc3b48a9e5b897144edff580bcb8edab28123a089f32ded1340e

data/README.md

@@ -5,7 +5,7 @@ MongoDB Ruby Driver
 
 The officially supported Ruby driver for [MongoDB](https://www.mongodb.org/).
 
-The Ruby driver supports Ruby 2.5-3.0 and JRuby 9.2.
+The Ruby driver supports Ruby 2.5-3.2 and JRuby 9.2-9.3.
 
 ## Documentation
 

data/lib/mongo/collection/view/iterable.rb

@@ -185,6 +185,8 @@ module Mongo
             collection.client.log_warn("The :oplog_replay option is deprecated and ignored by MongoDB 4.4 and later")
           end
 
+          maybe_set_tailable_options(spec)
+
           if explained?
             spec[:explain] = options[:explain]
             Operation::Explain.new(spec)
@@ -200,6 +202,19 @@ module Mongo
         def use_query_cache?
           QueryCache.enabled? && !collection.system_collection?
         end
+
+        # Add tailable cusror options to the command specifiction if needed.
+        #
+        # @param [ Hash ] spec The command specification.
+        def maybe_set_tailable_options(spec)
+          case cursor_type
+          when :tailable
+            spec[:tailable] = true
+          when :tailable_await
+            spec[:tailable] = true
+            spec[:await_data] = true
+          end
+        end
       end
     end
   end

data/lib/mongo/collection/view.rb

@@ -127,6 +127,7 @@ module Mongo
       #   return in each response from MongoDB.
       # @option options [ Hash ] :collation The collation to use.
       # @option options [ String ] :comment Associate a comment with the query.
+      # @option options [ :tailable, :tailable_await ] :cursor_type The type of cursor to use.
       # @option options [ Hash ] :explain Execute an explain with the provided
       #   explain options (known options are :verbose and :verbosity) rather
       #   than a find.

data/lib/mongo/crypt/auto_encrypter.rb

@@ -91,6 +91,7 @@ module Mongo
       # @raise [ ArgumentError ] If required options are missing or incorrectly
       #   formatted.
       def initialize(options)
+        Crypt.validate_ffi!
         # Note that this call may eventually, via other method invocations,
         # create additional clients which have to be cleaned up.
         @options = set_default_options(options).freeze

data/lib/mongo/crypt/explicit_encrypter.rb

@@ -36,6 +36,7 @@ module Mongo
       #   should be hashes of TLS connection options. The options are equivalent
       #   to TLS connection options of Mongo::Client.
       def initialize(key_vault_client, key_vault_namespace, kms_providers, kms_tls_options)
+        Crypt.validate_ffi!
         @crypt_handle = Handle.new(
           kms_providers,
           kms_tls_options,

data/lib/mongo/crypt.rb

@@ -35,5 +35,16 @@ module Mongo
     autoload(:ExplicitEncrypter, 'mongo/crypt/explicit_encrypter')
     autoload(:AutoEncrypter, 'mongo/crypt/auto_encrypter')
     autoload(:KMS, 'mongo/crypt/kms')
+
+    def validate_ffi!
+      return if defined?(FFI)
+
+      require 'ffi'
+    rescue LoadError => e
+      raise Error::UnmetDependency, 'Cannot enable encryption because the ffi gem ' \
+                                    "has not been installed. Add \"gem 'ffi'\" to your Gemfile and run " \
+                                    "\"bundle install\" to install the gem. (#{e.class}: #{e})"
+    end
+    module_function :validate_ffi!
   end
 end

data/lib/mongo/grid/file/chunk.rb

@@ -133,11 +133,12 @@ module Mongo
         #
         # @param [ BSON::ByteBuffer ] buffer The encoded BSON buffer to append to.
         # @param [ true, false ] validating_keys Whether keys should be validated when serializing.
+        #   This option is deprecated and will not be used. It will removed in version 3.0.
         #
         # @return [ String ] The raw BSON data.
         #
         # @since 2.0.0
-        def to_bson(buffer = BSON::ByteBuffer.new, validating_keys = BSON::Config.validating_keys?)
+        def to_bson(buffer = BSON::ByteBuffer.new, validating_keys = nil)
           document.to_bson(buffer)
         end
 

data/lib/mongo/grid/file/info.rb

@@ -228,11 +228,12 @@ module Mongo
         #
         # @param [ BSON::ByteBuffer ] buffer The encoded BSON buffer to append to.
         # @param [ true, false ] validating_keys Whether keys should be validated when serializing.
+        #   This option is deprecated and will not be used. It will removed in version 3.0.
         #
         # @return [ String ] The raw BSON data.
         #
         # @since 2.0.0
-        def to_bson(buffer = BSON::ByteBuffer.new, validating_keys = BSON::Config.validating_keys?)
+        def to_bson(buffer = BSON::ByteBuffer.new, validating_keys = nil)
           if @client_md5 && !document[:md5]
             document[:md5] = @client_md5.hexdigest
           end

data/lib/mongo/protocol/bit_vector.rb

@@ -39,9 +39,11 @@ module Mongo
         #
         # @param buffer [ String ] Buffer to receive the serialized vector
         # @param value [ Array<Symbol> ] Array of flags to encode
+        # @param [ true, false ] validating_keys Whether keys should be validated when serializing.
+        #   This option is deprecated and will not be used. It will removed in version 3.0.
         #
         # @return [ String ] Buffer that received the serialized vector
-        def serialize(buffer, value, validating_keys = BSON::Config.validating_keys?)
+        def serialize(buffer, value, validating_keys = nil)
           bits = 0
           value.each { |flag| bits |= (@masks[flag] || 0) }
           buffer.put_int32(bits)

data/lib/mongo/protocol/caching_hash.rb

@@ -38,32 +38,15 @@ module Mongo
       #
       # @param [ BSON::ByteBuffer ] buffer The encoded BSON buffer to append to.
       # @param [ true, false ] validating_keys Whether keys should be validated when serializing.
+      #   This option is deprecated and will not be used. It will removed in version 3.0.
       #
       # @return [ BSON::ByteBuffer ] The buffer with the encoded object.
-      def to_bson(buffer = BSON::ByteBuffer.new, validating_keys = BSON::Config.validating_keys?)
+      def to_bson(buffer = BSON::ByteBuffer.new, validating_keys = nil)
         if !@bytes
-          @bytes = @hash.to_bson(BSON::ByteBuffer.new, validating_keys).to_s
-        elsif needs_validation?(validating_keys)
-          @validated = true
-          return @hash.to_bson(buffer, validating_keys)
+          @bytes = @hash.to_bson(BSON::ByteBuffer.new).to_s
         end
-        @validated ||= validating_keys
         buffer.put_bytes(@bytes)
       end
-
-      private
-
-      # Checks the current value for validating keys, and whether or not this
-      # bson has been validated in the past, and decides if we need to recalculate
-      # the to_bson to check the validations.
-      #
-      # @param [ true, false ] validating_keys Whether keys should be validated when serializing.
-      #
-      # @return [ true, false ] Whether or not the bson needs to be recalculated
-      #   with validation.
-      def needs_validation?(validating_keys)
-        !@validated && validating_keys
-      end
     end
   end
 end

data/lib/mongo/protocol/message.rb

@@ -354,16 +354,16 @@ module Mongo
           if field[:multi]
             value.each do |item|
               if field[:type].respond_to?(:size_limited?)
-                field[:type].serialize(buffer, item, max_bson_size, validating_keys?)
+                field[:type].serialize(buffer, item, max_bson_size)
               else
-                field[:type].serialize(buffer, item, validating_keys?)
+                field[:type].serialize(buffer, item)
               end
             end
           else
             if field[:type].respond_to?(:size_limited?)
-              field[:type].serialize(buffer, value, max_bson_size, validating_keys?)
+              field[:type].serialize(buffer, value, max_bson_size)
             else
-              field[:type].serialize(buffer, value, validating_keys?)
+              field[:type].serialize(buffer, value)
             end
           end
         end
@@ -456,10 +456,6 @@ module Mongo
           field[:type].deserialize(io, options)
         )
       end
-
-      def validating_keys?
-        @options[:validating_keys] if @options
-      end
     end
   end
 end

data/lib/mongo/protocol/msg.rb

@@ -58,6 +58,7 @@ module Mongo
       # @option options [ true, false ] validating_keys Whether keys should be
       #   validated for being valid document keys (i.e. not begin with $ and
       #   not contain dots).
+      #   This option is deprecated and will not be used. It will removed in version 3.0.
       #
       # @api private
       #

data/lib/mongo/protocol/serializers.rb

@@ -51,9 +51,11 @@ module Mongo
         #
         # @param buffer [ String ] Buffer to receive the serialized value.
         # @param value [ String ] Header value to be serialized.
+        # @param [ true, false ] validating_keys Whether keys should be validated when serializing.
+        #   This option is deprecated and will not be used. It will removed in version 3.0.
         #
         # @return [ String ] Buffer with serialized value.
-        def self.serialize(buffer, value, validating_keys = BSON::Config.validating_keys?)
+        def self.serialize(buffer, value, validating_keys = nil)
           buffer.put_bytes(value.pack(HEADER_PACK))
         end
 
@@ -80,7 +82,7 @@ module Mongo
         # @param value [ String ] The string to be serialized.
         #
         # @return [ String ] Buffer with serialized value.
-        def self.serialize(buffer, value, validating_keys = BSON::Config.validating_keys?)
+        def self.serialize(buffer, value, validating_keys = nil)
           buffer.put_cstring(value)
         end
       end
@@ -96,7 +98,7 @@ module Mongo
         # @param value [ Fixnum ] Ignored value.
         #
         # @return [ String ] Buffer with serialized value.
-        def self.serialize(buffer, value, validating_keys = BSON::Config.validating_keys?)
+        def self.serialize(buffer, value, validating_keys = nil)
           buffer.put_int32(ZERO)
         end
       end
@@ -112,7 +114,7 @@ module Mongo
         # @param value [ Integer | BSON::Int32 ] 32-bit integer to be serialized.
         #
         # @return [String] Buffer with serialized value.
-        def self.serialize(buffer, value, validating_keys = BSON::Config.validating_keys?)
+        def self.serialize(buffer, value, validating_keys = nil)
           if value.is_a?(BSON::Int32)
             if value.respond_to?(:value)
               # bson-ruby >= 4.6.0
@@ -146,7 +148,7 @@ module Mongo
         # @param value [ Integer | BSON::Int64 ] 64-bit integer to be serialized.
         #
         # @return [ String ] Buffer with serialized value.
-        def self.serialize(buffer, value, validating_keys = BSON::Config.validating_keys?)
+        def self.serialize(buffer, value, validating_keys = nil)
           if value.is_a?(BSON::Int64)
             if value.respond_to?(:value)
               # bson-ruby >= 4.6.0
@@ -182,19 +184,20 @@ module Mongo
         # @param [ Array<Hash, BSON::Document> ] value The sections to be serialized.
         # @param [ Fixnum ] max_bson_size The max bson size of documents in the sections.
         # @param [ true, false ] validating_keys Whether to validate document keys.
+        #   This option is deprecated and will not be used. It will removed in version 3.0.
         #
         # @return [ BSON::ByteBuffer ] Buffer with serialized value.
         #
         # @since 2.5.0
-        def self.serialize(buffer, value, max_bson_size = nil, validating_keys = BSON::Config.validating_keys?)
+        def self.serialize(buffer, value, max_bson_size = nil, validating_keys = nil)
           value.each do |section|
             case section[:type]
             when PayloadZero::TYPE
-              PayloadZero.serialize(buffer, section[:payload], max_bson_size, false)
+              PayloadZero.serialize(buffer, section[:payload], max_bson_size)
             when nil
-              PayloadZero.serialize(buffer, section[:payload], max_bson_size, false)
+              PayloadZero.serialize(buffer, section[:payload], max_bson_size)
             when PayloadOne::TYPE
-              PayloadOne.serialize(buffer, section[:payload], max_bson_size, validating_keys)
+              PayloadOne.serialize(buffer, section[:payload], max_bson_size)
             else
               raise Error::UnknownPayloadType.new(section[:type])
             end
@@ -259,13 +262,14 @@ module Mongo
           # @param [ BSON::Document, Hash ] value The object to serialize.
           # @param [ Fixnum ] max_bson_size The max bson size of documents in the section.
           # @param [ true, false ] validating_keys Whether to validate document keys.
+          #   This option is deprecated and will not be used. It will removed in version 3.0.
           #
           # @return [ BSON::ByteBuffer ] Buffer with serialized value.
           #
           # @since 2.5.0
-          def self.serialize(buffer, value, max_bson_size = nil, validating_keys = BSON::Config.validating_keys?)
+          def self.serialize(buffer, value, max_bson_size = nil, validating_keys = nil)
             buffer.put_byte(TYPE_BYTE)
-            Serializers::Document.serialize(buffer, value, max_bson_size, validating_keys)
+            Serializers::Document.serialize(buffer, value, max_bson_size)
           end
 
           # Deserializes a section of payload type 0 of an OP_MSG from the IO stream.
@@ -307,17 +311,18 @@ module Mongo
           # @param [ BSON::Document, Hash ] value The object to serialize.
           # @param [ Fixnum ] max_bson_size The max bson size of documents in the section.
           # @param [ true, false ] validating_keys Whether to validate document keys.
+          #   This option is deprecated and will not be used. It will removed in version 3.0.
           #
           # @return [ BSON::ByteBuffer ] Buffer with serialized value.
           #
           # @since 2.5.0
-          def self.serialize(buffer, value, max_bson_size = nil, validating_keys = BSON::Config.validating_keys?)
+          def self.serialize(buffer, value, max_bson_size = nil, validating_keys = nil)
             buffer.put_byte(TYPE_BYTE)
             start = buffer.length
             buffer.put_int32(0) # hold for size
             buffer.put_cstring(value[:identifier])
             value[:sequence].each do |document|
-              Document.serialize(buffer, document, max_bson_size, validating_keys)
+              Document.serialize(buffer, document, max_bson_size)
             end
             buffer.replace_int32(start, buffer.length - start)
           end
@@ -356,9 +361,9 @@ module Mongo
         # @param value [ Hash ] Document to serialize as BSON.
         #
         # @return [ String ] Buffer with serialized value.
-        def self.serialize(buffer, value, max_bson_size = nil, validating_keys = BSON::Config.validating_keys?)
+        def self.serialize(buffer, value, max_bson_size = nil, validating_keys = nil)
           start_size = buffer.length
-          value.to_bson(buffer, validating_keys)
+          value.to_bson(buffer)
           serialized_size = buffer.length - start_size
           if max_bson_size && serialized_size > max_bson_size
             raise Error::MaxBSONSize,
@@ -401,11 +406,12 @@ module Mongo
         # @param [ BSON::ByteBuffer ] buffer Buffer to receive the single byte.
         # @param [ String ] value The byte to write to the buffer.
         # @param [ true, false ] validating_keys Whether to validate keys.
+        #   This option is deprecated and will not be used. It will removed in version 3.0.
         #
         # @return [ BSON::ByteBuffer ] Buffer with serialized value.
         #
         # @since 2.5.0
-        def self.serialize(buffer, value, validating_keys = BSON::Config.validating_keys?)
+        def self.serialize(buffer, value, validating_keys = nil)
           buffer.put_byte(value)
         end
 
@@ -432,11 +438,12 @@ module Mongo
         # @param [ BSON::ByteBuffer ] buffer Buffer to receive the bytes.
         # @param [ String ] value The bytes to write to the buffer.
         # @param [ true, false ] validating_keys Whether to validate keys.
+        #   This option is deprecated and will not be used. It will removed in version 3.0.
         #
         # @return [ BSON::ByteBuffer ] Buffer with serialized value.
         #
         # @since 2.5.0
-        def self.serialize(buffer, value, validating_keys = BSON::Config.validating_keys?)
+        def self.serialize(buffer, value, validating_keys = nil)
           buffer.put_bytes(value)
         end
 

data/lib/mongo/server/app_metadata/environment.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+# Copyright (C) 2016-2023 MongoDB Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Mongo
+  class Server
+    class AppMetadata
+      # Implements the logic from the handshake spec, for deducing and
+      # reporting the current FaaS environment in which the program is
+      # executing.
+      #
+      # @api private
+      class Environment
+        # Error class for reporting that too many discriminators were found
+        # in the environment. (E.g. if the environment reports that it is
+        # running under both AWS and Azure.)
+        class TooManyEnvironments < Mongo::Error; end
+
+        # Error class for reporting that a required environment variable is
+        # missing.
+        class MissingVariable < Mongo::Error; end
+
+        # Error class for reporting that the wrong type was given for a
+        # field.
+        class TypeMismatch < Mongo::Error; end
+
+        # Error class for reporting that the value for a field is too long.
+        class ValueTooLong < Mongo::Error; end
+
+        # This value is not explicitly specified in the spec, only implied to be
+        # less than 512.
+        MAXIMUM_VALUE_LENGTH = 500
+
+        # The mapping that determines which FaaS environment is active, based
+        # on which environment variable(s) are present.
+        DISCRIMINATORS = {
+          'AWS_EXECUTION_ENV' => { pattern: /^AWS_Lambda_/, name: 'aws.lambda' },
+          'AWS_LAMBDA_RUNTIME_API' => { name: 'aws.lambda' },
+          'FUNCTIONS_WORKER_RUNTIME' => { name: 'azure.func' },
+          'K_SERVICE' => { name: 'gcp.func' },
+          'FUNCTION_NAME' => { name: 'gcp.func' },
+          'VERCEL' => { name: 'vercel' },
+        }.freeze
+
+        # Describes how to coerce values of the specified type.
+        COERCIONS = {
+          string: ->(v) { String(v) },
+          integer: ->(v) { Integer(v) }
+        }.freeze
+
+        # Describes which fields are required for each FaaS environment,
+        # along with their expected types, and how they should be named in
+        # the handshake document.
+        FIELDS = {
+          'aws.lambda' => {
+            'AWS_REGION' => { field: :region, type: :string },
+            'AWS_LAMBDA_FUNCTION_MEMORY_SIZE' => { field: :memory_mb, type: :integer },
+          },
+
+          'azure.func' => {},
+
+          'gcp.func' => {
+            'FUNCTION_MEMORY_MB' => { field: :memory_mb, type: :integer },
+            'FUNCTION_TIMEOUT_SEC' => { field: :timeout_sec, type: :integer },
+            'FUNCTION_REGION' => { field: :region, type: :string },
+          },
+
+          'vercel' => {
+            'VERCEL_URL' => { field: :url, type: :string },
+            'VERCEL_REGION' => { field: :region, type: :string },
+          },
+        }.freeze
+
+        # @return [ String | nil ] the name of the FaaS environment that was
+        #   detected, or nil if no valid FaaS environment was detected.
+        attr_reader :name
+
+        # @return [ Hash | nil ] the fields describing the detected FaaS
+        #   environment.
+        attr_reader :fields
+
+        # @return [ String | nil ] the error message explaining why a valid
+        #   FaaS environment was not detected, or nil if no error occurred.
+        #
+        # @note These error messagess are not to be propogated to the
+        #   user; they are intended only for troubleshooting and debugging.)
+        attr_reader :error
+
+        # Create a new AppMetadata::Environment object, initializing it from
+        # the current ENV variables. If no FaaS environment is detected, or
+        # if the environment contains invalid or contradictory state, it will
+        # be initialized with {{name}} set to {{nil}}.
+        def initialize
+          @error = nil
+          @name = detect_environment
+          populate_fields
+        rescue TooManyEnvironments => e
+          self.error = "too many environments detected: #{e.message}"
+        rescue MissingVariable => e
+          self.error = "missing environment variable: #{e.message}"
+        rescue TypeMismatch => e
+          self.error = e.message
+        rescue ValueTooLong => e
+          self.error = "value for #{e.message} is too long"
+        end
+
+        # Queries whether the current environment is a valid FaaS environment.
+        #
+        # @return [ true | false ] whether the environment is a FaaS
+        #   environment or not.
+        def faas?
+          @name != nil
+        end
+
+        # Queries whether the current environment is a valid AWS Lambda
+        # environment.
+        #
+        # @return [ true | false ] whether the environment is a AWS Lambda
+        #   environment or not.
+        def aws?
+          @name == 'aws.lambda'
+        end
+
+        # Queries whether the current environment is a valid Azure
+        # environment.
+        #
+        # @return [ true | false ] whether the environment is a Azure
+        #   environment or not.
+        def azure?
+          @name == 'azure.func'
+        end
+
+        # Queries whether the current environment is a valid GCP
+        # environment.
+        #
+        # @return [ true | false ] whether the environment is a GCP
+        #   environment or not.
+        def gcp?
+          @name == 'gcp.func'
+        end
+
+        # Queries whether the current environment is a valid Vercel
+        # environment.
+        #
+        # @return [ true | false ] whether the environment is a Vercel
+        #   environment or not.
+        def vercel?
+          @name == 'vercel'
+        end
+
+        # Compiles the detected environment information into a Hash. It will
+        # always include a {{name}} key, but may include other keys as well,
+        # depending on the detected FaaS environment. (See the handshake
+        # spec for details.)
+        #
+        # @return [ Hash ] the detected environment information.
+        def to_h
+          fields.merge(name: name)
+        end
+
+        private
+
+        # Searches the DESCRIMINATORS list to see which (if any) apply to
+        # the current environment.
+        #
+        # @return [ String | nil ] the name of the detected FaaS provider.
+        #
+        # @raise [ TooManyEnvironments ] if the environment contains
+        #   discriminating variables for more than one FaaS provider.
+        def detect_environment
+          matches = DISCRIMINATORS.keys.select { |k| discriminator_matches?(k) }
+          names = matches.map { |m| DISCRIMINATORS[m][:name] }.uniq
+
+          raise TooManyEnvironments, names.join(', ') if names.length > 1
+
+          names.first
+        end
+
+        # Determines whether the named environment variable exists, and (if
+        # a pattern has been declared for that descriminator) whether the
+        # pattern matches the value of the variable.
+        #
+        # @param [ String ] var the name of the environment variable
+        #
+        # @return [ true | false ] if the variable describes the current
+        #   environment or not.
+        def discriminator_matches?(var)
+          return false unless ENV[var]
+
+          disc = DISCRIMINATORS[var]
+          return true unless disc[:pattern]
+
+          disc[:pattern].match?(ENV[var])
+        end
+
+        # Extracts environment information from the current environment
+        # variables, based on the detected FaaS environment. Populates the
+        # {{@fields}} instance variable.
+        def populate_fields
+          return unless name
+
+          @fields = FIELDS[name].each_with_object({}) do |(var, defn), fields|
+            fields[defn[:field]] = extract_field(var, defn)
+          end
+        end
+
+        # Extracts the named variable from the environment and validates it
+        # against its declared definition.
+        #
+        # @param [ String ] var The name of the environment variable to look
+        #   for.
+        # @param [ Hash ] definition The definition of the field that applies
+        #   to the named variable.
+        #
+        # @return [ Integer | String ] the validated and coerced value of the
+        #   given environment variable.
+        #
+        # @raise [ MissingVariable ] if the environment does not include a
+        #   variable required by the current FaaS provider.
+        # @raise [ ValueTooLong ] if a required variable is too long.
+        # @raise [ TypeMismatch ] if a required variable cannot be coerced to
+        #   the expected type.
+        def extract_field(var, definition)
+          raise MissingVariable, var unless ENV[var]
+          raise ValueTooLong, var if ENV[var].length > MAXIMUM_VALUE_LENGTH
+
+          COERCIONS[definition[:type]].call(ENV[var])
+        rescue ArgumentError
+          raise TypeMismatch,
+                "#{var} must be #{definition[:type]} (got #{ENV[var].inspect})"
+        end
+
+        # Sets the error message to the given value and sets the name to nil.
+        #
+        # @param [ String ] msg The error message to store.
+        def error=(msg)
+          @name = nil
+          @error = msg
+        end
+      end
+    end
+  end
+end