Class: Parse::LiveQuery::Configuration

Inherits:
Object
  • Object
show all
Defined in:
lib/parse/live_query/configuration.rb

Overview

Centralized configuration for LiveQuery client.

Examples:

Configure LiveQuery

Parse::LiveQuery.configure do |config|
  config.url = "wss://your-server.com"
  config.ping_interval = 20.0
  config.logging_enabled = true
end

Constant Summary collapse

TLS_VERSION_MAP =

Map of TLS version symbols to OpenSSL constants

{
  TLSv1: OpenSSL::SSL::TLS1_VERSION,
  TLSv1_1: OpenSSL::SSL::TLS1_1_VERSION,
  TLSv1_2: OpenSSL::SSL::TLS1_2_VERSION,
  TLSv1_3: OpenSSL::SSL::TLS1_3_VERSION,
}.freeze
VALID_TLS_VERSIONS =

Valid TLS version symbols

[nil, :TLSv1, :TLSv1_1, :TLSv1_2, :TLSv1_3].freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Configuration

Initialize with sensible defaults



135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
 
# File 'lib/parse/live_query/configuration.rb', line 135

def initialize
  # Connection
  @url = nil
  @application_id = nil
  @client_key = nil
  @master_key = nil
  # ACL-scoped by default; opt into admin (ACL-bypassing)
  # connections explicitly. See attr doc above.
  @use_master_key = false
  @auto_connect = true
  @auto_reconnect = true

  # Health monitoring
  @ping_interval = 30.0
  @pong_timeout = 10.0

  # Circuit breaker
  @circuit_failure_threshold = 5
  @circuit_reset_timeout = 60.0

  # Reconnection backoff
  @initial_reconnect_interval = 1.0
  @max_reconnect_interval = 30.0
  @reconnect_multiplier = 1.5
  @reconnect_jitter = 0.2

  # Event queue
  @event_queue_size = 1000
  @backpressure_strategy = :drop_oldest

  # Security
  @max_message_size = 1_048_576  # 1MB
  @frame_read_timeout = 30       # 30 seconds
  @ssl_min_version = :TLSv1_2    # Enforce modern TLS by default
  @ssl_max_version = nil         # No maximum (use highest available)
  @allow_insecure = false        # Refuse ws:// downgrade on non-loopback hosts

  # Logging
  @logging_enabled = false
  @log_level = :info
  @logger = nil
end

Instance Attribute Details

#allow_insecure ⇒ Boolean

Returns when false (default), refuse to derive a ws:// URL from an http:// server URL on any non-loopback host. The default Parse::LiveQuery::Client#derive_websocket_url path silently picks ws:// when the Parse server URL is http://, carrying master keys and session tokens over a cleartext socket. Set to true to explicitly opt into insecure WebSocket transport (local development, container-internal networks). Loopback hosts (localhost, 127.0.0.1, ::1) are exempt and emit a warning instead.

Returns:

  • (Boolean) —

    when false (default), refuse to derive a ws:// URL from an http:// server URL on any non-loopback host. The default Parse::LiveQuery::Client#derive_websocket_url path silently picks ws:// when the Parse server URL is http://, carrying master keys and session tokens over a cleartext socket. Set to true to explicitly opt into insecure WebSocket transport (local development, container-internal networks). Loopback hosts (localhost, 127.0.0.1, ::1) are exempt and emit a warning instead.



95
96
97
 
# File 'lib/parse/live_query/configuration.rb', line 95

def allow_insecure
  @allow_insecure
end

#application_id ⇒ String

Returns Parse application ID.

Returns:

  • (String) —

    Parse application ID



21
22
23
 
# File 'lib/parse/live_query/configuration.rb', line 21

def application_id
  @application_id
end

#auto_connect ⇒ Boolean

Returns automatically connect on client creation (default: true).

Returns:

  • (Boolean) —

    automatically connect on client creation (default: true)



38
39
40
 
# File 'lib/parse/live_query/configuration.rb', line 38

def auto_connect
  @auto_connect
end

#auto_reconnect ⇒ Boolean

Returns automatically reconnect on disconnect (default: true).

Returns:

  • (Boolean) —

    automatically reconnect on disconnect (default: true)



41
42
43
 
# File 'lib/parse/live_query/configuration.rb', line 41

def auto_reconnect
  @auto_reconnect
end

#backpressure_strategy ⇒ Symbol

Returns backpressure strategy :block, :drop_oldest, :drop_newest (default: :drop_oldest).

Returns:

  • (Symbol) —

    backpressure strategy :block, :drop_oldest, :drop_newest (default: :drop_oldest)



75
76
77
 
# File 'lib/parse/live_query/configuration.rb', line 75

def backpressure_strategy
  @backpressure_strategy
end

#circuit_failure_threshold ⇒ Integer

Circuit breaker settings

Returns:

  • (Integer) —

    failures before circuit opens (default: 5)



52
53
54
 
# File 'lib/parse/live_query/configuration.rb', line 52

def circuit_failure_threshold
  @circuit_failure_threshold
end

#circuit_reset_timeout ⇒ Float

Returns seconds before circuit transitions to half-open (default: 60.0).

Returns:

  • (Float) —

    seconds before circuit transitions to half-open (default: 60.0)



55
56
57
 
# File 'lib/parse/live_query/configuration.rb', line 55

def circuit_reset_timeout
  @circuit_reset_timeout
end

#client_key ⇒ String

Returns Parse client key.

Returns:

  • (String) —

    Parse client key



24
25
26
 
# File 'lib/parse/live_query/configuration.rb', line 24

def client_key
  @client_key
end

#event_queue_size ⇒ Integer

Event queue settings

Returns:

  • (Integer) —

    maximum queued events before backpressure (default: 1000)



72
73
74
 
# File 'lib/parse/live_query/configuration.rb', line 72

def event_queue_size
  @event_queue_size
end

#frame_read_timeout ⇒ Integer

Returns frame read timeout in seconds (default: 30) Prevents indefinite blocking when reading from socket.

Returns:

  • (Integer) —

    frame read timeout in seconds (default: 30) Prevents indefinite blocking when reading from socket



84
85
86
 
# File 'lib/parse/live_query/configuration.rb', line 84

def frame_read_timeout
  @frame_read_timeout
end

#initial_reconnect_interval ⇒ Float

Reconnection backoff settings

Returns:

  • (Float) —

    initial reconnect delay in seconds (default: 1.0)



59
60
61
 
# File 'lib/parse/live_query/configuration.rb', line 59

def initial_reconnect_interval
  @initial_reconnect_interval
end

#log_level ⇒ Symbol

Returns log level :debug, :info, :warn, :error (default: :info).

Returns:

  • (Symbol) —

    log level :debug, :info, :warn, :error (default: :info)



129
130
131
 
# File 'lib/parse/live_query/configuration.rb', line 129

def log_level
  @log_level
end

#logger ⇒ Logger?

Returns custom logger instance (default: nil, uses STDOUT).

Returns:

  • (Logger, nil) —

    custom logger instance (default: nil, uses STDOUT)



132
133
134
 
# File 'lib/parse/live_query/configuration.rb', line 132

def logger
  @logger
end

#logging_enabled ⇒ Boolean

Logging settings

Returns:

  • (Boolean) —

    enable structured logging (default: false)



126
127
128
 
# File 'lib/parse/live_query/configuration.rb', line 126

def logging_enabled
  @logging_enabled
end

#master_key ⇒ String

Returns Parse master key (optional).

Returns:

  • (String) —

    Parse master key (optional)



27
28
29
 
# File 'lib/parse/live_query/configuration.rb', line 27

def master_key
  @master_key
end

#max_message_size ⇒ Integer

Security settings

Returns:

  • (Integer) —

    maximum WebSocket message size in bytes (default: 1MB) Prevents memory exhaustion from malicious oversized frames



80
81
82
 
# File 'lib/parse/live_query/configuration.rb', line 80

def max_message_size
  @max_message_size
end

#max_reconnect_interval ⇒ Float

Returns maximum reconnect delay in seconds (default: 30.0).

Returns:

  • (Float) —

    maximum reconnect delay in seconds (default: 30.0)



62
63
64
 
# File 'lib/parse/live_query/configuration.rb', line 62

def max_reconnect_interval
  @max_reconnect_interval
end

#ping_interval ⇒ Float

Health monitoring settings

Returns:

  • (Float) —

    seconds between ping frames (default: 30.0)



45
46
47
 
# File 'lib/parse/live_query/configuration.rb', line 45

def ping_interval
  @ping_interval
end

#pong_timeout ⇒ Float

Returns seconds to wait for pong response (default: 10.0).

Returns:

  • (Float) —

    seconds to wait for pong response (default: 10.0)



48
49
50
 
# File 'lib/parse/live_query/configuration.rb', line 48

def pong_timeout
  @pong_timeout
end

#reconnect_jitter ⇒ Float

Returns jitter factor for reconnect delay, 0.0-1.0 (default: 0.2).

Returns:

  • (Float) —

    jitter factor for reconnect delay, 0.0-1.0 (default: 0.2)



68
69
70
 
# File 'lib/parse/live_query/configuration.rb', line 68

def reconnect_jitter
  @reconnect_jitter
end

#reconnect_multiplier ⇒ Float

Returns reconnect delay multiplier (default: 1.5).

Returns:

  • (Float) —

    reconnect delay multiplier (default: 1.5)



65
66
67
 
# File 'lib/parse/live_query/configuration.rb', line 65

def reconnect_multiplier
  @reconnect_multiplier
end

#ssl_max_version ⇒ Symbol?

Returns maximum TLS version :TLSv1, :TLSv1_1, :TLSv1_2, :TLSv1_3 (default: nil = highest available) Caps the maximum TLS version (rarely needed, use for compatibility).

Returns:

  • (Symbol, nil) —

    maximum TLS version :TLSv1, :TLSv1_1, :TLSv1_2, :TLSv1_3 (default: nil = highest available) Caps the maximum TLS version (rarely needed, use for compatibility)



103
104
105
 
# File 'lib/parse/live_query/configuration.rb', line 103

def ssl_max_version
  @ssl_max_version
end

#ssl_min_version ⇒ Symbol?

Returns minimum TLS version :TLSv1, :TLSv1_1, :TLSv1_2, :TLSv1_3 (default: :TLSv1_2) Enforces minimum TLS version for WebSocket connections.

Returns:

  • (Symbol, nil) —

    minimum TLS version :TLSv1, :TLSv1_1, :TLSv1_2, :TLSv1_3 (default: :TLSv1_2) Enforces minimum TLS version for WebSocket connections



99
100
101
 
# File 'lib/parse/live_query/configuration.rb', line 99

def ssl_min_version
  @ssl_min_version
end

#url ⇒ String

Connection settings

Returns:

  • (String) —

    WebSocket URL for LiveQuery server



18
19
20
 
# File 'lib/parse/live_query/configuration.rb', line 18

def url
  @url
end

#use_master_key ⇒ Boolean

Returns build admin connections that send the master key on the connect frame, bypassing ACL/CLP for ALL subscriptions. Defaults to false — connections are ACL-scoped. Set true ONLY for dedicated admin/event-tap consumers; never for clients that serve end-user, session-scoped streams. See Parse::LiveQuery::Client#use_master_key.

Returns:

  • (Boolean) —

    build admin connections that send the master key on the connect frame, bypassing ACL/CLP for ALL subscriptions. Defaults to false — connections are ACL-scoped. Set true ONLY for dedicated admin/event-tap consumers; never for clients that serve end-user, session-scoped streams. See Parse::LiveQuery::Client#use_master_key.



35
36
37
 
# File 'lib/parse/live_query/configuration.rb', line 35

def use_master_key
  @use_master_key
end

Class Method Details

.tls_version_constant(version) ⇒ Integer?

Convert a TLS version symbol to OpenSSL constant

Parameters:

  • version (Symbol, nil) —

    TLS version symbol

Returns:

  • (Integer, nil) —

    OpenSSL TLS version constant or nil



119
120
121
122
 
# File 'lib/parse/live_query/configuration.rb', line 119

def self.tls_version_constant(version)
  return nil if version.nil?
  TLS_VERSION_MAP[version]
end

Instance Method Details

#to_h ⇒ Hash

Convert to hash

Returns:



207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
 
# File 'lib/parse/live_query/configuration.rb', line 207

def to_h
  {
    url: @url,
    application_id: @application_id,
    client_key: @client_key.nil? ? nil : "[REDACTED]",
    master_key: @master_key.nil? ? nil : "[REDACTED]",
    use_master_key: @use_master_key,
    auto_connect: @auto_connect,
    auto_reconnect: @auto_reconnect,
    ping_interval: @ping_interval,
    pong_timeout: @pong_timeout,
    circuit_failure_threshold: @circuit_failure_threshold,
    circuit_reset_timeout: @circuit_reset_timeout,
    initial_reconnect_interval: @initial_reconnect_interval,
    max_reconnect_interval: @max_reconnect_interval,
    reconnect_multiplier: @reconnect_multiplier,
    reconnect_jitter: @reconnect_jitter,
    event_queue_size: @event_queue_size,
    backpressure_strategy: @backpressure_strategy,
    max_message_size: @max_message_size,
    frame_read_timeout: @frame_read_timeout,
    ssl_min_version: @ssl_min_version,
    ssl_max_version: @ssl_max_version,
    logging_enabled: @logging_enabled,
    log_level: @log_level,
  }
end

#valid? ⇒ Boolean

Check if configuration is valid

Returns:

  • (Boolean) 


201
202
203
 
# File 'lib/parse/live_query/configuration.rb', line 201

def valid?
  validate.empty?
end

#validate ⇒ Array<String>

Validate configuration

Returns:



180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
 
# File 'lib/parse/live_query/configuration.rb', line 180

def validate
  errors = []
  errors << "ping_interval must be positive" if @ping_interval && @ping_interval <= 0
  errors << "pong_timeout must be positive" if @pong_timeout && @pong_timeout <= 0
  errors << "circuit_failure_threshold must be positive" if @circuit_failure_threshold && @circuit_failure_threshold <= 0
  errors << "event_queue_size must be positive" if @event_queue_size && @event_queue_size <= 0
  errors << "reconnect_jitter must be between 0.0 and 1.0" if @reconnect_jitter && (@reconnect_jitter < 0.0 || @reconnect_jitter > 1.0)
  errors << "backpressure_strategy must be :block, :drop_oldest, or :drop_newest" unless [:block, :drop_oldest, :drop_newest].include?(@backpressure_strategy)
  errors << "max_message_size must be positive" if @max_message_size && @max_message_size <= 0
  errors << "frame_read_timeout must be positive" if @frame_read_timeout && @frame_read_timeout <= 0
  errors << "log_level must be :debug, :info, :warn, or :error" unless [:debug, :info, :warn, :error].include?(@log_level)

  # SSL/TLS version validation
  errors << "ssl_min_version must be nil, :TLSv1, :TLSv1_1, :TLSv1_2, or :TLSv1_3" unless VALID_TLS_VERSIONS.include?(@ssl_min_version)
  errors << "ssl_max_version must be nil, :TLSv1, :TLSv1_1, :TLSv1_2, or :TLSv1_3" unless VALID_TLS_VERSIONS.include?(@ssl_max_version)

  errors
end