Feature/websocket lifecycle callbacks

api-reference/lifecycle-hooks/on-chat-start.mdx

@@ -2,7 +2,7 @@
 title: "on_chat_start"
 ---
 
-Hook to react to the user websocket connection event.
+Hook to react to the initial user websocket connection event. Note: this callback will only fire on the initial connection for a user's session - use `on_socket_connect` to react to the connection being reestablished.
 
 ## Usage
 

api-reference/lifecycle-hooks/on_socket_connect.mdx

@@ -0,0 +1,28 @@
+---
+title: "on_socket_connect"
+---
+
+Hook to react to a new websocket connection to the front end. Note: this event should be triggered on all connection/reconnection events, including after client-side (eg browser moved to background on mobile), server-side (eg timeout) or connectivity issues. This event does not depend on authentication or data persistence - you can use the Chainlit session id to restore the chat state if required.
+
+## Usage
+
+```python
+import chainlit as cl
+
+@cl.on_socket_connect
+async def on_socket_connect:
+    print("Websocket connection established")
+    wsgi_env = cl.context.session.environ
+        # print(f"WSGI Environment: {wsgi_env}")
+        cookies = wsgi_env.get("HTTP_COOKIE", "No cookies found")
+        print(f"Cookies: {cookies}")
+        # Parse the cookie string to extract X-Chainlit-Session-id
+        session_id = "unknown"
+        if cookies != "No cookies found":
+            cookie_parts = [part.strip().split("=") for part in cookies.split(";")]
+            session_cookie = next((p[1] for p in cookie_parts if len(p) == 2 and p[0] == "X-Chainlit-Session-id"), None)
+            if session_cookie:
+                session_id = session_cookie
+                cl.user_session.set("session_id", session_id)
+        print(f"X-Chainlit-Session-id: {session_id}")
+```

api-reference/lifecycle-hooks/on_socket_disconnect.mdx

@@ -0,0 +1,21 @@
+---
+title: "on_socket_disconnect"
+---
+
+Hook to react to websocket disconnection. Note: this event should be triggered on all disconnection events, including after client-side (eg browser moved to background on mobile), server-side (eg timeout) or connectivity issues. Unlike `on_chat_end` it is not called in response to user-initiated changes in chat context, eg clicking "New Chat." The session id should be available in subsequent reconnection events - see `on_socket_connect` for how to retrieve it.
+
+## Usage
+
+```python
+import chainlit as cl
+
+@cl.on_socket_disconnect
+async def on_socket_disconnect():
+    print("WebSocket connection closed")
+    print(f"Context available: {hasattr(cl, 'context')}")
+    if hasattr(cl, "context"):
+        print(f"Session ID: {getattr(cl.context, 'session', None) and cl.context.session.id}")
+        print(f"Session type: {type(getattr(cl.context, 'session', None)).__name__ if hasattr(cl.context, 'session') else 'No session'}")
+    else:
+        print("No context available in on_socket_disconnect")
+```