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.



536
537
538
539
540
541
542
543
544
545
546
547
548
 
# File 'documented/internal_api/active_sessions.rb', line 536

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.

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

Returns:

  • (Boolean) 


83
84
85
86
87
88
89
90
 
# File 'documented/internal_api/active_sessions.rb', line 83

def self.enabled?
  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



99
100
101
102
103
 
# File 'documented/internal_api/active_sessions.rb', line 99

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



218
219
220
221
222
223
224
225
226
 
# File 'documented/internal_api/active_sessions.rb', line 218

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



147
148
149
150
151
152
 
# File 'documented/internal_api/active_sessions.rb', line 147

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:



234
235
236
237
238
239
240
241
242
243
 
# File 'documented/internal_api/active_sessions.rb', line 234

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



197
198
199
200
201
202
203
204
205
206
207
 
# File 'documented/internal_api/active_sessions.rb', line 197

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.



252
253
254
255
256
257
258
259
260
261
262
263
264
265
 
# File 'documented/internal_api/active_sessions.rb', line 252

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



175
176
177
178
179
180
 
# File 'documented/internal_api/active_sessions.rb', line 175

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

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