Refactor resource-related API to stream-based (#58)

* refactor(core): make resource process streaming

* refactor(core): remove file size limitation of Int.MAX_VALUE

* chore(core): arrange code

* fix(core): correctly handle source close

* refactor(milky): move Bot injection to MilkyContext init block

* refactor: make `resolveUri` return MediaSource

* refactor: make MediaSource abstract

* feat: implement contextual, disposable scope

* update(core): optimize ByteArrayMediaSource

* refactor: use streaming API in Codec and command execution

* docs: add warning for ffmpegPath config

* feat: add more rich logging for MediaSource

Author: Wesley-Young

acidify-core/src/commonMain/kotlin/org/ntqqrev/acidify/FileOps.kt

@@ -1,9 +1,9 @@
 package org.ntqqrev.acidify
 
+import org.ntqqrev.acidify.common.MediaSource
+import org.ntqqrev.acidify.common.MediaSource.Companion.toMediaSource
 import org.ntqqrev.acidify.internal.service.file.*
-import org.ntqqrev.acidify.internal.util.md5
-import org.ntqqrev.acidify.internal.util.sha1
-import org.ntqqrev.acidify.internal.util.triSha1
+import org.ntqqrev.acidify.internal.util.MediaSourceMetadata
 import org.ntqqrev.acidify.struct.BotGroupFileEntry
 import org.ntqqrev.acidify.struct.BotGroupFileSystemList
 import org.ntqqrev.acidify.struct.BotGroupFolderEntry
@@ -13,24 +13,25 @@ import org.ntqqrev.acidify.struct.BotGroupFolderEntry
  * 上传群文件
  * @param groupUin 群号
  * @param fileName 文件名
- * @param fileData 文件数据
- * @param parentFolderId 父文件夹 ID，默认为根目录 "/"
+ * @param fileSource 文件数据源
+ * @param parentFolderId 父文件夹 ID，默认为根目录 `/`
  * @return 文件 ID
  */
 suspend fun AbstractBot.uploadGroupFile(
     groupUin: Long,
     fileName: String,
-    fileData: ByteArray,
+    fileSource: MediaSource,
     parentFolderId: String = "/"
 ): String {
+    val metadata = MediaSourceMetadata.from(fileSource)
     val uploadResp = client.callService(
         UploadGroupFile, UploadGroupFile.Req(
             groupUin = groupUin,
             fileName = fileName,
-            fileSize = fileData.size.toLong(),
-            fileMd5 = fileData.md5(),
-            fileSha1 = fileData.sha1(),
-            fileTriSha1 = fileData.triSha1(),
+            fileSize = metadata.size,
+            fileMd5 = metadata.md5,
+            fileSha1 = metadata.sha1,
+            fileTriSha1 = metadata.triSha1,
             parentFolderId = parentFolderId
         )
     )
@@ -40,7 +41,10 @@ suspend fun AbstractBot.uploadGroupFile(
             senderUin = uin,
             groupUin = groupUin,
             fileName = fileName,
-            fileData = fileData,
+            fileSource = fileSource,
+            fileSize = metadata.size,
+            fileMd5 = metadata.md5,
+            md510M = metadata.md510M,
             fileId = uploadResp.fileId,
             fileKey = uploadResp.fileKey,
             checkKey = uploadResp.checkKey,
@@ -58,47 +62,66 @@ suspend fun AbstractBot.uploadGroupFile(
     return uploadResp.fileId
 }
 
+/**
+ * 上传群文件
+ * @param groupUin 群号
+ * @param fileName 文件名
+ * @param fileData 文件原始字节数据
+ * @param parentFolderId 父文件夹 ID，默认为根目录 `/`
+ * @return 文件 ID
+ */
+suspend fun AbstractBot.uploadGroupFile(
+    groupUin: Long,
+    fileName: String,
+    fileData: ByteArray,
+    parentFolderId: String = "/"
+): String = uploadGroupFile(
+    groupUin = groupUin,
+    fileName = fileName,
+    fileSource = fileData.toMediaSource(),
+    parentFolderId = parentFolderId,
+)
+
 /**
  * 上传私聊文件
  * @param friendUin 好友 QQ 号
  * @param fileName 文件名
- * @param fileData 文件数据
+ * @param fileSource 文件数据源
  * @return 文件 ID
  */
 suspend fun AbstractBot.uploadPrivateFile(
     friendUin: Long,
     fileName: String,
-    fileData: ByteArray
+    fileSource: MediaSource
 ): String {
     val friendUid = getUidByUin(friendUin)
-    val fileMd5 = fileData.md5()
-    val fileSha1 = fileData.sha1()
-    val md510M = fileData.copyOfRange(0, minOf(10002432, fileData.size)).md5()
-    val fileTriSha1 = fileData.triSha1()
+    val metadata = MediaSourceMetadata.from(fileSource)
+    val md510M = metadata.md510M
 
     val uploadResp = client.callService(
         UploadPrivateFile,
         UploadPrivateFile.Req(
             senderUid = uid,
             receiverUid = friendUid,
             fileName = fileName,
-            fileSize = fileData.size,
-            fileMd5 = fileMd5,
-            fileSha1 = fileSha1,
+            fileSize = metadata.size,
+            fileMd5 = metadata.md5,
+            fileSha1 = metadata.sha1,
             md510M = md510M,
-            fileTriSha1 = fileTriSha1
+            fileTriSha1 = metadata.triSha1
         )
     )
 
     if (!uploadResp.fileExist) {
         client.highwayContext.uploadPrivateFile(
             receiverUin = friendUin,
             fileName = fileName,
-            fileData = fileData,
-            fileMd5 = fileMd5,
-            fileSha1 = fileSha1,
+            fileSource = fileSource,
+            fileSize = metadata.size,
+            fileMd5 = metadata.md5,
+            fileSha1 = metadata.sha1,
             md510M = md510M,
-            fileTriSha1 = fileTriSha1,
+            fileTriSha1 = metadata.triSha1,
             fileId = uploadResp.fileId,
             uploadKey = uploadResp.uploadKey,
             uploadIpAndPorts = uploadResp.ipAndPorts
@@ -113,14 +136,31 @@ suspend fun AbstractBot.uploadPrivateFile(
             fileId = uploadResp.fileId,
             fileMd510M = md510M,
             fileName = fileName,
-            fileSize = fileData.size.toLong(),
+            fileSize = metadata.size,
             crcMedia = uploadResp.fileCrcMedia
         )
     )
 
     return uploadResp.fileId
 }
 
+/**
+ * 上传私聊文件
+ * @param friendUin 好友 QQ 号
+ * @param fileName 文件名
+ * @param fileData 文件完整字节数据
+ * @return 文件 ID
+ */
+suspend fun AbstractBot.uploadPrivateFile(
+    friendUin: Long,
+    fileName: String,
+    fileData: ByteArray
+): String = uploadPrivateFile(
+    friendUin = friendUin,
+    fileName = fileName,
+    fileSource = fileData.toMediaSource(),
+)
+
 /**
  * 获取私聊文件下载链接
  * @param friendUin 好友 QQ 号
@@ -290,4 +330,4 @@ suspend fun AbstractBot.deleteGroupFolder(
 ) = client.callService(
     DeleteGroupFolder,
     DeleteGroupFolder.Req(groupUin, folderId)
-)
+)

acidify-core/src/commonMain/kotlin/org/ntqqrev/acidify/GroupOps.kt

@@ -6,12 +6,17 @@ import io.ktor.client.request.forms.*
 import io.ktor.http.*
 import kotlinx.coroutines.async
 import kotlinx.coroutines.awaitAll
+import kotlinx.io.buffered
+import kotlinx.io.readByteArray
 import kotlinx.serialization.json.Json
 import kotlinx.serialization.json.buildJsonObject
 import kotlinx.serialization.json.put
+import org.ntqqrev.acidify.common.MediaSource
+import org.ntqqrev.acidify.common.MediaSource.Companion.toMediaSource
 import org.ntqqrev.acidify.exception.WebApiException
 import org.ntqqrev.acidify.internal.json.*
 import org.ntqqrev.acidify.internal.service.group.*
+import org.ntqqrev.acidify.internal.util.MediaSourceMetadata
 import org.ntqqrev.acidify.internal.util.unescapeHttp
 import org.ntqqrev.acidify.message.BotEssenceMessageResult
 import org.ntqqrev.acidify.message.ImageFormat
@@ -33,6 +38,19 @@ suspend fun AbstractBot.setGroupName(
     SetGroupName.Req(groupUin, groupName)
 )
 
+/**
+ * 设置群头像
+ * @param groupUin 群号
+ * @param imageSource 群头像数据源
+ */
+suspend fun AbstractBot.setGroupAvatar(
+    groupUin: Long,
+    imageSource: MediaSource
+) {
+    val metadata = MediaSourceMetadata.from(imageSource)
+    client.highwayContext.uploadGroupAvatar(groupUin, imageSource, metadata.md5)
+}
+
 /**
  * 设置群头像
  * @param groupUin 群号
@@ -41,7 +59,7 @@ suspend fun AbstractBot.setGroupName(
 suspend fun AbstractBot.setGroupAvatar(
     groupUin: Long,
     imageData: ByteArray
-) = client.highwayContext.uploadGroupAvatar(groupUin, imageData)
+) = setGroupAvatar(groupUin, imageData.toMediaSource())
 
 /**
  * 设置群成员的群名片
@@ -199,10 +217,16 @@ suspend fun AbstractBot.getGroupAnnouncements(groupUin: Long): List<BotGroupAnno
 }
 
 /**
- * 发送群公告
+ * 发送群公告。
+ *
+ * 可选图片参数改为 [MediaSource]，以便与其他媒体上传接口保持一致。
+ * 若提供 [imageSource]，则必须同时提供 [imageFormat]。
+ * 当前群公告图片上传最终仍会走表单上传，因此内部会在发送前一次性读取图片内容。
+ *
  * @param groupUin 群号
  * @param content 公告内容
- * @param imageData 公告图片数据（字节数组，可选，暂不支持）
+ * @param imageSource 公告图片数据源，可为 `null`
+ * @param imageFormat 公告图片格式；当 [imageSource] 不为 `null` 时必填
  * @param showEditCard 是否显示编辑名片提示
  * @param showTipWindow 是否显示提示窗口
  * @param confirmRequired 是否需要确认
@@ -212,16 +236,16 @@ suspend fun AbstractBot.getGroupAnnouncements(groupUin: Long): List<BotGroupAnno
 suspend fun AbstractBot.sendGroupAnnouncement(
     groupUin: Long,
     content: String,
-    imageData: ByteArray? = null,
+    imageSource: MediaSource?,
     imageFormat: ImageFormat? = null,
     showEditCard: Boolean = false,
     showTipWindow: Boolean = true,
     confirmRequired: Boolean = true,
     isPinned: Boolean = false,
 ): String {
-    val announceImage = if (imageData != null) {
+    val announceImage = if (imageSource != null) {
         requireNotNull(imageFormat) { "imageFormat is required when imageData is provided" }
-        uploadGroupAnnouncementImage(imageData, imageFormat)
+        uploadGroupAnnouncementImage(imageSource.readByteArray(), imageFormat)
     } else {
         null
     }
@@ -268,6 +292,38 @@ suspend fun AbstractBot.sendGroupAnnouncement(
     return sendResp.noticeId
 }
 
+/**
+ * 发送群公告
+ * @param groupUin 群号
+ * @param content 公告内容
+ * @param imageData 公告图片完整字节数据，可为 `null`
+ * @param imageFormat 公告图片格式；当 [imageData] 不为 `null` 时必填
+ * @param showEditCard 是否显示编辑名片提示
+ * @param showTipWindow 是否显示提示窗口
+ * @param confirmRequired 是否需要确认
+ * @param isPinned 是否置顶
+ * @return 公告 ID
+ */
+suspend fun AbstractBot.sendGroupAnnouncement(
+    groupUin: Long,
+    content: String,
+    imageData: ByteArray? = null,
+    imageFormat: ImageFormat? = null,
+    showEditCard: Boolean = false,
+    showTipWindow: Boolean = true,
+    confirmRequired: Boolean = true,
+    isPinned: Boolean = false,
+): String = sendGroupAnnouncement(
+    groupUin = groupUin,
+    content = content,
+    imageSource = imageData?.toMediaSource(),
+    imageFormat = imageFormat,
+    showEditCard = showEditCard,
+    showTipWindow = showTipWindow,
+    confirmRequired = confirmRequired,
+    isPinned = isPinned,
+)
+
 private suspend fun AbstractBot.uploadGroupAnnouncementImage(
     imageData: ByteArray,
     imageFormat: ImageFormat

acidify-core/src/commonMain/kotlin/org/ntqqrev/acidify/SystemOps.kt

@@ -2,11 +2,14 @@ package org.ntqqrev.acidify
 
 import kotlinx.coroutines.*
 import kotlinx.coroutines.sync.withLock
+import org.ntqqrev.acidify.common.MediaSource
+import org.ntqqrev.acidify.common.MediaSource.Companion.toMediaSource
 import org.ntqqrev.acidify.internal.proto.misc.UserInfoKey
 import org.ntqqrev.acidify.internal.service.friend.FetchFriends
 import org.ntqqrev.acidify.internal.service.group.FetchGroupMembers
 import org.ntqqrev.acidify.internal.service.group.FetchGroups
 import org.ntqqrev.acidify.internal.service.system.*
+import org.ntqqrev.acidify.internal.util.MediaSourceMetadata
 import org.ntqqrev.acidify.struct.*
 
 /**
@@ -237,11 +240,20 @@ suspend fun AbstractBot.setFriendPin(friendUin: Long, isPinned: Boolean) =
 suspend fun AbstractBot.setGroupPin(groupUin: Long, isPinned: Boolean) =
     client.callService(SetGroupPin, SetGroupPin.Req(groupUin, isPinned))
 
+/**
+ * 设置账号头像
+ * @param imageSource 头像数据源
+ */
+suspend fun AbstractBot.setAvatar(imageSource: MediaSource) {
+    val metadata = MediaSourceMetadata.from(imageSource)
+    client.highwayContext.uploadAvatar(imageSource, metadata.md5)
+}
+
 /**
  * 设置账号头像
  * @param imageData 头像原始字节数据
  */
-suspend fun AbstractBot.setAvatar(imageData: ByteArray) = client.highwayContext.uploadAvatar(imageData)
+suspend fun AbstractBot.setAvatar(imageData: ByteArray) = setAvatar(imageData.toMediaSource())
 
 /**
  * 设置账号昵称
@@ -290,4 +302,4 @@ suspend fun AbstractBot.getCookies(domain: String) = mapOf(
 /**
  * 获取 CSRF Token。
  */
-suspend fun AbstractBot.getCsrfToken() = client.ticketContext.getCsrfToken()
+suspend fun AbstractBot.getCsrfToken() = client.ticketContext.getCsrfToken()