pigeonhole-db 1.1.0

data/src/budget.rs

@@ -0,0 +1,205 @@
+//! D308's byte-budgeted reads (#1308): a scan's or a multi-get's page within a byte budget,
+//! and the positions to resume them from. A page comes back as `[rows, bytes,
+//! cut_by_budget, next_bytes, resume]`, which `lib/pigeonhole/api.rb` turns into a frozen
+//! `ScanPage` or `KeysPage`.
+
+use std::ops::Bound as KeyBound;
+
+use magnus::{Error, IntoValue, RArray, RString, Ruby, TryConvert, Value, prelude::*};
+use pigeonhole::KeySet;
+
+use crate::classes::{KeysPosition, Row, ScanPosition, Snapshot, Table};
+use crate::convert::{self, Bytes, arg_error, binary};
+use crate::error::{OrRb, engine};
+use crate::read::snapshot_arg;
+use crate::table::either;
+use crate::walk::byte_list;
+
+/// A position class's methods: its bytes, `from_bytes`, its key, equality and hashing.
+macro_rules! position {
+    ($name:ident, $inner:ty, $key:ident) => {
+        impl $name {
+            /// The position as bytes: versioned and stable, so a client can hand them back
+            /// later.
+            pub(crate) fn to_bytes(ruby: &Ruby, rb_self: &Self) -> RString {
+                binary(ruby, &rb_self.0.to_bytes())
+            }
+
+            /// The position `to_bytes` wrote; anything else (another kind of position
+            /// included) raises `InvalidArgument`.
+            pub(crate) fn from_bytes(ruby: &Ruby, b: Bytes) -> Result<Self, Error> {
+                <$inner>::from_bytes(&b.0).or_rb(ruby).map(Self)
+            }
+
+            /// The row (or key) the position is in, at or after.
+            pub(crate) fn $key(ruby: &Ruby, rb_self: &Self) -> RString {
+                binary(ruby, rb_self.0.$key())
+            }
+
+            /// The same position.
+            pub(crate) fn eq(&self, other: Value) -> bool {
+                <&$name>::try_convert(other).is_ok_and(|o| o.0 == self.0)
+            }
+
+            /// A hash consistent with `==`.
+            pub(crate) fn hash(&self) -> i64 {
+                use std::hash::{Hash, Hasher};
+                let mut h = std::hash::DefaultHasher::new();
+                self.0.hash(&mut h);
+                h.finish().cast_signed()
+            }
+        }
+    };
+}
+
+position!(ScanPosition, pigeonhole::ScanPosition, row);
+position!(KeysPosition, pigeonhole::KeysPosition, key);
+
+/// A page's fields as an Array: `[rows, bytes, cut_by_budget, next_bytes, resume]`.
+fn page(
+    ruby: &Ruby,
+    rows: Vec<pigeonhole::Row>,
+    bytes: u64,
+    cut: bool,
+    next: Option<u64>,
+    resume: Value,
+) -> Result<RArray, Error> {
+    let out = ruby.ary_new_capa(5);
+    out.push(ruby.ary_from_iter(rows.into_iter().map(Row)))?;
+    out.push(bytes)?;
+    out.push(cut)?;
+    out.push(next)?;
+    out.push(resume)?;
+    Ok(out)
+}
+
+impl Table {
+    /// `scan_within(bytes, prefix, start, end, families, qualifier_prefix, versions, limit,
+    /// column_limit, snapshot, after)`: a scan's page of at most `bytes` (D308), resumed
+    /// `after` a position.
+    #[allow(clippy::too_many_arguments)]
+    pub(crate) fn scan_within(
+        ruby: &Ruby,
+        rb_self: &Self,
+        bytes: u64,
+        prefix: Option<Bytes>,
+        start: Option<Bytes>,
+        end: Option<Bytes>,
+        families: Option<RArray>,
+        qualifier_prefix: Option<Bytes>,
+        versions: u32,
+        limit: Option<u64>,
+        column_limit: Option<u32>,
+        snapshot: Option<&Snapshot>,
+        after: Option<&ScanPosition>,
+    ) -> Result<RArray, Error> {
+        let (prefix, start, end) = (
+            convert::opt_bytes(prefix),
+            convert::opt_bytes(start),
+            convert::opt_bytes(end),
+        );
+        if prefix.is_some() && (start.is_some() || end.is_some()) {
+            return Err(arg_error(
+                ruby,
+                "scan_within takes a prefix or start:/end:, not both",
+            ));
+        }
+        let families = convert::names(families)?;
+        let qp = convert::opt_bytes(qualifier_prefix);
+        let snap = snapshot_arg(ruby, snapshot)?;
+        let after = after.map(|a| a.0.clone());
+        let h = rb_self.handle(ruby)?.clone();
+        let p = engine(ruby, move || {
+            either!(&h, |t| {
+                let mut s = match &prefix {
+                    Some(p) => t.scan_prefix(p),
+                    None => t.scan_bounds(
+                        start
+                            .as_deref()
+                            .map_or(KeyBound::Unbounded, KeyBound::Included),
+                        end.as_deref()
+                            .map_or(KeyBound::Unbounded, KeyBound::Excluded),
+                    ),
+                }
+                .versions(versions);
+                if let Some(f) = &families {
+                    s = s.families(f.iter().map(String::as_str));
+                }
+                if let Some(q) = &qp {
+                    s = s.qualifier_prefix(q);
+                }
+                if let Some(n) = limit {
+                    s = s.limit(n);
+                }
+                if let Some(n) = column_limit {
+                    s = s.column_limit(n);
+                }
+                if let Some(sn) = &snap {
+                    s = s.snapshot(sn);
+                }
+                if let Some(a) = &after {
+                    s = s.resume_after(a);
+                }
+                s.read_within(bytes)
+            })
+        })?;
+        let (bytes, cut, next) = (p.bytes(), p.cut_by_budget(), p.next_bytes());
+        let resume = p.resume().cloned().map_or_else(
+            || ruby.qnil().as_value(),
+            |r| ScanPosition(r).into_value_with(ruby),
+        );
+        page(ruby, p.into_rows(), bytes, cut, next, resume)
+    }
+
+    /// `multi_get_within(keys, bytes, families, qualifier_prefix, versions, column_limit,
+    /// snapshot, after)`: a page of `multi_get`'s cells in key order, at most `bytes` long
+    /// (D308), resumed `after` a position.
+    #[allow(clippy::too_many_arguments)]
+    pub(crate) fn multi_get_within(
+        ruby: &Ruby,
+        rb_self: &Self,
+        keys: RArray,
+        bytes: u64,
+        families: Option<RArray>,
+        qualifier_prefix: Option<Bytes>,
+        versions: u32,
+        column_limit: Option<u32>,
+        snapshot: Option<&Snapshot>,
+        after: Option<&KeysPosition>,
+    ) -> Result<RArray, Error> {
+        let given = byte_list(keys)?;
+        let families = convert::names(families)?;
+        let qp = convert::opt_bytes(qualifier_prefix);
+        let snap = snapshot_arg(ruby, snapshot)?;
+        let after = after.map(|a| a.0.clone());
+        let h = rb_self.handle(ruby)?.clone();
+        let p = engine(ruby, move || {
+            let set = KeySet::from_unsorted(&given);
+            either!(&h, |t| {
+                let mut r = t.keys(&set).versions(versions);
+                if let Some(f) = &families {
+                    r = r.families(f.iter().map(String::as_str));
+                }
+                if let Some(q) = &qp {
+                    r = r.qualifier_prefix(q);
+                }
+                if let Some(n) = column_limit {
+                    r = r.column_limit(n);
+                }
+                if let Some(s) = &snap {
+                    r = r.snapshot(s);
+                }
+                if let Some(a) = &after {
+                    r = r.resume_after(a);
+                }
+                r.read_within(bytes)
+            })
+        })?;
+        let (bytes, cut, next) = (p.bytes(), p.cut_by_budget(), p.next_bytes());
+        let resume = p.resume().cloned().map_or_else(
+            || ruby.qnil().as_value(),
+            |r| KeysPosition(r).into_value_with(ruby),
+        );
+        page(ruby, p.into_rows(), bytes, cut, next, resume)
+    }
+}

data/src/classes.rs

@@ -0,0 +1,279 @@
+//! The Ruby classes' Rust data: one struct per wrapped class. Their methods live in
+//! `db.rs`, `table.rs` and `read.rs`.
+//!
+//! **Unsafe:** this module allows `unsafe_code` only because `#[magnus::wrap]` expands to an
+//! `unsafe impl magnus::TypedData` for each struct. It contains no hand-written unsafe.
+#![allow(unsafe_code)]
+
+use std::sync::{Mutex, RwLock};
+
+use crate::fork::ForkSafe;
+use crate::table::{Durability, Handle, Op};
+
+/// `Pigeonhole::Database`: the writer process's handle; `None` once closed.
+#[magnus::wrap(class = "Pigeonhole::Database", free_immediately, size)]
+pub(crate) struct Database(
+    pub(crate) ForkSafe<RwLock<Option<pigeonhole::Pigeonhole>>>,
+    /// The memory stores opened on it (PR 3a): `close` closes them first, so their forgetter
+    /// threads stop (simp724's P1 on #1340, as in Python).
+    pub(crate) crate::memory::Stores<crate::memory::StoreSlot>,
+);
+
+/// `Pigeonhole::Reader`: a reader process's handle; `None` once closed.
+#[magnus::wrap(class = "Pigeonhole::Reader", free_immediately, size)]
+pub(crate) struct Reader(
+    pub(crate) ForkSafe<RwLock<Option<pigeonhole::PigeonholeReader>>>,
+    /// The memory stores opened on it: `close` closes them first.
+    pub(crate) crate::memory::Stores<crate::memory::ReadSlot>,
+);
+
+/// `Pigeonhole::TableBuilder`'s state.
+pub(crate) struct Builder {
+    pub(crate) db: pigeonhole::Pigeonhole,
+    pub(crate) name: String,
+    pub(crate) families: Mutex<Vec<(String, pigeonhole::Family)>>,
+}
+
+/// `Pigeonhole::TableBuilder`.
+#[magnus::wrap(class = "Pigeonhole::TableBuilder", free_immediately, size)]
+pub(crate) struct TableBuilder(pub(crate) ForkSafe<Builder>);
+
+/// `Pigeonhole::Table`: a writer or reader table handle.
+#[magnus::wrap(class = "Pigeonhole::Table", free_immediately, size)]
+pub(crate) struct Table(pub(crate) ForkSafe<Handle>);
+
+/// `Pigeonhole::Mutation`'s state: writes recorded against one row.
+pub(crate) struct MutationState {
+    pub(crate) table: pigeonhole::Table,
+    pub(crate) row: Vec<u8>,
+    /// `None` once committed.
+    pub(crate) ops: Mutex<Option<Vec<Op>>>,
+    pub(crate) durability: Mutex<Option<Durability>>,
+}
+
+/// `Pigeonhole::Mutation`.
+#[magnus::wrap(class = "Pigeonhole::Mutation", free_immediately, size)]
+pub(crate) struct Mutation(pub(crate) ForkSafe<MutationState>);
+
+/// One recorded batch write: its table, its row and the write.
+pub(crate) type BatchOp = (pigeonhole::Table, Vec<u8>, Op);
+
+/// `Pigeonhole::WriteBatch`'s state.
+pub(crate) struct BatchState {
+    pub(crate) db: pigeonhole::Pigeonhole,
+    /// `None` once committed or discarded.
+    pub(crate) ops: Mutex<Option<Vec<BatchOp>>>,
+}
+
+/// `Pigeonhole::WriteBatch`.
+#[magnus::wrap(class = "Pigeonhole::WriteBatch", free_immediately, size)]
+pub(crate) struct WriteBatch(pub(crate) ForkSafe<BatchState>);
+
+/// `Pigeonhole::Transaction`: the engine transaction behind a mutex (simp724's R4); `None`
+/// once committed or rolled back.
+#[magnus::wrap(class = "Pigeonhole::Transaction", free_immediately, size)]
+pub(crate) struct Transaction(pub(crate) ForkSafe<Mutex<Option<pigeonhole::Transaction>>>);
+
+/// `Pigeonhole::Snapshot`; `None` once released.
+#[magnus::wrap(class = "Pigeonhole::Snapshot", free_immediately, size)]
+pub(crate) struct Snapshot(pub(crate) ForkSafe<Mutex<Option<pigeonhole::Snapshot>>>);
+
+/// `Pigeonhole::Cell`.
+#[magnus::wrap(class = "Pigeonhole::Cell", free_immediately, size)]
+pub(crate) struct Cell(pub(crate) pigeonhole::Cell);
+
+/// `Pigeonhole::Incremented`: the counter cells a `Mutation#commit_returning` wrote, after
+/// its commit (D314). Plain data: no handle, so nothing to guard across a fork.
+#[magnus::wrap(class = "Pigeonhole::Incremented", free_immediately, size)]
+pub(crate) struct Incremented(pub(crate) pigeonhole::Incremented);
+
+/// `Pigeonhole::Row`.
+#[magnus::wrap(class = "Pigeonhole::Row", free_immediately, size)]
+pub(crate) struct Row(pub(crate) pigeonhole::Row);
+
+/// `Pigeonhole::Family`: a family's options.
+#[magnus::wrap(class = "Pigeonhole::Family", free_immediately, size)]
+pub(crate) struct Family(pub(crate) pigeonhole::Family);
+
+/// `Pigeonhole::FamilyInfo`: a family's stored options.
+#[magnus::wrap(class = "Pigeonhole::FamilyInfo", free_immediately, size)]
+pub(crate) struct FamilyInfo(pub(crate) pigeonhole::FamilyInfo);
+
+/// `Pigeonhole::Condition`.
+#[magnus::wrap(class = "Pigeonhole::Condition", free_immediately, size)]
+pub(crate) struct Condition(pub(crate) pigeonhole::Condition);
+
+/// What a scan reads, converted and checked when `Table#scan` is called; each enumeration
+/// starts its own cursor from it.
+pub(crate) struct ScanArgs {
+    pub(crate) table: Handle,
+    pub(crate) prefix: Option<Vec<u8>>,
+    pub(crate) start: Option<Vec<u8>>,
+    pub(crate) end: Option<Vec<u8>>,
+    pub(crate) families: Option<Vec<String>>,
+    pub(crate) qualifier_prefix: Option<Vec<u8>>,
+    pub(crate) versions: u32,
+    pub(crate) limit: Option<u64>,
+    pub(crate) column_limit: Option<u32>,
+    pub(crate) chunk: usize,
+}
+
+/// `Pigeonhole::Native::ScanSpec` (internal): a scan's arguments.
+#[magnus::wrap(class = "Pigeonhole::Native::ScanSpec", free_immediately, size)]
+pub(crate) struct ScanSpec(pub(crate) ForkSafe<ScanArgs>);
+
+/// `Pigeonhole::Native::ScanCursor` (internal): one enumeration's rows, read at one
+/// snapshot (simp724's R3); `None` once finished or closed.
+#[magnus::wrap(class = "Pigeonhole::Native::ScanCursor", free_immediately, size)]
+pub(crate) struct ScanCursor {
+    pub(crate) rows: ForkSafe<Mutex<Option<pigeonhole::RowIter<'static>>>>,
+    pub(crate) chunk: usize,
+}
+
+/// `Pigeonhole::VectorSpec`: a vector family's dimension, element type and metric.
+#[magnus::wrap(class = "Pigeonhole::VectorSpec", free_immediately, size)]
+pub(crate) struct VectorSpec(pub(crate) pigeonhole::VectorSpec);
+
+/// `Pigeonhole::RowPosition`: where a walk of a row's pages stopped.
+#[magnus::wrap(class = "Pigeonhole::RowPosition", free_immediately, size)]
+pub(crate) struct RowPosition(pub(crate) pigeonhole::RowPosition);
+
+/// `Pigeonhole::ScanPosition`: where a `scan_within` page stopped.
+#[magnus::wrap(class = "Pigeonhole::ScanPosition", free_immediately, size)]
+pub(crate) struct ScanPosition(pub(crate) pigeonhole::ScanPosition);
+
+/// `Pigeonhole::KeysPosition`: where a `multi_get_within` page stopped.
+#[magnus::wrap(class = "Pigeonhole::KeysPosition", free_immediately, size)]
+pub(crate) struct KeysPosition(pub(crate) pigeonhole::KeysPosition);
+
+/// What a walk of a row's pages reads, and where it is.
+pub(crate) struct PagesState {
+    pub(crate) table: Handle,
+    pub(crate) row: Vec<u8>,
+    pub(crate) size: usize,
+    pub(crate) families: Option<Vec<String>>,
+    pub(crate) qualifier_prefix: Option<Vec<u8>>,
+    pub(crate) versions: u32,
+    pub(crate) snapshot: Option<pigeonhole::Snapshot>,
+    /// Where the last page ended.
+    pub(crate) position: Option<pigeonhole::RowPosition>,
+    pub(crate) done: bool,
+}
+
+/// `Pigeonhole::Pages`: a wide row's pages, each read when it is asked for.
+#[magnus::wrap(class = "Pigeonhole::Pages", free_immediately, size)]
+pub(crate) struct Pages(pub(crate) ForkSafe<Mutex<PagesState>>);
+
+/// `Pigeonhole::Feed`: a change feed subscription (its state is `crate::feed::FeedState`).
+#[magnus::wrap(class = "Pigeonhole::Feed", free_immediately, size)]
+pub(crate) struct Feed(pub(crate) ForkSafe<crate::feed::FeedState>);
+
+// ---- Pigeonhole::Memory (PR 3a; methods in memory.rs) ------------------------------
+
+/// `Pigeonhole::Memory::MemoryId`: a memory's id. Its text form is RFC 4648 base32 of its
+/// byte form (ICR 0107).
+#[magnus::wrap(class = "Pigeonhole::Memory::MemoryId", free_immediately, size)]
+#[derive(Clone)]
+pub(crate) struct MemoryId(pub(crate) pigeonhole_memory::MemoryId);
+
+/// `Pigeonhole::Memory::EmbeddingModel`: the model a store is pinned to.
+#[magnus::wrap(class = "Pigeonhole::Memory::EmbeddingModel", free_immediately, size)]
+#[derive(Clone)]
+pub(crate) struct EmbeddingModel(pub(crate) pigeonhole_memory::EmbeddingModel);
+
+/// `Pigeonhole::Memory::IvfOptions`: a store's IVF index options (D311 T8).
+#[magnus::wrap(class = "Pigeonhole::Memory::IvfOptions", free_immediately, size)]
+#[derive(Clone, Copy)]
+pub(crate) struct IvfOptions(pub(crate) pigeonhole_memory::IvfOptions);
+
+/// `Pigeonhole::Memory::Weights`: recall's signal weights (1 by default; `recency` 0.25,
+/// `graph` and `consolidated` 0.5).
+#[magnus::wrap(class = "Pigeonhole::Memory::Weights", free_immediately, size)]
+#[derive(Clone)]
+pub(crate) struct Weights(pub(crate) pigeonhole_memory::Weights);
+
+/// `Pigeonhole::Memory::Expand`: a recall's graph expansion (T4).
+#[magnus::wrap(class = "Pigeonhole::Memory::Expand", free_immediately, size)]
+#[derive(Clone)]
+pub(crate) struct Expand(pub(crate) pigeonhole_memory::Expand);
+
+/// `Pigeonhole::Memory::ForgetPolicy`: a store's forget policy (T2).
+#[magnus::wrap(class = "Pigeonhole::Memory::ForgetPolicy", free_immediately, size)]
+#[derive(Clone)]
+pub(crate) struct ForgetPolicy(pub(crate) pigeonhole_memory::ForgetPolicy);
+
+/// `Pigeonhole::Memory::ConsolidatePolicy`: how `consolidate` picks and folds groups (T3).
+#[magnus::wrap(
+    class = "Pigeonhole::Memory::ConsolidatePolicy",
+    free_immediately,
+    size
+)]
+#[derive(Clone)]
+pub(crate) struct ConsolidatePolicy(pub(crate) pigeonhole_memory::ConsolidatePolicy);
+
+/// `Pigeonhole::Memory::NearDedup`: a store's near-duplicate dedup (T3).
+#[magnus::wrap(class = "Pigeonhole::Memory::NearDedup", free_immediately, size)]
+#[derive(Clone, Copy)]
+pub(crate) struct NearDedup(pub(crate) pigeonhole_memory::NearDedup);
+
+/// `Pigeonhole::Memory::Memory`: a memory to write, what a consolidator returns.
+#[magnus::wrap(class = "Pigeonhole::Memory::Memory", free_immediately, size)]
+#[derive(Clone)]
+pub(crate) struct Memory {
+    pub(crate) text: String,
+    pub(crate) inner: pigeonhole_memory::Memory,
+}
+
+/// `Pigeonhole::Memory::Store`: a memory store in the writer process.
+#[magnus::wrap(class = "Pigeonhole::Memory::Store", free_immediately, size)]
+pub(crate) struct Store(pub(crate) ForkSafe<std::sync::Arc<crate::memory::StoreSlot>>);
+
+/// `Pigeonhole::Memory::ReadStore`: a memory store in a reader process.
+#[magnus::wrap(class = "Pigeonhole::Memory::ReadStore", free_immediately, size)]
+pub(crate) struct ReadStore(pub(crate) ForkSafe<std::sync::Arc<crate::memory::ReadSlot>>);
+
+// ---- Pigeonhole::Text and Pigeonhole::Vector (PR 3b; methods in index.rs) ----------------
+
+/// `Pigeonhole::Text::Query`: a full-text query.
+#[magnus::wrap(class = "Pigeonhole::Text::Query", free_immediately, size)]
+pub(crate) struct TextQuery(pub(crate) pigeonhole_text::Query);
+
+/// `Pigeonhole::Text::Index`: a full-text index in the writer process.
+#[magnus::wrap(class = "Pigeonhole::Text::Index", free_immediately, size)]
+pub(crate) struct TextIndex(pub(crate) ForkSafe<pigeonhole_text::Index>);
+
+/// `Pigeonhole::Text::ReadIndex`: a full-text index in a reader process.
+#[magnus::wrap(class = "Pigeonhole::Text::ReadIndex", free_immediately, size)]
+pub(crate) struct TextReadIndex(pub(crate) ForkSafe<pigeonhole_text::ReadIndex>);
+
+/// `Pigeonhole::Vector::Index`: a vector index in the writer process.
+#[magnus::wrap(class = "Pigeonhole::Vector::Index", free_immediately, size)]
+pub(crate) struct VectorIndex(pub(crate) ForkSafe<pigeonhole_vector::Index>);
+
+/// `Pigeonhole::Vector::ReadIndex`: a vector index in a reader process.
+#[magnus::wrap(class = "Pigeonhole::Vector::ReadIndex", free_immediately, size)]
+pub(crate) struct VectorReadIndex(pub(crate) ForkSafe<pigeonhole_vector::ReadIndex>);
+
+/// `Pigeonhole::Vector::Placed`: one transaction's writes to one index; `None` once passed
+/// to `after_commit`.
+#[magnus::wrap(class = "Pigeonhole::Vector::Placed", free_immediately, size)]
+pub(crate) struct Placed(pub(crate) ForkSafe<Mutex<Option<pigeonhole_vector::Placed>>>);
+
+/// `Pigeonhole::Vector::Rebalancer`: a background-mode index's rebalancing, for a Ruby
+/// thread to drive.
+#[magnus::wrap(class = "Pigeonhole::Vector::Rebalancer", free_immediately, size)]
+pub(crate) struct Rebalancer(
+    pub(crate) ForkSafe<crate::index::Fair<pigeonhole_vector::Rebalancer>>,
+);
+
+/// `Pigeonhole::Vector::BulkLoad`: a bulk load in progress; `None` once finished.
+#[magnus::wrap(class = "Pigeonhole::Vector::BulkLoad", free_immediately, size)]
+pub(crate) struct VectorBulkLoad(pub(crate) ForkSafe<Mutex<Option<crate::index::BulkState>>>);
+
+/// `Pigeonhole::Memory::Watch`: a store's memory events (T9); `None` once closed.
+#[magnus::wrap(class = "Pigeonhole::Memory::Watch", free_immediately, size)]
+pub(crate) struct Watch(pub(crate) ForkSafe<crate::index::Fair<Option<pigeonhole_memory::Watch>>>);
+
+/// `Pigeonhole::Memory::ConsolidateLoop`: feed-driven consolidation (T9).
+#[magnus::wrap(class = "Pigeonhole::Memory::ConsolidateLoop", free_immediately, size)]
+pub(crate) struct ConsolidateLoop(pub(crate) ForkSafe<Mutex<crate::memory::LoopSlot>>);

data/src/convert.rs

@@ -0,0 +1,192 @@
+//! Ruby arguments to Rust: byte strings, names, cell values, durations and durability (each
+//! a [`TryConvert`] type, so the native methods take them directly), plus the binding's own
+//! argument errors and lock helpers.
+
+use std::borrow::Cow;
+use std::sync::{Mutex, MutexGuard, PoisonError};
+use std::time::Duration;
+
+use magnus::{Error, Float, Integer, RArray, RString, Ruby, Symbol, TryConvert, Value, prelude::*};
+
+use crate::table::Durability;
+
+/// A row key, qualifier or byte value: a String's bytes as they are (any encoding).
+pub(crate) struct Bytes(pub(crate) Vec<u8>);
+
+impl TryConvert for Bytes {
+    fn try_convert(val: Value) -> Result<Self, Error> {
+        let ruby = Ruby::get_with(val);
+        match RString::from_value(val) {
+            Some(s) => Ok(Self(s.to_bytes().to_vec())),
+            None => Err(type_error(
+                &ruby,
+                format!("expected a String (bytes), not {}", class_name(val)),
+            )),
+        }
+    }
+}
+
+/// An optional byte string.
+pub(crate) fn opt_bytes(b: Option<Bytes>) -> Option<Vec<u8>> {
+    b.map(|b| b.0)
+}
+
+/// A name (a family, a table, a kind): a Symbol or a String.
+pub(crate) struct Name(pub(crate) String);
+
+impl TryConvert for Name {
+    fn try_convert(val: Value) -> Result<Self, Error> {
+        let ruby = Ruby::get_with(val);
+        if let Some(sym) = Symbol::from_value(val) {
+            return Ok(Self(sym.name()?.into_owned()));
+        }
+        if let Some(s) = RString::from_value(val) {
+            return Ok(Self(s.to_string()?));
+        }
+        Err(type_error(
+            &ruby,
+            format!("expected a Symbol or a String, not {}", class_name(val)),
+        ))
+    }
+}
+
+/// An Array of names (`families:`).
+pub(crate) fn names(a: Option<RArray>) -> Result<Option<Vec<String>>, Error> {
+    let Some(a) = a else { return Ok(None) };
+    let mut out = Vec::with_capacity(a.len());
+    for i in 0..a.len() {
+        let v: Value = a.entry(isize::try_from(i).unwrap_or(isize::MAX))?;
+        out.push(Name::try_convert(v)?.0);
+    }
+    Ok(Some(out))
+}
+
+/// A cell value as written: the Ruby class picks the cell type.
+#[derive(Debug, Clone)]
+pub(crate) enum Val {
+    Bytes(Vec<u8>),
+    I64(i64),
+    F64(f64),
+}
+
+/// A `String` is bytes, an `Integer` an `i64` (`RangeError` past it), a `Float` an `f64`.
+/// `true`, `false`, `nil` and other classes are refused (`TypeError`): a stored 1 is rarely
+/// what `true` meant.
+pub(crate) struct CellValue(pub(crate) Val);
+
+impl TryConvert for CellValue {
+    fn try_convert(v: Value) -> Result<Self, Error> {
+        let ruby = Ruby::get_with(v);
+        if let Some(s) = RString::from_value(v) {
+            return Ok(Self(Val::Bytes(s.to_bytes().to_vec())));
+        }
+        if let Some(n) = Integer::from_value(v) {
+            return n.to_i64().map(|n| Self(Val::I64(n))).map_err(|_| {
+                range_error(
+                    &ruby,
+                    "an Integer value must fit in an i64 (put_u64 writes a u64)",
+                )
+            });
+        }
+        if let Some(x) = Float::from_value(v) {
+            return Ok(Self(Val::F64(x.to_f64())));
+        }
+        Err(type_error(
+            &ruby,
+            format!(
+                "a cell value is a String, an Integer or a Float, not {}",
+                class_name(v)
+            ),
+        ))
+    }
+}
+
+/// A duration: Numeric seconds, non-negative and finite.
+pub(crate) struct Secs(pub(crate) Duration);
+
+impl TryConvert for Secs {
+    fn try_convert(v: Value) -> Result<Self, Error> {
+        let ruby = Ruby::get_with(v);
+        if v.is_kind_of(ruby.class_true_class()) || v.is_kind_of(ruby.class_false_class()) {
+            return Err(type_error(
+                &ruby,
+                "a duration is Numeric seconds, not a boolean",
+            ));
+        }
+        let s = f64::try_convert(v)?;
+        Duration::try_from_secs_f64(s).map(Self).map_err(|_| {
+            arg_error(
+                &ruby,
+                "a duration must be a non-negative, finite number of seconds",
+            )
+        })
+    }
+}
+
+impl TryConvert for Durability {
+    /// `:none`, `:buffered`, `:group_sync` or `:sync`.
+    fn try_convert(v: Value) -> Result<Self, Error> {
+        let ruby = Ruby::get_with(v);
+        let Some(sym) = Symbol::from_value(v) else {
+            return Err(type_error(
+                &ruby,
+                format!(
+                    "durability is a Symbol (:none, :buffered, :group_sync or :sync), not {}",
+                    class_name(v)
+                ),
+            ));
+        };
+        Ok(match sym.name()?.as_ref() {
+            "none" => Self::None_,
+            "buffered" => Self::Buffered,
+            "group_sync" => Self::GroupSync,
+            "sync" => Self::Sync,
+            other => {
+                return Err(arg_error(
+                    &ruby,
+                    format!("unknown durability :{other} (:none, :buffered, :group_sync or :sync)"),
+                ));
+            }
+        })
+    }
+}
+
+/// A binary (`ASCII-8BIT`) String holding `b`.
+pub(crate) fn binary(ruby: &Ruby, b: &[u8]) -> RString {
+    ruby.str_from_slice(b)
+}
+
+/// A frozen binary String, for a value inside a frozen `Data` result: mutating it would
+/// change the result's `==` and `hash`.
+pub(crate) fn frozen(ruby: &Ruby, b: &[u8]) -> RString {
+    let s = binary(ruby, b);
+    s.freeze();
+    s
+}
+
+/// `v`'s class name, for messages.
+pub(crate) fn class_name(v: Value) -> String {
+    v.class().inspect()
+}
+
+/// `ArgumentError` with `msg`.
+pub(crate) fn arg_error(ruby: &Ruby, msg: impl Into<Cow<'static, str>>) -> Error {
+    Error::new(ruby.exception_arg_error(), msg)
+}
+
+/// `TypeError` with `msg`.
+pub(crate) fn type_error(ruby: &Ruby, msg: impl Into<Cow<'static, str>>) -> Error {
+    Error::new(ruby.exception_type_error(), msg)
+}
+
+/// `RangeError` with `msg`.
+pub(crate) fn range_error(ruby: &Ruby, msg: impl Into<Cow<'static, str>>) -> Error {
+    Error::new(ruby.exception_range_error(), msg)
+}
+
+/// Locks `m`, ignoring poisoning: a panic is re-raised as a Ruby exception, and each guarded
+/// value stays consistent across one (every critical section is a take, a push or one
+/// engine call that fails as a whole).
+pub(crate) fn lock<T>(m: &Mutex<T>) -> MutexGuard<'_, T> {
+    m.lock().unwrap_or_else(PoisonError::into_inner)
+}