feat: migrate state-machine-api from databend workspace to standalone crate

- Add complete source code from databend/src/meta/state-machine-api
- Update Cargo.toml to use correct crate name and standalone dependencies
- All tests passing (22 tests)

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: drmingdrmer

Cargo.lock

@@ -0,0 +1,18 @@
+[package]
+name = "state-machine-api"
+version = "0.1.0"
+authors = ["drmingdrmer <[email protected]>"]
+license = "Apache-2.0"
+publish = true
+edition = "2021"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+display-more = { git = "https://github.com/databendlabs/display-more", tag = "v0.2.0" }
+map-api = { git = "https://github.com/databendlabs/map-api", tag = "v0.2.7" }
+serde = { version = "1.0", features = ["derive"] }
+
+[dev-dependencies]
+anyhow = "1.0"
+serde_json = "1.0"

Cargo.toml

@@ -0,0 +1,94 @@
+// Copyright 2021 Datafuse Labs
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//! This mod defines a key space in state machine to store the index of keys with an expiration time.
+//!
+//! This secondary index is `(expire_time, seq) -> key`, as the key-value's primary index is `key -> (seq, expire_time, value)`.
+//! Because `seq` in meta-store is globally unique, it may be used to identify every update to every key.
+
+use std::fmt::Display;
+use std::fmt::Formatter;
+use std::time::Duration;
+
+use display_more::DisplayUnixTimeStampExt;
+use map_api::MapKey;
+
+/// The identifier of the index for kv with expiration.
+///
+/// Encoding to `exp-/<timestamp>/<primary_key_seq>`.
+/// The encoded value is `<ver=1>null<string_key>`. The `null` is json string for empty meta
+#[derive(
+    Default,
+    Debug,
+    Clone,
+    Copy,
+    serde::Serialize,
+    serde::Deserialize,
+    PartialEq,
+    Eq,
+    PartialOrd,
+    Ord,
+)]
+pub struct ExpireKey {
+    /// The time in millisecond when a key will be expired.
+    pub time_ms: u64,
+
+    /// The `seq` of the value when the key is written.
+    ///
+    /// The `seq` of value is globally unique in meta-store.
+    pub seq: u64,
+}
+
+impl MapKey for ExpireKey {
+    type V = String;
+}
+
+impl ExpireKey {
+    pub fn new(time_ms: u64, seq: u64) -> Self {
+        Self { time_ms, seq }
+    }
+
+    /// Return true if the provided time in millisecond is expired.
+    ///
+    /// NOTE that `time_ms` equal to `self.time_ms` is not considered expired.
+    pub fn is_expired(&self, time_ms: u64) -> bool {
+        time_ms > self.time_ms
+    }
+}
+
+impl Display for ExpireKey {
+    fn fmt(&self, f: &mut Formatter) -> std::fmt::Result {
+        write!(
+            f,
+            "{}={}",
+            Duration::from_millis(self.time_ms).display_unix_timestamp_short(),
+            self.seq
+        )
+    }
+}
+
+#[cfg(test)]
+mod tests {
+
+    use super::*;
+
+    #[test]
+    fn test_expire_key_display() -> anyhow::Result<()> {
+        let ms = 1666670258202;
+        let k = ExpireKey::new(ms, 1000);
+        assert_eq!("2022-10-25T03:57:38.202=1000", format!("{}", k));
+
+        Ok(())
+    }
+}

src/expire_key.rs

@@ -0,0 +1,161 @@
+// Copyright 2021 Datafuse Labs
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use map_api::Marked;
+use map_api::SeqMarked;
+
+/// The value of an expiration index is the record key.
+#[derive(Default, Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub struct ExpireValue {
+    #[serde(skip_serializing_if = "is_zero")]
+    #[serde(default)]
+    pub seq: u64,
+    pub key: String,
+}
+
+fn is_zero(v: &u64) -> bool {
+    *v == 0
+}
+
+impl ExpireValue {
+    pub fn new(key: impl ToString, seq: u64) -> Self {
+        Self {
+            key: key.to_string(),
+            seq,
+        }
+    }
+    /// Convert internally used expire-index value `Marked<String>` to externally used type `ExpireValue`.
+    ///
+    /// `Marked<String>` is the value of an expire-index in the state machine.
+    /// `ExpireValue.seq` equals to the seq of the str-map record,
+    /// i.e., when an expire-index is inserted, the seq does not increase.
+    pub fn from_marked(seq_marked: SeqMarked<String>) -> Option<Self> {
+        let (seq, mm) = seq_marked.into_parts();
+
+        match mm {
+            Marked::TombStone => None,
+            Marked::Normal(s) => Some(ExpireValue::new(s, seq)),
+        }
+    }
+}
+
+impl From<ExpireValue> for SeqMarked<String> {
+    fn from(value: ExpireValue) -> Self {
+        SeqMarked::new_normal(value.seq, value.key)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_expire_value_serde() -> anyhow::Result<()> {
+        {
+            let v = ExpireValue {
+                seq: 0,
+                key: "a".to_string(),
+            };
+            let s = serde_json::to_string(&v)?;
+            let want = r#"{"key":"a"}"#;
+            assert_eq!(want, s);
+
+            let got = serde_json::from_str::<ExpireValue>(want)?;
+            assert_eq!(v, got);
+        }
+
+        {
+            let v = ExpireValue {
+                seq: 5,
+                key: "a".to_string(),
+            };
+            let s = serde_json::to_string(&v)?;
+            let want = r#"{"seq":5,"key":"a"}"#;
+            assert_eq!(want, s);
+
+            let got = serde_json::from_str::<ExpireValue>(want)?;
+            assert_eq!(v, got);
+        }
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_from_seq_marked() {
+        // Test normal case - should return Some(ExpireValue)
+        {
+            let seq = 42;
+            let key = "test_key".to_string();
+            let marked = Marked::Normal(key.clone());
+            let seq_marked = SeqMarked::new(seq, marked);
+
+            let result = ExpireValue::from_marked(seq_marked);
+
+            assert!(result.is_some());
+            let expire_value = result.unwrap();
+            assert_eq!(expire_value.seq, seq);
+            assert_eq!(expire_value.key, key);
+        }
+
+        // Test tombstone case - should return None
+        {
+            let seq = 100;
+            let marked = Marked::TombStone;
+            let seq_marked = SeqMarked::new(seq, marked);
+
+            let result = ExpireValue::from_marked(seq_marked);
+
+            assert!(result.is_none());
+        }
+
+        // Test with zero seq
+        {
+            let seq = 0;
+            let key = "zero_seq_key".to_string();
+            let marked = Marked::Normal(key.clone());
+            let seq_marked = SeqMarked::new(seq, marked);
+
+            let result = ExpireValue::from_marked(seq_marked);
+
+            assert!(result.is_some());
+            let expire_value = result.unwrap();
+            assert_eq!(expire_value.seq, seq);
+            assert_eq!(expire_value.key, key);
+        }
+    }
+
+    // Test From<ExpireValue> for Marked<String>
+    #[test]
+    fn test_from_expire_value_for_marked() -> anyhow::Result<()> {
+        let m = SeqMarked::new_normal(1, "2".to_string());
+        let s = ExpireValue::new("2", 1);
+        assert_eq!(m, s.into());
+
+        Ok(())
+    }
+
+    // Test From<Marked<String>> for Option<ExpireValue>
+    #[test]
+    fn test_from_marked_for_option_expire_value() -> anyhow::Result<()> {
+        let m = SeqMarked::new_normal(1, "2".to_string());
+        let s: Option<ExpireValue> = Some(ExpireValue::new("2".to_string(), 1));
+        assert_eq!(s, ExpireValue::from_marked(m));
+
+        let m = SeqMarked::new_tombstone(1);
+        let s: Option<ExpireValue> = None;
+        assert_eq!(s, ExpireValue::from_marked(m));
+
+        Ok(())
+    }
+}