mongo 2.26.0 → 2.26.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. checksums.yaml +4 -4
  2. data/lib/mongo/address/validator.rb +14 -9
  3. data/lib/mongo/auth.rb +8 -3
  4. data/lib/mongo/client.rb +40 -9
  5. data/lib/mongo/client_encryption.rb +47 -1
  6. data/lib/mongo/cluster/topology.rb +3 -3
  7. data/lib/mongo/collection/view/aggregation.rb +9 -9
  8. data/lib/mongo/collection/view/change_stream.rb +1 -5
  9. data/lib/mongo/collection/view/iterable.rb +2 -9
  10. data/lib/mongo/collection/view/map_reduce.rb +5 -4
  11. data/lib/mongo/collection/view/readable.rb +3 -3
  12. data/lib/mongo/crypt/auto_encrypter.rb +15 -1
  13. data/lib/mongo/crypt/context.rb +30 -4
  14. data/lib/mongo/crypt/encryption_io.rb +103 -17
  15. data/lib/mongo/crypt/explicit_encrypter.rb +6 -2
  16. data/lib/mongo/csot_timeout_holder.rb +5 -2
  17. data/lib/mongo/cursor.rb +13 -0
  18. data/lib/mongo/database/view.rb +7 -6
  19. data/lib/mongo/database.rb +7 -10
  20. data/lib/mongo/error/invalid_read_option.rb +9 -2
  21. data/lib/mongo/error/invalid_uri.rb +14 -6
  22. data/lib/mongo/index/view.rb +3 -2
  23. data/lib/mongo/monitoring/event/secure.rb +6 -1
  24. data/lib/mongo/operation/map_reduce/result.rb +6 -2
  25. data/lib/mongo/operation/shared/result/aggregatable.rb +3 -3
  26. data/lib/mongo/options/redacted.rb +230 -30
  27. data/lib/mongo/protocol/serializers.rb +1 -9
  28. data/lib/mongo/server/app_metadata.rb +1 -2
  29. data/lib/mongo/server/connection.rb +7 -0
  30. data/lib/mongo/server/connection_pool.rb +60 -9
  31. data/lib/mongo/session.rb +7 -0
  32. data/lib/mongo/socket/ssl.rb +32 -6
  33. data/lib/mongo/srv/resolver.rb +38 -6
  34. data/lib/mongo/srv/result.rb +8 -6
  35. data/lib/mongo/tracing/open_telemetry/command_tracer.rb +142 -103
  36. data/lib/mongo/tracing/open_telemetry/operation_tracer.rb +56 -32
  37. data/lib/mongo/tracing/open_telemetry/tracer.rb +16 -30
  38. data/lib/mongo/uri/options_mapper.rb +44 -22
  39. data/lib/mongo/uri/srv_protocol.rb +18 -11
  40. data/lib/mongo/uri.rb +174 -41
  41. data/lib/mongo/version.rb +1 -1
  42. metadata +545 -537
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 439e028e8b9ce062d109e1760508977f13a87dd6ee4cb9d5221a6a3108fec214
4
- data.tar.gz: bb346a893717256c3eac12af4a63c718bfd4f567b1ec17b95727e45f9f8e11d5
3
+ metadata.gz: a4dfa71c9688fae83124ffe96a6140aa3311f1d39f40463da86a7f4daed87d74
4
+ data.tar.gz: cbaf4ce8e9f68ab04e5f72770b66765d83cddf3daddec159fae022dbf711e687
5
5
  SHA512:
6
- metadata.gz: 3d650edf8067fbe760d1c0526e62bef7cfda7c27284b725ffcc5a8e3c33c712011b3aa478e87db2abea876d36e332daf733d1180954ed6bd1e5003a258a05f49
7
- data.tar.gz: 6832d11c4cae68a7776c8e5f7ef8e5bd9fcbda45bedf8e8cb208fdc5103060582a315cb75434e003462500b4da05deb5e71618a6856159262ff3655fbe16888d
6
+ metadata.gz: 0138b1673aeccd44470a08f6ec2226dc8cca34665bedb0b30351f8f46f05a5fa98390602478d2a22365c253067dc8552f81a78d5c859d98f42c1058275832621
7
+ data.tar.gz: e992ad9fce6e2470ecfbc5565b79a339ceff6178a4719307bbeafad9dc49ec51bf543fb0a59f8d9bf949815dcdae1c34e373c1db4a0e882fa74df2abba8808c7
@@ -20,6 +20,12 @@ module Mongo
20
20
  module Validator
21
21
  # Takes an address string in ipv4/ipv6/hostname/socket path format and
22
22
  # validates its format.
23
+ #
24
+ # Error messages describe the component at fault without quoting the
25
+ # address: a malformed connection string may not have had its
26
+ # credentials delimited, in which case the text being validated is
27
+ # itself the credential. See "Disclosure of Sensitive Values" in the
28
+ # connection string specification.
23
29
  def validate_address_str!(address_str)
24
30
  case address_str
25
31
  when /\A\[[\d:]+\](?::(\d+))?\z/
@@ -41,19 +47,18 @@ module Mongo
41
47
  # Not a host:port nor an ipv4 address with optional port.
42
48
  # Possibly botched ipv6 address with e.g. port delimiter present and
43
49
  # port missing, or extra junk before or after.
44
- raise Error::InvalidAddress,
45
- "Invalid hostname: #{address_str}"
50
+ raise Error::InvalidAddress, 'Invalid host identifier.'
46
51
  when /:.*:/m
47
52
  raise Error::InvalidAddress,
48
- "Multiple port delimiters are not allowed: #{address_str}"
53
+ 'Multiple port delimiters are not allowed in the host identifier.'
49
54
  else
50
55
  # host:port or ipv4 address with optional port number
51
56
  host, port = address_str.split(':')
52
- raise Error::InvalidAddress, "Host is empty: #{address_str}" if host.empty?
57
+ raise Error::InvalidAddress, 'Host is empty.' if host.empty?
53
58
 
54
59
  validate_hostname!(host)
55
60
 
56
- raise Error::InvalidAddress, "Port is empty: #{address_str}" if port && port.empty?
61
+ raise Error::InvalidAddress, 'Port is empty.' if port && port.empty?
57
62
 
58
63
  validate_port_str!(port)
59
64
  end
@@ -72,18 +77,18 @@ module Mongo
72
77
  # and runs of multiple dots. DNS resolution of SRV records yields
73
78
  # hostnames with trailing dots, those trailing dots are removed
74
79
  # during normalization process prior to validation.
75
- raise Error::InvalidAddress, "Hostname cannot start with a dot: #{host}" if host.start_with?('.')
76
- raise Error::InvalidAddress, "Hostname cannot end with a dot: #{host}" if host.end_with?('.')
80
+ raise Error::InvalidAddress, 'Hostname cannot start with a dot.' if host.start_with?('.')
81
+ raise Error::InvalidAddress, 'Hostname cannot end with a dot.' if host.end_with?('.')
77
82
  return unless host.include?('..')
78
83
 
79
- raise Error::InvalidAddress, "Runs of multiple dots are not allowed in hostname: #{host}"
84
+ raise Error::InvalidAddress, 'Runs of multiple dots are not allowed in a hostname.'
80
85
  end
81
86
 
82
87
  def validate_port_str!(port)
83
88
  return if port.nil? || (port.length > 0 && port.to_i > 0 && port.to_i <= 65_535)
84
89
 
85
90
  raise Error::InvalidAddress,
86
- "Invalid port: #{port}. Port must be an integer greater than 0 and less than 65536"
91
+ 'Invalid port. Port must be an integer greater than 0 and less than 65536'
87
92
  end
88
93
  end
89
94
  end
data/lib/mongo/auth.rb CHANGED
@@ -109,17 +109,22 @@ module Mongo
109
109
  class InvalidMechanism < InvalidConfiguration
110
110
  # Instantiate the new error.
111
111
  #
112
+ # The mechanism is not included in the message: an unrecognized value
113
+ # comes from the connection string and may contain text the user
114
+ # intended as a credential. The known mechanisms are listed so the
115
+ # message stays actionable.
116
+ #
112
117
  # @example Instantiate the error.
113
118
  # Mongo::Auth::InvalidMechanism.new(:test)
114
119
  #
115
- # @param [ Symbol ] mechanism The provided mechanism.
120
+ # @param [ Symbol | String | nil ] _mechanism The provided mechanism.
116
121
  #
117
122
  # @since 2.0.0
118
- def initialize(mechanism)
123
+ def initialize(_mechanism = nil)
119
124
  known_mechanisms = SOURCES.keys.sort.map do |key|
120
125
  key.inspect
121
126
  end.join(', ')
122
- super("#{mechanism.inspect} is invalid, please use one of the following mechanisms: #{known_mechanisms}")
127
+ super("Invalid authentication mechanism, please use one of the following mechanisms: #{known_mechanisms}")
123
128
  end
124
129
  end
125
130
 
data/lib/mongo/client.rb CHANGED
@@ -531,6 +531,18 @@ module Mongo
531
531
  # encryption key cache, in milliseconds. Must be a non-negative
532
532
  # integer. A value of 0 means the cache never expires. Defaults to
533
533
  # 60000.
534
+ # - :kms_connect_callback => Proc | Method | #call | nil, a callable
535
+ # invoked as call(host, port, timeout_ms) when the driver needs to
536
+ # reach a KMS host. It must return an fd-backed IO (a real IO or Socket)
537
+ # already connected to host:port (for example, after performing an HTTP
538
+ # CONNECT handshake with a proxy). The driver wraps the returned object
539
+ # in TLS to the KMS host, and Ruby's OpenSSL requires an fd-backed
540
+ # object, so the callback cannot return another OpenSSL::SSL::SSLSocket;
541
+ # a TLS-to-proxy connection needs a socketpair bridge. The driver
542
+ # bounds the call by the connect budget, so a callback that blocks
543
+ # cannot outlive the operation; the callback should still honor
544
+ # timeout_ms for its own work. See Mongo::ClientEncryption#initialize
545
+ # for a usage example.
534
546
  #
535
547
  # Notes on automatic encryption:
536
548
  # - Automatic encryption is an enterprise only feature that only applies
@@ -1345,9 +1357,10 @@ module Mongo
1345
1357
  processed[:addresses] = addresses
1346
1358
  processed[:options] = options
1347
1359
 
1348
- addresses.each do |addr|
1360
+ addresses.each_with_index do |addr, index|
1349
1361
  if %r{\Amongodb(\+srv)?://}i.match?(addr)
1350
- raise ArgumentError, "Host '#{addr}' should not contain protocol. Did you mean to not use an array?"
1362
+ raise ArgumentError, "Host at index #{index} should not contain protocol. " \
1363
+ 'Did you mean to not use an array?'
1351
1364
  end
1352
1365
  end
1353
1366
 
@@ -1496,6 +1509,9 @@ module Mongo
1496
1509
  _options[key] = compressors unless compressors.empty?
1497
1510
  elsif key == :srv_max_hosts
1498
1511
  if v && (!v.is_a?(Integer) || v < 0)
1512
+ # A value for srv_max_hosts that is not a non-negative integer
1513
+ # can only come from the Ruby options: the URI converter drops
1514
+ # such values. It is therefore safe to report it.
1499
1515
  log_warn("#{v} is not a valid integer for srv_max_hosts")
1500
1516
  else
1501
1517
  _options[key] = v
@@ -1541,12 +1557,12 @@ module Mongo
1541
1557
  connect = options[:connect]&.to_sym
1542
1558
 
1543
1559
  if connect && !%i[direct replica_set sharded load_balanced].include?(connect)
1544
- raise ArgumentError, "Invalid :connect option value: #{connect}"
1560
+ raise ArgumentError, 'Invalid :connect option value'
1545
1561
  end
1546
1562
 
1547
1563
  if options[:direct_connection]
1548
1564
  if connect && connect != :direct
1549
- raise ArgumentError, "Conflicting client options: direct_connection=true and connect=#{connect}"
1565
+ raise ArgumentError, 'Conflicting client options: direct_connection=true and a connect option other than direct'
1550
1566
  end
1551
1567
  # When a new client is created, we get the list of seed addresses
1552
1568
  if addresses && addresses.length > 1
@@ -1572,7 +1588,7 @@ module Mongo
1572
1588
  end
1573
1589
 
1574
1590
  if connect && connect != :load_balanced
1575
- raise ArgumentError, "connect=#{connect} cannot be used with load_balanced=true"
1591
+ raise ArgumentError, 'A connect option other than load_balanced cannot be used with load_balanced=true'
1576
1592
  end
1577
1593
 
1578
1594
  raise ArgumentError, 'load_balanced=true cannot be used with replica_set option' if options[:replica_set]
@@ -1587,7 +1603,7 @@ module Mongo
1587
1603
  end
1588
1604
 
1589
1605
  if options[:direct_connection] == false && connect && connect == :direct
1590
- raise ArgumentError, "Conflicting client options: direct_connection=false and connect=#{connect}"
1606
+ raise ArgumentError, 'Conflicting client options: direct_connection=false and connect=direct'
1591
1607
  end
1592
1608
 
1593
1609
  %i[connect_timeout socket_timeout].each do |key|
@@ -1681,6 +1697,18 @@ module Mongo
1681
1697
  raise Mongo::Auth::InvalidConfiguration, "Password is required for auth mechanism #{auth_mech}"
1682
1698
  end
1683
1699
 
1700
+ if auth_mech == :plain
1701
+ if user.include?("\0")
1702
+ raise Mongo::Auth::InvalidConfiguration,
1703
+ 'PLAIN authentication username cannot contain NUL characters'
1704
+ end
1705
+
1706
+ if password.include?("\0")
1707
+ raise Mongo::Auth::InvalidConfiguration,
1708
+ 'PLAIN authentication password cannot contain NUL characters'
1709
+ end
1710
+ end
1711
+
1684
1712
  if password && auth_mech == :mongodb_x509
1685
1713
  raise Mongo::Auth::InvalidConfiguration, 'Password is not supported for :mongodb_x509 auth mechanism'
1686
1714
  end
@@ -1693,7 +1721,7 @@ module Mongo
1693
1721
  if %i[aws gssapi mongodb_x509].include?(auth_mech)
1694
1722
  unless [ '$external', nil ].include?(auth_source)
1695
1723
  raise Mongo::Auth::InvalidConfiguration,
1696
- "#{auth_source} is an invalid auth source for #{auth_mech}; valid options are $external and nil"
1724
+ "Invalid auth source for #{auth_mech}; valid options are $external and nil"
1697
1725
  end
1698
1726
  elsif auth_source == ''
1699
1727
  # Auth source is the database name, and thus cannot be the empty string.
@@ -1712,7 +1740,7 @@ module Mongo
1712
1740
 
1713
1741
  true
1714
1742
  else
1715
- log_warn("Unsupported compressor '#{compressor}' in list '#{compressors}'. " +
1743
+ log_warn('Unsupported compressor in the compressors list. ' +
1716
1744
  'This compressor will not be used.')
1717
1745
  false
1718
1746
  end
@@ -1769,6 +1797,9 @@ module Mongo
1769
1797
  # for custom classes implementing key access ([]).
1770
1798
  # Instead reject common cases of strings and symbols.
1771
1799
  if read.is_a?(String) || read.is_a?(Symbol)
1800
+ # Only a Ruby option can be a bare string or symbol here: URI
1801
+ # parsing always produces a Hash for the read preference. It is
1802
+ # therefore safe to include the value in the message.
1772
1803
  raise Error::InvalidReadOption.new(read,
1773
1804
  "the read preference must be specified as a hash: { mode: #{read.inspect} }")
1774
1805
  end
@@ -1776,7 +1807,7 @@ module Mongo
1776
1807
  if (mode = read[:mode])
1777
1808
  mode = mode.to_sym
1778
1809
  unless Mongo::ServerSelector::PREFERENCES.include?(mode)
1779
- raise Error::InvalidReadOption.new(read, "mode #{mode} is not one of recognized modes")
1810
+ raise Error::InvalidReadOption.new(read, 'the mode is not one of the recognized modes')
1780
1811
  end
1781
1812
  end
1782
1813
  end
@@ -46,6 +46,51 @@ module Mongo
46
46
  # encryption key cache, in milliseconds. Must be a non-negative integer.
47
47
  # An explicit value of 0 means the cache never expires. The default is
48
48
  # 60000.
49
+ # @option options [ Proc | Method | #call ] :kms_connect_callback A callable
50
+ # invoked as +call(host, port, timeout_ms)+ when the driver needs to reach
51
+ # a KMS host. It must return an fd-backed IO (a real +IO+ or +Socket+)
52
+ # already connected to +host:port+ (for example, after performing an HTTP
53
+ # CONNECT handshake with a proxy). The driver wraps the returned object in
54
+ # TLS to the KMS host, and Ruby's OpenSSL requires an fd-backed object, so
55
+ # the callback cannot return another +OpenSSL::SSL::SSLSocket+; a
56
+ # TLS-to-proxy connection needs a socketpair bridge (see the example
57
+ # below). The driver bounds the call by the connect budget (the remaining
58
+ # operation timeout, or the driver's connect timeout when no timeout is
59
+ # set), so a callback that blocks cannot outlive the operation. The
60
+ # callback should still honor +timeout_ms+ for its own work, so it can
61
+ # fail cleanly and close any socket it opened.
62
+ #
63
+ # @example Tunnel KMS traffic through an HTTP CONNECT proxy.
64
+ # connect_via_proxy = lambda do |host, port, timeout_ms|
65
+ # timeout = timeout_ms ? timeout_ms / 1_000.0 : nil
66
+ # socket = Socket.tcp('proxy.example.com', 9004, connect_timeout: timeout)
67
+ # begin
68
+ # socket.write("CONNECT #{host}:#{port} HTTP/1.1\r\n" \
69
+ # "Host: #{host}:#{port}\r\n\r\n")
70
+ # status = socket.gets
71
+ # unless status&.start_with?('HTTP/1.1 200')
72
+ # raise "proxy CONNECT failed: #{status.inspect}"
73
+ # end
74
+ #
75
+ # # Consume the rest of the response headers up to the blank line, so
76
+ # # the TLS handshake does not read them as tunneled bytes.
77
+ # loop do
78
+ # line = socket.gets
79
+ # break if line.nil? || line == "\r\n"
80
+ # end
81
+ # rescue StandardError
82
+ # socket.close
83
+ # raise
84
+ # end
85
+ # socket
86
+ # end
87
+ #
88
+ # client_encryption = Mongo::ClientEncryption.new(
89
+ # key_vault_client,
90
+ # key_vault_namespace: 'keyvault.datakeys',
91
+ # kms_providers: { aws: { access_key_id: '...', secret_access_key: '...' } },
92
+ # kms_connect_callback: connect_via_proxy
93
+ # )
49
94
  #
50
95
  # @raise [ ArgumentError ] If required options are missing or incorrectly
51
96
  # formatted.
@@ -56,7 +101,8 @@ module Mongo
56
101
  Crypt::KMS::Credentials.new(options[:kms_providers]),
57
102
  Crypt::KMS::Validations.validate_tls_options(options[:kms_tls_options]),
58
103
  options[:timeout_ms],
59
- options[:key_expiration_ms]
104
+ options[:key_expiration_ms],
105
+ options[:kms_connect_callback]
60
106
  )
61
107
  end
62
108
 
@@ -90,7 +90,7 @@ module Mongo
90
90
  connect = options[:connect]&.to_sym
91
91
  cls = if options[:direct_connection]
92
92
  if connect && connect != :direct
93
- raise ArgumentError, "Conflicting topology options: direct_connection=true and connect=#{connect}"
93
+ raise ArgumentError, 'Conflicting topology options: direct_connection=true and a connect option other than direct'
94
94
  end
95
95
  if options[:load_balanced]
96
96
  raise ArgumentError, 'Conflicting topology options: direct_connection=true and load_balanced=true'
@@ -98,11 +98,11 @@ module Mongo
98
98
 
99
99
  Single
100
100
  elsif options[:direct_connection] == false && connect && connect == :direct
101
- raise ArgumentError, "Conflicting topology options: direct_connection=false and connect=#{connect}"
101
+ raise ArgumentError, 'Conflicting topology options: direct_connection=false and connect=direct'
102
102
  elsif connect && connect != :load_balanced
103
103
  if options[:load_balanced]
104
104
  raise ArgumentError,
105
- "Conflicting topology options: connect=#{options[:connect].inspect} and load_balanced=true"
105
+ 'Conflicting topology options: a connect option other than load_balanced and load_balanced=true'
106
106
  end
107
107
 
108
108
  OPTIONS.fetch(options[:connect].to_sym)
@@ -115,15 +115,15 @@ module Mongo
115
115
 
116
116
  def send_initial_query(server, context, operation: nil)
117
117
  if server.load_balancer?
118
- # Connection will be checked in when cursor is drained.
119
- connection = server.pool.check_out(context: context)
120
- initial_query_op(
121
- context.session,
122
- effective_read_preference(connection)
123
- ).execute_with_connection(
124
- connection,
125
- context: context
126
- )
118
+ server.pool.with_cursor_connection(context: context) do |connection|
119
+ initial_query_op(
120
+ context.session,
121
+ effective_read_preference(connection)
122
+ ).execute_with_connection(
123
+ connection,
124
+ context: context
125
+ )
126
+ end
127
127
  else
128
128
  server.with_connection do |connection|
129
129
  initial_query_op(
@@ -350,8 +350,7 @@ module Mongo
350
350
  if server.load_balancer?
351
351
  # In load balanced topology, manually check out a connection
352
352
  # so it remains checked out and pinned to the cursor.
353
- connection = server.pool.check_out(context: context)
354
- begin
353
+ server.pool.with_cursor_connection(context: context) do |connection|
355
354
  result = send_initial_query(connection, context)
356
355
 
357
356
  start_at_operation_time = if (doc = result.replies.first && result.replies.first.documents.first)
@@ -360,9 +359,6 @@ module Mongo
360
359
  nil
361
360
  end
362
361
  result
363
- rescue StandardError
364
- server.pool.check_in(connection)
365
- raise
366
362
  end
367
363
  else
368
364
  server.with_connection do |connection|
@@ -172,16 +172,9 @@ module Mongo
172
172
  def send_initial_query(server, context, operation: nil)
173
173
  operation ||= initial_query_op(context.session)
174
174
  if server.load_balancer?
175
- # Connection will be checked in when cursor is drained,
176
- # unless the connection is pinned to a transaction (in which
177
- # case it stays checked out for the transaction duration).
178
- if context.connection_global_id
179
- connection = server.pool.check_out_pinned_connection(
180
- context.connection_global_id
181
- )
175
+ server.pool.with_cursor_connection(context: context) do |connection|
176
+ operation.execute_with_connection(connection, context: context)
182
177
  end
183
- connection ||= server.pool.check_out(context: context)
184
- operation.execute_with_connection(connection, context: context)
185
178
  else
186
179
  operation.execute(server, context: context)
187
180
  end
@@ -73,10 +73,11 @@ module Mongo
73
73
  context = Operation::Context.new(client: client, session: session,
74
74
  operation_timeouts: view.operation_timeouts)
75
75
  if server.load_balancer?
76
- # Connection will be checked in when cursor is drained.
77
- connection = server.pool.check_out(context: context)
78
- result = send_initial_query_with_connection(connection, context.session, context: context)
79
- result = send_fetch_query_with_connection(connection, session) unless inline?
76
+ result = server.pool.with_cursor_connection(context: context) do |connection|
77
+ res = send_initial_query_with_connection(connection, context.session, context: context)
78
+ res = send_fetch_query_with_connection(connection, session) unless inline?
79
+ res
80
+ end
80
81
  else
81
82
  result = send_initial_query(server, context)
82
83
  result = send_fetch_query(server, session) unless inline?
@@ -739,9 +739,9 @@ module Mongo
739
739
  connection_global_id: result.connection_global_id
740
740
  )
741
741
  result = if server.load_balancer?
742
- # Connection will be checked in when cursor is drained.
743
- connection = server.pool.check_out(context: context)
744
- op.execute_with_connection(connection, context: context)
742
+ server.pool.with_cursor_connection(context: context) do |connection|
743
+ op.execute_with_connection(connection, context: context)
744
+ end
745
745
  else
746
746
  op.execute(server, context: context)
747
747
  end
@@ -84,6 +84,19 @@ module Mongo
84
84
  # @option options [ Integer | nil ] :key_expiration_ms The lifetime of the
85
85
  # data encryption key cache, in milliseconds. A value of 0 means the
86
86
  # cache never expires. Defaults to 60000.
87
+ # @option options [ Proc | Method | #call ] :kms_connect_callback A callable
88
+ # invoked as +call(host, port, timeout_ms)+ when the driver needs to
89
+ # reach a KMS host. It must return an fd-backed IO (a real +IO+ or
90
+ # +Socket+) already connected to +host:port+ (for example, after
91
+ # performing an HTTP CONNECT handshake with a proxy). The driver wraps
92
+ # the returned object in TLS to the KMS host, and Ruby's OpenSSL
93
+ # requires an fd-backed object, so the callback cannot return another
94
+ # +OpenSSL::SSL::SSLSocket+; a TLS-to-proxy connection needs a socketpair
95
+ # bridge. +timeout_ms+ is the remaining operation timeout in
96
+ # milliseconds, or nil when no timeout is set. The driver bounds the
97
+ # call by the connect budget, so a callback that blocks cannot outlive
98
+ # the operation; the callback should still honor +timeout_ms+ for its
99
+ # own work. See Mongo::ClientEncryption#initialize for a usage example.
87
100
  #
88
101
  # @raise [ ArgumentError ] If required options are missing or incorrectly
89
102
  # formatted.
@@ -134,7 +147,8 @@ module Mongo
134
147
  key_vault_namespace: @options[:key_vault_namespace],
135
148
  key_vault_client: @key_vault_client,
136
149
  metadata_client: @metadata_client,
137
- mongocryptd_options: @mongocryptd_options
150
+ mongocryptd_options: @mongocryptd_options,
151
+ kms_connect_callback: @options[:kms_connect_callback]
138
152
  )
139
153
  rescue StandardError
140
154
  begin
@@ -95,7 +95,7 @@ module Mongo
95
95
  when :need_mongo_markings
96
96
  provide_markings(timeout_ms)
97
97
  when :need_kms
98
- feed_kms
98
+ feed_kms(timeout_holder)
99
99
  when :need_kms_credentials
100
100
  Binding.ctx_provide_kms_providers(
101
101
  self,
@@ -158,14 +158,27 @@ module Mongo
158
158
  mongocrypt_done
159
159
  end
160
160
 
161
- def feed_kms
161
+ # Sends KMS requests to the KMS provider(s) on behalf of libmongocrypt,
162
+ # retrying transient failures in place.
163
+ #
164
+ # The remaining timeout budget is recomputed for every request: the state
165
+ # machine can need several KMS contexts, and a single context can be
166
+ # retried, so a budget snapshotted once per state-machine iteration would
167
+ # let later attempts run past the operation deadline.
168
+ #
169
+ # @param [ CsotTimeoutHolder ] timeout_holder CSOT timeouts for the
170
+ # operation.
171
+ #
172
+ # @raise [ Error::TimeoutError ] If the operation deadline has passed.
173
+ def feed_kms(timeout_holder)
162
174
  while (kms_context = Binding.ctx_next_kms_ctx(self))
163
175
  begin
164
176
  delay = Binding.kms_ctx_usleep(kms_context)
165
- sleep(delay / 1_000_000.0) unless delay.nil?
177
+ sleep_before_kms_request(delay, timeout_holder) unless delay.nil?
178
+ timeout_ms = timeout_holder.remaining_timeout_ms!
166
179
  provider = Binding.kms_ctx_get_kms_provider(kms_context)
167
180
  tls_options = @mongocrypt_handle.kms_tls_options(provider)
168
- @encryption_io.feed_kms(kms_context, tls_options)
181
+ @encryption_io.feed_kms(kms_context, tls_options, timeout_ms: timeout_ms)
169
182
  rescue Error::KmsError => e
170
183
  raise unless e.network_error?
171
184
  next if Binding.kms_ctx_fail(kms_context)
@@ -176,6 +189,19 @@ module Mongo
176
189
  Binding.ctx_kms_done(self)
177
190
  end
178
191
 
192
+ # Sleep for the backoff libmongocrypt asks for before the next KMS
193
+ # request, clamped so the wait never runs past the operation deadline.
194
+ #
195
+ # @param [ Integer ] delay_us The requested backoff, in microseconds.
196
+ # @param [ CsotTimeoutHolder ] timeout_holder CSOT timeouts for the
197
+ # operation.
198
+ def sleep_before_kms_request(delay_us, timeout_holder)
199
+ delay_sec = delay_us / 1_000_000.0
200
+ remaining_sec = timeout_holder.remaining_timeout_sec
201
+ delay_sec = remaining_sec if remaining_sec && remaining_sec < delay_sec
202
+ sleep(delay_sec) if delay_sec.positive?
203
+ end
204
+
179
205
  # Raise a KmsError that wraps the KMS status message (which describes the
180
206
  # retry exhaustion) with the error from the last attempt.
181
207
  #