Merge pull request #59 from simple-robot/dev/support-without-ws

允许不启用WebSocket连接

Author: ForteScarlet

Writerside/topics/OneBot11.md

@@ -13,3 +13,10 @@ OneBot组件选择使用
 作为事件订阅的方式。
 
 简单来说，就是不论是API交互还是事件订阅，都由OneBot组件作为**主动方**：主动发起HTTP请求、主动发起WebSocket连接。
+
+## 反向？
+
+如果你真的想要通过反向HTTP来接收事件推送，那么你需要自行搭建 HTTP 服务端，然后使用 `OneBotBot.push` 手动推送原始事件的JSON字符串。
+你可以前往参考 
+`OneBotBot` 的
+<a href="onebot11-OneBotBot.md#外部事件" /> 。

Writerside/topics/onebot11-OneBotBot.md

@@ -469,3 +469,264 @@ public class MyComponent {
 有关事件的更多内容参考 
 <a href="onebot11-event.md" /> 。
 </warning>
+
+
+## 外部事件
+
+`OneBotBot` 提供了 `push(String)` 来允许直接从外部推送一个原始的事件字符串。
+
+<tabs group="code">
+<tab title="Kotlin" group-key="Kotlin">
+
+```Kotlin
+val json = """
+{
+    "time": 1515204254,
+    "self_id": 10001000,
+    "post_type": "message",
+    "message_type": "private",
+    "sub_type": "friend",
+    "message_id": 12,
+    "user_id": 12345678,
+    "message": "你好～",
+    "raw_message": "你好～",
+    "font": 456,
+    "sender": {
+        "nickname": "小不点",
+        "sex": "male",
+        "age": 18
+    }
+}
+"""
+
+bot.push(json).collect()
+```
+
+</tab>
+<tab title="Java" group-key="Java">
+
+```Java
+var json = """
+    {
+        "time": 1515204254,
+        "self_id": 10001000,
+        "post_type": "message",
+        "message_type": "private",
+        "sub_type": "friend",
+        "message_id": 12,
+        "user_id": 12345678,
+        "message": "你好～",
+        "raw_message": "你好～",
+        "font": 456,
+        "sender": {
+            "nickname": "小不点",
+            "sex": "male",
+            "age": 18
+        }
+    }
+    """
+
+// 推送并在异步中处理
+bot.pushAndLaunch(json);
+```
+
+由于 `bot.push` 返回的结果是 `Flow`, 因此 Java 中想要直接使用它会比较困难。
+你可以先通过 `Collectables.valueOf(flow)` 将其转化为 `Collectable` (与关系对象相关API的结果类型一样)，
+然后再做进一步操作。
+
+
+```java
+var collectable = Collectables.valueOf(flow);
+// 使用 collectAsync 异步遍历
+// 或者 Collectables 中提供的各种辅助API
+// 或者 transform 转化为其他的类型，比如响应式的 Flux
+```
+
+</tab>
+</tabs>
+
+> 示例JSON来自 
+> https://github.com/botuniverse/onebot-11/blob/master/communication/http-post.md 。
+
+这可以让你能够使用**反向事件推送**来接收事件，比如通过接收来自 HTTP 的事件推送请求。
+
+简单示例：
+
+<tabs>
+<tab title="Ktor">
+
+```kotlin
+suspend fun main() {
+    val application = launchSimpleApplication {
+        useOneBot11()
+    }
+    // 注册事件省略...
+
+    // 注册bot并启动
+    val bot = application.oneBot11Bots {
+        register {
+            // 内容省略
+        }.apply { start() }
+    }
+
+    // 启动一个Ktor Server
+    embeddedServer(Netty, port = 5959, module = { serverModule(bot) })
+        .start(wait = true)
+}
+
+fun io.ktor.server.application.Application.serverModule(bot: OneBotBot) {
+    routing {
+        post("/event") {
+            // 收到事件，推送并在异步中处理
+            // 你也可以选择直接 push(body).collect(), 
+            // 直到事件被完全处理后在返回
+            val body = call.receiveText()
+            bot.pushAndLaunch(body)
+
+            // 响应一个默认的空JSON结果
+            call.response.header(HttpHeaders.ContentType, "application/json")
+            call.respond("{}")
+        }
+    }
+}
+```
+
+</tab>
+<tab title="Spring Boot Web">
+
+```java
+@RestController
+public class MyController {
+    private final Application application;
+
+    // 一个简单的返回值类型，假设始终返回空JSON {}
+    public record Result() {
+    }
+
+    private static final Result OK = new Result();
+
+    public MyController(Application application) {
+        this.application = application;
+    }
+
+    /**
+     * 通过 /xxx/event 接收事件，
+     * xxx 为你bot配置的 uniqueBotId
+     */
+    @PostMapping("/{botId}/event")
+    public Result onEvent(@PathVariable String botId, @RequestBody String body) {
+        for (var botManager : application.getBotManagers()) {
+            if (botManager instanceof OneBotBotManager obManager) {
+                // 找到这个bot
+                var bot = obManager.find(Identifies.of(botId));
+                // 如果有就推送这个事件并退出寻找
+                if (bot != null) {
+                    // 推送事件并在异步中处理
+                    // 你也可以参考上面有关 Flux 和 Collectable 的说明
+                    // 来阻塞地等待事件处理完成后再返回
+                    bot.pushAndLaunch(body);
+                    break;
+                }
+            }
+        }
+
+        return OK;
+    }
+}
+```
+
+</tab>
+<tab title="Spring Boot WebFlux">
+
+<tabs>
+<tab title="异步处理">
+
+如果选择直接异步处理，那么其实跟 Spring Boot Web 的情况下没什么太大区别。
+
+```java
+@RestController
+public class MyController {
+    private final Application application;
+
+    public record Result() {
+    }
+
+    private static final Result OK = new Result();
+
+    public MyController(Application application) {
+        this.application = application;
+    }
+
+    /**
+     * 通过 /xxx/event 接收事件，
+     * xxx 为你bot配置的 uniqueBotId
+     */
+    @PostMapping("/{botId}/event")
+    public Mono<Result> onEvent(@PathVariable String botId, @RequestBody String body) {
+        for (var botManager : application.getBotManagers()) {
+            if (botManager instanceof OneBotBotManager obManager) {
+                // 找到这个bot
+                var bot = obManager.find(Identifies.of(botId));
+                // 如果有就推送这个事件并退出寻找
+                if (bot != null) {
+                    bot.pushAndLaunch(body);
+                    break;
+                }
+            }
+        }
+
+        return Mono.just(OK);
+    }
+}
+```
+
+</tab>
+<tab title="顺序响应式处理">
+
+```java
+@RestController
+public class MyController {
+    private final Application application;
+
+    public record Result() {
+    }
+
+    private static final Result OK = new Result();
+
+    public MyController(Application application) {
+        this.application = application;
+    }
+
+    /**
+     * 通过 /xxx/event 接收事件，
+     * xxx 为你bot配置的 uniqueBotId
+     */
+    @PostMapping("/{botId}/event")
+    public Mono<Result> onEvent(@PathVariable String botId, @RequestBody String body) {
+        for (var botManager : application.getBotManagers()) {
+            if (botManager instanceof OneBotBotManager obManager) {
+                // 找到这个bot
+                var bot = obManager.find(Identifies.of(botId));
+                // 如果有就推送这个事件并退出寻找
+                if (bot != null) {
+                    final var flow = bot.push(body);
+                    // 将 flow 转为 reactor 的 Flux
+                    // 需要添加依赖 [[[kotlinx-coroutines-reactor|https://github.com/Kotlin/kotlinx.coroutines/tree/master/reactive]]]
+                    return ReactorFlowKt
+                            .asFlux(flow)
+                            .then(Mono.just(OK));
+                }
+            }
+        }
+
+        // 没找到，直接返回
+        return Mono.just(OK);
+    }
+}
+```
+
+</tab>
+</tabs>
+
+</tab>
+</tabs>

Writerside/topics/onebot11-bot-config.md

@@ -24,7 +24,8 @@ Bot配置文件通常情况下是配合Spring Boot starter的时候用的。
         "botUniqueId": "123456",
         // api地址，是个http/https服务器的路径，默认localhost:3000
         "apiServerHost": "http://localhost:3000",
-        // 订阅事件的服务器地址，是个ws/wss路径，默认localhost:3001
+        // 订阅事件的服务器地址，是个ws/wss路径，默认 `null`
+        // 如果为 `null` 则不会连接 ws 和订阅事件
         "eventServerHost": "ws://localhost:3001",
         // 配置的 token，可以是null, 代表同时配置 apiAccessToken 和 eventAccessToken
         "accessToken": null,

simbot-component-onebot-v11/simbot-component-onebot-v11-core/src/commonMain/kotlin/love/forte/simbot/component/onebot/v11/core/bot/OneBotBotConfiguration.kt

@@ -119,17 +119,18 @@ public class OneBotBotConfiguration {
     }
 
     /**
-     * 必填属性，订阅事件的目标服务器地址。应当是ws或wss协议。
+     * 订阅事件的目标服务器地址。应当是ws或wss协议。
+     * 如果为 `null` 则不启用 ws 连接。
      */
-    public var eventServerHost: Url = Url("ws://localhost:3001")
+    public var eventServerHost: Url? = null
 
     /**
      * 配置 [eventServerHost]
      *
      * @see eventServerHost
      */
-    public fun setEventServerHost(urlString: String) {
-        eventServerHost = Url(urlString)
+    public fun setEventServerHost(urlString: String?) {
+        eventServerHost = urlString?.let { Url(it) }
     }
 
     /**