Leptos Axum Socket

https://docs.rs/leptos-axum-socket
Admin
Leptos Axum Socket enables realtime pub/sub communication for Leptos and Axum applications using...
Tokens:11,328
Snippets:93
Trust Score:9.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### Subscribe to and Send Messages in a Leptos Component

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket

Use the expect_socket_context to get the socket instance within a Leptos component. Subscribe to messages using a key and a callback, and send messages using the send method.

```rust
#[component]
pub fn MyComponent() -> impl IntoView {
    let socket = expect_socket_context();

    // Subscribe to receive messages that are sent with the given key
    socket.subscribe(
        MyKey {
            bla: "bla".to_string(),
        },
        |msg: &MyMsg| {
            // Simply log the message
            leptos::logging::log!("message: {msg:#?}");
        },
    );

    let on_click = move || {
        // Send a message with the given key
        socket.send(
            MyKey {
                bla: "bla".to_string(),
            },
            MyMsg {
                awesome_msg: "awesome message".to_string(),
            },
        );
    };

    view! { "..." }
```

--------------------------------

### Subscribe and Send Messages in a Leptos Component

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket/index.html

Use `expect_socket_context` to get the socket instance within a Leptos component. Subscribe to messages using a key and send messages with a key and payload.

```rust
#[component]
pub fn MyComponent() -> impl IntoView {
    let socket = expect_socket_context();

    // Subscribe to receive messages that are sent with the given key
    socket.subscribe(
        MyKey {
            bla: "bla".to_string(),
        },
        |msg: &MyMsg| {
            // Simply log the message
            leptos::logging::log!("message: {msg:#?}");
        },
    );

    let on_click = move || {
        // Send a message with the given key
        socket.send(
            MyKey {
                bla: "bla".to_string(),
            },
            MyMsg {
                awesome_msg: "awesome message".to_string(),
            },
        );
    };

    view! { "..." }
}
```

--------------------------------

### Implement SocketMsg for Message Types

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket/trait.SocketMsg.html

Example implementation of the SocketMsg trait for a custom message struct, linking it to a key and an optional server-side application state.

```rust
// Define the key and message types
#[derive(Clone, Serialize, Deserialize)]
pub struct MyKey {
    pub bla: String,
}

#[derive(Clone, Serialize, Deserialize, Debug)]
pub struct MyMsg {
    pub awesome_msg: String,
}

// Implement the SocketMsg trait for MyMsg to link the key and message types
impl SocketMsg for MyMsg {
    type Key = MyKey;
    #[cfg(feature = "ssr")]
    type AppState = AppState;
}
```

--------------------------------

### Reconnect WebSocket

Source: https://docs.rs/leptos-axum-socket/latest/src/leptos_axum_socket/channel/context.rs.html

Disconnects and re-connects the WebSocket. Useful for resetting the context, for example, after user login/logout.

```rust
pub fn reconnect(&self) {
        #[cfg(not(feature = "ssr"))]
        {
            for (_, stop) in self.effect_stops.write_value().drain() {
                stop();
            }

            self.close.get_value()();
            self.open.get_value()();

            for (key, subscriber) in &*self.subscribers.read_value() {
                self.subscribe_effect(key.clone(), Arc::clone(subscriber));
            }
        }
    }
```

--------------------------------

### Get Socket Context

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket/channel/fn.expect_socket_context.html

Call this function when you need to subscribe to or send a message within your component. It retrieves the current SocketContext.

```rust
pub fn expect_socket_context() -> SocketContext
```

--------------------------------

### Initialize Axum Application

Source: https://docs.rs/leptos-axum-socket/latest/index.html

Set up the Axum router with the server socket, optional filters, and the WebSocket connection handler.

```rust
#[tokio::main]
async fn main() {
    let conf = get_configuration(None).unwrap();
    let addr = conf.leptos_options.site_addr;

    let routes = generate_route_list(App);

    // Construct the Axum app state
    let state = AppState {
        leptos_options: conf.leptos_options,
        server_socket: ServerSocket::new(),
    };

    // Optional: add subscription filters and message mappers
    {
        let mut server_socket = state.server_socket.lock().await;
        server_socket.add_subscribe_filter(async |key: MyKey, _ctx: &()| { key.bla == "bla" });
        server_socket.add_send_mapper(|key: MyKey, msg: MyMsg, _ctx: &()| {
            if key.bla == "bla" {
                Some(MyMsg {
                    awesome_msg: msg.awesome_msg.replace("old", "new"),
                })
            } else {
                None
            }
        });
    }

    // Init the Axum app
    let app: Router<AppState> = Router::new()
        .leptos_routes(&state, routes, {
            let leptos_options = state.leptos_options.clone();
            move || shell(leptos_options.clone())
        })
        .socket_route(connect_to_websocket)    // Register the socket route (implementation below)
        .fallback(leptos_axum::file_and_error_handler::<AppState, _>(shell))
        .with_state(state);    // Register the state

    let listener = tokio::net::TcpListener::bind(&addr).await.unwrap();
    // axum::serve(listener, app.into_make_service())
    //    .await
    //    .unwrap();
}

// Implement the `connect_to_websocket` handler:
#[cfg(feature = "ssr")]
pub async fn connect_to_websocket(
    ws: WebSocketUpgrade,
    State(socket): State<ServerSocket>,
) -> Response {
    // You could do authentication here

    // Provide extra context like the user's ID for example that is passed to the permission filters
    let ctx = ();

    upgrade_websocket(ws, socket, ctx)
}
```

--------------------------------

### Initialize Axum App with ServerSocket and Socket Route

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket

Initialize your Axum application in main.rs, constructing the AppState with ServerSocket::new(). Register the socket route using .socket_route(connect_to_websocket) and provide the state.

```rust

#[tokio::main]
async fn main() {
    let conf = get_configuration(None).unwrap();
    let addr = conf.leptos_options.site_addr;

    let routes = generate_route_list(App);

    // Construct the Axum app state
    let state = AppState {
        leptos_options: conf.leptos_options,
        server_socket: ServerSocket::new(),
    };

    // Optional: add subscription filters and message mappers
    {
        let mut server_socket = state.server_socket.lock().await;
        server_socket.add_subscribe_filter(async |key: MyKey, _ctx: &()| { key.bla == "bla" });
        server_socket.add_send_mapper(|key: MyKey, msg: MyMsg, _ctx: &()| {
            if key.bla == "bla" {
                Some(MyMsg {
                    awesome_msg: msg.awesome_msg.replace("old", "new"),
                })
            } else {
                None
            }
        });
    }

    // Init the Axum app
    let app: Router<AppState> = Router::new()
        .leptos_routes(&state, routes, {
            let leptos_options = state.leptos_options.clone();
            move || shell(leptos_options.clone())
        })
        .socket_route(connect_to_websocket)    // Register the socket route (implementation below)
        .fallback(leptos_axum::file_and_error_handler::<AppState, _>(shell))
        .with_state(state);    // Register the state

    let listener = tokio::net::TcpListener::bind(&addr).await.unwrap();
    // axum::serve(listener, app.into_make_service())
    //    .await
    //    .unwrap();
}
```

--------------------------------

### Initialize Axum App with ServerSocket and Routes

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket/index.html

Initialize your Axum application, construct the `AppState`, and register the WebSocket route using `socket_route`. Optional subscription filters and message mappers can be added.

```rust
#[tokio::main]
async fn main() {
    let conf = get_configuration(None).unwrap();
    let addr = conf.leptos_options.site_addr;

    let routes = generate_route_list(App);

    // Construct the Axum app state
    let state = AppState {
        leptos_options: conf.leptos_options,
        server_socket: ServerSocket::new(),
    };

    // Optional: add subscription filters and message mappers
    {
        let mut server_socket = state.server_socket.lock().await;
        server_socket.add_subscribe_filter(async |key: MyKey, _ctx: &()| { key.bla == "bla" });
        server_socket.add_send_mapper(|key: MyKey, msg: MyMsg, _ctx: &()| {
            if key.bla == "bla" {
                Some(MyMsg {
                    awesome_msg: msg.awesome_msg.replace("old", "new"),
                })
            } else {
                None
            }
        });
    }

    // Init the Axum app
    let app: Router<AppState> = Router::new()
        .leptos_routes(&state, routes, {
            let leptos_options = state.leptos_options.clone();
            move || shell(leptos_options.clone())
        })
        .socket_route(connect_to_websocket)    // Register the socket route (implementation below)
        .fallback(leptos_axum::file_and_error_handler::<AppState, _>(shell))
        .with_state(state);    // Register the state

    let listener = tokio::net::TcpListener::bind(&addr).await.unwrap();
    // axum::serve(listener, app.into_make_service())
    //    .await
    //    .unwrap();
}
```

--------------------------------

### Initialize Axum Application

Source: https://docs.rs/leptos-axum-socket/latest/src/leptos_axum_socket/lib.rs.html

Configure the Axum router with the server socket and optional filters or mappers.

```rust
# use leptos::prelude::*;
# use leptos_axum_socket::{ServerSocket, SocketMsg, SocketRoute, handlers::upgrade_websocket};
# use serde::{Deserialize, Serialize};
# use axum::{Router, extract::{State, WebSocketUpgrade, FromRef}, response::Response};
# use leptos_axum::{generate_route_list, LeptosRoutes};
#
# #[derive(Clone, FromRef)]
# pub struct AppState {
#     pub server_socket: ServerSocket,
#     pub leptos_options: LeptosOptions,
# }
#
# fn shell(options: LeptosOptions) -> impl IntoView {
#     ()
# }
# fn App() -> impl IntoView {
#     ()
# }
#
# #[derive(Clone, Serialize, Deserialize, PartialEq, Eq, Hash, Debug)]
# pub struct MyKey {
#     pub bla: String,
# }
#
# #[derive(Clone, Serialize, Deserialize, Debug)]
# pub struct MyMsg {
#     pub awesome_msg: String,
# }
#
# impl SocketMsg for MyMsg {
#     type Key = MyKey;
#     #[cfg(feature = "ssr")]
#     type AppState = AppState;
# }
#
#[tokio::main]
async fn main() {
    let conf = get_configuration(None).unwrap();
    let addr = conf.leptos_options.site_addr;

    let routes = generate_route_list(App);

    // Construct the Axum app state
    let state = AppState {
        leptos_options: conf.leptos_options,
        server_socket: ServerSocket::new(),
    };

    // Optional: add subscription filters and message mappers
    {
        let mut server_socket = state.server_socket.lock().await;
        server_socket.add_subscribe_filter(async |key: MyKey, _ctx: &()| { key.bla == "bla" });
        server_socket.add_send_mapper(|key: MyKey, msg: MyMsg, _ctx: &()| {
            if key.bla == "bla" {
                Some(MyMsg {
                    awesome_msg: msg.awesome_msg.replace("old", "new"),
                })
```

--------------------------------

### provide_socket_context_with_query

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket/channel/fn.provide_socket_context_with_query.html

Initializes the socket context with query parameters for use in a Leptos application.

```APIDOC
## provide_socket_context_with_query

### Description
Call this function in your root component to provide the socket context with specific query parameters.

### Parameters
- **query** (T: Serialize + ?Sized) - Required - The query parameters to be serialized and provided to the socket context.

### Request Example
```rust
provide_socket_context_with_query(&[("user_id", "123456789")]);
```
```

--------------------------------

### Provide socket context with query parameters

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket/channel/fn.provide_socket_context_with_query.html

Call this function in the root component to initialize the socket context with specific query parameters.

```rust
provide_socket_context_with_query(&[("user_id", "123456789")]);
```

--------------------------------

### Implement WebSocket Connection Handler

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket/index.html

Implement the `connect_to_websocket` handler for Axum to upgrade the WebSocket connection. Authentication can be performed here.

```rust
#[cfg(feature = "ssr")]
pub async fn connect_to_websocket(
    ws: WebSocketUpgrade,
    State(socket): State<ServerSocket>,
) -> Response {
    // You could do authentication here

    // Provide extra context like the user's ID for example that is passed to the permission filters
    let ctx = ();

    upgrade_websocket(ws, socket, ctx)
}
```

--------------------------------

### provide_socket_context

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket/channel/fn.provide_socket_context.html

Initializes the socket context for the application. This function should be called within the root component.

```APIDOC
## provide_socket_context

### Description
Call this function in your root component to provide the socket context for the application.

### Signature
`pub fn provide_socket_context() -> SocketContext`
```

--------------------------------

### Provide Socket Context

Source: https://docs.rs/leptos-axum-socket/latest/src/leptos_axum_socket/channel/context.rs.html

Initializes and provides the socket context to the Leptos component tree, optionally with query parameters.

```rust
pub fn provide_socket_context() -> SocketContext {
    if let Some(ctx) = use_context::<SocketContext>() {
        ctx
    } else {
        let ctx = SocketContext::new("".to_string());
        provide_context(ctx);
        ctx
    }
}
```

```rust
pub fn provide_socket_context_with_query<T: Serialize + ?Sized>(query: &T) -> SocketContext {
    let query_string = serde_urlencoded::to_string(query).expect("Failed to serialize query");
    let ctx = SocketContext::new(query_string);
    provide_context(ctx);
    ctx
}
```

--------------------------------

### Structs

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket/all.html

Information about the available structs in the leptos-axum-socket crate.

```APIDOC
## Structs

### `channel::SocketContext`

Represents the context for a WebSocket connection.
```

--------------------------------

### Initialize SocketContext

Source: https://docs.rs/leptos-axum-socket/latest/src/leptos_axum_socket/channel/context.rs.html

Initializes the SocketContext with WebSocket connection details and options. It sets up reconnection logic and error handling.

```rust
fn new(query: String) -> Self {
        use crate::WEBSOCKET_CHANNEL_URL;
        use leptos::server::codee::string::JsonSerdeCodec;
        use leptos_use::{
            ReconnectLimit,
            UseWebSocketOptions,
            UseWebSocketReturn,
            use_websocket_with_options,
        };

        let query = if query.is_empty() {
            String::new()
        } else {
            format!(
```

```rust
            format!("?{query}")
        };
        let url = format!("{WEBSOCKET_CHANNEL_URL}{query}");

        let UseWebSocketReturn {
            message,
            send,
            ready_state,
            open,
            close,
            ..
        } = use_websocket_with_options::<ChannelMsg, ChannelMsg, JsonSerdeCodec, _, _>(
            &url,
            UseWebSocketOptions::default()
                .reconnect_limit(ReconnectLimit::Infinite)
                .on_error(|error| {
                    leptos::logging::error!("WebSocket error: {}", error);
                }),
        );

        Self {
            message,
            send: StoredValue::new(Arc::new(send)),
            ready_state,
            open: StoredValue::new(Arc::new(open)),
            close: StoredValue::new(Arc::new(close)),
            effect_stops: StoredValue::new(HashMap::new()),
            subscribers: StoredValue::new(HashMap::new()),
        }
    }
```

--------------------------------

### Provide Socket Context

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket/channel/fn.provide_socket_context.html

Call this in your root component to provide the socket context. This function initializes the necessary context for socket communication within your Leptos application.

```rust
pub fn provide_socket_context() -> SocketContext
```

--------------------------------

### Provide Socket Context in Leptos

Source: https://docs.rs/leptos-axum-socket/latest/src/leptos_axum_socket/lib.rs.html

Initialize the socket context within the root Leptos component.

```rust
# use leptos::prelude::*;
# use leptos_axum_socket::provide_socket_context;
#
#[component]
pub fn App() -> impl IntoView {
    provide_socket_context();

    view! { "..." }
}
```

--------------------------------

### Constants

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket/all.html

Information about the constants defined in the leptos-axum-socket crate.

```APIDOC
## Constants

### `channel::WEBSOCKET_CHANNEL_URL`

The default URL for WebSocket channels.
```

--------------------------------

### Functions

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket/all.html

Details on the functions provided by the leptos-axum-socket crate.

```APIDOC
## Functions

### `channel::expect_socket_context()`

Retrieves the `SocketContext` from the current scope, panicking if it's not available.

### `channel::provide_socket_context()`

Provides a `SocketContext` to the current scope.

### `channel::provide_socket_context_with_query()`

Provides a `SocketContext` to the current scope, allowing for query parameters.

### `channel::use_socket_context()`

Retrieves the `SocketContext` from the current scope, returning `None` if it's not available.
```

--------------------------------

### Configure Axum Router and WebSocket Handler

Source: https://docs.rs/leptos-axum-socket/latest/src/leptos_axum_socket/lib.rs.html

Register the WebSocket route in the Axum router and implement the handler function to upgrade connections.

```rust
    // Init the Axum app
    let app: Router<AppState> = Router::new()
        .leptos_routes(&state, routes, {
            let leptos_options = state.leptos_options.clone();
            move || shell(leptos_options.clone())
        })
        .socket_route(connect_to_websocket)    // Register the socket route (implementation below)
        .fallback(leptos_axum::file_and_error_handler::<AppState, _>(shell))
        .with_state(state);    // Register the state

    let listener = tokio::net::TcpListener::bind(&addr).await.unwrap();
    // axum::serve(listener, app.into_make_service())
    //    .await
    //    .unwrap();
}

// Implement the `connect_to_websocket` handler:
#[cfg(feature = "ssr")]
pub async fn connect_to_websocket(
    ws: WebSocketUpgrade,
    State(socket): State<ServerSocket>,
) -> Response {
    // You could do authentication here

    // Provide extra context like the user's ID for example that is passed to the permission filters
    let ctx = ();

    upgrade_websocket(ws, socket, ctx)
}
```

--------------------------------

### Implement Pub/Sub Communication

Source: https://docs.rs/leptos-axum-socket/latest/src/leptos_axum_socket/lib.rs.html

Define key and message types, implement the SocketMsg trait, and use the socket context in components or server functions.

```rust
# use leptos::prelude::*;
# use leptos_axum_socket::{expect_socket_context, ServerSocket, SocketMsg};
# use serde::{Serialize, Deserialize};
# use axum::extract::{State, FromRef};
#
# #[derive(FromRef, Clone)]
# pub struct AppState {
#     pub socket: ServerSocket,
# }
#
// Define the key and message types
#[derive(Clone, Serialize, Deserialize, PartialEq, Eq, Hash, Debug)]
pub struct MyKey {
    pub bla: String,
}

#[derive(Clone, Serialize, Deserialize, Debug)]
pub struct MyMsg {
    pub awesome_msg: String,
}

// Implement the SocketMsg trait for MyMsg to link the key and message types
impl SocketMsg for MyMsg {
    type Key = MyKey;
    #[cfg(feature = 
```

--------------------------------

### Provide Socket Context in Root Leptos Component

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket

Provide the socket context in your root Leptos component using provide_socket_context(). This makes the socket available throughout your Leptos application.

```rust

#[component]
pub fn App() -> impl IntoView {
    provide_socket_context();

    view! { "..." }
}
```

--------------------------------

### Define Axum AppState with Leptos Axum Socket

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket

Define your application state in lib.rs, including the leptos_axum_socket::ServerSocket. This state is required for Leptos Axum Socket to function correctly within an Axum application.

```rust
use leptos::prelude::*;

#[cfg(feature = "ssr")]
#[derive(Clone, axum::extract::FromRef)]
pub struct AppState {
    // This is required for Leptos Axum Socket to work
    pub socket: leptos_axum_socket::ServerSocket,

    // this is required for Leptos to work with axum
    pub leptos_options: LeptosOptions,
}
```

--------------------------------

### Socket Context Management

Source: https://docs.rs/leptos-axum-socket/latest/src/leptos_axum_socket/channel/context.rs.html

Utility functions to provide and consume socket context within Leptos components.

```APIDOC
## provide_socket_context

### Description
Initializes and provides the socket context to the component tree.

## provide_socket_context_with_query

### Description
Initializes the socket context with a serialized query string.

### Parameters
#### Request Body
- **query** (Serialize) - Required - The query parameters to include in the socket connection.

## expect_socket_context

### Description
Retrieves the socket context, panicking if it is not found.

## use_socket_context

### Description
Attempts to retrieve the socket context, returning None if not present.
```

--------------------------------

### Implement Axum WebSocket Handler

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket

Implement the connect_to_websocket handler for Axum. This handler upgrades the WebSocket connection and can be used for authentication and providing extra context to permission filters.

```rust

#[cfg(feature = "ssr")]
pub async fn connect_to_websocket(
    ws: WebSocketUpgrade,
    State(socket): State<ServerSocket>,
) -> Response {
    // You could do authentication here

    // Provide extra context like the user's ID for example that is passed to the permission filters
    let ctx = ();

    upgrade_websocket(ws, socket, ctx)
}
```

--------------------------------

### Traits

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket/all.html

Information about the available traits in the leptos-axum-socket crate.

```APIDOC
## Traits

### `SocketMsg`

A trait for messages that can be sent over a WebSocket.
```

--------------------------------

### Attempt to Serialize Output into HTTP Response (Patch)

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket/channel/struct.SocketContext.html

Attempts to serialize the output into an HTTP response for the Patch method. Requires the response type to implement TryRes and the encoding to implement Encodes.

```rust
async fn into_res(self) -> Result<Response, E>
```

--------------------------------

### Socket Context Management

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket/channel/index.html

Provides functions to manage the WebSocket context for sending and subscribing to messages within Leptos components.

```APIDOC
## Socket Context Management

### Description

This section details the functions related to managing the `SocketContext` for real-time communication in Leptos applications using the leptos-axum-socket crate.

### Functions

#### `provide_socket_context()`

- **Description**: Call this in your root component to provide the socket context.
- **Usage**: Initializes the WebSocket context for the application.

#### `provide_socket_context_with_query()`

- **Description**: Call this in your root component to provide the socket context, potentially with query parameters.
- **Usage**: Initializes the WebSocket context, allowing for configuration via query parameters.

#### `expect_socket_context()`

- **Description**: Call this when you want to subscribe or send a message in your component.
- **Usage**: Retrieves the active socket context, essential for interacting with the WebSocket.

#### `use_socket_context()`

- **Description**: Call this when you want to subscribe or send a message in your component.
- **Usage**: Similar to `expect_socket_context`, provides access to the socket context for sending and subscribing.

### Structs

#### `SocketContext`

- **Description**: The context to be used for sending and subscribing to messages in your component. You probably don’t want to use this directly, but rather use the `expect_socket_context` hook.

### Constants

#### `WEBSOCKET_CHANNEL_URL`

- **Description**: Represents the URL for the WebSocket channel.
```

--------------------------------

### Take Storage Value

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket/channel/struct.SocketContext.html

Takes ownership of the stored value, leaving the original storage empty or in a default state. Use this when you need to consume the value.

```rust
fn into_taken(self) -> T
```

--------------------------------

### Define Socket Messages and Usage

Source: https://docs.rs/leptos-axum-socket/latest/index.html

Implement the SocketMsg trait to link key and message types, then use expect_socket_context to subscribe or send messages within components and server functions.

```rust
// Define the key and message types
#[derive(Clone, Serialize, Deserialize, PartialEq, Eq, Hash, Debug)]
pub struct MyKey {
    pub bla: String,
}

#[derive(Clone, Serialize, Deserialize, Debug)]
pub struct MyMsg {
    pub awesome_msg: String,
}

// Implement the SocketMsg trait for MyMsg to link the key and message types
impl SocketMsg for MyMsg {
    type Key = MyKey;
    #[cfg(feature = "ssr")]
    type AppState = AppState;
}

#[component]
pub fn MyComponent() -> impl IntoView {
    let socket = expect_socket_context();

    // Subscribe to receive messages that are sent with the given key
    socket.subscribe(
        MyKey {
            bla: "bla".to_string(),
        },
        |msg: &MyMsg| {
            // Simply log the message
            leptos::logging::log!("message: {msg:#?}");
        },
    );

    let on_click = move || {
        // Send a message with the given key
        socket.send(
            MyKey {
                bla: "bla".to_string(),
            },
            MyMsg {
                awesome_msg: "awesome message".to_string(),
            },
        );
    };

    view! { "..." }
}

#[server]
pub async fn my_server_function() -> Result<(), ServerFnError> {
    // Send from the server
    leptos_axum_socket::send(
       &MyKey {
           bla: "bla".to_string(),
       },
       &MyMsg {
           awesome_msg: "Hello, world!".to_string(),
       },
    ).await;

    Ok(())
}
```

--------------------------------

### Send Messages from an Axum Server Function

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket/index.html

Send messages from the server using the `leptos_axum_socket::send` function. Ensure the `ssr` feature is enabled.

```rust
#[server]
pub async fn my_server_function() -> Result<(), ServerFnError> {
    // Send from the server
    leptos_axum_socket::send(
       &MyKey {
           bla: "bla".to_string(),
       },
       &MyMsg {
           awesome_msg: "Hello, world!".to_string(),
       },
    ).await;

    Ok(())
}
```

--------------------------------

### Define Key and Message Types for Socket Communication

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket

Define serializable and cloneable key and message types for your socket communication. Implement the SocketMsg trait to link them. The AppState type is required for SSR.

```rust
#[derive(Clone, Serialize, Deserialize, PartialEq, Eq, Hash, Debug)]
pub struct MyKey {
    pub bla: String,
}

#[derive(Clone, Serialize, Deserialize, Debug)]
pub struct MyMsg {
    pub awesome_msg: String,
}

// Implement the SocketMsg trait for MyMsg to link the key and message types
impl SocketMsg for MyMsg {
    type Key = MyKey;
    #[cfg(feature = "ssr")]
    type AppState = AppState;
}
```

--------------------------------

### SocketMsg Trait Implementation

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket/trait.SocketMsg.html

This snippet demonstrates how to implement the SocketMsg trait for custom message types, linking them to their corresponding key types and optionally defining an application state for server-side usage.

```APIDOC
## Trait SocketMsg

### Description
Implement this trait to link your socket message types to your key types. In order to use this crate you have to implement this trait for your socket messages. On the server you have to provide the application state as well.

### Required Associated Types
#### type Key

### Example Implementation
```rust
// Define the key and message types
#[derive(Clone, Serialize, Deserialize)]
pub struct MyKey {
    pub bla: String,
}

#[derive(Clone, Serialize, Deserialize, Debug)]
pub struct MyMsg {
    pub awesome_msg: String,
}

// Implement the SocketMsg trait for MyMsg to link the key and message types
impl SocketMsg for MyMsg {
    type Key = MyKey;
    #[cfg(feature = "ssr")]
    type AppState = AppState;
}
```
```

--------------------------------

### Define WEBSOCKET_CHANNEL_URL

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket/channel/constant.WEBSOCKET_CHANNEL_URL.html

This constant specifies the default path for WebSocket messages. Ensure this matches the server configuration.

```rust
pub const WEBSOCKET_CHANNEL_URL: &str = "/socket-msg";
```

--------------------------------

### Attempt to Serialize into HTTP Request (Patch)

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket/channel/struct.SocketContext.html

Attempts to serialize the arguments into an HTTP request for the Patch method. Requires the request type to implement ClientReq and the encoding to implement Encodes.

```rust
fn into_req(self, path: &str, accepts: &str) -> Result<Request, E>
```

--------------------------------

### Socket Subscription and Messaging API

Source: https://docs.rs/leptos-axum-socket/latest/src/leptos_axum_socket/channel/context.rs.html

Methods for managing socket subscriptions and sending messages to specific keys.

```APIDOC
## Unsubscribe

### Description
Stop listening for messages associated with a specific key.

### Parameters
#### Request Body
- **key** (Serialize) - Required - The key identifier to unsubscribe from.

---

## Send Message

### Description
Broadcast a message to all subscribers of a given key.

### Parameters
#### Request Body
- **key** (Msg::Key) - Required - The key to broadcast the message to.
- **msg** (Msg) - Required - The message payload to send.
```

--------------------------------

### Create Owned Data from Borrowed Data

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket/channel/struct.SocketContext.html

Creates an owned version of the data, typically by cloning the borrowed data. This is the standard way to obtain ownership from a reference.

```rust
fn to_owned(&self) -> T
```

--------------------------------

### Define SocketContext structure

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket/channel/struct.SocketContext.html

The internal structure definition for SocketContext.

```rust
pub struct SocketContext { /* private fields */ }
```

--------------------------------

### Serialize Key to String

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket/channel/struct.SocketContext.html

Serializes the key into a unique string representation. This is useful for creating unique identifiers or keys for storage.

```rust
fn ser_key(&self) -> String
```

--------------------------------

### Send Messages from the Server using Leptos Axum Socket

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket

Send messages from the server-side using the leptos_axum_socket::send function. This function is available within server functions.

```rust

#[server]
pub async fn my_server_function() -> Result<(), ServerFnError> {
    // Send from the server
    leptos_axum_socket::send(
       &MyKey {
           bla: "bla".to_string(),
       },
       &MyMsg {
           awesome_msg: "Hello, world!".to_string(),
       },
    ).await;

    Ok(())
}
```

--------------------------------

### use_socket_context Function

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket/channel/fn.use_socket_context.html

The `use_socket_context` function allows components to subscribe to or send messages through the socket.

```APIDOC
## use_socket_context

### Description
Call this when you want to subscribe or send a message in your component.

### Signature
```rust
pub fn use_socket_context() -> Option<SocketContext>
```

### Returns
An `Option<SocketContext>` which is `Some(SocketContext)` if a socket context is available, otherwise `None`.
```

--------------------------------

### Socket Context Management

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket/channel/fn.expect_socket_context.html

Provides a function to access the socket context, essential for sending and receiving messages within components.

```APIDOC
## expect_socket_context

### Description
Call this when you want to subscribe or send a message in your component.

### Function Signature
```rust
pub fn expect_socket_context() -> SocketContext
```

### Usage
This function is typically called within a Leptos component to obtain the `SocketContext`.

### Parameters
None

### Returns
- `SocketContext`: An instance of the socket context.

### Example
```rust
let socket_context = expect_socket_context();
// Use socket_context to send or subscribe to messages
```
```

--------------------------------

### Subscribe Effect Implementation

Source: https://docs.rs/leptos-axum-socket/latest/src/leptos_axum_socket/channel/context.rs.html

Handles the reactive subscription effect and cleanup logic for client-side socket connections.

```rust
#[cfg(not(feature = "ssr"))]
    fn subscribe_effect(self, key_value: Value, handler: Arc<dyn Fn() + Send + Sync>) {
        Effect::new({
            let key_value = key_value.clone();

            move || {
                if self.ready_state.get() == ConnectionReadyState::Open {
                    self.send.get_value()(&ChannelMsg::Subscribe {
                        key: key_value.clone(),
                    });
                }
            }
        });

        on_cleanup({
            let key_value = key_value.clone();

            move || {
                self.unsubscribe(key_value);
            }
        });

        let effect = Effect::new(move || handler());

        self.effect_stops
            .write_value()
            .insert(key_value, Box::new(move || effect.stop()));
    }
```

--------------------------------

### Response Serialization API

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket/channel/struct.SocketContext.html

Asynchronous methods for serializing outputs into HTTP responses.

```APIDOC
## POST/PUT/PATCH into_res

### Description
Attempts to serialize the output into an HTTP response asynchronously for Patch, Post, or Put operations.
```

--------------------------------

### Define Channel Message Structures and Server Utilities

Source: https://docs.rs/leptos-axum-socket/latest/src/leptos_axum_socket/channel/mod.rs.html

Defines the ChannelMsg enum for WebSocket communication and exports server-side socket utilities when the ssr feature is enabled.

```rust
1use std::fmt::Debug;

3use serde::{Deserialize, Serialize};

5mod context;
6#[cfg(feature = "ssr")]
7mod server;

9pub use context::*;
10use serde_json::Value;
11#[cfg(feature = "ssr")]
12pub use server::{ServerSocket, ServerSocketInner, send, send_to_self};

14pub const WEBSOCKET_CHANNEL_URL: &str = "/socket-msg";

16#[derive(Debug, Serialize, Deserialize, Clone)]
17pub(crate) enum ChannelMsg {
18    Msg { key: Value, msg: Value },
19    Subscribe { key: Value },
20    Unsubscribe { key: Value },
21}
```

--------------------------------

### Access Socket Context

Source: https://docs.rs/leptos-axum-socket/latest/src/leptos_axum_socket/channel/context.rs.html

Helper functions to retrieve the socket context from the current Leptos scope.

```rust
pub fn expect_socket_context() -> SocketContext {
    expect_context()
}
```

```rust
pub fn use_socket_context() -> Option<SocketContext> {
    use_context()
}
```

--------------------------------

### WEBSOCKET_CHANNEL_URL Constant

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket/channel/constant.WEBSOCKET_CHANNEL_URL.html

Defines the default endpoint path used for WebSocket communication.

```APIDOC
## GET /socket-msg

### Description
The default endpoint path used for establishing a WebSocket connection for message handling.

### Method
GET

### Endpoint
/socket-msg
```

--------------------------------

### SocketContext Methods

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket/channel/struct.SocketContext.html

The SocketContext provides functionality to manage WebSocket connections and message handling within Leptos components.

```APIDOC
## SocketContext

leptos_axum_socket::channel

### Description
The context to be used for sending and subscribing to messages in your component. You probably don’t want to use this directly, but rather use the `expect_socket_context` hook.

### Methods

#### `reconnect(&self)`

Disconnects and re-connects the WebSocket. This helps if you want to reset the context on the server. For example, you can use this method to update the websocket handler context when the user logs out or in.

#### `subscribe<Msg>(self, key_value: Msg::Key, handler: impl Fn(&Msg) + Send + Sync + 'static)`

When someone sends a message with the given key, the handler will be called.

**Type Parameters**
* `Msg`: Must implement `SocketMsg`, `Serialize`, `Clone`, and `Deserialize`.
* `Msg::Key`: Must implement `Serialize` and `Deserialize`.

**Parameters**
* `key_value`: The key to subscribe to.
* `handler`: The function to be called when a message with the given key is received.

#### `unsubscribe<Key>(self, key: Key)`

Stop listening for messages with the given key.

**Type Parameters**
* `Key`: Must implement `Serialize`.

**Parameters**
* `key`: The key of the messages to stop listening for.

#### `send<Msg>(self, key: Msg::Key, msg: Msg)`

Broadcast a message to all subscribers of the given key.

**Type Parameters**
* `Msg`: Must implement `SocketMsg`, `Serialize`, `Clone`, and `Deserialize`.
* `Msg::Key`: Must implement `Serialize` and `Deserialize`.

**Parameters**
* `key`: The key of the message.
* `msg`: The message to send.
```

--------------------------------

### Broadcast Socket Messages

Source: https://docs.rs/leptos-axum-socket/latest/src/leptos_axum_socket/channel/context.rs.html

Serializes and sends a message to the server for a specific key, provided the environment is not SSR.

```rust
pub fn send<Msg>(self, key: Msg::Key, msg: Msg)
    where
        Msg: SocketMsg + serde::Serialize + Clone,
        for<'de> Msg: serde::Deserialize<'de>,
        Msg::Key: serde::Serialize,
        for<'de> Msg::Key: serde::Deserialize<'de>,
    {
        #[cfg(feature = "ssr")]
        {
            let _ = key;
            let _ = msg;
        }

        #[cfg(not(feature = "ssr"))]
        {
            let key_value = serde_json::to_value(key)
                .map_err(|err| {
                    leptos::logging::error!("Failed to serialize key: {}", err);
                })
                .unwrap();

            let msg_value = serde_json::to_value(msg)
                .map_err(|err| {
                    leptos::logging::error!("Failed to serialize message: {}", err);
                })
                .unwrap();

            self.send.get_value()(&ChannelMsg::Msg {
                msg: msg_value,
                key: key_value,
            });
        }
    }
```

--------------------------------

### Subscribe to WebSocket Messages

Source: https://docs.rs/leptos-axum-socket/latest/src/leptos_axum_socket/channel/context.rs.html

Subscribes a handler to be called when a message with a specific key is received. Handles message deserialization and error logging.

```rust
pub fn subscribe<Msg>(self, key_value: Msg::Key, handler: impl Fn(&Msg) + Send + Sync + 'static)
    where
        Msg: SocketMsg + serde::Serialize + Clone,
        for<'de> Msg: serde::Deserialize<'de>,
        Msg::Key: serde::Serialize,
        for<'de> Msg::Key: serde::Deserialize<'de>,
    {
        #[cfg(feature = "ssr")]
        {
            let _ = key_value;
            let _ = handler;
        }

        #[cfg(not(feature = "ssr"))]
        {
            let key_value = serde_json::to_value(key_value)
                .map_err(|err| {
                    leptos::logging::error!("Failed to serialize key: {}", err);
                })
                .unwrap();

            let handler = {
                let key_value = key_value.clone();

                Arc::new(move || {
                    if let Some(msg) = self.message.read().as_ref() {
                        match msg {
                            ChannelMsg::Msg { msg, key } if &key_value == key => {
                                match serde_json::from_value(msg.clone()) {
                                    Err(err) => {
                                        leptos::logging::error!(
                                            "Failed to deserialize message: {}",
                                            err
                                        );
                                    }
                                    Ok(msg) => {
                                        handler(&msg);
                                    }
                                }
                            }
                            _ => {}
                        }
                    }
                })
            };
            self.subscribe_effect(key_value, handler);
        }
    }
```

--------------------------------

### SocketContext API

Source: https://docs.rs/leptos-axum-socket/latest/src/leptos_axum_socket/channel/context.rs.html

Provides context for sending and subscribing to messages via WebSocket. It manages connection state, message sending, and event subscriptions.

```APIDOC
## SocketContext

### Description
The `SocketContext` provides the necessary tools for components to interact with a WebSocket connection. It allows for sending messages, subscribing to specific message types, and monitoring the connection's ready state.

### Methods

#### `new(query: String) -> Self`

- **Description**: Initializes a new `SocketContext` instance. It constructs the WebSocket URL using the provided query string and establishes a WebSocket connection using `use_websocket_with_options`.
- **Parameters**:
  - `query` (String) - Optional query string to append to the WebSocket URL.

#### `reconnect(&self)`

- **Description**: Disconnects the current WebSocket connection and immediately attempts to re-establish it. This is useful for resetting the server-side context, for example, after a user logs in or out.
- **Usage**: Call this method when you need to force a reconnection, ensuring the server has the latest context.

#### `subscribe<Msg>(self, key_value: Msg::Key, handler: impl Fn(&Msg) + Send + Sync + 'static)`

- **Description**: Subscribes a handler function to be called when a message with a specific key is received. The handler is executed only if the received message's key matches the provided `key_value`.
- **Type Parameters**:
  - `Msg`: A type that implements `SocketMsg`, `Serialize`, and `Clone`. It also requires `Deserialize` for its key.
- **Parameters**:
  - `key_value` (Msg::Key) - The key to subscribe to. This is used to filter incoming messages.
  - `handler` (impl Fn(&Msg) + Send + Sync + 'static) - The callback function to execute when a matching message is received. It receives the deserialized message of type `Msg`.
- **Error Handling**: Logs an error if the `key_value` fails to serialize or if the incoming message fails to deserialize.

### Fields

- **`ready_state`**: `Signal<ConnectionReadyState>` - A signal that reflects the current connection status (e.g., Connecting, Open, Closing, Closed).
- **`send`**: `StoredValue<Arc<dyn Fn(&ChannelMsg) + Send + Sync + 'static>>` - A stored value containing a function to send `ChannelMsg` over the WebSocket.
- **`open`**: `StoredValue<Arc<dyn Fn() + Send + Sync + 'static>>` - A stored value containing a function to manually open the WebSocket connection.
- **`close`**: `StoredValue<Arc<dyn Fn() + Send + Sync + 'static>>` - A stored value containing a function to manually close the WebSocket connection.
- **`message`**: `Signal<Option<ChannelMsg>>` - A signal that emits the latest received `ChannelMsg`.
- **`effect_stops`**: `StoredValue<HashMap<Value, Box<dyn Fn() + Send + Sync + 'static>>>` - Internal storage for effect cleanup functions, keyed by message value.
- **`subscribers`**: `StoredValue<HashMap<Value, Arc<dyn Fn() + Send + Sync>>>` - Internal storage for active message subscribers.
```

--------------------------------

### Request Serialization API

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket/channel/struct.SocketContext.html

Methods for serializing arguments into HTTP requests for various HTTP methods.

```APIDOC
## POST/PUT/PATCH into_req

### Description
Attempts to serialize the arguments into an HTTP request for Patch, Post, or Put operations.

### Parameters
#### Path Parameters
- **path** (str) - Required - The target path for the request.
- **accepts** (str) - Required - The accepted content type header.
```

--------------------------------

### Define Socket Message Types

Source: https://docs.rs/leptos-axum-socket/latest/src/leptos_axum_socket/lib.rs.html

Implement the SocketMsg trait to link custom message types with keys and application state.

```rust
# use leptos_axum_socket::{ServerSocket, SocketMsg};
# use serde::{Serialize, Deserialize};
# use axum::extract::FromRef;
#
# #[derive(FromRef, Clone)]
# pub struct AppState {
#     pub socket: ServerSocket,
# }
#
// Define the key and message types
#[derive(Clone, Serialize, Deserialize)]
pub struct MyKey {
    pub bla: String,
}

#[derive(Clone, Serialize, Deserialize, Debug)]
pub struct MyMsg {
    pub awesome_msg: String,
}

// Implement the SocketMsg trait for MyMsg to link the key and message types
impl SocketMsg for MyMsg {
    type Key = MyKey;
    #[cfg(feature = "ssr")]
    type AppState = AppState;
}
```

--------------------------------

### Borrow Storage Value

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket/channel/struct.SocketContext.html

Provides a borrowed reference to the stored value. This allows accessing the value without taking ownership.

```rust
fn as_borrowed(&self) -> &T
```

--------------------------------

### Replace Owned Data with Borrowed Data

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket/channel/struct.SocketContext.html

Uses borrowed data to replace the contents of owned data, usually by cloning. This is an efficient way to update owned data in place.

```rust
fn clone_into(&self, target: &mut T)
```

--------------------------------

### Access SocketContext

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket/channel/fn.use_socket_context.html

Call this function within a component to retrieve the current socket context.

```rust
pub fn use_socket_context() -> Option<SocketContext>
```

--------------------------------

### Convert to Either Variant

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket/channel/struct.SocketContext.html

Converts `self` into a `Left` or `Right` variant of `Either<Self, Self>` based on a provided closure's boolean return value.

```rust
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,
```

--------------------------------

### Attempt Conversion to Another Type

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket/channel/struct.SocketContext.html

Attempts to convert `self` into type `U`. The conversion may fail, returning a specific error type defined by `U`'s `TryFrom` implementation.

```rust
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
```

--------------------------------

### Unsubscribe from Socket Messages

Source: https://docs.rs/leptos-axum-socket/latest/src/leptos_axum_socket/channel/context.rs.html

Removes subscription handlers and sends an unsubscribe message to the server when not in SSR mode.

```rust
pub fn unsubscribe<Key>(self, key: Key)
    where
        Key: serde::Serialize,
    {
        #[cfg(feature = "ssr")]
        {
            let _ = key;
        }

        #[cfg(not(feature = "ssr"))]
        {
            let key_value = serde_json::to_value(key)
                .map_err(|err| {
                    leptos::logging::error!("Failed to serialize key: {}", err);
                })
                .unwrap();

            self.effect_stops.write_value().remove(&key_value);
            self.subscribers.write_value().remove(&key_value);

            self.send.get_value()(&ChannelMsg::Unsubscribe { key: key_value });
        }
    }
```

--------------------------------

### Define SocketMsg Trait

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket/trait.SocketMsg.html

The base definition of the SocketMsg trait requiring a Key associated type.

```rust
pub trait SocketMsg {
    type Key;
}
```

--------------------------------

### Perform Conversion from Another Type

Source: https://docs.rs/leptos-axum-socket/latest/leptos_axum_socket/channel/struct.SocketContext.html

Performs a conversion from type `U` into type `T`. The conversion may fail, returning an `Infallible` error type, indicating that this specific conversion is always possible if `U` can be converted into `T`.

```rust
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
```
Tokens:
Raw