Phoenix.SocketClient.Message (phoenix_socket_client v0.7.0)

Defines the message structure and protocol for Phoenix Channels communication.

This module provides message encoding/decoding and handles both V1 and V2 Phoenix Channels protocol versions. It defines the structure for messages sent between client and server.

Message Structure

The message struct contains:

  • :topic - The channel topic (e.g., "rooms:lobby")
  • :event - The event name (e.g., "phx_join", "new_msg")
  • :payload - The message payload (any term)
  • :channel_pid - The channel process PID (internal use)
  • :ref - Message reference for reply matching
  • :join_ref - Reference for channel joins

Protocol Versions

Supports both V1 and V2 Phoenix Channels protocols:

  • V1: Legacy protocol with different message format
  • V2: Current protocol with improved message structure

Summary

Types

t()

Represents a Phoenix Channels message.

Functions

decode!(serializer, msg, json_library)

Decodes a raw message string into a Message struct.

encode!(serializer, msg, json_library)

Encodes a Message struct into a JSON string.

generate_ref()

Generates a unique reference string for message correlation.

join(topic, params)

Creates a join message for channel subscription.

leave(topic)

Creates a leave message for channel unsubscription.

push(topic, event, payload)

Creates a push message for sending data to a channel.

serializer(arg1)

Returns the appropriate serializer module for the given protocol version.

Types

t()

@type t() :: %Phoenix.SocketClient.Message{
  channel_pid: pid() | nil,
  event: String.t() | nil,
  join_ref: String.t() | nil,
  payload: any(),
  ref: String.t() | nil,
  topic: String.t() | nil
}

Represents a Phoenix Channels message.

Functions

decode!(serializer, msg, json_library)

@spec decode!(module(), String.t(), module()) :: t()

Decodes a raw message string into a Message struct.

Parameters

  • serializer - Serializer module (V1 or V2)
  • msg - Raw JSON message string
  • json_library - JSON library module (e.g., Jason)

Returns

  • Phoenix.SocketClient.Message.t() - Decoded message struct

Examples

message = Phoenix.SocketClient.Message.decode!(V2, raw_json, Jason)

encode!(serializer, msg, json_library)

@spec encode!(module(), t(), module()) :: String.t()

Encodes a Message struct into a JSON string.

Parameters

  • serializer - Serializer module (V1 or V2)
  • msg - Message struct to encode
  • json_library - JSON library module (e.g., Jason)

Returns

  • String - JSON-encoded message

Examples

json = Phoenix.SocketClient.Message.encode!(V2, message, Jason)

generate_ref()

@spec generate_ref() :: String.t()

Generates a unique reference string for message correlation.

Returns

  • String - Unique reference string

join(topic, params)

@spec join(String.t(), map() | keyword()) :: t()

Creates a join message for channel subscription.

Parameters

  • topic - Channel topic (e.g., "rooms:lobby")
  • params - Join parameters (map or keyword list)

Returns

  • Phoenix.SocketClient.Message.t() - Join message

Examples

message = Phoenix.SocketClient.Message.join("rooms:lobby", %{user_id: 123})

leave(topic)

@spec leave(String.t()) :: t()

Creates a leave message for channel unsubscription.

Parameters

  • topic - Channel topic to leave

Returns

  • Phoenix.SocketClient.Message.t() - Leave message

Examples

message = Phoenix.SocketClient.Message.leave("rooms:lobby")

push(topic, event, payload)

@spec push(String.t(), String.t(), any()) :: t()

Creates a push message for sending data to a channel.

Parameters

  • topic - Channel topic
  • event - Event name (e.g., "new_msg")
  • payload - Message payload

Returns

  • Phoenix.SocketClient.Message.t() - Push message

Examples

message = Phoenix.SocketClient.Message.push("rooms:lobby", "new_msg", %{body: "Hello"})

serializer(arg1)

@spec serializer(String.t()) :: module()

Returns the appropriate serializer module for the given protocol version.

Parameters

  • vsn - Protocol version string ("1.0.0" or "2.0.0")

Returns

  • Module - Serializer module for the protocol version

Deprecation Notice

V1 protocol ("1.0.0") is deprecated and will be removed in a future version. Use V2 protocol ("2.0.0") for new applications.