nats_messaging 1.6.0 → 1.7.0

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.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 29004a0c5885d2492ffef134f17af546250d9b24aa6d24bef5410a9dbff5e014
4
- data.tar.gz: a6c1b23843eed5f8391ee1e4f6acbd8274089e3066884c1d5adbfd7a2877e76b
3
+ metadata.gz: d6fe61ff1050738994de1718468ccdaa2b35f86dd5f80743f8b952da20300bcd
4
+ data.tar.gz: e33dd893ba8013b630a49dcd6196835e7a534c5df216d08481932a0f883d0dae
5
5
  SHA512:
6
- metadata.gz: f1ce4f99c59a8e24daef41297201809092350b33631cbfafebf70d703a83fdc9c84bb60d15e545bd2da890910eb97cd4897536664d3a1886c98d9e9266c1b464
7
- data.tar.gz: af5310ce484fcfd98bf497378fa8bfbe018379f211fa8909fe9366866ed82fc31792641afc5f509c40b731ad3071e68b33a67d7402a1c052c2643335a2cdc61f
6
+ metadata.gz: '0390c4cf09fe9f3423cd12b1c92a5e8447953558dd5bca37ddb8cc47ed14a6fa6df1234a39258fc0e9c5e53daa770b6ef19d714a853727a554eb74b037d8530a'
7
+ data.tar.gz: 291a5c3d3bffd7348ac55f3031dbe4e2e6ac033ff7c3170fcdcd0545ae6ced815b745f2f2fdc120af40ed0e14445f5700efefd19b35b0b6deb41725a08aecc3c
@@ -2,7 +2,10 @@ require 'nats/io/client'
2
2
  require 'msgpack'
3
3
  require 'logger'
4
4
  require 'active_support'
5
+ require 'active_support/parameter_filter'
5
6
  require 'active_support/core_ext/hash/indifferent_access'
7
+ require 'timeout'
8
+ require 'json'
6
9
 
7
10
  module NatsMessaging
8
11
  class NatsService
@@ -17,12 +20,39 @@ module NatsMessaging
17
20
  max_outstanding_pings: 2
18
21
  }.freeze
19
22
 
23
+ # nats-pure usa el mismo max_reconnect_attempts tanto para el connect
24
+ # inicial (establish_connection!) como para la reconexión de una conexión
25
+ # ya establecida (attempt_reconnect): con max_reconnect_attempts: -1,
26
+ # can_reuse_server? siempre devuelve true y el connect inicial reintenta
27
+ # para siempre sin lanzar excepción, colgando el arranque del proceso host.
28
+ # El `connect_timeout` propio de nats-pure no sirve para acotar esto: solo
29
+ # limita un intento de conexión TCP/handshake individual, no la cantidad
30
+ # de reintentos. No hay forma nativa en nats-pure 2.5 de distinguir
31
+ # "primer connect" de "reconexión posterior", así que se acota el connect
32
+ # inicial desde afuera con Timeout.
33
+ DEFAULT_INITIAL_CONNECT_TIMEOUT = 15
34
+
35
+ # Los payloads pueden traer documentos en base64 (varios MB) además de
36
+ # tokens/passwords. Además de los filter_parameters, cualquier String que
37
+ # supere este tamaño en bytes se reemplaza en el log por
38
+ # "[FILTERED N bytes]". Se puede desactivar con log_max_value_bytes: nil.
39
+ DEFAULT_LOG_MAX_VALUE_BYTES = 1024
40
+
20
41
  attr_reader :pid
21
42
 
22
- def initialize(nats_url, stream_name: nil, subjects: [], connect_options: {})
43
+ def initialize(nats_url, stream_name: nil, subjects: [], connect_options: {}, initial_connect_timeout: DEFAULT_INITIAL_CONNECT_TIMEOUT, filter_parameters: nil, log_max_value_bytes: DEFAULT_LOG_MAX_VALUE_BYTES)
23
44
  @pid = Process.pid
24
45
  @subscriptions = {} # Store active subscriptions
25
- @nats = NATS.connect(nats_url, DEFAULT_CONNECT_OPTIONS.merge(connect_options))
46
+ @filter_parameters = filter_parameters
47
+ @log_max_value_bytes = log_max_value_bytes
48
+ begin
49
+ @nats = Timeout.timeout(initial_connect_timeout) do
50
+ NATS.connect(nats_url, DEFAULT_CONNECT_OPTIONS.merge(connect_options))
51
+ end
52
+ rescue Timeout::Error
53
+ raise NatsMessaging::InitialConnectTimeoutError,
54
+ "Could not connect to NATS at #{nats_url} within #{initial_connect_timeout}s"
55
+ end
26
56
  register_lifecycle_callbacks
27
57
  if stream_name
28
58
  @js = @nats.jetstream
@@ -34,24 +64,49 @@ module NatsMessaging
34
64
  @logger ||= (defined?(Rails) && Rails.logger) || Logger.new(STDOUT)
35
65
  end
36
66
 
67
+ # Punto de entrada ÚNICO de logging del gem. Todos los +args+ pasan por
68
+ # sanitize_for_log antes de formatearse, de modo que ninguna línea puede
69
+ # escribir un payload o el mensaje de una excepción sin filtrar. No
70
+ # interpolar nada directamente en logger.* dentro del gem.
71
+ #
72
+ # Con +start_time+ (Process.clock_gettime monotónico) el prefijo es
73
+ # "NATS [%.2fs]: "; con nil es "NATS: ". Los args se sustituyen en
74
+ # +message_format+ con String#%: usar %s para texto sin comillas y %p para
75
+ # el inspect (Strings entre comillas, nil como "nil"). +level+ es el nivel
76
+ # del logger; si está deshabilitado se retorna sin sanitizar ni formatear.
77
+ def log_filtered(start_time, message_format, *args, level: :info)
78
+ predicate = :"#{level}?"
79
+ return if logger.respond_to?(predicate) && !logger.public_send(predicate)
80
+
81
+ prefix = if start_time
82
+ format("NATS [%.2fs]: ", Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time)
83
+ else
84
+ "NATS: "
85
+ end
86
+ logger.public_send(level, prefix + (message_format % args.map { |arg| sanitize_for_log(arg) }))
87
+ end
88
+
89
+ # Deprecado: usar log_filtered. Se mantiene por compatibilidad y también filtra.
37
90
  def log_duration(start_time, message_format, *args)
38
- duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
39
- full_message = "NATS [%.2fs]: #{message_format}" % [duration, *args]
40
- logger.info full_message
91
+ log_filtered(start_time, message_format, *args)
41
92
  end
42
93
 
43
94
  def register_lifecycle_callbacks
44
95
  @nats.on_disconnect do |e|
45
- logger.warn "NATS: disconnected#{e ? " (#{e.message})" : ''}"
96
+ if e
97
+ log_filtered(nil, "disconnected (%s)", e, level: :warn)
98
+ else
99
+ log_filtered(nil, "disconnected", level: :warn)
100
+ end
46
101
  end
47
102
  @nats.on_reconnect do
48
- logger.info "NATS: reconnected to #{@nats.connected_server}"
103
+ log_filtered(nil, "reconnected to %s", @nats.connected_server)
49
104
  end
50
105
  @nats.on_error do |e|
51
- logger.error "NATS: error: #{e.message}"
106
+ log_filtered(nil, "error: %s", e, level: :error)
52
107
  end
53
108
  @nats.on_close do
54
- logger.error "NATS: connection CLOSED permanently"
109
+ log_filtered(nil, "connection CLOSED permanently", level: :error)
55
110
  end
56
111
  end
57
112
 
@@ -60,12 +115,12 @@ module NatsMessaging
60
115
  begin
61
116
  start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
62
117
  stream = @js.stream_info(stream_name)
63
- log_duration(start_time, "Stream %s already exists", stream_name)
118
+ log_filtered(start_time, "Stream %s already exists", stream_name)
64
119
  rescue NATS::JetStream::Error::NotFound
65
120
  @js.add_stream(name: stream_name, subjects: subjects)
66
- log_duration(start_time, "Stream %s created", stream_name)
121
+ log_filtered(start_time, "Stream %s created", stream_name)
67
122
  rescue => e
68
- log_duration(start_time, "Failed to create stream: %s", e.message)
123
+ log_filtered(start_time, "Failed to create stream: %s", e, level: :error)
69
124
  end
70
125
  end
71
126
 
@@ -76,20 +131,20 @@ module NatsMessaging
76
131
  begin
77
132
  start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
78
133
  ack = @js.publish(subject, packed_message)
79
- log_duration(start_time, "Message sent to %s: %s, ACK: %s", subject, message, ack.inspect)
134
+ log_filtered(start_time, "Message sent to %s: %s, ACK: %s", subject, message, ack.inspect)
80
135
  rescue NATS::JetStream::Error::NotFound
81
136
  @nats.publish(subject, packed_message)
82
- log_duration(start_time, "Stream not found, falling back to regular NATS publish for subject %s", subject)
137
+ log_filtered(start_time, "Stream not found, falling back to regular NATS publish for subject %s", subject)
83
138
  rescue => e
84
- log_duration(start_time, "Unexpected error while publishing to %s: %s", subject, e.message)
139
+ log_filtered(start_time, "Unexpected error while publishing to %s: %s", subject, e, level: :error)
85
140
  end
86
141
  else
87
142
  begin
88
143
  start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
89
144
  @nats.publish(subject, packed_message)
90
- log_duration(start_time, "Message sent to %s: %s", subject, message)
145
+ log_filtered(start_time, "Message sent to %s: %s", subject, message)
91
146
  rescue => e
92
- log_duration(start_time, "Unexpected error: %s", e.message)
147
+ log_filtered(start_time, "Unexpected error: %s", e, level: :error)
93
148
  end
94
149
  end
95
150
  end
@@ -104,7 +159,7 @@ module NatsMessaging
104
159
 
105
160
  # Subscribe to a subject using MessagePack
106
161
  def subscribe_to_subject(subject, durable_name = "durable_name")
107
- logger.info "NATS: Subscribing to #{subject}"
162
+ log_filtered(nil, "Subscribing to %s", subject)
108
163
  if @js
109
164
  @subscriptions[subject] = @js.subscribe(subject, durable: durable_name) do |msg|
110
165
  unpacked_data = process_received_message(msg, subject)
@@ -127,30 +182,30 @@ module NatsMessaging
127
182
  begin
128
183
  start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
129
184
  unpacked_data = MessagePack.unpack(msg.data)
130
- log_duration(start_time, "Message received on %s: %s", subject, unpacked_data.inspect)
185
+ log_filtered(start_time, "Message received on %s: %p", subject, unpacked_data)
131
186
  unpacked_data
132
187
  rescue => e
133
- log_duration(start_time, "Error while processing message on %s: %s", subject, e.message)
188
+ log_filtered(start_time, "Error while processing message on %s: %s", subject, e, level: :error)
134
189
  end
135
190
  end
136
191
 
137
192
  # Send a request to a subject and wait for response using MessagePack
138
193
  def send_request(subject, message, timeout = 5)
139
- logger.info "NATS: Sending request to #{subject} with message: #{message}"
194
+ log_filtered(nil, "Sending request to %s with message: %s", subject, message)
140
195
  start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
141
196
  begin
142
197
  packed_message = message.to_msgpack # Serializar el mensaje
143
198
  response = @nats.request(subject, packed_message, timeout: timeout) # Timeout of 5 seconds or custom
144
199
  unpacked_response = MessagePack.unpack(response.data) # Deserializar respuesta
145
- log_duration(start_time, "Received reply: %s", unpacked_response.inspect)
200
+ log_filtered(start_time, "Received reply: %p", unpacked_response)
146
201
  indifferent_unpacked_data = make_data_indifferent(unpacked_response)
147
202
  yield(subject, indifferent_unpacked_data) if block_given?
148
203
  indifferent_unpacked_data
149
204
  rescue NATS::IO::Timeout
150
- log_duration(start_time, "Request timed out for subject: %s", subject)
205
+ log_filtered(start_time, "Request timed out for subject: %s", subject)
151
206
  nil
152
207
  rescue => e
153
- log_duration(start_time, "Unexpected error for subject %s: %s", subject, e.message)
208
+ log_filtered(start_time, "Unexpected error for subject %s: %s", subject, e, level: :error)
154
209
  nil
155
210
  end
156
211
  end
@@ -163,13 +218,13 @@ module NatsMessaging
163
218
  end
164
219
  begin
165
220
  # Create a new subscription
166
- logger.info "NATS: Listening on #{subject} with reply message: #{reply_message}"
221
+ log_filtered(nil, "Listening on %s with reply message: %s", subject, reply_message)
167
222
  start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) # En caso de que falle antes del segundo begin
168
223
  @subscriptions[subject] = @nats.subscribe(subject) do |msg|
169
224
  begin
170
225
  start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
171
226
  unpacked_data = MessagePack.unpack(msg.data) # Deserializar mensaje recibido
172
- logger.info "NATS: Received request on #{subject}: #{unpacked_data}"
227
+ log_filtered(nil, "Received request on %s: %s", subject, unpacked_data)
173
228
  indifferent_unpacked_data = make_data_indifferent(unpacked_data)
174
229
  yield_return = yield(subject, indifferent_unpacked_data) if block_given?
175
230
  reply = reply_message.nil? ? yield_return : reply_message
@@ -177,19 +232,120 @@ module NatsMessaging
177
232
  # Asegurar que msg.reply existe antes de responder
178
233
  if msg.reply
179
234
  @nats.publish(msg.reply, packed_reply)
180
- log_duration(start_time, "Replied to %s with message: %s", subject, reply.inspect)
235
+ log_filtered(start_time, "Replied to %s with message: %p", subject, reply)
181
236
  else
182
- log_duration(start_time, "No reply subject for %s, cannot respond", subject)
237
+ log_filtered(start_time, "No reply subject for %s, cannot respond", subject)
183
238
  end
184
239
  indifferent_unpacked_data
185
240
  rescue => e
186
- log_duration(start_time, "Error while processing message on %s: %s", subject, e.message)
241
+ log_filtered(start_time, "Error while processing message on %s: %s", subject, e, level: :error)
187
242
  logger.error e.backtrace.join("\n")
188
243
  end
189
244
  end
190
245
  rescue => e
191
- log_duration(start_time, "Error while replying: %s", e.message)
246
+ log_filtered(start_time, "Error while replying: %s", e, level: :error)
247
+ end
248
+ end
249
+
250
+ private
251
+
252
+ # Devuelve un objeto seguro para formatear: Hash/Array filtrados (sin
253
+ # convertirlos antes a texto), Strings con límite y filtrado de JSON,
254
+ # excepciones como texto sin payload, y el resto limitado en tamaño.
255
+ def sanitize_for_log(obj)
256
+ case obj
257
+ when Hash, Array then filter_for_log(obj)
258
+ when String then sanitize_string(obj)
259
+ when Exception then sanitize_exception(obj)
260
+ when nil, true, false, Numeric, Symbol then obj
261
+ else guard_for_log(obj.inspect)
262
+ end
263
+ rescue StandardError
264
+ # Un fallo al filtrar nunca debe romper el flujo de mensajería.
265
+ "[unloggable #{obj.class}]"
266
+ end
267
+
268
+ # Superado el límite se reemplaza sin parsear nada. Si no, y parece JSON
269
+ # (empieza con { o [), se parsea y se loguea filtrado como JSON; si no
270
+ # parsea o no es Hash/Array se loguea tal cual.
271
+ def sanitize_string(string)
272
+ guarded = guard_for_log(string)
273
+ return guarded unless guarded.equal?(string)
274
+
275
+ parsed = begin
276
+ JSON.parse(string) if string.lstrip.start_with?("{", "[")
277
+ rescue StandardError
278
+ nil
279
+ end
280
+ parsed.is_a?(Hash) || parsed.is_a?(Array) ? filter_for_log(parsed).to_json : string
281
+ end
282
+
283
+ # Clase + mensaje seguro. En NameError/NoMethodError (Ruby < 3.4) y
284
+ # FrozenError el mensaje incluye el inspect del receptor, que puede ser el
285
+ # payload completo: se reconstruye sin receptor. Lo mismo con
286
+ # NoMatchingPatternError (su mensaje es el inspect del valor) y
287
+ # NoMatchingPatternKeyError (valor + clave): de esta última solo se deja la
288
+ # clave. El resto del mensaje pasa por sanitize_string.
289
+ def sanitize_exception(error)
290
+ detail = case error
291
+ when ->(e) { key_error?(e) } then "key not found: #{error.key.inspect}"
292
+ when NoMatchingPatternError then "no pattern matched"
293
+ when NoMethodError then "undefined method '#{error.name}'"
294
+ when NameError then "undefined local variable or constant '#{error.name}'"
295
+ when FrozenError then "can't modify frozen object"
296
+ else sanitize_string(error.message.to_s)
297
+ end
298
+ "#{error.class}: #{detail}"
299
+ end
300
+
301
+ # NoMatchingPatternKeyError existe desde Ruby 3.1 (el gemspec exige >= 3.0).
302
+ def key_error?(error)
303
+ defined?(NoMatchingPatternKeyError) && error.is_a?(NoMatchingPatternKeyError)
304
+ end
305
+
306
+ def filter_for_log(obj)
307
+ case obj
308
+ when Hash then parameter_filter.filter(obj)
309
+ when Array then obj.map { |item| filter_for_log(item) }
310
+ when String then guard_for_log(obj)
311
+ else obj
192
312
  end
193
313
  end
314
+
315
+ # bytesize (y no regex ni length) para soportar encodings inválidos o binarios.
316
+ # Única definición del marcador: la reutiliza el filtro de valores anidados.
317
+ def guard_for_log(string)
318
+ return string if @log_max_value_bytes.nil? || string.bytesize <= @log_max_value_bytes
319
+
320
+ "[FILTERED #{string.bytesize} bytes]"
321
+ end
322
+
323
+ # Resolución perezosa: los initializers de la app agregan filtros a
324
+ # Rails.application.config.filter_parameters después de que el gem se
325
+ # inicializa (y `+=` crea un Array nuevo), así que se lee en cada log y el
326
+ # ParameterFilter se reconstruye si la lista de origen cambió (otro objeto
327
+ # o distinto tamaño).
328
+ def parameter_filter
329
+ source = @filter_parameters || rails_filter_parameters
330
+ size = source.respond_to?(:size) ? source.size : nil
331
+ return @parameter_filter if @parameter_filter && @parameter_filter_source.equal?(source) && @parameter_filter_size == size
332
+
333
+ # ParameterFilter duplica el valor antes de llamar los bloques, por lo
334
+ # que replace no toca el original.
335
+ size_guard = lambda { |_key, value|
336
+ guarded = guard_for_log(value) if value.is_a?(String)
337
+ value.replace(guarded) if guarded && !guarded.equal?(value)
338
+ }
339
+ filter = ActiveSupport::ParameterFilter.new(Array(source) + [size_guard])
340
+ @parameter_filter_source = source
341
+ @parameter_filter_size = size
342
+ @parameter_filter = filter
343
+ end
344
+
345
+ def rails_filter_parameters
346
+ return [] unless defined?(Rails) && Rails.respond_to?(:application) && Rails.application
347
+
348
+ Rails.application.config.filter_parameters
349
+ end
194
350
  end
195
351
  end
@@ -1,6 +1,12 @@
1
1
  require 'nats_messaging/nats_service'
2
2
 
3
3
  module NatsMessaging
4
+ # Se lanza cuando el connect inicial no logra establecerse dentro de
5
+ # initial_connect_timeout segundos. No debe confundirse con las
6
+ # desconexiones posteriores a una conexión ya establecida, que nats-pure
7
+ # reintenta indefinidamente en su propio hilo sin lanzar excepciones.
8
+ class InitialConnectTimeoutError < StandardError; end
9
+
4
10
  # Main entry point to expose the functionalities.
5
11
  #
6
12
  # Memoiza la instancia por PID: si el proceso actual forkeó (Puma/solid_queue)
@@ -8,13 +14,16 @@ module NatsMessaging
8
14
  # socket pertenece al padre) y se descarta sin intentar cerrarla, creando una
9
15
  # instancia nueva con los parámetros de ESTA llamada. Dentro del mismo PID la
10
16
  # memoización ignora los parámetros de llamadas posteriores, igual que antes.
11
- def self.service(nats_url, stream_name: nil, subjects: [], connect_options: {})
17
+ def self.service(nats_url, stream_name: nil, subjects: [], connect_options: {}, initial_connect_timeout: NatsService::DEFAULT_INITIAL_CONNECT_TIMEOUT, filter_parameters: nil, log_max_value_bytes: NatsService::DEFAULT_LOG_MAX_VALUE_BYTES)
12
18
  @service = nil if @service && @service.pid != Process.pid
13
19
  @service ||= NatsService.new(
14
20
  nats_url,
15
21
  stream_name: stream_name,
16
22
  subjects: subjects,
17
- connect_options: connect_options
23
+ connect_options: connect_options,
24
+ initial_connect_timeout: initial_connect_timeout,
25
+ filter_parameters: filter_parameters,
26
+ log_max_value_bytes: log_max_value_bytes
18
27
  )
19
28
  end
20
29
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: nats_messaging
3
3
  version: !ruby/object:Gem::Version
4
- version: 1.6.0
4
+ version: 1.7.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Bea Graboloza
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2026-07-10 00:00:00.000000000 Z
11
+ date: 2026-11-03 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: nats-pure
@@ -107,7 +107,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
107
107
  - !ruby/object:Gem::Version
108
108
  version: '0'
109
109
  requirements: []
110
- rubygems_version: 3.5.16
110
+ rubygems_version: 3.0.9
111
111
  signing_key:
112
112
  specification_version: 4
113
113
  summary: a NATS service for messaging