feat(ws): release generic WebSocket client and server v0.31.0-preview

examples/managedService/.goOmni/apiManifest.json

@@ -13,7 +13,7 @@
   "generated": {
     "docs/openapi.json": "0370fd6bd6a387e2ef21f6b42b009ce66749846b8bea3d481009a34f3af039a5",
     "internal/config/loadGen.go": "d85e3123e4c96c95cb0886e60e4760230426efca4d2bbbfc981822da08b90d13",
-    "internal/handler/appGen.go": "f5251b4dc33e2312b0bdb71ead70d2171977d851265e124f640458d705a2cc9d",
+    "internal/handler/appGen.go": "66e54c8f60fc273b4dc856c9578390b15604d99ad2e581a1899cc4b7ebb70f3b",
     "internal/handler/demo/handlersGen.go": "3c76d85dbe89eb5127d9d134dc625203ecf9719dd11d174c1f335691b99e1375",
     "internal/handler/openapiGen.go": "f24cab3abbb8557a3fc4dd93fba23cc0b093f3e0c944d3ba1bd5b0eeff2d96f3",
     "internal/handler/responseGen.go": "84397a502bba4777ebfa6fae3d3bc418297acab4f26b04b42e3c31b36c735399",

examples/managedService/internal/handler/appGen.go

@@ -2,6 +2,7 @@
 package handler
 
 import (
+	"errors"
 	"fmt"
 	omni "git.yuntuo.hk/k2safe/go-omni"
 	"git.yuntuo.hk/k2safe/go-omni/contract"
@@ -66,5 +67,11 @@ func NewApp(deps *svc.ServiceContext) (*omni.App, error) {
 		}
 		app.GET(cfg.Endpoints.Readiness.Path, deps.Health.ReadinessHandler(options...))
 	}
+	// Optional project-owned extension; no generated file needs hand edits.
+	if extension, ok := any(deps).(interface{ RegisterCustomRoutes(*omni.App) error }); ok {
+		if err := extension.RegisterCustomRoutes(app); err != nil {
+			return nil, errors.Join(err, app.Close())
+		}
+	}
 	return app, nil
 }

examples/mixedWorkspace/README.md

@@ -1,11 +1,11 @@
 # API 与通用工程混合工作区
 
-本例只定义生成工程的类型与目录，不包含业务模型、外部服务或特定调度方式。使用 v0.30.0-preview 或更新版本 CLI。
+本例只定义生成工程的类型与目录，不包含业务模型、外部服务或特定调度方式。使用 v0.31.0-preview 或更新版本 CLI。
 
 下面从一个空目录创建两个独立 Go module；API 工程来自 API 模板，通用工程默认不监听端口。
 
 ```sh
-go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.30.0-preview
+go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.31.0-preview
 mkdir mixed-demo
 cd mixed-demo
 go-omni api new apps/interface --module example.com/interface

examples/recursiveResponse/README.md

@@ -5,7 +5,7 @@
 在 go-omni 仓库根目录执行（新建独立临时目录）：
 
 ```sh
-go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.30.0-preview
+go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.31.0-preview
 example_dir="$(mktemp -d)/recursive"
 go-omni api generate --api examples/recursiveResponse/service.api --dir "$example_dir" --module example.com/recursive
 # 以下文件仅是本次新生成示例的占位实现，替换为示例自身维护的逻辑。

examples/websocket/README.md

@@ -0,0 +1,17 @@
+# WebSocket 通用示例
+
+不依赖外部基础设施，默认在随机本机端口启动 GoOmni Server、Go Client 和 Hub，完成文本回显、分组广播后排空退出：
+
+```sh
+go run ./examples/websocket
+```
+
+预期输出 `hello websocket`、`hello group`。浏览器标准 WebSocket 示例：
+
+```sh
+go run ./examples/websocket -serve
+```
+
+打开 http://127.0.0.1:8088 的两个标签页，点击连接、发送、广播。Ctrl+C 触发 HTTP 排空、WS Stop/Drain、Hub 关闭。示例只监听 loopback，无鉴权；接入项目在升级前验证自己的身份和分组权限。浏览器使用同源策略；跨域部署通过明确的 `AllowedOrigins` 配置。
+
+完整 API、限制与安全说明见 [ws](../../ws/README.md)；双向调用与重连订阅见 [websocketRPC](../websocketRPC/README.md)。

examples/websocket/index.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="zh-CN"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>GoOmni WebSocket 示例</title>
+<style>body{font:16px system-ui;max-width:720px;margin:60px auto;padding:0 24px;color:#182b3d}button,input{font:inherit;padding:10px;margin:4px}pre{white-space:pre-wrap;background:#f2f5f8;padding:20px;min-height:180px}#state{color:#52697b}</style>
+<h1>WebSocket 回显与分组广播</h1><p>打开两个标签页，连接后发送文本或广播。</p>
+<p id="state">未连接</p><button id="connect">连接</button><button id="disconnect">断开</button>
+<p><input id="message" value="你好 WebSocket" aria-label="消息"><button id="send">发送</button><button id="broadcast">广播</button></p><pre id="log"></pre>
+<script>
+let socket; const log=document.querySelector('#log'),state=document.querySelector('#state');
+function append(text){log.textContent=(log.textContent+text+'\n').slice(-12000)}
+document.querySelector('#connect').onclick=()=>{if(socket&&socket.readyState<2)return;socket=new WebSocket((location.protocol==='https:'?'wss://':'ws://')+location.host+'/ws');socket.onopen=()=>state.textContent='已连接';socket.onmessage=e=>append('收到：'+e.data);socket.onclose=e=>state.textContent='已断开，关闭码 '+e.code;socket.onerror=()=>append('连接发生错误')};
+function send(value){if(socket?.readyState===WebSocket.OPEN){socket.send(value);append('发送：'+value)}else append('请先连接')}
+document.querySelector('#send').onclick=()=>send(document.querySelector('#message').value);
+document.querySelector('#broadcast').onclick=()=>send('broadcast');
+document.querySelector('#disconnect').onclick=()=>socket?.close(1000,'');
+</script></html>

examples/websocket/main.go

@@ -0,0 +1,107 @@
+package main
+
+import (
+	"context"
+	_ "embed"
+	"errors"
+	"flag"
+	"fmt"
+	"net/http/httptest"
+	"os"
+	"strings"
+	"time"
+
+	omni "git.yuntuo.hk/k2safe/go-omni"
+	"git.yuntuo.hk/k2safe/go-omni/httpx"
+	"git.yuntuo.hk/k2safe/go-omni/ws"
+	"git.yuntuo.hk/k2safe/go-omni/ws/hub"
+	wsomni "git.yuntuo.hk/k2safe/go-omni/ws/omni"
+)
+
+//go:embed index.html
+var page []byte
+
+func main() {
+	serve := flag.Bool("serve", false, "serve the browser demo on 127.0.0.1:8088")
+	flag.Parse()
+	if err := run(*serve); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
+
+func run(serve bool) (runErr error) {
+	application := omni.New(omni.WithLogger(false))
+	defer func() { runErr = errors.Join(runErr, application.Close()) }()
+	connections, err := hub.New(hub.Config{})
+	if err != nil {
+		return err
+	}
+	application.OnShutdown(connections.Close)
+	server, err := ws.NewServer(ws.ServerConfig{})
+	if err != nil {
+		return err
+	}
+	if err = wsomni.Mount(application, "/ws", server, ws.Handlers{
+		OnOpen: func(_ context.Context, s *ws.Session) error {
+			if err := connections.Add(s); err != nil {
+				return err
+			}
+			return connections.Join(s.ID(), "demo")
+		},
+		OnMessage: func(ctx context.Context, s *ws.Session, m ws.Message) error {
+			if m.Type == ws.Text && string(m.Data) == "broadcast" {
+				result, err := connections.SendGroup("demo", ws.Message{Type: ws.Text, Data: []byte("hello group")})
+				if err != nil {
+					return err
+				}
+				if len(result.Errors) > 0 {
+					return s.SendJSON(ctx, map[string]int{"queued": result.Queued, "failed": len(result.Errors)})
+				}
+				return nil
+			}
+			return s.Send(ctx, m)
+		},
+	}); err != nil {
+		return err
+	}
+	application.GET("/", func(c *httpx.Context) error {
+		c.Raw().Header().Set("Content-Type", "text/html; charset=utf-8")
+		_, err := c.Raw().Write(page)
+		return err
+	})
+	if serve {
+		fmt.Println("Open http://127.0.0.1:8088 in two browser tabs; Ctrl+C stops cleanly.")
+		return application.Run("127.0.0.1:8088")
+	}
+	httpServer := httptest.NewServer(application)
+	defer httpServer.Close()
+	client, err := ws.NewClient(ws.ClientConfig{ProxyMode: "direct"})
+	if err != nil {
+		return err
+	}
+	defer func() {
+		ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+		defer cancel()
+		runErr = errors.Join(runErr, client.Shutdown(ctx))
+	}()
+	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+	defer cancel()
+	replies := make(chan string, 2)
+	session, err := client.Dial(ctx, "ws"+strings.TrimPrefix(httpServer.URL, "http")+"/ws", ws.Handlers{OnMessage: func(_ context.Context, _ *ws.Session, m ws.Message) error { replies <- string(m.Data); return nil }})
+	if err != nil {
+		return err
+	}
+	for _, message := range []string{"hello websocket", "broadcast"} {
+		if err = session.Send(ctx, ws.Message{Type: ws.Text, Data: []byte(message)}); err != nil {
+			return err
+		}
+		select {
+		case reply := <-replies:
+			fmt.Println(reply)
+		case <-ctx.Done():
+			return ctx.Err()
+		}
+	}
+	return nil
+}

examples/websocketRPC/README.md

@@ -0,0 +1,16 @@
+# 双向 RPC 与订阅恢复
+
+从仓库根目录运行，无外部服务、数据库或凭证：
+
+```sh
+go run ./examples/websocketRPC
+go test -race ./examples/websocketRPC
+```
+
+示例在本地随机端口启动 HTTP/1.1 WebSocket 服务，客户端与服务端协商 `go-omni.rpc.v1`。每条连接创建独立 Peer：客户端调用 `double`，服务端处理 `identify` 时反向调用客户端的 `client.name`。随后客户端恢复 `updates` 订阅，服务端通过进程内 Hub 广播 RPC 事件；完成取消订阅和关闭后，用新连接再次执行恢复。
+
+每代输出包含 `double=42`、反向调用返回值、`restored=1` 和对应事件序号。两次连接之间保留的是本地期望订阅，不是历史事件。示例显式创建第二条连接，方便验证每代 Peer 和订阅恢复的责任边界；自动网络重连使用 `ws.Client.Run` 与 `Prepare` 创建新 Peer，再从 `OnOpen` 外等待 `WaitReady` 并恢复订阅。
+
+示例的订阅授权只允许公开的 `updates` 主题。生产项目在握手 `Prepare` 验证身份，每次订阅/恢复时检查具体主题权限。服务器注册订阅路由时通过连接 ID 加入 Hub；JSON 中的 key 不自动构成授权。没有离线补发、自动重试业务调用或持久化投递。
+
+关闭 Client/Server 都使用独立、有界 context 并检查错误。RPC 的 OnClose 回调纳入实际业务任务完成屏障，示例的包装保留了该回调。完整协议、配置和退出语义见 [ws/rpc](../../ws/rpc/README.md)。

examples/websocketRPC/main.go

@@ -0,0 +1,200 @@
+// websocketRPC demonstrates bidirectional calls and explicit subscription
+// restoration over two successive real TCP connections, without external services.
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"time"
+
+	"git.yuntuo.hk/k2safe/go-omni/ws"
+	"git.yuntuo.hk/k2safe/go-omni/ws/hub"
+	"git.yuntuo.hk/k2safe/go-omni/ws/rpc"
+)
+
+func main() {
+	if err := run(); err != nil {
+		panic(err)
+	}
+}
+
+func run() (runErr error) {
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	groups, err := hub.New(hub.Config{})
+	if err != nil {
+		return err
+	}
+	defer groups.Close()
+	server, err := ws.NewServer(ws.ServerConfig{
+		Context: ctx, Subprotocols: []string{rpc.Subprotocol}, RequireSubprotocol: true,
+		Prepare: func(context.Context, *http.Request) (ws.Handlers, error) {
+			peer, err := rpc.New(rpc.Config{})
+			if err != nil {
+				return ws.Handlers{}, err
+			}
+			var session *ws.Session
+			if err = peer.Handle("double", func(_ context.Context, raw json.RawMessage) (any, error) {
+				var n int
+				if json.Unmarshal(raw, &n) != nil {
+					return nil, &rpc.Error{Code: "INVALID_INPUT", Message: "integer required"}
+				}
+				return n * 2, nil
+			}); err != nil {
+				return ws.Handlers{}, err
+			}
+			if err = peer.Handle("identify", func(ctx context.Context, _ json.RawMessage) (any, error) {
+				var name string
+				err := peer.Call(ctx, "client.name", nil, &name)
+				return name, err
+			}); err != nil {
+				return ws.Handlers{}, err
+			}
+			if err = peer.Handle("rpc.subscribe", func(_ context.Context, raw json.RawMessage) (any, error) {
+				var sub rpc.Subscription
+				if json.Unmarshal(raw, &sub) != nil {
+					return nil, &rpc.Error{Code: "INVALID_INPUT", Message: "invalid subscription"}
+				}
+				// Demo policy. A real project authenticates in Prepare, then authorizes the
+				// requested topic against that verified identity on every subscription.
+				if sub.Key != "updates" {
+					return nil, &rpc.Error{Code: "DENIED", Message: "topic not allowed"}
+				}
+				return nil, groups.Join(session.ID(), sub.Key)
+			}); err != nil {
+				return ws.Handlers{}, err
+			}
+			if err = peer.Handle("rpc.unsubscribe", func(_ context.Context, raw json.RawMessage) (any, error) {
+				var sub struct {
+					Key string `json:"key"`
+				}
+				if json.Unmarshal(raw, &sub) != nil {
+					return nil, &rpc.Error{Code: "INVALID_INPUT", Message: "invalid subscription"}
+				}
+				groups.Leave(session.ID(), sub.Key)
+				return nil, nil
+			}); err != nil {
+				return ws.Handlers{}, err
+			}
+			handlers := peer.Handlers()
+			open := handlers.OnOpen
+			handlers.OnOpen = func(ctx context.Context, s *ws.Session) error {
+				session = s
+				if err := open(ctx, s); err != nil {
+					return err
+				}
+				return groups.Add(s)
+			}
+			closeHandler := handlers.OnClose
+			handlers.OnClose = func(s *ws.Session, err error) { closeHandler(s, err); groups.Remove(s.ID()) }
+			return handlers, nil
+		},
+	})
+	if err != nil {
+		return err
+	}
+	httpServer := httptest.NewServer(server.Handler(ws.Handlers{}))
+	defer httpServer.Close()
+	defer func() {
+		stop, done := context.WithTimeout(context.Background(), 2*time.Second)
+		defer done()
+		runErr = errors.Join(runErr, server.Shutdown(stop))
+	}()
+	client, err := ws.NewClient(ws.ClientConfig{ProxyMode: "direct", Subprotocols: []string{rpc.Subprotocol}, RequireSubprotocol: true})
+	if err != nil {
+		return err
+	}
+	defer func() {
+		stop, done := context.WithTimeout(context.Background(), 2*time.Second)
+		defer done()
+		runErr = errors.Join(runErr, client.Shutdown(stop))
+	}()
+	subscriptions, err := rpc.NewSubscriptions(rpc.SubscriptionConfig{})
+	if err != nil {
+		return err
+	}
+	if err = subscriptions.Subscribe(ctx, nil, "updates", nil); err != nil {
+		return err
+	}
+	endpoint := "ws" + strings.TrimPrefix(httpServer.URL, "http")
+	for generation := 1; generation <= 2; generation++ {
+		peer, err := rpc.New(rpc.Config{})
+		if err != nil {
+			return err
+		}
+		events := make(chan int, 1)
+		if err = peer.Handle("client.name", func(context.Context, json.RawMessage) (any, error) { return "generic Go client", nil }); err != nil {
+			return err
+		}
+		if err = peer.Handle("updates.changed", func(ctx context.Context, raw json.RawMessage) (any, error) {
+			var v int
+			if err := json.Unmarshal(raw, &v); err != nil {
+				return nil, err
+			}
+			select {
+			case events <- v:
+				return nil, nil
+			case <-ctx.Done():
+				return nil, ctx.Err()
+			}
+		}); err != nil {
+			return err
+		}
+		session, err := client.Dial(ctx, endpoint, peer.Handlers())
+		if err != nil {
+			return err
+		}
+		if err = peer.WaitReady(ctx); err != nil {
+			return err
+		}
+		var doubled int
+		if err = peer.Call(ctx, "double", 21, &doubled); err != nil {
+			return err
+		}
+		var name string
+		if err = peer.Call(ctx, "identify", nil, &name); err != nil {
+			return err
+		}
+		restored, err := subscriptions.Restore(ctx, peer)
+		if err != nil {
+			return err
+		}
+		// The documented envelope also permits native browser clients and Hub fanout.
+		payload, err := json.Marshal(map[string]any{"v": 1, "type": "event", "method": "updates.changed", "params": generation})
+		if err != nil {
+			return err
+		}
+		sent, err := groups.SendGroup("updates", ws.Message{Type: ws.Text, Data: payload})
+		if err != nil {
+			return err
+		}
+		if sent.Queued != 1 || len(sent.Errors) > 0 {
+			return fmt.Errorf("broadcast failed: queued %d of %d", sent.Queued, sent.Attempted)
+		}
+		select {
+		case received := <-events:
+			fmt.Printf("connection %d: double=%d, remote callback=%q, restored=%d, event=%d\n", generation, doubled, name, restored, received)
+		case <-ctx.Done():
+			return ctx.Err()
+		}
+		if err = subscriptions.Unsubscribe(ctx, peer, "updates"); err != nil {
+			return err
+		}
+		// Keep desired state separately for the next physical connection.
+		if err = subscriptions.Subscribe(ctx, nil, "updates", nil); err != nil {
+			return err
+		}
+		if err = session.Close(1000, ""); err != nil {
+			return err
+		}
+		if err = session.Wait(ctx); err != nil {
+			return err
+		}
+	}
+	return nil
+}

examples/websocketRPC/main_test.go

@@ -0,0 +1,9 @@
+package main
+
+import "testing"
+
+func TestBidirectionalRPCAndRestore(t *testing.T) {
+	if err := run(); err != nil {
+		t.Fatal(err)
+	}
+}