feat: (WIP) SSC Server Side Computed

mirkobrombin · mirkobrombin · commit d23852a5be64 · 2025-08-22T00:52:51.000+02:00
replacing SSR Server Side Rendering
diff --git a/cmd/rfw/build/build.go b/cmd/rfw/build/build.go
@@ -25,19 +25,28 @@ func Build() error {
 		return fmt.Errorf("failed to copy wasm_exec.js: %w", err)
 	}
 
-	cmd := exec.Command("go", "build", "-o", "main.wasm", "main.go")
+	cmd := exec.Command("go", "build", "-o", "app.wasm", "main.go")
 	cmd.Env = append(os.Environ(), "GOARCH=wasm", "GOOS=js")
 	output, err := cmd.CombinedOutput()
 	if err != nil {
 		return fmt.Errorf("failed to build project: %s: %w", output, err)
 	}
 
 	var manifest struct {
+		Build struct {
+			Type string `json:"type"`
+		} `json:"build"`
 		Plugins map[string]json.RawMessage `json:"plugins"`
 	}
 	if data, err := os.ReadFile("rfw.json"); err == nil {
 		_ = json.Unmarshal(data, &manifest)
 	}
+	if strings.EqualFold(manifest.Build.Type, "ssc") {
+		hostCmd := exec.Command("go", "build", "-o", "host/host", "./host")
+		if hostOutput, err := hostCmd.CombinedOutput(); err != nil {
+			return fmt.Errorf("failed to build host components: %s: %w", hostOutput, err)
+		}
+	}
 	if err := plugins.Configure(manifest.Plugins); err != nil {
 		return fmt.Errorf("failed to run plugins: %w", err)
 	}
diff --git a/cmd/rfw/server/server.go b/cmd/rfw/server/server.go
@@ -2,11 +2,13 @@ package server
 
 import (
 	"bufio"
+	"encoding/json"
 	"expvar"
 	"fmt"
 	"net/http"
 	"net/http/pprof"
 	"os"
+	"os/exec"
 	"os/signal"
 	"path/filepath"
 	"strings"
@@ -21,11 +23,13 @@ import (
 var rebuilds = expvar.NewInt("rebuilds")
 
 type Server struct {
-	Port    string
-	Host    bool
-	Debug   bool
-	stopCh  chan os.Signal
-	watcher *fsnotify.Watcher
+	Port      string
+	Host      bool
+	Debug     bool
+	stopCh    chan os.Signal
+	watcher   *fsnotify.Watcher
+	hostCmd   *exec.Cmd
+	buildType string
 }
 
 func NewServer(port string, host, debug bool) *Server {
@@ -43,6 +47,14 @@ func (s *Server) Start() error {
 		return err
 	}
 
+	// Detect build type from manifest to know if host components are enabled.
+	s.buildType = readBuildType()
+	if s.buildType == "ssc" {
+		if err := s.startHost(); err != nil {
+			return err
+		}
+	}
+
 	mux := http.NewServeMux()
 
 	fs := http.FileServer(http.Dir("."))
@@ -93,6 +105,7 @@ func (s *Server) Start() error {
 
 	<-s.stopCh
 	utils.Info("Server stopped.")
+	s.stopHost()
 	return nil
 }
 
@@ -171,6 +184,12 @@ func (s *Server) watchFiles() {
 				if err := build.Build(); err != nil {
 					utils.Fatal("Failed to rebuild project: ", err)
 				}
+				if s.buildType == "ssc" {
+					s.stopHost()
+					if err := s.startHost(); err != nil {
+						utils.Fatal("Failed to restart host server: ", err)
+					}
+				}
 			}
 		case err, ok := <-s.watcher.Errors:
 			if !ok {
@@ -179,7 +198,38 @@ func (s *Server) watchFiles() {
 			utils.Info(fmt.Sprintf("Watcher error: %v", err))
 		case <-s.stopCh:
 			s.watcher.Close()
+			s.stopHost()
 			return
 		}
 	}
 }
+
+// readBuildType reads the build type from rfw.json if present.
+func readBuildType() string {
+	var manifest struct {
+		Build struct {
+			Type string `json:"type"`
+		} `json:"build"`
+	}
+	data, err := os.ReadFile("rfw.json")
+	if err != nil {
+		return ""
+	}
+	_ = json.Unmarshal(data, &manifest)
+	return strings.ToLower(manifest.Build.Type)
+}
+
+func (s *Server) startHost() error {
+	s.hostCmd = exec.Command("./host/host")
+	s.hostCmd.Stdout = os.Stdout
+	s.hostCmd.Stderr = os.Stderr
+	return s.hostCmd.Start()
+}
+
+func (s *Server) stopHost() {
+	if s.hostCmd != nil && s.hostCmd.Process != nil {
+		_ = s.hostCmd.Process.Kill()
+		_, _ = s.hostCmd.Process.Wait()
+	}
+	s.hostCmd = nil
+}
diff --git a/docs/articles/guide/ssc.md b/docs/articles/guide/ssc.md
@@ -0,0 +1,13 @@
+# Server Side Computed
+
+The project manifest (`rfw.json`) can declare the build type. Setting it to `ssc` enables Server Side Computed builds.
+
+```json
+{
+  "build": {
+    "type": "ssc"
+  }
+}
+```
+
+When `ssc` is active, `rfw build` compiles the Wasm bundle and also builds the Go sources in the `host` directory into a server binary. The server keeps variables and commands prefixed with `h:` synchronized with the client through a persistent WebSocket connection.
diff --git a/docs/articles/sidebar.json b/docs/articles/sidebar.json
@@ -17,7 +17,8 @@
             { "title": "API Integration", "path": "guide/api-integration.md" },
             { "title": "Animations", "path": "guide/animation.md" },
             { "title": "Plugins", "path": "guide/plugins.md" },
-            { "title": "Server-Side Rendering", "path": "guide/ssr.md" }
+            { "title": "Server-Side Rendering", "path": "guide/ssr.md" },
+            { "title": "Server Side Computed", "path": "guide/ssc.md" }
         ]
     },
     {
diff --git a/docs/components/home_component.go b/docs/components/home_component.go
@@ -16,6 +16,7 @@ var homeTpl []byte
 
 func NewHomeComponent() *core.HTMLComponent {
 	c := core.NewComponent("HomeComponent", homeTpl, nil)
+	c.AddHostComponent("HomeHost")
 	c.SetOnMount(func(cmp *core.HTMLComponent) {
 		doc := js.Document()
 		add := func(sel, path string) {
diff --git a/docs/components/templates/home_component.rtml b/docs/components/templates/home_component.rtml
@@ -10,6 +10,7 @@
     <section class="text-center py-20 bg-gradient-to-r from-blue-500 to-purple-600 text-white">
       <h1 class="text-5xl font-extrabold mb-4">Build reactive apps in Go</h1>
       <p class="text-lg mb-8">rfw lets you write modern web UIs with Go and WebAssembly.</p>
+      <p class="mt-4">{h:welcome}</p>
       <a href="/docs/getting-started" class="px-6 py-3 bg-white text-blue-600 font-semibold rounded shadow">Get Started</a>
     </section>
     <section class="py-20 bg-gray-50">
diff --git a/docs/host/host b/docs/host/host
diff --git a/docs/host/main.go b/docs/host/main.go
@@ -0,0 +1,49 @@
+package main
+
+import (
+	"encoding/json"
+	"io"
+	"log"
+	"net/http"
+
+	"golang.org/x/net/websocket"
+
+	"github.com/rfwlab/rfw/v1/host"
+)
+
+type inbound struct {
+	Component string          `json:"component"`
+	Payload   json.RawMessage `json:"payload"`
+}
+
+func main() {
+	http.Handle("/ws", websocket.Handler(func(ws *websocket.Conn) {
+		defer ws.Close()
+		for {
+			var raw []byte
+			if err := websocket.Message.Receive(ws, &raw); err != nil {
+				if err == io.EOF {
+					break
+				}
+				log.Printf("recv: %v", err)
+				return
+			}
+			var msg inbound
+			if err := json.Unmarshal(raw, &msg); err != nil {
+				log.Printf("unmarshal: %v", err)
+				continue
+			}
+			if hc, ok := host.Get(msg.Component); ok {
+				ctx := host.NewContext(ws, msg.Component)
+				hc.Handle(ctx, msg.Payload)
+			}
+		}
+	}))
+	log.Fatal(http.ListenAndServe(":8090", nil))
+}
+
+func init() {
+	host.Register(host.NewHostComponent("HomeHost", func(ctx *host.Context, payload json.RawMessage) {
+		_ = ctx.Notify(map[string]any{"welcome": "hello from host"})
+	}))
+}
diff --git a/docs/main.wasm b/docs/main.wasm
diff --git a/docs/rfw.json b/docs/rfw.json
@@ -1,4 +1,7 @@
 {
+    "build": {
+        "type": "ssc"
+    },
     "plugins": {
         "tailwind": {
             "input": "input.css",
diff --git a/go.mod b/go.mod
@@ -7,6 +7,7 @@ require (
 	github.com/fsnotify/fsnotify v1.9.0
 	github.com/mirkobrombin/go-cli-builder v1.0.0
 	golang.org/x/net v0.33.0
+	nhooyr.io/websocket v1.8.10
 )
 
 require (
diff --git a/go.sum b/go.sum
@@ -15,3 +15,5 @@ golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBc
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.28.0 h1:Fksou7UEQUWlKvIdsqzJmUmCX3cZuD2+P3XyyzwMhlA=
 golang.org/x/sys v0.28.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+nhooyr.io/websocket v1.8.10 h1:mv4p+MnGrLDcPlBoWsvPP7XCzTYMXP9F9eIGoKbgx7Q=
+nhooyr.io/websocket v1.8.10/go.mod h1:rN9OFWIUwuxg4fR5tELlYC04bXYowCP9GX47ivo2l+c=
diff --git a/v1/core/html_component.go b/v1/core/html_component.go
@@ -13,6 +13,7 @@ import (
 	"strings"
 
 	"github.com/rfwlab/rfw/v1/dom"
+	hostclient "github.com/rfwlab/rfw/v1/hostclient"
 	js "github.com/rfwlab/rfw/v1/js"
 	"github.com/rfwlab/rfw/v1/state"
 )
@@ -40,7 +41,10 @@ type HTMLComponent struct {
 	Store             *state.Store
 	Props             map[string]any
 	Slots             map[string]any
+	HostComponent     string
 	conditionContents map[string]ConditionContent
+	hostVars          []string
+	hostCmds          []string
 	component         Component
 	onMount           func(*HTMLComponent)
 	onUnmount         func(*HTMLComponent)
@@ -123,6 +127,11 @@ func (c *HTMLComponent) Render() (renderedTemplate string) {
 	// Handle @prop:propName syntax for props
 	renderedTemplate = replacePropPlaceholders(renderedTemplate, c)
 
+	// Handle host variable and command placeholders
+	if c.HostComponent != "" {
+		renderedTemplate = replaceHostPlaceholders(renderedTemplate, c)
+	}
+
 	// Handle @if:condition syntax for conditional rendering
 	renderedTemplate = replaceConditionals(renderedTemplate, c)
 
@@ -135,6 +144,10 @@ func (c *HTMLComponent) Render() (renderedTemplate string) {
 	// Render any components introduced via rt-is placeholders
 	renderedTemplate = replaceIncludePlaceholders(c, renderedTemplate)
 
+	if c.HostComponent != "" {
+		hostclient.RegisterComponent(c.ID, c.HostComponent, c.hostVars)
+	}
+
 	return renderedTemplate
 }
 
@@ -227,6 +240,13 @@ func (c *HTMLComponent) SetRouteParams(params map[string]string) {
 	}
 }
 
+// AddHostComponent links this HTML component to a server-side HostComponent
+// by name. When running in SSC mode, messages from the wasm runtime will be
+// routed to the corresponding host component on the server.
+func (c *HTMLComponent) AddHostComponent(name string) {
+	c.HostComponent = name
+}
+
 func generateComponentID(name string, props map[string]any) string {
 	hasher := sha1.New()
 	hasher.Write([]byte(name))
diff --git a/v1/core/rtml.go b/v1/core/rtml.go
@@ -277,6 +277,22 @@ func replacePropPlaceholders(template string, c *HTMLComponent) string {
 	})
 }
 
+func replaceHostPlaceholders(template string, c *HTMLComponent) string {
+	varRegex := regexp.MustCompile(`\{h:(\w+)\}`)
+	template = varRegex.ReplaceAllStringFunc(template, func(match string) string {
+		name := varRegex.FindStringSubmatch(match)[1]
+		c.hostVars = append(c.hostVars, name)
+		return fmt.Sprintf(`<span data-host-var="%s"></span>`, name)
+	})
+	cmdRegex := regexp.MustCompile(`@h:(\w+)`)
+	template = cmdRegex.ReplaceAllStringFunc(template, func(match string) string {
+		name := cmdRegex.FindStringSubmatch(match)[1]
+		c.hostCmds = append(c.hostCmds, name)
+		return fmt.Sprintf(`data-host-cmd="%s"`, name)
+	})
+	return template
+}
+
 func replaceEventHandlers(template string) string {
 	// Match event directives ensuring they are terminated by whitespace,
 	// a self-closing slash or the end of the tag. The terminating
diff --git a/v1/host/host_component.go b/v1/host/host_component.go
@@ -0,0 +1,66 @@
+package host
+
+import (
+	"encoding/json"
+
+	"golang.org/x/net/websocket"
+)
+
+// Context wraps a WebSocket connection and the component name so that
+// host components can easily notify the connected wasm runtime.
+// Messages are serialized as {"component": "name", "payload": any}.
+type Context struct {
+	conn      *websocket.Conn
+	component string
+}
+
+// NewContext creates a communication context for the given WebSocket
+// connection and component name.
+func NewContext(conn *websocket.Conn, component string) *Context {
+	return &Context{conn: conn, component: component}
+}
+
+// Notify sends a payload back to the wasm client for this component.
+func (c *Context) Notify(payload any) error {
+	msg := struct {
+		Component string `json:"component"`
+		Payload   any    `json:"payload"`
+	}{Component: c.component, Payload: payload}
+	b, err := json.Marshal(msg)
+	if err != nil {
+		return err
+	}
+	return websocket.Message.Send(c.conn, b)
+}
+
+// Handler processes inbound payloads for a HostComponent.
+type Handler func(ctx *Context, payload json.RawMessage)
+
+// HostComponent represents server-side logic backing an HTML component.
+type HostComponent struct {
+	name    string
+	handler Handler
+}
+
+// NewHostComponent registers a handler for the given component name.
+func NewHostComponent(name string, handler Handler) *HostComponent {
+	return &HostComponent{name: name, handler: handler}
+}
+
+func (hc *HostComponent) Name() string { return hc.name }
+
+// Handle executes the component's handler.
+func (hc *HostComponent) Handle(ctx *Context, payload json.RawMessage) {
+	if hc.handler != nil {
+		hc.handler(ctx, payload)
+	}
+}
+
+var registry = make(map[string]*HostComponent)
+
+// Register adds a HostComponent to the global registry so incoming messages
+// can be routed to it.
+func Register(hc *HostComponent) { registry[hc.name] = hc }
+
+// Get returns a registered HostComponent by name.
+func Get(name string) (*HostComponent, bool) { hc, ok := registry[name]; return hc, ok }
diff --git a/v1/hostclient/runtime.go b/v1/hostclient/runtime.go

Original file line number	Diff line number	Diff line change
`@@ -25,19 +25,28 @@ func Build() error {`
`25`	`25`	`return fmt.Errorf("failed to copy wasm_exec.js: %w", err)`
`26`	`26`	`}`
`27`	`27`
`28`		`- cmd := exec.Command("go", "build", "-o", "main.wasm", "main.go")`
	`28`	`+ cmd := exec.Command("go", "build", "-o", "app.wasm", "main.go")`
`29`	`29`	`cmd.Env = append(os.Environ(), "GOARCH=wasm", "GOOS=js")`
`30`	`30`	`output, err := cmd.CombinedOutput()`
`31`	`31`	`if err != nil {`
`32`	`32`	`return fmt.Errorf("failed to build project: %s: %w", output, err)`
`33`	`33`	`}`
`34`	`34`
`35`	`35`	`var manifest struct {`
	`36`	`+ Build struct {`
	`37`	+ Type string `json:"type"`
	`38`	+ } `json:"build"`
`36`	`39`	Plugins map[string]json.RawMessage `json:"plugins"`
`37`	`40`	`}`
`38`	`41`	`if data, err := os.ReadFile("rfw.json"); err == nil {`
`39`	`42`	`_ = json.Unmarshal(data, &manifest)`
`40`	`43`	`}`
	`44`	`+ if strings.EqualFold(manifest.Build.Type, "ssc") {`
	`45`	`+ hostCmd := exec.Command("go", "build", "-o", "host/host", "./host")`
	`46`	`+ if hostOutput, err := hostCmd.CombinedOutput(); err != nil {`
	`47`	`+ return fmt.Errorf("failed to build host components: %s: %w", hostOutput, err)`
	`48`	`+ }`
	`49`	`+ }`
`41`	`50`	`if err := plugins.Configure(manifest.Plugins); err != nil {`
`42`	`51`	`return fmt.Errorf("failed to run plugins: %w", err)`
`43`	`52`	`}`
Original file line number	Diff line number	Diff line change
`@@ -17,7 +17,8 @@`
`17`	`17`	`{ "title": "API Integration", "path": "guide/api-integration.md" },`
`18`	`18`	`{ "title": "Animations", "path": "guide/animation.md" },`
`19`	`19`	`{ "title": "Plugins", "path": "guide/plugins.md" },`
`20`		`- { "title": "Server-Side Rendering", "path": "guide/ssr.md" }`
	`20`	`+ { "title": "Server-Side Rendering", "path": "guide/ssr.md" },`
	`21`	`+ { "title": "Server Side Computed", "path": "guide/ssc.md" }`
`21`	`22`	`]`
`22`	`23`	`},`
`23`	`24`	`{`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,7 @@`
`1`	`1`	`{`
	`2`	`+ "build": {`
	`3`	`+ "type": "ssc"`
	`4`	`+ },`
`2`	`5`	`"plugins": {`
`3`	`6`	`"tailwind": {`
`4`	`7`	`"input": "input.css",`