WebsockexNova.Auth.AuthFlow (WebsockexNova v0.1.0)

View Source

Manages authentication flows for WebSocket connections.

The AuthFlow module provides standardized functions for:

  • Initial authentication when a connection is established
  • Reauthentication when tokens expire or authentication fails
  • Processing authentication responses from the server
  • Determining when reauthentication is needed

Authentication Flow

  1. When a connection is established, authenticate/2 is called
  2. The AuthHandler generates authentication data via generate_auth_data/1
  3. Authentication data is sent to the server
  4. Server responds with success or error
  5. handle_auth_response/2 processes the response and updates state
  6. During connection, check_reauthentication/2 checks if auth renewal is needed

Example Usage

# During initial connection
{:ok, state} = AuthFlow.authenticate(state, &send_frame_fn/4)

# When a message is received that might be an auth response
{:ok, updated_state} = AuthFlow.handle_auth_response(message, state)

# Periodically check if reauthentication is needed
case AuthFlow.check_reauthentication(state, &send_frame_fn/4) do
  {:ok, state} -> state # No reauthentication needed
  {:reauthenticated, state} -> state # Reauthentication initiated
end

Summary

Functions

Initiates the authentication process using the configured AuthHandler.

Checks if reauthentication is needed and initiates the process if necessary.

Handles an authentication response from the server.

Functions

authenticate(state, send_frame_fn)

@spec authenticate(map(), function()) ::
  {:ok, map()} | {:error, atom() | String.t(), map()}

Initiates the authentication process using the configured AuthHandler.

This function:

  1. Retrieves the AuthHandler from the state
  2. Calls generate_auth_data/1 to get authentication data
  3. Sends the authentication data to the server
  4. Returns the updated state

The actual authentication response will be processed later via handle_auth_response/2.

Parameters

  • state: The current state containing authentication handler configuration
  • send_frame_fn: Function to send frames to the WebSocket server, with signature (conn, frame_type, frame_data, stream_ref) -> :ok | {:error, reason}

Returns

  • {:ok, updated_state}: Authentication data sent successfully
  • {:error, reason, updated_state}: Error generating authentication data

check_reauthentication(state, send_frame_fn)

@spec check_reauthentication(map(), function()) ::
  {:ok, map()}
  | {:reauthenticated, map()}
  | {:error, atom() | String.t(), map()}

Checks if reauthentication is needed and initiates the process if necessary.

This function:

  1. Retrieves the AuthHandler from the state
  2. Calls needs_reauthentication?/1 to check if reauthentication is needed
  3. If needed, initiates the authentication process

Parameters

  • state: The current state containing authentication handler configuration
  • send_frame_fn: Function to send frames to the WebSocket server, with signature (conn, frame_type, frame_data, stream_ref) -> :ok | {:error, reason}

Returns

  • {:ok, state}: No reauthentication needed
  • {:reauthenticated, state}: Reauthentication initiated
  • {:error, reason, state}: Error during reauthentication

handle_auth_response(response, state)

@spec handle_auth_response(map(), map()) ::
  {:ok, map()} | {:error, atom() | String.t(), map()}

Handles an authentication response from the server.

This function:

  1. Retrieves the AuthHandler from the state
  2. Calls handle_auth_response/2 to process the authentication response
  3. Updates the state with the result

Parameters

  • response: The response message received from the server
  • state: The current state containing authentication handler configuration

Returns

  • {:ok, updated_state}: Authentication successful or message processed
  • {:error, reason, updated_state}: Authentication failed