feat: (WIP) session management for websocket conn in SSC

Author: mirkobrombin

docs/articles/api/host.md

@@ -6,6 +6,18 @@ The `host` package lets Go code back HTML components with server side logic. Com
 | --- | --- |
 | `HostComponent` | Couples a component name with a handler. |
 | `Register(hc *HostComponent)` | Adds a component to the global registry. |
+| `HandlerWithSession` | Function signature `func(*Session, map[string]any) any`. |
+| `NewHostComponentWithSession(name string, handler HandlerWithSession) *HostComponent` | Registers a session-aware handler that receives per-connection context. |
+| `(*HostComponent).HandleWithSession(session *Session, payload map[string]any) any` | Executes the session-aware callback, falling back to legacy handlers. |
 | `ListenAndServe(addr, root string)` | Serves files and exposes the WebSocket endpoint. |
 | `NewMux(root string)` | Returns a configured `*http.ServeMux`. |
+| `Broadcast(name string, payload any, opts ...BroadcastOption)` | Sends a payload to all subscribers or to a filtered session set. |
+| `WithSessionTarget(sessionID string) BroadcastOption` | Restricts a broadcast to a single session ID. |
+| `SessionByID(id string) (*Session, bool)` | Looks up the session currently attached to a WebSocket. |
+| `(*Session).ID() string` | Returns the server-generated session identifier. |
+| `(*Session).StoreManager() *state.StoreManager` | Exposes an isolated store manager for the connection. |
+| `(*Session).ContextSet/Get/Delete` | Manage arbitrary per-session context data. |
+| `(*Session).Snapshot() map[string]map[string]map[string]any` | Captures all stores registered in the session. |
+
+See the [SSC guide](../guide/ssc.md#session-scoped-hydration-data) for usage patterns.
 

docs/articles/api/hostclient.md

@@ -8,4 +8,7 @@ The `hostclient` runtime runs inside the WebAssembly bundle and maintains a WebS
 | `Send(name string, payload any)` | Serialise and write a payload to the socket. |
 | `RegisterHandler(name string, h func(map[string]any))` | Attach a callback for inbound payloads. |
 | `EnableDebug()` | Log WebSocket connection and message events. |
+| `SessionID() string` | Returns the last session identifier received from the host (also injected as `_session` in handler payloads). |
+
+See the [SSC guide](../guide/ssc.md#session-scoped-hydration-data) for session-aware patterns.
 

v1/host/host_component.go

@@ -1,31 +1,72 @@
 package host
 
+import "github.com/rfwlab/rfw/v1/state"
+
 // Handler processes inbound payloads for a HostComponent and returns a
 // response payload to send back to the wasm runtime. Returning nil results in
 // no message being sent.
 type Handler func(payload map[string]any) any
 
+// HandlerWithSession processes inbound payloads with the associated Session.
+type HandlerWithSession func(*Session, map[string]any) any
+
 // HostComponent represents server-side logic backing an HTML component.
 type HostComponent struct {
-	name    string
-	handler Handler
+	name           string
+	handler        Handler
+	sessionHandler HandlerWithSession
 }
 
 // NewHostComponent registers a handler for the given component name.
 func NewHostComponent(name string, handler Handler) *HostComponent {
-	return &HostComponent{name: name, handler: handler}
+	hc := &HostComponent{name: name, handler: handler}
+	if handler != nil {
+		hc.sessionHandler = func(_ *Session, payload map[string]any) any {
+			return handler(payload)
+		}
+	}
+	return hc
 }
 
 func (hc *HostComponent) Name() string { return hc.name }
 
 // Handle executes the component's handler.
 func (hc *HostComponent) Handle(payload map[string]any) any {
+	if hc.handler == nil {
+		return nil
+	}
+	return hc.handler(payload)
+}
+
+// NewHostComponentWithSession registers a session-aware handler.
+func NewHostComponentWithSession(name string, handler HandlerWithSession) *HostComponent {
+	return &HostComponent{name: name, sessionHandler: handler}
+}
+
+// HandleWithSession executes the session-aware handler when available.
+func (hc *HostComponent) HandleWithSession(session *Session, payload map[string]any) any {
+	if hc.sessionHandler != nil {
+		return hc.sessionHandler(session, payload)
+	}
 	if hc.handler != nil {
 		return hc.handler(payload)
 	}
 	return nil
 }
 
+// SessionAware reports whether the component registered a session handler.
+func (hc *HostComponent) SessionAware() bool { return hc.sessionHandler != nil }
+
+// StoreManager returns the session-specific store manager when available.
+// If session is nil a reference to the global manager is returned for
+// backward compatibility with legacy handlers.
+func (hc *HostComponent) StoreManager(session *Session) *state.StoreManager {
+	if session != nil {
+		return session.StoreManager()
+	}
+	return state.GlobalStoreManager
+}
+
 var registry = make(map[string]*HostComponent)
 
 // Register adds a HostComponent to the global registry so incoming messages

v1/host/host_test.go

@@ -24,6 +24,33 @@ func TestHostComponent(t *testing.T) {
 	}
 }
 
+func TestHostComponentWithSession(t *testing.T) {
+	hc := NewHostComponentWithSession("withSession", func(session *Session, payload map[string]any) any {
+		if session == nil {
+			t.Fatalf("session should not be nil")
+		}
+		store := session.StoreManager().NewStore("test")
+		store.Set("value", payload["v"])
+		return store.Snapshot()
+	})
+
+	sess := newSession("abc")
+	resp := hc.HandleWithSession(sess, map[string]any{"v": 42})
+	snap, ok := resp.(map[string]any)
+	if !ok {
+		t.Fatalf("unexpected response type %T", resp)
+	}
+	if snap["value"] != 42 {
+		t.Fatalf("unexpected store snapshot: %v", snap)
+	}
+	if !hc.SessionAware() {
+		t.Fatalf("expected session aware component")
+	}
+	if hc.StoreManager(sess) != sess.StoreManager() {
+		t.Fatalf("StoreManager helper mismatch")
+	}
+}
+
 // TestLogLevel checks environment variable parsing.
 func TestLogLevel(t *testing.T) {
 	t.Setenv("RFW_LOG_LEVEL", "debug")

v1/host/session.go

@@ -0,0 +1,97 @@
+package host
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"sync"
+
+	"github.com/rfwlab/rfw/v1/state"
+)
+
+// Session represents per-connection state for a WebSocket client.
+// It exposes an isolated StoreManager and a context bag for arbitrary data.
+type Session struct {
+	id     string
+	stores *state.StoreManager
+
+	ctxMu sync.RWMutex
+	ctx   map[string]any
+}
+
+func newSession(id string) *Session {
+	return &Session{
+		id:     id,
+		stores: state.NewStoreManager(),
+		ctx:    make(map[string]any),
+	}
+}
+
+func (s *Session) ID() string { return s.id }
+
+func (s *Session) StoreManager() *state.StoreManager { return s.stores }
+
+// ContextGet retrieves a value from the session context.
+func (s *Session) ContextGet(key string) (any, bool) {
+	s.ctxMu.RLock()
+	defer s.ctxMu.RUnlock()
+	v, ok := s.ctx[key]
+	return v, ok
+}
+
+// ContextSet stores a value in the session context.
+func (s *Session) ContextSet(key string, value any) {
+	s.ctxMu.Lock()
+	s.ctx[key] = value
+	s.ctxMu.Unlock()
+}
+
+// ContextDelete removes a value from the session context.
+func (s *Session) ContextDelete(key string) {
+	s.ctxMu.Lock()
+	delete(s.ctx, key)
+	s.ctxMu.Unlock()
+}
+
+// Snapshot returns a copy of all stores registered in this session.
+func (s *Session) Snapshot() map[string]map[string]map[string]any {
+	return s.stores.Snapshot()
+}
+
+var (
+	sessionMu sync.RWMutex
+	sessions  = make(map[string]*Session)
+)
+
+func allocateSession() *Session {
+	id := generateSessionID()
+	session := newSession(id)
+	sessionMu.Lock()
+	sessions[id] = session
+	sessionMu.Unlock()
+	return session
+}
+
+func releaseSession(session *Session) {
+	if session == nil {
+		return
+	}
+	sessionMu.Lock()
+	delete(sessions, session.id)
+	sessionMu.Unlock()
+}
+
+// SessionByID retrieves a session for the given ID.
+func SessionByID(id string) (*Session, bool) {
+	sessionMu.RLock()
+	defer sessionMu.RUnlock()
+	s, ok := sessions[id]
+	return s, ok
+}
+
+func generateSessionID() string {
+	buf := make([]byte, 16)
+	if _, err := rand.Read(buf); err != nil {
+		panic(err)
+	}
+	return hex.EncodeToString(buf)
+}