Jido.Messaging.SessionManager (Jido Messaging v1.0.0)

Partitioned route-state manager for deterministic session routing.

Route state is sharded by session key hash so updates and lookups avoid a singleton bottleneck. Each partition enforces TTL and bounded capacity.

Summary

Types

fallback_reason()

prune_result()

resolution()

route()

route_record()

session_key()

Functions

config(instance_module)

Return manager config merged from defaults, global opts, and instance opts.

get(instance_module, session_key)

Fetch fresh route state for a session key.

partition_count(instance_module)

Return configured partition count.

partition_pid(instance_module, partition)

Return the PID for a partition worker, if running.

prune(instance_module)

Trigger pruning across all partitions and return total expired deletions.

resolve(instance_module, session_key, fallback_routes \\ [])

Resolve a route for a session key, using fallbacks when needed.

route_partition(instance_module, session_key)

Resolve the partition index for a session key.

set(instance_module, session_key, route, opts \\ [])

Store route state for a session key.

Types

fallback_reason()

@type fallback_reason() :: :stale | :miss | :thread_scope_miss | :session_unavailable

prune_result()

@type prune_result() :: %{pruned: non_neg_integer(), partitions: pos_integer()}

resolution()

@type resolution() :: %{
  :external_room_id => term(),
  :route => route(),
  :partition => non_neg_integer(),
  :session_key => session_key(),
  :source => :state_hit | :partition_fallback | :provided_fallback,
  :fallback => boolean(),
  :stale => boolean(),
  optional(:fallback_reason) => fallback_reason()
}

route()

@type route() :: %{
  :external_room_id => term(),
  optional(:channel_type) => atom(),
  optional(:bridge_id) => String.t(),
  optional(:room_id) => String.t() | nil,
  optional(:thread_id) => String.t() | nil,
  optional(atom()) => term()
}

route_record()

@type route_record() :: %{
  route: route(),
  updated_at_ms: integer(),
  expires_at_ms: integer()
}

session_key()

@type session_key() :: Jido.Messaging.SessionKey.t()

Functions

config(instance_module)

@spec config(module()) :: keyword()

Return manager config merged from defaults, global opts, and instance opts.

get(instance_module, session_key)

@spec get(module(), session_key()) ::
  {:ok, route_record()}
  | {:error, :not_found | :expired | :partition_unavailable}

Fetch fresh route state for a session key.

partition_count(instance_module)

@spec partition_count(module()) :: pos_integer()

Return configured partition count.

partition_pid(instance_module, partition)

@spec partition_pid(module(), session_key() | non_neg_integer()) :: pid() | nil

Return the PID for a partition worker, if running.

prune(instance_module)

@spec prune(module()) :: prune_result()

Trigger pruning across all partitions and return total expired deletions.

resolve(instance_module, session_key, fallback_routes \\ [])

@spec resolve(module(), session_key(), [route()] | route()) ::
  {:ok, resolution()} | {:error, term()}

Resolve a route for a session key, using fallbacks when needed.

route_partition(instance_module, session_key)

@spec route_partition(module(), session_key()) :: non_neg_integer()

Resolve the partition index for a session key.

set(instance_module, session_key, route, opts \\ [])

@spec set(module(), session_key(), route(), keyword()) :: :ok | {:error, term()}

Store route state for a session key.