Module: Turbocable

Defined in:
lib/turbocable.rb,
lib/turbocable/auth.rb,
lib/turbocable/client.rb,
lib/turbocable/codecs.rb,
lib/turbocable/errors.rb,
lib/turbocable/version.rb,
lib/turbocable/codecs/json.rb,
lib/turbocable/null_adapter.rb,
lib/turbocable/configuration.rb,
lib/turbocable/codecs/msgpack.rb,
lib/turbocable/nats_connection.rb

Overview

codecs/msgpack is loaded lazily on first :msgpack request (requires optional msgpack gem)

Defined Under Namespace

Modules: Auth, Codecs Classes: AuthError, Client, Configuration, ConfigurationError, Error, HealthCheckError, InvalidStreamName, NatsConnection, NullAdapter, PayloadTooLargeError, PublishError, SerializationError

Constant Summary collapse

VERSION = 
"1.0.2"

Class Method Summary collapse

Class Method Details

.broadcast(stream_name, payload, codec: nil) ⇒ NATS::JetStream::PubAck

Publishes payload to the stream identified by stream_name.

This is the primary public API. It delegates to the process-wide Client singleton, creating it on first call.

Parameters:

  • stream_name (String) —

    logical stream name (e.g. “chat_room_42”)

  • payload (Object) —

    any value serializable by the codec

  • codec (Symbol, nil) (defaults to: nil) —

    override the configured default codec

Returns:

  • (NATS::JetStream::PubAck)

Raises:



95
96
97
 
# File 'lib/turbocable.rb', line 95

def broadcast(stream_name, payload, codec: nil)
  client.broadcast(stream_name, payload, codec: codec)
end

.client ⇒ Turbocable::Client

Returns the process-wide Client singleton. Created lazily on first call.

Uses a dedicated mutex separate from the config mutex so that Client.new(config) can call config internally without deadlocking.

Returns:



105
106
107
108
 
# File 'lib/turbocable.rb', line 105

def client
  @client_mutex ||= Mutex.new
  @client_mutex.synchronize { @client ||= Client.new(config) }
end

.config ⇒ Turbocable::Configuration

Returns the process-wide configuration object.

Returns:



35
36
37
38
 
# File 'lib/turbocable.rb', line 35

def config
  @config_mutex ||= Mutex.new
  @config_mutex.synchronize { @config ||= Configuration.new }
end

.configure {|config| ... } ⇒ void

This method returns an undefined value.

Yields the configuration object and then freezes it for thread-safety. May be called multiple times — subsequent calls merge into the existing config rather than replacing it.

Yield Parameters:



46
47
48
 
# File 'lib/turbocable.rb', line 46

def configure
  yield config
end

.healthcheck! ⇒ true

Like healthy? but raises on failure instead of returning false.

Useful for Kubernetes startupProbe handlers or other contexts where an exception is easier to handle than a boolean.

Returns:

  • (true)

Raises:



141
142
143
144
145
146
147
148
149
 
# File 'lib/turbocable.rb', line 141

def healthcheck!
  return true if healthy?

  raise HealthCheckError.new(
    "Turbocable health check failed: NATS is unreachable at " \
    "#{config.nats_url} within #{config.publish_timeout}s. " \
    "Verify the NATS server is running and the publisher is correctly configured."
  )
end

.healthy? ⇒ Boolean

Checks whether the publisher can reach NATS.

For the :nats adapter this issues a NATS flush (PING/PONG round-trip) within config.publish_timeout seconds. For the :null adapter it always returns true.

What this probe does and does not check

A true result means the *publisher process* can reach the *NATS server*. It does not confirm that turbocable-server (the gateway) is running or that messages are being fanned out to WebSocket clients. To check gateway liveness, hit its HTTP endpoint directly:

curl http://turbocable-server:9292/health

For a stricter check that raises on failure see healthcheck!.

Returns:

  • (Boolean) —

    true if NATS is reachable, false otherwise

Raises:



129
130
131
 
# File 'lib/turbocable.rb', line 129

def healthy?
  client.healthy?
end

.reset! ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Resets the configuration and the client singleton. Intended for use in test suites between examples.

Only closes the underlying connection when it is a known real adapter (NatsConnection or NullAdapter). This avoids triggering RSpec mock verification failures when the connection has been replaced with an instance_double in a test.



60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
 
# File 'lib/turbocable.rb', line 60

def reset!
  @config_mutex ||= Mutex.new
  @client_mutex ||= Mutex.new
  @client_mutex.synchronize do
    conn = begin
      @client&.send(:connection)
    rescue
      nil
    end
    if conn.is_a?(NatsConnection) || conn.is_a?(NullAdapter)
      begin
        conn.close
      rescue
        nil
      end
    end
    @client = nil
  end
  @config_mutex.synchronize { @config = nil }
  NullAdapter.reset!
end