Struct RemoteSession 

pub struct RemoteSession { /* private fields */ }

Implementations

impl RemoteSession

pub fn new(config: SessionConfig) -> Self

Create a new remote session.

Sets up the engine with the component resolver and module, but does NOT render yet. The initial render happens in [handle_hello].

pub fn on_route_enter<F>(&self, pattern: impl Into<String>, handler: F)

where F: Fn(&HashMap<String, String>, &mut HashMap<String, Value>, &Arc<GlobalContext>) + Send + Sync + 'static,

Register a route-entry hook.

Called whenever the session’s router lands on pattern (via any @router.push / @router.replace / @router.back dispatch). The hook receives the extracted route params, a mutable handle to the shared state map (keyed by lowercase module name; "" = primary), and the session’s GlobalContext.

Typical use: load data for a :id / :postId route and write it into the corresponding nested module’s state slot. The state changes are flushed to the engine at the end of the surrounding handle_action call, so any patches land in the same WebSocket response.

session.on_route_enter("/comments/:postId", move |params, state, _ctx| {
    let post_id = params.get("postId").cloned().unwrap_or_default();
    let comments = load_comments(&db, &post_id);
    if let Some(slot) = state.get_mut("comments") {
        if let Some(obj) = slot.as_object_mut() {
            obj.insert("postId".into(), Value::String(post_id));
            obj.insert("comments".into(), serde_json::to_value(&comments).unwrap());
        }
    }
});

pub fn router(&self) -> &Arc<HypenRouter>

The router driving this session.

The engine’s reserved router.* action namespace is wired to this router automatically in Self::new — DSL authors get @router.push / @router.replace / @router.back for free. Callers that want programmatic nav, to subscribe to on_navigate, or to attach a ManagedRouter use this handle.

pub fn context(&self) -> &Arc<GlobalContext>

The global context associated with this session.

Paired with Self::router; the session sets the router on the context at construction so any attached ManagedRouter can find it via context.router().

pub fn from_definition<S: State>( def: Arc<ModuleDefinition<S>>, components: ComponentRegistry, ) -> Self

Create a session from a ModuleDefinition, automatically wiring up typed action handlers, UI source, and resources.

This is the recommended way to create a RemoteSession when using the ModuleBuilder API. It eliminates manual SessionConfig construction and raw action handler closures.

Example

let module = Arc::new(HypenApp::module::<MyState>("App")
    .state(MyState::default())
    .ui_file("./components/App/component.hypen")
    .on_action::<()>("increment", |s, _, _| s.count += 1)
    .build());

let session = RemoteSession::from_definition(module, components);

pub fn from_definition_with_state<S: State>( def: Arc<ModuleDefinition<S>>, components: ComponentRegistry, initial_state: S, modules: Vec<ModuleSessionConfig>, ) -> Self

Create a session from a ModuleDefinition with a per-client state override and optional nested modules.

Use this when initial state varies per client (e.g., loaded from a database for the connected user).

Example

let search_mod = Arc::new(HypenApp::module::<SearchState>("Search")
    .state(SearchState::default())
    .on_action::<()>("search", |s, _, _| { /* filter */ })
    .build());

let session = RemoteSession::from_definition_with_state(
    app_module.clone(),
    components,
    client_state,
    vec![ModuleSessionConfig::from_definition(search_mod)],
);

pub fn set_action_handler<F>(&self, handler: F)

where F: Fn(&str, Option<&Value>, &Value) -> Value + Send + Sync + 'static,

Set the action handler for the session’s primary module.

Called whenever a dispatchAction message arrives whose action belongs to the primary module (i.e. engine.action_scope_for returns None). The handler receives the action name, optional payload, and current primary-module state, and must return the new state.

Nested-module handlers are installed internally by from_definition_with_state.

pub fn session_id(&self) -> &str

The session ID assigned to this client.

pub fn handle_hello(&self, client_session_id: Option<&str>) -> Vec<String>

Handle the hello handshake. Returns [sessionAck, initialTree] as JSON.

If client_session_id is Some(id) and a SessionManager was used to suspend that session earlier, the caller should call handle_reconnect with the PendingSession.saved_state BEFORE calling this method so the state is restored before the initial render.

Call this either:

• When you receive a hello message from the client, or
• Immediately after connection (for clients that don’t send hello)

pub fn handle_message(&self, json: &str) -> Vec<String>

Handle an incoming JSON message. Returns response messages as JSON strings.

pub fn get_state(&self) -> Value

Get a snapshot of the current primary-module state.

pub fn revision(&self) -> u64

Get the current revision number.

pub fn fire_disconnect(&self, session_info: &SessionInfo)

Fire the on_disconnect handler with a snapshot of the current primary-module state. Call this when the last WebSocket connection for the session drops and you’re about to suspend it via [SessionManager::suspend_session].

No-op if no on_disconnect handler was registered on the ModuleDefinition (i.e. the session was created via RemoteSession::new without from_definition).

pub fn fire_reconnect(&self, session_info: &SessionInfo, saved_state: &Value)

Fire the on_reconnect handler and apply the saved state to the session. Call this when a client resumes a suspended session (i.e. after [SessionManager::resume_session] returns Some(pending)).

The handler receives a mutable reference to the current primary state (as JSON) and the saved state — it can choose to merge, replace, or ignore the saved state. If no handler is registered, the saved state replaces the primary state directly.

pub fn fire_expire(&self, session_info: &SessionInfo)

Fire the on_expire handler. Call this from the [SessionManager] suspension’s on_expire callback when the TTL elapses without a reconnect.