基于KotlinxIO改善Resource[部分]

Signed-off-by: ForteScarlet <ForteScarlet@163.com>

simbot-api/src/commonMain/kotlin/love/forte/simbot/message/OfflineImageResolver.kt

@@ -23,11 +23,8 @@
 
 package love.forte.simbot.message
 
-import love.forte.simbot.resource.ByteArrayResource
-import love.forte.simbot.resource.Resource
-import love.forte.simbot.resource.ResourceResolver
+import love.forte.simbot.resource.*
 import love.forte.simbot.resource.ResourceResolver.Companion.resolve
-import love.forte.simbot.resource.StringResource
 import kotlin.jvm.JvmStatic
 
 
@@ -76,6 +73,7 @@ public interface OfflineImageResolver<C> {
  * 继承 [OfflineImageResolver] 和 [ResourceResolver]，
  * 对其中可能出现的实际内容物（例如 [ByteArray] 或 [String]）进行处理。
  */
+@ScheduledDeprecatedResourceApi
 public interface OfflineImageValueResolver<C> :
     OfflineImageResolver<C>,
     ResourceResolver<C> {

simbot-api/src/commonMain/kotlin/love/forte/simbot/resource/Resource.kt

@@ -62,8 +62,6 @@ import kotlin.jvm.JvmName
  * @author ForteScarlet
  */
 public sealed interface Resource {
-    // TODO become `sealed` for ByteArrayResource and SourceResource.
-
     /**
      * 读取此资源的字节数据。
      *

simbot-api/src/commonMain/kotlin/love/forte/simbot/resource/ResourceResolver.kt

@@ -23,8 +23,23 @@
 
 package love.forte.simbot.resource
 
+import kotlin.annotation.AnnotationRetention.BINARY
+import kotlin.annotation.AnnotationTarget.CLASS
+import kotlin.annotation.AnnotationTarget.FUNCTION
 import kotlin.jvm.JvmStatic
 
+/**
+ * 计划被废弃的与 [Resource] 相关的API
+ */
+@RequiresOptIn(
+    message = "计划被废弃的与 `Resource` 相关的API. 详见 " +
+        "`love.forte.simbot.resource.ResourceResolver` 和 " +
+        "`love.forte.simbot.resource.Resource` 中的有关说明。"
+)
+@Retention(BINARY)
+@Target(CLASS, FUNCTION)
+@MustBeDocumented
+public annotation class ScheduledDeprecatedResourceApi
 
 /**
  * 使用 [ResourceResolver] 分析处理一个 [Resource].
@@ -33,8 +48,14 @@ import kotlin.jvm.JvmStatic
  *
  * 在 JVM 平台会提供一个具有更多能力的类型。
  *
+ * Note: 由于[Resource]现在已经通过 `sealed` 限制了子类型范围,
+ * 因此可以直接使用 [ByteArrayResource] 或 [SourceResource]。
+ * 得益于 `kotlinx-io`，明确 resolve 多平台（尤其是JVM平台）下的独特类型的情况已经不多了。
+ * [ResourceResolver] 可能会在未来废弃, 且现在开始不再建议使用。
+ *
  * @author ForteScarlet
  */
+@ScheduledDeprecatedResourceApi
 public interface ResourceResolver<C> {
     /**
      * 处理一个未知的 [Resource] 类型的 resource.

simbot-api/src/jvmMain/kotlin/love/forte/simbot/message/OfflineImageResolver.jvm.kt

@@ -71,6 +71,7 @@ public interface JvmOfflineImageResolver<C> : OfflineImageResolver<C> {
  * 实现 [JvmOfflineImageResolver] 和 [JvmResourceResolver]，
  * 对其中可能出现的实际内容物（例如 [File] 或 [Path]）进行处理。
  */
+@ScheduledDeprecatedResourceApi
 public abstract class JvmOfflineImageValueResolver<C> :
     OfflineImageValueResolver<C>,
     JvmOfflineImageResolver<C>,

simbot-api/src/jvmMain/kotlin/love/forte/simbot/resource/Resource.jvm.kt

@@ -50,6 +50,15 @@ public fun SourceResource.inputStream(): InputStream {
     return source().asInputStream()
 }
 
+/**
+ * 提供JVM平台独特实现的类型，与 [SourceResource] 内容相同。
+ *
+ * @see FileResource
+ * @see PathResource
+ * @see URIResource
+ */
+public sealed interface JvmSourceResource : SourceResource
+
 /**
  * 能够获取到 [InputStream] 资源的 [Resource] 扩展实现。
  *
@@ -148,7 +157,11 @@ public interface ReaderResource : JvmStringReadableResource {
  *
  * @author forte
  */
-public interface FileResource : InputStreamResource, ReaderResource {
+@Suppress("DEPRECATION")
+public interface FileResource :
+    JvmSourceResource,
+    InputStreamResource,
+    ReaderResource {
     /**
      * 与此资源关联的 [File]
      */
@@ -248,7 +261,11 @@ private data class FileResourceImpl(override val file: File, private val charset
  *
  * @author forte
  */
-public interface PathResource : InputStreamResource, ReaderResource {
+@Suppress("DEPRECATION")
+public interface PathResource :
+    JvmSourceResource,
+    InputStreamResource,
+    ReaderResource {
     /**
      * 与此资源关联的 [Path]
      */
@@ -350,7 +367,11 @@ private data class PathResourceImpl(
  *
  * @author forte
  */
-public interface URIResource : InputStreamResource, JvmStringReadableResource {
+@Suppress("DEPRECATION")
+public interface URIResource :
+    JvmSourceResource,
+    InputStreamResource,
+    JvmStringReadableResource {
     /**
      * 与此资源关联的 [URI]
      */

simbot-api/src/jvmMain/kotlin/love/forte/simbot/resource/ResourceResolver.jvm.kt

@@ -32,6 +32,7 @@ import kotlin.io.path.toPath
  * JVM 平台下 [ResourceResolver] 的进一步扩展类型。
  *
  */
+@ScheduledDeprecatedResourceApi
 public interface JvmResourceResolver<C> : ResourceResolver<C> {
     /**
      * 处理类型为 [FileResource] 的 resource.
@@ -71,6 +72,7 @@ public interface JvmResourceResolver<C> : ResourceResolver<C> {
 /**
  * [JvmResourceResolver] 的更安全的抽象类型，将 [resolveUnknown] 固定为 `final`。
  */
+@ScheduledDeprecatedResourceApi
 public abstract class AbstractJvmResourceResolver<C> : JvmResourceResolver<C> {
     final override fun resolveUnknown(resource: Resource, context: C) {
         super.resolveUnknown(resource, context)
@@ -81,6 +83,7 @@ public abstract class AbstractJvmResourceResolver<C> : JvmResourceResolver<C> {
  * 基于 Resource 中的值进行处理。
  * 其中，如果 [URI.scheme] == `"file"` 则会被处理为 [Path].
  */
+@ScheduledDeprecatedResourceApi
 public interface JvmResourceValueResolver<C> : JvmResourceResolver<C> {
     /**
      * 解析 [FileResource] 类型的 resource，
@@ -172,6 +175,7 @@ public interface JvmResourceValueResolver<C> : JvmResourceResolver<C> {
  * [JvmResourceValueResolver] 的更安全的抽象类型，
  * 会将部分直接解析 [Resource] 的函数固定为 `final`。
  */
+@ScheduledDeprecatedResourceApi
 public abstract class AbstractJvmResourceValueResolver<C> : JvmResourceValueResolver<C> {
     final override fun resolveFile(resource: FileResource, context: C) {
         super.resolveFile(resource, context)

simbot-api/src/jvmTest/kotlin/message/OfflineImageResolverTests.jvm.kt

@@ -33,6 +33,7 @@ import love.forte.simbot.message.OfflineImageResolver.Companion.resolve
 import love.forte.simbot.message.OfflinePathImage.Companion.toOfflineImage
 import love.forte.simbot.message.OfflineURIImage.Companion.toOfflineImage
 import love.forte.simbot.resource.Resource
+import love.forte.simbot.resource.ScheduledDeprecatedResourceApi
 import love.forte.simbot.resource.toResource
 import java.io.File
 import java.net.URI
@@ -59,6 +60,7 @@ class JvmOfflineImageResolverTests {
         U
     }
 
+    @OptIn(ScheduledDeprecatedResourceApi::class)
     @Test
     fun jvmOfflineImageValueResolverTest() = runTest {
         val path = Files.createTempFile("PRE", "SUF")
@@ -109,9 +111,7 @@ class JvmOfflineImageResolverTests {
             Value.UKN_R,
             suspendCancellableCoroutine { c ->
                 resolver.resolve(
-                    object : Resource {
-                        override fun data(): ByteArray = byteArrayOf()
-                    }.toOfflineImage(),
+                    byteArrayOf().toOfflineImage(),
                     c
                 )
             }