ExWapp.Session.Outbound.Direct (ExWapp v0.1.2)

Direct-message and self-chat outbound orchestration decisions.

The session worker provides callbacks for USync and prekey IQ effects and remains responsible for encryption, persistence, and transport sends. This module owns direct session preparation, payload construction, fanout resolution, and final direct message-node composition.

Summary

Types

discover_fun()

discovery_result()

payloads()

target_hints()

Functions

build_encrypted_message_node(jid, message_id, participant_nodes, store, include_identity)

Builds the final multi-device direct message node.

build_payloads(proto, jid, opts)

Builds padded recipient and own-device payloads for a direct send.

message_id(opts, own_jid)

Returns the retry message ID or generates a new outbound ID.

prepare_sessions(state, jid, now_ms, discover_fun, fetch_many_fun, fetch_one_fun, opts \\ [])

Prepares Signal sessions and target hints for a direct or self-chat send.

resolve_targets(store, signal_sessions, jid, prekey_bundles, target_hints, opts)

Resolves direct recipient and own-device fanout targets.

validate_participant_family(jid, participant_nodes)

Verifies that every encrypted participant uses the destination JID family.

Types

discover_fun()

@type discover_fun() :: (String.t(), String.t(), non_neg_integer() | nil ->
                     discovery_result())

discovery_result()

@type discovery_result() ::
  {[String.t()], [String.t()], [String.t()], [String.t()], [String.t()],
   [String.t()]}

payloads()

@type payloads() :: %{recipient: binary(), own: binary(), raw_size: non_neg_integer()}

target_hints()

@type target_hints() :: %{
  recipient_devices: [String.t()],
  recipient_cached_devices: [String.t()],
  own_devices: [String.t()],
  own_cached_devices: [String.t()],
  own_identity_jid: String.t(),
  all_usync_devices: [String.t()]
}

Functions

build_encrypted_message_node(jid, message_id, participant_nodes, store, include_identity)

@spec build_encrypted_message_node(
  String.t(),
  String.t(),
  [ExWapp.Binary.Node.t()],
  term(),
  boolean()
) :: ExWapp.Binary.Node.t()

Builds the final multi-device direct message node.

build_payloads(proto, jid, opts)

@spec build_payloads(WAWebProtobufsE2E.Message.t(), String.t(), keyword()) ::
  {:ok, payloads()} | {:error, {:proto_encode, term()}}

Builds padded recipient and own-device payloads for a direct send.

message_id(opts, own_jid)

@spec message_id(
  keyword(),
  String.t()
) :: String.t()

Returns the retry message ID or generates a new outbound ID.

prepare_sessions(state, jid, now_ms, discover_fun, fetch_many_fun, fetch_one_fun, opts \\ [])

@spec prepare_sessions(
  map(),
  String.t(),
  non_neg_integer(),
  discover_fun(),
  ExWapp.Session.Outbound.Prekeys.fetch_many_fun(),
  ExWapp.Session.Outbound.Prekeys.fetch_one_fun(),
  keyword()
) ::
  {:ok, ExWapp.Signal.SessionStore.t(), map(), target_hints()}
  | {:error, term()}

Prepares Signal sessions and target hints for a direct or self-chat send.

Network effects are supplied as callbacks so the worker keeps ownership of IQ sends, receives, and timeouts.

resolve_targets(store, signal_sessions, jid, prekey_bundles, target_hints, opts)

@spec resolve_targets(
  term(),
  ExWapp.Signal.SessionStore.t(),
  String.t(),
  map(),
  map(),
  keyword()
) :: {[map()], [String.t()]}

Resolves direct recipient and own-device fanout targets.

Stale cached device entries rejected by the resolution are evicted.

validate_participant_family(jid, participant_nodes)

@spec validate_participant_family(String.t(), [ExWapp.Binary.Node.t()]) ::
  :ok | {:error, {:mixed_addressing_family, non_neg_integer()}}

Verifies that every encrypted participant uses the destination JID family.

This is the final pre-send invariant. Fanout resolution performs the mapping; this check prevents a later regression from putting a PN participant into a LID message (or the reverse).