rally_runtime/effect

The API that page modules import for server communication, broadcast, and navigation.

This module has a split personality by design. Each function has two implementations: the server-side version here (which queues push frames via the process dictionary or is a no-op), and a client-side version in the generated rally_runtime/effect.gleam shim (which calls the browser WebSocket transport). The codegen rewrites imports so the client package uses the shim, not this file.

Two server communication models:

rpc(msg, on_response:) Stateless request-response. Define a ServerX message type and server_x handler. Client sends, server returns a value. Use this by default.

send_to_server(msg) Stateful bidirectional. Define ToServer/ ToClient types and server_init/server_update. Server keeps a ServerModel per connection and can push ToClient messages any time. Use when the server needs state between calls.

Types

Effect

</>

pub type Effect(a) =
  effect.Effect(a)

Values

broadcast_to_app

</>

pub fn broadcast_to_app(msg: a) -> effect.Effect(b)

Broadcast a message to every connection in the app.

broadcast_to_page

</>

pub fn broadcast_to_page(msg: a) -> effect.Effect(b)

Broadcast a message to all connections viewing the current page. Broadcasts via pg topics for other connections, plus push_outgoing_frame for the sender’s own connection (which isn’t subscribed to its own topic).

broadcast_to_session

</>

pub fn broadcast_to_session(msg: a) -> effect.Effect(b)

Broadcast a message to all connections in the current browser session.

clear_ws_auth_state

</>

pub fn clear_ws_auth_state() -> Nil

Clear identity and reset timestamp to 0. Hostname is preserved (connection-scoped, not auth-scoped). Used during reauth and in tests.

decode_rally_push

</>

pub fn decode_rally_push(msg: a) -> Result(BitArray, Nil)

Decode an inbound push frame (ETF protocol).

decode_rally_push_json

</>

pub fn decode_rally_push_json(msg: a) -> Result(String, Nil)

Decode an inbound push frame (JSON protocol).

drain_outgoing_frames

</>

pub fn drain_outgoing_frames() -> List(a)

Drain all queued push frames. Called by the WS handler after dispatch.

from

</>

pub fn from(f: fn(fn(a) -> Nil) -> Nil) -> effect.Effect(a)

get_stored_server_context

</>

pub fn get_stored_server_context() -> Result(a, Nil)

Retrieve the server context stored on the current WS process.

get_ws_auth_timestamp

</>

pub fn get_ws_auth_timestamp() -> Int

Retrieve the auth timestamp. Returns 0 when not set (0 = never authed, triggers immediate reauth on first RPC).

get_ws_conn

</>

pub fn get_ws_conn() -> Result(a, Nil)

Get the mist connection handle for this WS process.

get_ws_hostname

</>

pub fn get_ws_hostname() -> String

Retrieve the stored hostname. Returns “” when not set.

get_ws_identity

</>

pub fn get_ws_identity() -> Result(a, Nil)

Retrieve the stored identity. Returns Error(Nil) when no identity has been stored (fresh process or pre-auth connection).

get_ws_page

</>

pub fn get_ws_page() -> String

Get the current page name for this WS connection.

get_ws_session

</>

pub fn get_ws_session() -> String

Get the session ID for the current WS connection.

navigate

</>

pub fn navigate(path: String) -> effect.Effect(a)

Navigate to a new URL path. Pushes a new history entry and triggers a route change via modem’s popstate listener. On the server, this is a no-op.

none

</>

pub fn none() -> effect.Effect(a)

put_ws_auth_timestamp

</>

pub fn put_ws_auth_timestamp(ts: Int) -> Nil

Store the Unix timestamp of the last successful auth check.

put_ws_hostname

</>

pub fn put_ws_hostname(hostname: String) -> Nil

Store the hostname extracted during WebSocket upgrade.

put_ws_identity

</>

pub fn put_ws_identity(identity: a) -> Nil

Store the resolved identity on the WebSocket connection process. The identity type is opaque to Rally; it’s stored as an Erlang term.

put_ws_session

</>

pub fn put_ws_session(session_id: String) -> Nil

Store the session ID on the current WS process.

put_ws_state

</>

pub fn put_ws_state(
  conn: a,
  server_context: b,
  page: String,
) -> Nil

Store the WS connection handle, server context, and current page name.

read_dark_mode

</>

pub fn read_dark_mode() -> Bool

Read the dark mode preference from the cookie. Falls back to prefers-color-scheme media query. On the server, returns False.

read_lang

</>

pub fn read_lang() -> String

Read the language preference from the cookie. On the server, returns “en”.

rpc

</>

pub fn rpc(
  msg: a,
  on_response on_response: fn(b) -> msg,
) -> effect.Effect(msg)

Call a server_* RPC handler and deliver the return value to on_response. Part of the stateless RPC model (ServerX type + server_x function). On the server this is a no-op. On the client, the generated transport module encodes the message and sends it over WebSocket.

send_to_client

</>

pub fn send_to_client(msg: a) -> effect.Effect(b)

Send a ToClient variant to the connected client. Encodes the message as a protocol-specific push frame and queues it for the WebSocket handler to send after the current dispatch.

send_to_client_context

</>

pub fn send_to_client_context(msg: a) -> effect.Effect(b)

Send a ClientContextMsg to update the client’s shared context. On the server, encodes and queues a push frame tagged “ClientContext”. On the client, the generated app dispatches it through client_context.update.

send_to_server

</>

pub fn send_to_server(msg: a) -> effect.Effect(b)

Send a ToServer variant to the server over WebSocket. Part of the stateful model (ToServer/ToClient/ServerModel). On the server this is a no-op. On the client, the generated transport module provides the real implementation.

set_dark_mode

</>

pub fn set_dark_mode(enabled: Bool) -> effect.Effect(a)

Toggle dark mode. On the client, sets the cookie and toggles the class. On the server, this is a no-op.

set_lang

</>

pub fn set_lang(lang: String) -> effect.Effect(a)

Set the language preference cookie. On the server, this is a no-op.