Module: Lich::InternalAPI::ActiveSessions Private

Defined in:
documented/internal_api/active_sessions.rb,
documented/internal_api/active_sessions/client.rb,
documented/internal_api/active_sessions/server.rb,
documented/internal_api/active_sessions/registry.rb,
documented/internal_api/active_sessions/lifecycle.rb

Overview

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

Namespace for active-sessions reporting and lifecycle management.

Coordinates registration and heartbeat updates with the active-sessions service to track live Lich processes and their connection state across the GemStone IV and DragonRealms game worlds.

Defined Under Namespace

Modules: Lifecycle Classes: Client, Registry, Server

Constant Summary collapse

FEATURE_FLAG =

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

Feature flag name that enables the active sessions API.

Returns:

  • (Symbol) 
:active_sessions_api
DEFAULT_HOST =

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

Loopback host used by the local TCP service.

Returns:

'127.0.0.1'
EPHEMERAL_PORT =

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

Port passed to the transport to request an OS-assigned ephemeral port. The actual bound port is read back after Server#start and published in the discovery file.

Returns:

  • (Integer) 
0
DISCOVERY_FILENAME =

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

Filename used to publish the current owner metadata for local clients.

Returns:

'lich-active-sessions.json'
LOCK_FILENAME =

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

Filename of the advisory lock used to elect a single service owner across processes.

Returns:

'lich-active-sessions.lock'

Class Method Summary collapse

Class Method Details

.cleanup_discovery_if_last_session! ⇒ 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.

Removes the discovery file and stops the service when the current process still owns the service and the shared registry is now empty.



561
562
563
564
565
566
567
568
569
570
571
572
573
 
# File 'documented/internal_api/active_sessions.rb', line 561

def self.cleanup_discovery_if_last_session!
  discovery = load_discovery
  return unless discovery[:owner_pid].to_i == Process.pid

  current_snapshot = query_snapshot
  return if current_snapshot[:error]
  return unless current_snapshot[:source] == 'ActiveSessionsAPI'
  return unless current_snapshot[:total].to_i.zero?

  stop_service!
rescue StandardError
  nil
end

.enabled? ⇒ Boolean

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.

Indicates whether the active sessions API is enabled.

An explicit --active-session-dir=PATH CLI flag implies opt-in for this process only -- passing a coordination directory is a clear enough signal of intent that requiring the persisted feature_flag: active_sessions_api row too would just be friction. This never writes to lich_settings; removing the flag on a later launch reverts to whatever the persisted flag says (false by default).

Until feature-flag plumbing is present in core, this API otherwise remains safely dormant and returns empty snapshots.

Returns:

  • (Boolean) 


93
94
95
96
97
98
99
100
101
 
# File 'documented/internal_api/active_sessions.rb', line 93

def self.enabled?
  return true if defined?(ACTIVE_SESSION_DIR) && !ACTIVE_SESSION_DIR.to_s.empty?
  return false unless defined?(Lich::Common::FeatureFlags)

  Lich::Common::FeatureFlags.enabled?(FEATURE_FLAG)
rescue StandardError => e
  Lich.log("warning: ActiveSessions feature flag check failed: #{e.class}: #{e.message}") if Lich.respond_to?(:log)
  false
end

.ensure_service! ⇒ Boolean

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.

Starts the local service if no healthy service is already responding.

The first process to win the ownership lock becomes the in-process server owner. All later callers reuse the same endpoint through the client adapter.

Returns:

  • (Boolean) —

    true when a healthy service is available



110
111
112
113
114
 
# File 'documented/internal_api/active_sessions.rb', line 110

def self.ensure_service!
  return false unless enabled?

  ensure_service_internal!(allow_bootstrap: true)
end

.query_snapshot ⇒ Hash

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.

Queries the currently discovered active-sessions service without consulting the local feature flag state or attempting to bootstrap a new owner.

This is intended for read-only operator tools and CLI queries that may run outside a normal Lich session process. If no service is already available, the result is a normalized fallback payload.

Returns:

  • (Hash) —

    a normalized snapshot or an inert fallback payload



229
230
231
232
233
234
235
236
237
 
# File 'documented/internal_api/active_sessions.rb', line 229

def self.query_snapshot
  response = service_client&.snapshot
  return fallback_snapshot(error: 'active sessions service unavailable') unless response
  return fallback_snapshot(error: response[:error]) unless response[:ok]

  response[:payload]
rescue StandardError => e
  fallback_snapshot(error: e.message)
end

.register_session(payload) ⇒ Boolean

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.

Registers or updates a session record in the local service.

Parameters:

  • payload (Hash) —

    normalized session metadata

Returns:

  • (Boolean) —

    true when the service accepted the update



158
159
160
161
162
163
 
# File 'documented/internal_api/active_sessions.rb', line 158

def self.register_session(payload)
  return false unless enabled?
  return false unless ensure_service!

  service_client&.upsert(payload)&.fetch(:ok, false) || false
end

.service_info ⇒ Hash

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.

Returns sanitized metadata about the current active-sessions service.

The public shape intentionally omits the shared auth token while still exposing enough information for diagnostics and operator visibility.

Returns:



245
246
247
248
249
250
251
252
253
254
 
# File 'documented/internal_api/active_sessions.rb', line 245

def self.service_info
  discovery = load_discovery
  {
    source: 'ActiveSessionsAPI',
    owner_pid: discovery[:owner_pid],
    port: discovery[:port],
    updated_at: discovery[:updated_at],
    service_available: service_available?
  }.compact
end

.snapshot ⇒ Hash

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.

Returns the current active sessions snapshot.

Returns:

  • (Hash) —

    a normalized snapshot or an inert fallback payload



208
209
210
211
212
213
214
215
216
217
218
 
# File 'documented/internal_api/active_sessions.rb', line 208

def self.snapshot
  return fallback_snapshot unless enabled?
  return fallback_snapshot unless ensure_service!

  response = service_client&.snapshot || fallback_snapshot(error: 'active sessions service unavailable')
  return fallback_snapshot(error: response[:error]) unless response[:ok]

  response[:payload]
rescue StandardError => e
  fallback_snapshot(error: e.message)
end

.stop_service! ⇒ 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.

Stops the in-process server if this process owns one, releasing the ownership lock and clearing the published discovery record.

This is intended for explicit service shutdown paths, not ordinary lifecycle teardown for every session consumer.



263
264
265
266
267
268
269
270
271
272
273
274
275
276
 
# File 'documented/internal_api/active_sessions.rb', line 263

def self.stop_service!
  @mutex.synchronize do
    @server&.stop
    @server = nil
    @registry = nil
    release_ownership_lock
  end
  @service_client_mutex.synchronize do
    @service_client = nil
    @service_client_token = nil
    @service_client_port = nil
  end
  delete_discovery_if_owned
end

.unregister_session(pid:) ⇒ Boolean

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.

Removes a session record by pid.

Parameters:

  • pid (Integer)

Returns:

  • (Boolean) —

    true when the service accepted the removal request



186
187
188
189
190
191
 
# File 'documented/internal_api/active_sessions.rb', line 186

def self.unregister_session(pid:)
  return false unless enabled?
  return false unless ensure_service!

  service_client&.remove(pid)&.fetch(:ok, false) || false
end