WebSocket

SmartWeb 在 WebServer 抽象上提供 WebSocket Action。当前 SmartHTTP 包含具体 Handler；Undertow 支持程度应按源码和集成测试确认。

Controller DSL

@WebController
class ChatController {
    @NewWs("/chat")
    fun chat() = newWs {
        handShake { send("connected") }
        handleText { text ->
            attachment = text
            sendToAll("message: $text")
        }
        handleByteArray { bytes -> send(bytes) }
        close { println("closed: $name") }
        error { it.printStackTrace() }
    }
}

@WebController
public final class ChatController {
    @NewWs("/chat")
    public WsAction chat() {
        return new WsAction() {
            @Override
            public void onHandShake(WsSession session) {
                session.send("connected");
            }

            @Override
            public void handleTextMessage(WsSession session, String text) {
                session.setAttachment(text);
                session.sendToAll("message: " + text);
            }

            @Override
            public void handleBinaryMessage(WsSession session, byte[] bytes) {
                session.send(bytes);
            }

            @Override
            public void onClose(WsSession session) {
                System.out.println("closed: " + session.getName());
            }

            @Override
            public void onError(WsSession session, Throwable error) {
                error.printStackTrace();
            }
        };
    }
}

@NewWs 被 Loader 识别为 WebSocket channel。WebApp 启动服务器时调用 Controller 方法取得 KWsActionCreator 或 WsAction 并注册。

回调与并发

DSL 支持 handShake、handleText、handleByteArray、close、error。每个都是 suspend WsSession.()。

KWsAction 对每个回调执行 server.pool.launch，同一 Session 的多个消息可能并发，不保证串行。需要顺序处理时在 attachment 保存 Channel/Mutex，或实现自定义 WsAction。

WsSession

interface WsSession {
    val req: WsReq
    val resp: WsResp
    var attachment: Any?
    var name: String?
    var group: String?
}

WsReq 提供帧 opcode、payload、path、query 参数、远端/本地地址。握手阶段可设置可信 name/group，但必须先验证 Token，不能信任客户端自报身份。

发送

send("self")
sendToName("alice", "private")
sendToGroup("room-1", "group")
sendToAll("broadcast")

session.send("self");
session.sendToName("alice", "private");
session.sendToGroup("room-1", "group");
session.sendToAll("broadcast");

WsContext 维护 Session 集合，按 name 线性查找、按 group 过滤。大量连接时需评估复杂度与线程安全。

当前实现缺陷

WsSession.sendToGroup 当前委托 context.sendToName(group, data)，而不是 sendToGroup。修复前可直接调用 context.sendToGroup，并为目标版本写测试。

编程式注册

server.newWs("/events") {
    handleText { send("ack: $it") }
}

server.createWsAction("/events", new WsAction() {
    @Override
    public void handleTextMessage(WsSession session, String text) {
        session.send("ack: " + text);
    }

    @Override public void onHandShake(WsSession session) {}
    @Override public void onClose(WsSession session) {}
    @Override public void handleBinaryMessage(WsSession session, byte[] data) {}
    @Override public void onError(WsSession session, Throwable error) {}
});

底层调用 createWsAction(path, action)。也可直接实现 WsAction，完全控制并发和错误策略。

生产检查

• 握手认证，不信任 query 中的身份。
• 限制消息大小和发送队列。
• 明确同连接消息并发策略。
• 广播时隔离单连接失败。
• 停服关闭全部 Session。
• 多实例时本地 sendToAll 不跨 JVM，需消息中间件。
• 分别对 SmartHTTP、Undertow 做端到端测试。