Rename RichMessageOrigin to MessageOrigin (#1116)

* Rename `RichMessageOrigin` to `MessageOrigin`

* apiDump

* Change `MessageOrigin.origin` parameter type from `RichMessage` to `SingleMessage`;
Rename `RichMessageKind` to `MessageOriginKind`

* Make MessageOriginKind serializable and update docs

* Ensure binary compatibility with <2.6 and provide migration helpers

* apiDump

binary-compatibility-validator/android/api/binary-compatibility-validator-android.api

@@ -4608,6 +4608,62 @@ public abstract interface class net/mamoe/mirai/message/data/MessageMetadata : n
 	public fun contentToString ()Ljava/lang/String;
 }
 
+public final class net/mamoe/mirai/message/data/MessageOrigin : net/mamoe/mirai/message/data/ConstrainSingle, net/mamoe/mirai/message/data/MessageMetadata {
+	public static final field Key Lnet/mamoe/mirai/message/data/MessageOrigin$Key;
+	public static final field SERIAL_NAME Ljava/lang/String;
+	public synthetic fun <init> (ILnet/mamoe/mirai/message/data/SingleMessage;Ljava/lang/String;Lnet/mamoe/mirai/message/data/MessageOriginKind;Lkotlinx/serialization/internal/SerializationConstructorMarker;)V
+	public fun <init> (Lnet/mamoe/mirai/message/data/SingleMessage;Ljava/lang/String;Lnet/mamoe/mirai/message/data/MessageOriginKind;)V
+	public fun contentToString ()Ljava/lang/String;
+	public fun equals (Ljava/lang/Object;)Z
+	public synthetic fun getKey ()Lnet/mamoe/mirai/message/data/MessageKey;
+	public fun getKey ()Lnet/mamoe/mirai/message/data/MessageOrigin$Key;
+	public final fun getKind ()Lnet/mamoe/mirai/message/data/MessageOriginKind;
+	public final fun getOrigin ()Lnet/mamoe/mirai/message/data/SingleMessage;
+	public final fun getResourceId ()Ljava/lang/String;
+	public fun hashCode ()I
+	public fun toString ()Ljava/lang/String;
+	public static final fun write$Self (Lnet/mamoe/mirai/message/data/MessageOrigin;Lkotlinx/serialization/encoding/CompositeEncoder;Lkotlinx/serialization/descriptors/SerialDescriptor;)V
+}
+
+public final class net/mamoe/mirai/message/data/MessageOrigin$$serializer : kotlinx/serialization/internal/GeneratedSerializer {
+	public static final field INSTANCE Lnet/mamoe/mirai/message/data/MessageOrigin$$serializer;
+	public fun childSerializers ()[Lkotlinx/serialization/KSerializer;
+	public synthetic fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Ljava/lang/Object;
+	public fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Lnet/mamoe/mirai/message/data/MessageOrigin;
+	public fun getDescriptor ()Lkotlinx/serialization/descriptors/SerialDescriptor;
+	public synthetic fun serialize (Lkotlinx/serialization/encoding/Encoder;Ljava/lang/Object;)V
+	public fun serialize (Lkotlinx/serialization/encoding/Encoder;Lnet/mamoe/mirai/message/data/MessageOrigin;)V
+	public fun typeParametersSerializers ()[Lkotlinx/serialization/KSerializer;
+}
+
+public final class net/mamoe/mirai/message/data/MessageOrigin$Key : net/mamoe/mirai/message/data/AbstractMessageKey {
+	public final fun serializer ()Lkotlinx/serialization/KSerializer;
+}
+
+public final class net/mamoe/mirai/message/data/MessageOriginKind : java/lang/Enum {
+	public static final field Companion Lnet/mamoe/mirai/message/data/MessageOriginKind$Companion;
+	public static final field FORWARD Lnet/mamoe/mirai/message/data/MessageOriginKind;
+	public static final field LONG Lnet/mamoe/mirai/message/data/MessageOriginKind;
+	public static final field MUSIC_SHARE Lnet/mamoe/mirai/message/data/MessageOriginKind;
+	public static fun valueOf (Ljava/lang/String;)Lnet/mamoe/mirai/message/data/MessageOriginKind;
+	public static fun values ()[Lnet/mamoe/mirai/message/data/MessageOriginKind;
+}
+
+public final class net/mamoe/mirai/message/data/MessageOriginKind$$serializer : kotlinx/serialization/internal/GeneratedSerializer {
+	public static final field INSTANCE Lnet/mamoe/mirai/message/data/MessageOriginKind$$serializer;
+	public fun childSerializers ()[Lkotlinx/serialization/KSerializer;
+	public synthetic fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Ljava/lang/Object;
+	public fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Lnet/mamoe/mirai/message/data/MessageOriginKind;
+	public fun getDescriptor ()Lkotlinx/serialization/descriptors/SerialDescriptor;
+	public synthetic fun serialize (Lkotlinx/serialization/encoding/Encoder;Ljava/lang/Object;)V
+	public fun serialize (Lkotlinx/serialization/encoding/Encoder;Lnet/mamoe/mirai/message/data/MessageOriginKind;)V
+	public fun typeParametersSerializers ()[Lkotlinx/serialization/KSerializer;
+}
+
+public final class net/mamoe/mirai/message/data/MessageOriginKind$Companion {
+	public final fun serializer ()Lkotlinx/serialization/KSerializer;
+}
+
 public abstract class net/mamoe/mirai/message/data/MessageSource : net/mamoe/mirai/message/data/ConstrainSingle, net/mamoe/mirai/message/data/Message, net/mamoe/mirai/message/data/MessageMetadata {
 	public static final field Key Lnet/mamoe/mirai/message/data/MessageSource$Key;
 	public static final field SERIAL_NAME Ljava/lang/String;

binary-compatibility-validator/api/binary-compatibility-validator.api

@@ -4608,6 +4608,62 @@ public abstract interface class net/mamoe/mirai/message/data/MessageMetadata : n
 	public fun contentToString ()Ljava/lang/String;
 }
 
+public final class net/mamoe/mirai/message/data/MessageOrigin : net/mamoe/mirai/message/data/ConstrainSingle, net/mamoe/mirai/message/data/MessageMetadata {
+	public static final field Key Lnet/mamoe/mirai/message/data/MessageOrigin$Key;
+	public static final field SERIAL_NAME Ljava/lang/String;
+	public synthetic fun <init> (ILnet/mamoe/mirai/message/data/SingleMessage;Ljava/lang/String;Lnet/mamoe/mirai/message/data/MessageOriginKind;Lkotlinx/serialization/internal/SerializationConstructorMarker;)V
+	public fun <init> (Lnet/mamoe/mirai/message/data/SingleMessage;Ljava/lang/String;Lnet/mamoe/mirai/message/data/MessageOriginKind;)V
+	public fun contentToString ()Ljava/lang/String;
+	public fun equals (Ljava/lang/Object;)Z
+	public synthetic fun getKey ()Lnet/mamoe/mirai/message/data/MessageKey;
+	public fun getKey ()Lnet/mamoe/mirai/message/data/MessageOrigin$Key;
+	public final fun getKind ()Lnet/mamoe/mirai/message/data/MessageOriginKind;
+	public final fun getOrigin ()Lnet/mamoe/mirai/message/data/SingleMessage;
+	public final fun getResourceId ()Ljava/lang/String;
+	public fun hashCode ()I
+	public fun toString ()Ljava/lang/String;
+	public static final fun write$Self (Lnet/mamoe/mirai/message/data/MessageOrigin;Lkotlinx/serialization/encoding/CompositeEncoder;Lkotlinx/serialization/descriptors/SerialDescriptor;)V
+}
+
+public final class net/mamoe/mirai/message/data/MessageOrigin$$serializer : kotlinx/serialization/internal/GeneratedSerializer {
+	public static final field INSTANCE Lnet/mamoe/mirai/message/data/MessageOrigin$$serializer;
+	public fun childSerializers ()[Lkotlinx/serialization/KSerializer;
+	public synthetic fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Ljava/lang/Object;
+	public fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Lnet/mamoe/mirai/message/data/MessageOrigin;
+	public fun getDescriptor ()Lkotlinx/serialization/descriptors/SerialDescriptor;
+	public synthetic fun serialize (Lkotlinx/serialization/encoding/Encoder;Ljava/lang/Object;)V
+	public fun serialize (Lkotlinx/serialization/encoding/Encoder;Lnet/mamoe/mirai/message/data/MessageOrigin;)V
+	public fun typeParametersSerializers ()[Lkotlinx/serialization/KSerializer;
+}
+
+public final class net/mamoe/mirai/message/data/MessageOrigin$Key : net/mamoe/mirai/message/data/AbstractMessageKey {
+	public final fun serializer ()Lkotlinx/serialization/KSerializer;
+}
+
+public final class net/mamoe/mirai/message/data/MessageOriginKind : java/lang/Enum {
+	public static final field Companion Lnet/mamoe/mirai/message/data/MessageOriginKind$Companion;
+	public static final field FORWARD Lnet/mamoe/mirai/message/data/MessageOriginKind;
+	public static final field LONG Lnet/mamoe/mirai/message/data/MessageOriginKind;
+	public static final field MUSIC_SHARE Lnet/mamoe/mirai/message/data/MessageOriginKind;
+	public static fun valueOf (Ljava/lang/String;)Lnet/mamoe/mirai/message/data/MessageOriginKind;
+	public static fun values ()[Lnet/mamoe/mirai/message/data/MessageOriginKind;
+}
+
+public final class net/mamoe/mirai/message/data/MessageOriginKind$$serializer : kotlinx/serialization/internal/GeneratedSerializer {
+	public static final field INSTANCE Lnet/mamoe/mirai/message/data/MessageOriginKind$$serializer;
+	public fun childSerializers ()[Lkotlinx/serialization/KSerializer;
+	public synthetic fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Ljava/lang/Object;
+	public fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Lnet/mamoe/mirai/message/data/MessageOriginKind;
+	public fun getDescriptor ()Lkotlinx/serialization/descriptors/SerialDescriptor;
+	public synthetic fun serialize (Lkotlinx/serialization/encoding/Encoder;Ljava/lang/Object;)V
+	public fun serialize (Lkotlinx/serialization/encoding/Encoder;Lnet/mamoe/mirai/message/data/MessageOriginKind;)V
+	public fun typeParametersSerializers ()[Lkotlinx/serialization/KSerializer;
+}
+
+public final class net/mamoe/mirai/message/data/MessageOriginKind$Companion {
+	public final fun serializer ()Lkotlinx/serialization/KSerializer;
+}
+
 public abstract class net/mamoe/mirai/message/data/MessageSource : net/mamoe/mirai/message/data/ConstrainSingle, net/mamoe/mirai/message/data/Message, net/mamoe/mirai/message/data/MessageMetadata {
 	public static final field Key Lnet/mamoe/mirai/message/data/MessageSource$Key;
 	public static final field SERIAL_NAME Ljava/lang/String;

mirai-core-api/src/commonMain/kotlin/internal/message/MessageSerializersImpl.kt

@@ -99,11 +99,13 @@ private val builtInSerializersModule by lazy {
 
         contextual(ShowImageFlag::class, ShowImageFlag.Serializer)
 
+        contextual(MessageOriginKind::class, MessageOriginKind.serializer())
 
         fun PolymorphicModuleBuilder<MessageMetadata>.messageMetadataSubclasses() {
             subclass(MessageSource::class, MessageSource.serializer())
             subclass(QuoteReply::class, QuoteReply.serializer())
             subclass(ShowImageFlag::class, ShowImageFlag.Serializer)
+            subclass(MessageOrigin::class, MessageOrigin.serializer())
         }
 
         fun PolymorphicModuleBuilder<MessageContent>.messageContentSubclasses() {

mirai-core-api/src/commonMain/kotlin/message/data/Deprecated.kt

@@ -0,0 +1,142 @@
+/*
+ * Copyright 2019-2021 Mamoe Technologies and contributors.
+ *
+ *  此源代码的使用受 GNU AFFERO GENERAL PUBLIC LICENSE version 3 许可证的约束, 可以在以下链接找到该许可证.
+ *  Use of this source code is governed by the GNU AGPLv3 license that can be found through the following link.
+ *
+ *  https://github.com/mamoe/mirai/blob/master/LICENSE
+ */
+
+
+@file:JvmMultifileClass
+@file:JvmName("MessageUtils")
+@file:Suppress("unused")
+
+package net.mamoe.mirai.message.data
+
+import kotlinx.serialization.Polymorphic
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+import net.mamoe.mirai.IMirai
+import net.mamoe.mirai.utils.safeCast
+
+
+/**
+ * 兼容 2.6 以下的 [MessageOrigin]. 请使用 [MessageOrigin]
+ * @since 2.3
+ * @suppress Deprecated since 2.6
+ */
+@Suppress("DEPRECATION_ERROR")
+@Serializable
+@SerialName(RichMessageOrigin.SERIAL_NAME)
+@Deprecated(
+    "Use MessageOrigin instead.",
+    replaceWith = ReplaceWith(
+        "MessageOrigin",
+        "net.mamoe.mirai.message.data.MessageOrigin",
+    ),
+    level = DeprecationLevel.ERROR
+)
+public class RichMessageOrigin
+@Deprecated(
+    "Use MessageOrigin instead.",
+    replaceWith = ReplaceWith(
+        "MessageOrigin(origin, resourceId, kind)",
+        "net.mamoe.mirai.message.data.MessageOrigin",
+    ),
+    level = DeprecationLevel.ERROR
+)
+constructor(
+    /**
+     * 原 [RichMessage].
+     */
+    public val origin: @Polymorphic RichMessage,
+    /**
+     * 如果来自长消息或转发消息, 则会有 [resourceId], 否则为 `null`.
+     *
+     * - 下载长消息 [IMirai.downloadLongMessage]
+     * - 下载合并转发消息 [IMirai.downloadForwardMessage]
+     */
+    public val resourceId: String?,
+    /**
+     * 来源类型
+     */
+    @Suppress("DEPRECATION_ERROR")
+    public val kind: RichMessageKind,
+) : MessageMetadata, ConstrainSingle {
+    @Suppress("DEPRECATION_ERROR")
+    override val key: Key get() = Key
+
+    override fun toString(): String {
+        val resourceId = resourceId
+        return if (resourceId == null) "[mirai:origin:$kind]"
+        else "[mirai:origin:$kind,$resourceId]"
+    }
+
+    override fun contentToString(): String = ""
+
+    override fun equals(other: Any?): Boolean {
+        if (this === other) return true
+        if (javaClass != other?.javaClass) return false
+
+        @Suppress("DEPRECATION_ERROR")
+        other as RichMessageOrigin
+
+        if (origin != other.origin) return false
+        if (resourceId != other.resourceId) return false
+        if (kind != other.kind) return false
+
+        return true
+    }
+
+    override fun hashCode(): Int {
+        var result = origin.hashCode()
+        result = 31 * result + (resourceId?.hashCode() ?: 0)
+        result = 31 * result + kind.hashCode()
+        return result
+    }
+
+
+    @Deprecated(
+        "Use MessageOrigin instead.",
+        replaceWith = ReplaceWith(
+            "MessageOrigin",
+            "net.mamoe.mirai.message.data.MessageOrigin",
+        ),
+        level = DeprecationLevel.ERROR
+    )
+    @Suppress("DEPRECATION_ERROR")
+    public companion object Key : AbstractMessageKey<RichMessageOrigin>({ it.safeCast() }) {
+        public const val SERIAL_NAME: String = "RichMessageOrigin"
+    }
+}
+
+/**
+ * 消息来源
+ * @since 2.3
+ * @suppress Deprecated since 2.6
+ */
+@Deprecated(
+    "Use MessageOriginKind",
+    ReplaceWith("MessageOriginKind", "net.mamoe.mirai.message.data.MessageOriginKind"),
+    level = DeprecationLevel.ERROR
+)
+public enum class RichMessageKind {
+    /**
+     * 长消息
+     */
+    LONG,
+
+    /**
+     * 合并转发
+     * @see ForwardMessage
+     */
+    FORWARD,
+
+    /**
+     * 音乐分享
+     * @see MusicShare
+     * @since 2.4
+     */
+    MUSIC_SHARE,
+}

mirai-core-api/src/commonMain/kotlin/message/data/MessageOrigin.kt

@@ -26,24 +26,24 @@ import net.mamoe.mirai.utils.safeCast
  * - 合并转发也使用长消息通道传输, 拥有 [resourceId], mirai 解析为 [ForwardMessage]
  * - [MusicShare] 也有特殊通道上传, 但会作为 [LightApp] 接收.
  *
- * 这些经过转换的类型的来源 [RichMessage] 会被包装为 [RichMessageOrigin] 并加入消息链中.
+ * 这些经过转换的类型的来源 [RichMessage] 会被包装为 [MessageOrigin] 并加入消息链中.
  *
- * 如一条被 mirai 解析的长消息的消息链组成为, 第一个元素为 [MessageSource], 第二个元素为 [RichMessageOrigin], 随后为长消息内容.
+ * 如一条被 mirai 解析的长消息的消息链组成为, 第一个元素为 [MessageSource], 第二个元素为 [MessageOrigin], 随后为长消息内容.
  *
- * 又如一条被 mirai 解析的 [MusicShare] 的消息链组成为, 第一个元素为 [MessageSource], 第二个元素为 [RichMessageOrigin], 第三个元素为 [MusicShare].
+ * 又如一条被 mirai 解析的 [MusicShare] 的消息链组成为, 第一个元素为 [MessageSource], 第二个元素为 [MessageOrigin], 第三个元素为 [MusicShare].
  *
- * @suppress **注意**: 这是实验性 API: 类名, 类的类型, 构造, 属性等所有 API 均不稳定. 可能会在未来任意时刻变更.
+ * @suppress **注意**: 这是实验性 API: 可能会在未来任意时刻变更.
  *
- * @since 2.3
+ * @since 2.6
  */
 @Serializable
-@SerialName(RichMessageOrigin.SERIAL_NAME)
-@MiraiExperimentalApi("RichMessageOrigin 不稳定")
-public class RichMessageOrigin(
+@SerialName(MessageOrigin.SERIAL_NAME)
+@MiraiExperimentalApi
+public class MessageOrigin( // [2.3, 2.6-M1) 类名为 RichMessageOrigin
     /**
-     * 原 [RichMessage].
+     * 原 [SingleMessage].
      */
-    public val origin: @Polymorphic RichMessage,
+    public val origin: @Polymorphic SingleMessage,
     /**
      * 如果来自长消息或转发消息, 则会有 [resourceId], 否则为 `null`.
      *
@@ -54,7 +54,7 @@ public class RichMessageOrigin(
     /**
      * 来源类型
      */
-    public val kind: RichMessageKind,
+    public val kind: MessageOriginKind,
 ) : MessageMetadata, ConstrainSingle {
     override val key: Key get() = Key
 
@@ -70,7 +70,7 @@ public class RichMessageOrigin(
         if (this === other) return true
         if (javaClass != other?.javaClass) return false
 
-        other as RichMessageOrigin
+        other as MessageOrigin
 
         if (origin != other.origin) return false
         if (resourceId != other.resourceId) return false
@@ -87,20 +87,18 @@ public class RichMessageOrigin(
     }
 
 
-    public companion object Key : AbstractMessageKey<RichMessageOrigin>({ it.safeCast() }) {
-        public const val SERIAL_NAME: String = "RichMessageOrigin"
+    public companion object Key : AbstractMessageKey<MessageOrigin>({ it.safeCast() }) {
+        public const val SERIAL_NAME: String = "MessageOrigin"
     }
 }
 
 /**
- * 消息来源
- *
- * @suppress 随着更新, 元素数量会增加. 类名不稳定.
- *
- * @since 2.3
+ * [MessageOrigin] 来源
+ * @see MessageOrigin.kind
+ * @since 2.6
  */
-@MiraiExperimentalApi("RichMessageKind 类名不稳定")
-public enum class RichMessageKind {
+@Serializable
+public enum class MessageOriginKind { // [2.3, 2.6-M1) 类名为 RichMessageKind
     /**
      * 长消息
      */
@@ -115,7 +113,6 @@ public enum class RichMessageKind {
     /**
      * 音乐分享
      * @see MusicShare
-     * @since 2.4
      */
     MUSIC_SHARE,
 }

mirai-core-api/src/commonMain/kotlin/message/data/SingleMessage.kt

@@ -46,7 +46,7 @@ public interface SingleMessage : Message { // TODO: 2021/1/10 Make sealed interf
 /**
  * 消息元数据, 即不含内容的元素.
  *
- * 这种类型的 [Message] 只表示一条消息的属性. 其子类如 [MessageSource], [QuoteReply] 和 [CustomMessageMetadata]
+ * 这种类型的 [Message] 只表示一条消息的属性. 其子类如 [MessageSource], [QuoteReply], [MessageOrigin] 和 [CustomMessageMetadata]
  *
  * 所有子类的 [contentToString] 都应该返回空字符串.
  *

mirai-core/src/commonMain/kotlin/message/LongMessageInternal.kt

@@ -24,7 +24,7 @@ internal data class LongMessageInternal internal constructor(override val conten
         val bot = contact.bot.asQQAndroidBot()
         val long = Mirai.downloadLongMessage(bot, resId)
 
-        return RichMessageOrigin(SimpleServiceMessage(serviceId, content), resId, RichMessageKind.LONG) + long
+        return MessageOrigin(SimpleServiceMessage(serviceId, content), resId, MessageOriginKind.LONG) + long
     }
 
     companion object Key :
@@ -59,7 +59,7 @@ internal data class ForwardMessageInternal(override val content: String, val res
         val preview = titles
         val source = xmlFoot.findField("name")
 
-        return RichMessageOrigin(SimpleServiceMessage(serviceId, content), resId, RichMessageKind.FORWARD) + ForwardMessage(
+        return MessageOrigin(SimpleServiceMessage(serviceId, content), resId, MessageOriginKind.FORWARD) + ForwardMessage(
             preview = preview,
             title = title,
             brief = brief,

mirai-core/src/commonMain/kotlin/message/MarketFaceImpl.kt

@@ -45,7 +45,7 @@ internal class MarketFaceInternal(
     override val id: Int get() = delegate.tabId
 
     override suspend fun refine(contact: Contact, context: MessageChain): Message {
-        delegate.toDiceOrNull()?.let { return it } // TODO: 2021/2/12 add dice origin, maybe rename RichMessageOrigin
+        delegate.toDiceOrNull()?.let { return it } // TODO: 2021/2/12 add dice origin, maybe rename MessageOrigin
         return MarketFaceImpl(delegate)
     }
 

mirai-core/src/commonMain/kotlin/message/lightApp.kt

@@ -28,10 +28,10 @@ internal data class LightAppInternal(
             if (meta.music != null) {
                 MusicKind.values().find { it.appId.toInt() == meta.music.appid }?.let { musicType ->
                     meta.music.run {
-                        return RichMessageOrigin(
+                        return MessageOrigin(
                             LightApp(content),
                             null,
-                            RichMessageKind.MUSIC_SHARE
+                            MessageOriginKind.MUSIC_SHARE
                         ) + MusicShare(
                             kind = musicType, title = title, summary = desc,
                             jumpUrl = jumpUrl, pictureUrl = preview, musicUrl = musicUrl, brief = prompt

mirai-core/src/jvmTest/kotlin/message/data/MessageSerializationTest.kt

@@ -111,7 +111,7 @@ internal class MessageSerializationTest {
         image.flash(),
         image.toForwardMessage(1L, "test"),
         MusicShare(MusicKind.NeteaseCloudMusic, "123", "123", "123", "123", "123", "123"),
-        RichMessageOrigin(SimpleServiceMessage(1, "content"), "resource id", RichMessageKind.LONG),
+        MessageOrigin(SimpleServiceMessage(1, "content"), "resource id", MessageOriginKind.LONG),
         ShowImageFlag,
         Dice(1),
         FileMessageImpl("id", 2, "name", 1)