Phoenix.SocketClient.Router (phoenix_socket_client v0.8.1)

High-performance message routing utilities.

This module provides optimized message routing functions that use the route cache for fast channel discovery while falling back to Registry lookups when necessary.

Features

Cached route lookups for performance
Automatic cache population on successful lookups
Fallback to Registry for cache misses
Route statistics and monitoring
Configurable routing strategies

Usage

The router is used internally by message processing components to provide fast channel-to-process mapping.

Performance Benefits

O(1) cached lookups vs O(n) Registry operations
Automatic cache warming for frequently accessed channels
Reduced process discovery overhead
Scalable routing for high message volumes

Summary

Types

opts()

Routing options

Functions

clear_cache(cache_pid)

Clears all cached routes.

invalidate_route(topic, cache_pid)

Invalidates a cached route.

route_batch(topics, opts \\ [])

Routes multiple messages efficiently.

route_cached?(topic, cache_pid)

Checks if a route is cached.

route_message(topic, opts \\ [])

Routes a message to the appropriate channel process.

routing_stats(cache_pid)

Gets routing statistics for monitoring.

warm_up_cache(routes, cache_pid)

Pre-populates the route cache with known channels.

Types

opts()

@type opts() :: [
  cache_pid: pid(),
  registry_name: atom(),
  use_cache: boolean(),
  cache_on_hit: boolean()
]

Routing options

Functions

clear_cache(cache_pid)

@spec clear_cache(pid()) :: :ok

Clears all cached routes.

Useful for cache invalidation or testing.

Parameters

cache_pid - Route cache process PID

Returns

:ok on success

invalidate_route(topic, cache_pid)

@spec invalidate_route(String.t(), pid()) :: :ok

Invalidates a cached route.

Removes a topic from the route cache, forcing the next lookup to use Registry and potentially update the cache with fresh data.

Parameters

topic - The channel topic to invalidate
cache_pid - Route cache process PID

Returns

:ok on success

route_batch(topics, opts \\ [])

@spec route_batch([String.t()], opts()) :: [{:ok, pid()} | :error]

Routes multiple messages efficiently.

Processes a batch of topics and returns their corresponding PIDs. Uses cached lookups where possible and Registry fallbacks.

Parameters

topics - List of channel topics to route
opts - Routing options

Returns

List of {:ok, pid} or :error results for each topic

Examples

results = Router.route_batch(["rooms:lobby", "users:123"], opts)

route_cached?(topic, cache_pid)

@spec route_cached?(String.t(), pid()) :: boolean()

Checks if a route is cached.

Returns true if the topic exists in the route cache.

Parameters

topic - The channel topic to check
cache_pid - Route cache process PID

Returns

true if cached, false otherwise

route_message(topic, opts \\ [])

@spec route_message(String.t(), opts()) :: {:ok, pid()} | :error

Routes a message to the appropriate channel process.

This function attempts to find the channel PID using the cache first, then falls back to Registry lookups if the cache miss occurs.

Parameters

topic - The channel topic to route to
opts - Routing options including cache PID and registry name

Returns

{:ok, pid} - Channel process found
:error - Channel not found

Examples

{:ok, pid} = Router.route_message("rooms:lobby", [
  cache_pid: cache_pid,
  registry_name: MyRegistry
])

routing_stats(cache_pid)

@spec routing_stats(pid()) :: map()

Gets routing statistics for monitoring.

Returns statistics about cache performance and routing operations.

Parameters

cache_pid - Route cache process PID

Returns

Statistics map with hit rates, cache size, etc.

warm_up_cache(routes, cache_pid)

@spec warm_up_cache([{String.t(), pid()}], pid()) :: :ok | {:error, term()}

Pre-populates the route cache with known channels.

Useful for warming up the cache with expected channels.

Parameters

routes - List of {topic, pid} tuples
cache_pid - Route cache process PID

Returns

:ok on success, {:error, reason} on failure