Raxol.Core.Session.DistributedSessionRegistry (Raxol v2.0.1)

View Source

Distributed session registry that manages sessions across multiple nodes.

This module provides a distributed session management system that enables horizontal scaling and session continuity across node failures. It uses a combination of consistent hashing, eventual consistency, and conflict resolution to maintain session state across a cluster.

Features

  • Consistent Hashing: Sessions are distributed across nodes using consistent hashing
  • Session Migration: Sessions can be migrated between nodes for load balancing
  • Fault Tolerance: Session state is replicated across multiple nodes
  • Conflict Resolution: Handles session conflicts with last-writer-wins and merge strategies
  • Node Discovery: Automatic discovery and management of cluster nodes
  • Session Replication: Configurable replication factor for session durability

Architecture

The distributed session registry uses a ring-based consistent hashing algorithm to distribute sessions across nodes. Each session is assigned to a primary node and N-1 replica nodes based on the replication factor.

Usage

# Start the distributed registry
{:ok, _pid} = DistributedSessionRegistry.start_link()

# Register a session
DistributedSessionRegistry.register_session(session_id, session_data, [
  affinity: :cpu_bound,
  replicas: 3
])

# Find session location
{:ok, {primary_node, replica_nodes}} =
  DistributedSessionRegistry.locate_session(session_id)

# Migrate session to different node
DistributedSessionRegistry.migrate_session(session_id, target_node)

Summary

Types

node_id()
node_info()
session_affinity()
session_data()
session_id()
session_meta()

Functions

add_node(node_id)

Add a new node to the cluster.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

get_cluster_nodes(pid)

Get list of cluster nodes.

get_cluster_status()

Get cluster status and node information.

get_node_health(pid)

Get node health information.

get_session(session_id)

Get session data from the distributed registry.

handle_manager_cast(msg, state)

Callback implementation for Raxol.Core.Behaviours.BaseManager.handle_manager_cast/2.

list_local_sessions()

List all sessions managed by this node.

list_sessions(pid)

List all sessions in the registry.

locate_session(session_id)

Locate which nodes host a session.

locate_session(pid, session_id)
migrate_session(session_id, target_node)

Migrate a session to a different node.

register_session(session_id, session_data, opts \\ [])

Register a session in the distributed registry.

register_session(pid, session_id, node, opts)
remove_node(node_id)

Remove a node from the cluster (graceful shutdown).

start_link(init_opts \\ [])
sync_sessions()

Force a cluster-wide session synchronization.

unregister_session(session_id)

Remove a session from the distributed registry.

update_session(session_id, session_data)

Update session data in the distributed registry.

Types

node_id()

@type node_id() :: atom()

node_info()

@type node_info() :: %{
  node_id: node_id(),
  last_heartbeat: DateTime.t(),
  cpu_usage: float(),
  memory_usage: float(),
  session_count: non_neg_integer(),
  status: :active | :draining | :unhealthy
}

session_affinity()

@type session_affinity() :: :cpu_bound | :memory_bound | :io_bound | :network_bound

session_data()

@type session_data() :: term()

session_id()

@type session_id() :: String.t()

session_meta()

@type session_meta() :: %{
  session_id: session_id(),
  created_at: DateTime.t(),
  last_accessed: DateTime.t(),
  access_count: non_neg_integer(),
  affinity: session_affinity(),
  replicas: non_neg_integer(),
  version: non_neg_integer(),
  checksum: String.t()
}

Functions

add_node(node_id)

Add a new node to the cluster.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

get_cluster_nodes(pid)

Get list of cluster nodes.

get_cluster_status()

Get cluster status and node information.

get_node_health(pid)

Get node health information.

get_session(session_id)

Get session data from the distributed registry.

handle_manager_cast(msg, state)

Callback implementation for Raxol.Core.Behaviours.BaseManager.handle_manager_cast/2.

list_local_sessions()

List all sessions managed by this node.

list_sessions(pid)

List all sessions in the registry.

locate_session(session_id)

Locate which nodes host a session.

locate_session(pid, session_id)

migrate_session(session_id, target_node)

Migrate a session to a different node.

register_session(session_id, session_data, opts \\ [])

Register a session in the distributed registry.

register_session(pid, session_id, node, opts)

remove_node(node_id)

Remove a node from the cluster (graceful shutdown).

start_link(init_opts \\ [])

sync_sessions()

Force a cluster-wide session synchronization.

unregister_session(session_id)

Remove a session from the distributed registry.

update_session(session_id, session_data)

Update session data in the distributed registry.