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.

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)

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.