class Mongo::Server::AppMetadata

Application metadata that is sent to the server during a handshake,

when a new connection is established.

@api private

Constants

AUTH_OPTION_KEYS

Option keys that affect auth mechanism negotiation.

DRIVER_NAME

The driver name.

MAX_APP_NAME_SIZE

The max application name byte size.

PURPOSES

Possible connection purposes.

Attributes

platform[R]

@return [ String ] The platform information given when the object was

instantiated.
purpose[R]

@return [ Symbol ] The purpose of the connection for which this

app metadata is created.
server_api[R]

@return [ Hash | nil ] The requested server API version.

Thes hash can have the following items:
- *:version* -- string
- *:strict* -- boolean
- *:deprecation_errors* -- boolean
wrapping_libraries[R]

@return [ Array<Hash> | nil ] Information about libraries wrapping

the driver.

Public Class Methods

new(options = {}) click to toggle source

Instantiate the new AppMetadata object.

@example Instantiate the app metadata.

Mongo::Server::AppMetadata.new(options)

@param [ Hash ] options Metadata options. @option options [ String, Symbol ] :app_name Application name that is

printed to the mongod logs upon establishing a connection in server
versions >= 3.4.

@option options [ Symbol ] :auth_mech The authentication mechanism to

use. One of :mongodb_cr, :mongodb_x509, :plain, :scram, :scram256

@option options [ String ] :auth_source The source to authenticate from. @option options [ Array<String> ] :compressors A list of potential

compressors to use, in order of preference. The driver chooses the
first compressor that is also supported by the server. Currently the
driver only supports 'zstd', 'snappy' and 'zlib'.

@option options [ String ] :platform Platform information to include in

the metadata printed to the mongod logs upon establishing a connection
in server versions >= 3.4.

@option options [ Symbol ] :purpose The purpose of this connection. @option options [ Hash ] :server_api The requested server API version.

This hash can have the following items:
- *:version* -- string
- *:strict* -- boolean
- *:deprecation_errors* -- boolean

@option options [ String ] :user The user name. @option options [ Array<Hash> ] :wrapping_libraries Information about

libraries such as ODMs that are wrapping the driver. Specify the
lower level libraries first. Allowed hash keys: :name, :version,
:platform.

@since 2.4.0

# File lib/mongo/server/app_metadata.rb, line 74
def initialize(options = {})
  @app_name = options[:app_name].to_s if options[:app_name]
  @platform = options[:platform]

  @purpose = check_purpose!(options[:purpose])

  @compressors = options[:compressors] || []
  @wrapping_libraries = options[:wrapping_libraries]
  @server_api = options[:server_api]

  return unless options[:user] && !options[:auth_mech]

  auth_db = options[:auth_source] || 'admin'
  @request_auth_mech = "#{auth_db}.#{options[:user]}"
end

Public Instance Methods

client_document() click to toggle source

Get BSON::Document to be used as value for `client` key in handshake document.

@return [BSON::Document] Document describing client for handshake.

# File lib/mongo/server/app_metadata.rb, line 128
def client_document
  @client_document ||=
    BSON::Document.new.tap do |doc|
      doc[:application] = { name: @app_name } if @app_name
      doc[:driver] = driver_doc
      doc[:os] = os_doc
      doc[:platform] = platform_string
      env_doc.tap { |env| doc[:env] = env if env }
    end
end
validated_document() click to toggle source

Get the metadata as BSON::Document to be sent to as part of the handshake. The document should be appended to a suitable handshake command.

This method ensures that the metadata are valid.

@return [BSON::Document] Valid document for connection's handshake.

@raise [ Error::InvalidApplicationName ] When the metadata are invalid.

# File lib/mongo/server/app_metadata.rb, line 119
def validated_document
  validate!
  document
end

Private Instance Methods

architecture() click to toggle source
# File lib/mongo/server/app_metadata.rb, line 211
def architecture
  RbConfig::CONFIG['target_cpu']
end
check_purpose!(purpose) click to toggle source

Verifies that the given purpose is either nil, or is one of the allowed purposes.

@param [ String | nil ] purpose The purpose to validate

@return [ String | nil ] the {{purpose}} argument

@raise [ ArgumentError ] if the purpose is invalid

# File lib/mongo/server/app_metadata.rb, line 227
def check_purpose!(purpose)
  return purpose unless purpose && !PURPOSES.include?(purpose)

  raise ArgumentError, "Invalid purpose: #{purpose}"
end
document() click to toggle source

Get the metadata as BSON::Document to be sent to as part of the handshake. The document should be appended to a suitable handshake command.

@return [BSON::Document] Document for connection's handshake.

# File lib/mongo/server/app_metadata.rb, line 158
def document
  @document ||= begin
    client = Truncator.new(client_document).document
    BSON::Document.new(compression: @compressors, client: client).tap do |doc|
      doc[:saslSupportedMechs] = @request_auth_mech if @request_auth_mech
      doc.update(Utils.transform_server_api(@server_api)) if @server_api
    end
  end
end
driver_doc() click to toggle source
# File lib/mongo/server/app_metadata.rb, line 168
def driver_doc
  names = [ DRIVER_NAME ]
  versions = [ Mongo::VERSION ]
  wrapping_libraries&.each do |library|
    names << (library[:name] || '')
    versions << (library[:version] || '')
  end

  {
    name: names.join('|'),
    version: versions.join('|'),
  }
end
env_doc() click to toggle source

Returns the environment doc describing the current FaaS environment.

@return [ Hash | nil ] the environment doc (or nil if not in a FaaS

environment).
# File lib/mongo/server/app_metadata.rb, line 194
def env_doc
  env = Environment.new
  env.faas? ? env.to_h : nil
end
name() click to toggle source
# File lib/mongo/server/app_metadata.rb, line 207
def name
  RbConfig::CONFIG['host_os']
end
os_doc() click to toggle source
# File lib/mongo/server/app_metadata.rb, line 182
def os_doc
  {
    type: type,
    name: name,
    architecture: architecture,
  }
end
platform_string() click to toggle source
# File lib/mongo/server/app_metadata.rb, line 215
def platform_string
  Platform.new(self).to_s
end
type() click to toggle source
# File lib/mongo/server/app_metadata.rb, line 199
def type
  if RbConfig::CONFIG && RbConfig::CONFIG['host_os']
    RbConfig::CONFIG['host_os'].split('_').first[/[a-z]+/i].downcase
  else
    'unknown'
  end
end
validate!() click to toggle source

Check whether it is possible to build a valid app metadata document with params provided on intialization.

@raise [ Error::InvalidApplicationName ] When the metadata are invalid.

# File lib/mongo/server/app_metadata.rb, line 145
def validate!
  if @app_name && @app_name.bytesize > MAX_APP_NAME_SIZE
    raise Error::InvalidApplicationName.new(@app_name, MAX_APP_NAME_SIZE)
  end

  true
end