Class: Turbocable::Configuration

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

Overview

Holds all configuration for the Turbocable gem. Set via Turbocable.configure { |c| … }.

Every attribute that maps to an environment variable is read from the environment at *first access*, not at require time. This means containers that inject env vars after boot (e.g. via secrets sidecars) still work.

NATS auth modes

Exactly one of the following auth strategies may be active at a time:

  1. No auth (default — leave all auth fields nil)

  2. Credentials file (nats_creds_file) — JWT+nkey, used by NGS / managed NATS

  3. User+password (nats_user / nats_password)

  4. Static token (nats_token)

  5. mTLS (nats_tls = true, with optional cert/key/ca paths)

Mixing creds-file with user/token is rejected at #validate!.

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#adapter ⇒ Object

Selects the publish adapter. Accepted values:

  • :nats (default) — publishes to a live NATS JetStream connection.

  • :null — records broadcasts in memory without touching NATS. Intended for test suites; see Turbocable::NullAdapter.

Read from env TURBOCABLE_ADAPTER (+“nats”+ or “null”).



213
 
# File 'lib/turbocable/configuration.rb', line 213

attr_writer :adapter

#default_codec ⇒ Object

Default codec to use when none is specified on broadcast. Must be a key registered in Turbocable::Codecs (e.g. :json, :msgpack). (default: :json)



65
 
# File 'lib/turbocable/configuration.rb', line 65

attr_writer :default_codec

#jwt_issuer ⇒ Object

Optional iss claim added to every minted token. The server does not currently verify iss, but setting it is cheap future-proofing and helps off-platform token debuggers identify the issuer. Read from env TURBOCABLE_JWT_ISSUER.



255
 
# File 'lib/turbocable/configuration.rb', line 255

attr_writer :jwt_issuer

#jwt_kv_bucket ⇒ Object

NATS KV bucket name where the public key is published. Must match the bucket name the server is watching (default: “TC_PUBKEYS”).



266
 
# File 'lib/turbocable/configuration.rb', line 266

attr_writer :jwt_kv_bucket

#jwt_kv_key ⇒ Object

Key within jwt_kv_bucket under which the public key PEM is stored. Default: “rails_public_key” (confirmed in turbocable-server docs).



276
 
# File 'lib/turbocable/configuration.rb', line 276

attr_writer :jwt_kv_key

#jwt_private_key ⇒ Object

PEM-encoded RSA private key used to sign JWTs. Read from env TURBOCABLE_JWT_PRIVATE_KEY (newlines encoded as \n). Required by Turbocable::Auth.issue_token.



228
 
# File 'lib/turbocable/configuration.rb', line 228

attr_writer :jwt_private_key

#jwt_public_key ⇒ Object

PEM-encoded RSA public key corresponding to jwt_private_key. Read from env TURBOCABLE_JWT_PUBLIC_KEY (newlines as \n). Required by Turbocable::Auth.publish_public_key! and Turbocable::Auth.verify_token.

Never assign the private key here — publish_public_key! will detect private-key PEM markers and raise AuthError.



243
 
# File 'lib/turbocable/configuration.rb', line 243

attr_writer :jwt_public_key

#logger ⇒ Object

A Logger-compatible object. Defaults to Logger.new($stdout) at :warn level. Inject Rails.logger or any logger you prefer.



105
 
# File 'lib/turbocable/configuration.rb', line 105

attr_writer :logger

#max_payload_bytes ⇒ Object

Maximum encoded payload size in bytes (default: 1_000_000, matching NATS MaxMsgSize). Payloads that exceed this limit are rejected with PayloadTooLargeError before the connection is touched.



95
 
# File 'lib/turbocable/configuration.rb', line 95

attr_writer :max_payload_bytes

#max_retries ⇒ Object

How many times to retry after a transient NATS failure before raising PublishError (default: 3). A value of 0 disables retries.



84
 
# File 'lib/turbocable/configuration.rb', line 84

attr_writer :max_retries

#nats_creds_file ⇒ Object

Path to a NATS .creds file (JWT+nkey). Used by NGS and managed NATS clusters. Maps to env TURBOCABLE_NATS_CREDENTIALS_PATH. Mutually exclusive with nats_user/nats_token.



123
 
# File 'lib/turbocable/configuration.rb', line 123

attr_writer :nats_creds_file

#nats_password ⇒ Object

Password for NATS user+password auth. Maps to env TURBOCABLE_NATS_PASSWORD.



143
 
# File 'lib/turbocable/configuration.rb', line 143

attr_writer :nats_password

#nats_tls ⇒ Object

Enable TLS for the NATS connection (default: false). Set to true for TLS-only; combine with cert/key/ca fields for mTLS.



163
 
# File 'lib/turbocable/configuration.rb', line 163

attr_writer :nats_tls

#nats_tls_ca_file ⇒ Object

Path to a PEM CA certificate file for verifying the NATS server cert. Maps to env TURBOCABLE_NATS_TLS_CA_PATH.



175
 
# File 'lib/turbocable/configuration.rb', line 175

attr_writer :nats_tls_ca_file

#nats_tls_cert_file ⇒ Object

Path to a PEM client certificate file (mTLS). Maps to env TURBOCABLE_NATS_CERT_PATH.



185
 
# File 'lib/turbocable/configuration.rb', line 185

attr_writer :nats_tls_cert_file

#nats_tls_key_file ⇒ Object

Path to a PEM client private key file (mTLS). Maps to env TURBOCABLE_NATS_KEY_PATH.



195
 
# File 'lib/turbocable/configuration.rb', line 195

attr_writer :nats_tls_key_file

#nats_token ⇒ Object

Static auth token for NATS token auth. Maps to env TURBOCABLE_NATS_AUTH_TOKEN. Mutually exclusive with nats_creds_file.



153
 
# File 'lib/turbocable/configuration.rb', line 153

attr_writer :nats_token

#nats_url ⇒ Object

NATS server URL (default: TURBOCABLE_NATS_URL env or “nats://localhost:4222”).



33
 
# File 'lib/turbocable/configuration.rb', line 33

attr_writer :nats_url

#nats_user ⇒ Object

Username for NATS user+password auth. Maps to env TURBOCABLE_NATS_USER.



133
 
# File 'lib/turbocable/configuration.rb', line 133

attr_writer :nats_user

#publish_timeout ⇒ Object

Maximum seconds to wait for a JetStream publish ack (default: 2.0).



74
 
# File 'lib/turbocable/configuration.rb', line 74

attr_writer :publish_timeout

#stream_name ⇒ Object

JetStream stream name (default: “TURBOCABLE”). Must match the name the server creates — do not change unless you also change the server.



43
 
# File 'lib/turbocable/configuration.rb', line 43

attr_writer :stream_name

#subject_prefix ⇒ Object

NATS subject prefix used when building publish subjects (default: “TURBOCABLE”). A broadcast to stream “chat_room_42” will publish to “TURBOCABLE.chat_room_42”.



54
 
# File 'lib/turbocable/configuration.rb', line 54

attr_writer :subject_prefix

Instance Method Details

#validate! ⇒ void

This method returns an undefined value.

Validates all required fields and raises ConfigurationError on the first violation. Called lazily at publish time, not at configure time.

Raises:



291
292
293
294
 
# File 'lib/turbocable/configuration.rb', line 291

def validate!
  validate_auth_mutual_exclusion!
  validate_tls_paths!
end