add everything

Author: wmitros

Cargo.toml

@@ -1,5 +1,19 @@
 [workspace]
 members = [
+    "examples",
     "scylla-bindgen",
+    "scylla-bindgen-macros",
     "scylla-cql",
+    "tests",
 ]
+
+[workspace.package]
+edition = "2021"
+version = "0.0.1"
+repository = "https://github.com/wmitros/scylla-rust-udf"
+license = "MIT OR Apache-2.0"
+rust-version = "1.66.1"
+
+[workspace.dependencies]
+scylla-bindgen = { path = "scylla-bindgen" }
+scylla-bindgen-macros = { path = "scylla-bindgen-macros" }

README.md

@@ -1 +1,100 @@
-# Rust-utils-for-Scylla-UDFs
+# Rust helper library for Scylla UDFs
+
+## Usage
+
+### Prerequisites
+
+To use this helper library in Scylla you'll need:
+* Standard library for Rust `wasm32-wasi`
+  Can be added in rustup installations using `rustup target add wasm32-wasi`
+  For non rustup setups, you can try following the steps at https://rustwasm.github.io/docs/wasm-pack/prerequisites/non-rustup-setups.html
+  Also available as an rpm: `rust-std-static-wasm32-wasi`
+* `wasm2wat` parser
+  Available in many distributions in the `wabt` package
+
+### Compilation
+
+We recommend a setup with cargo.
+
+1. Start with a library package
+```
+cargo new --lib
+```
+2. Edit the Cargo.toml to set the crate-type to cdylib
+```
++ [lib]
++ crate-type = ["cdylib"]
+```
+3. Implement your package, exporting Scylla UDFs using the `scylla_bindgen::export_udf` macro.
+4. Build the package using the wasm32-wasi target:
+```
+cargo build --target=wasm32-wasi
+```
+5. Find the compiled `.wasm` binary. Let's assume it's `target/wasm32-wasi/debug/abc.wasm`.
+6. (optional) Optimize the binary using `wasm-opt -O3 target/wasm32-wasi/debug/abc.wasm` (can be combined with using `cargo build --release`  profile)
+7. Translate the binary into `wat`:
+```
+wasm2wat target/wasm32-wasi/debug/abc.wasm > target/wasm32/wasi/debug/abc.wat
+```
+
+### CQL Statement
+
+The resulting `target/wasm32/wasi/debug/abc.wat` code can now be used directly in a `CREATE FUNCTION` statement. The resulting code will most likely
+contain `'` characters, so it's recommended to use a `LANGUAGE xwasm AS $$ (module ...) $$` clause instead of `LANGUAGE xwasm AS ' (module ...) '`.
+For example, if you have an [Rust UDF](examples/commas.rs) that joins a list of words using commas you can create a Scylla UDF using the following statement:
+```
+CREATE FUNCTION commas(string list<text>) CALLED ON NULL INPUT RETURNS text AS $$ (module ...) $$
+```
+
+
+## CQL Type Mapping
+
+### Native types
+
+| CQL Type  | Rust type                     |
+| --------- | ----------------------------- |
+| ASCII     | String                        |
+| BIGINT    | i64                           |
+| BLOB      | Vec\<u8\>                     |
+| BOOLEAN   | bool                          |
+| COUNTER   | scylla_bindgen::Counter       |
+| DATE      | chrono::NaiveDate             |
+| DECIMAL   | bigdecimal::Decimal           |
+| DOUBLE    | f64                           |
+| DURATION  | scylla_bindgen::CqlDuration   |
+| FLOAT     | f32                           |
+| INET      | std::net::IpAddr              |
+| INT       | i32                           |
+| SMALLINT  | i16                           |
+| TEXT      | String                        |
+| TIME      | scylla_bindgen::Time          |
+| TIMESTAMP | scylla_bindgen::Timestamp     |
+| TIMEUUID  | uuid::Uuid                    |
+| TINYINT   | i8                            |
+| UUID      | uuid::Uuid                    |
+| VARCHAR   | String                        |
+| VARINT    | num_bigint::BigInt            |
+
+### Collections
+
+If a CQL type `T` maps to Rust type `RustT`, you can use it as a collection parameter:
+
+| CQL Type   | Rust type                                                               |
+| ---------- | ----------------------------------------------------------------------- |
+| LIST\<T\>  | Vec\<RustT\>                                                            |
+| MAP\<T\>   | std::collections::BTreeMap\<RustT\>, std::collections::HashMap\<RustT\> |
+| SET\<T\>   | std::collections::BTreeSet\<RustT\>, std::collections::HashSet\<RustT\> |
+
+
+### Tuples
+
+If CQL types `T1`, `T2`, ... map to Rust types `RustT1`, `RustT2`, ..., you can use them in tuples:
+
+| CQL Type | Rust type                          |
+| -------- | ---------------------------------- |
+| TUPLE\<T1, T2, ...\>  | (RustT1, RustT2, ...) |
+
+### Nulls
+
+If a CQL Value of type T, that's mapped to type RustT, may be a null (possible in non-`RETURNS NULL ON NULL INPUT` UDFs),
+the type used in the Rust function should be Option\<RustT\>.

examples/Cargo.toml

@@ -0,0 +1,65 @@
+[package]
+name = "examples"
+edition.workspace = true
+version.workspace = true
+repository.workspace = true
+license.workspace = true
+rust-version.workspace = true
+publish = false
+
+[dependencies]
+chrono = "0.4"
+bigdecimal = "0.2.0"
+num-bigint = "0.3"
+scylla-bindgen = { workspace = true }
+uuid = "1.0"
+
+[[example]]
+name = "add"
+path = "add.rs"
+crate-type = ["cdylib"]
+
+[[example]]
+name = "combine"
+path = "combine.rs"
+crate-type = ["cdylib"]
+
+[[example]]
+name = "commas"
+path = "commas.rs"
+crate-type = ["cdylib"]
+
+[[example]]
+name = "dbl"
+path = "dbl.rs"
+crate-type = ["cdylib"]
+
+[[example]]
+name = "fib"
+path = "fib.rs"
+crate-type = ["cdylib"]
+
+[[example]]
+name = "keys"
+path = "keys.rs"
+crate-type = ["cdylib"]
+
+[[example]]
+name = "len"
+path = "len.rs"
+crate-type = ["cdylib"]
+
+[[example]]
+name = "topn"
+path = "topn.rs"
+crate-type = ["cdylib"]
+
+[[example]]
+name = "udt"
+path = "udt.rs"
+crate-type = ["cdylib"]
+
+[[example]]
+name = "wordcount"
+path = "wordcount.rs"
+crate-type = ["cdylib"]

examples/add.rs

@@ -0,0 +1,8 @@
+use scylla_bindgen::export_udf;
+
+type SmallInt = i16;
+
+#[export_udf]
+fn add(i1: SmallInt, i2: SmallInt) -> SmallInt {
+    i1 + i2
+}

examples/combine.rs

@@ -0,0 +1,52 @@
+use scylla_bindgen::{export_udf, Counter, CqlDuration, Time, Timestamp};
+
+#[allow(clippy::too_many_arguments, clippy::type_complexity)]
+#[export_udf]
+fn combine(
+    b: bool,
+    blob: Vec<u8>,
+    cnt: Counter,
+    date: chrono::NaiveDate,
+    bd: bigdecimal::BigDecimal,
+    dbl: f64,
+    cqldur: CqlDuration,
+    flt: f32,
+    int32: i32,
+    int64: i64,
+    s: String,
+    tstamp: Timestamp,
+    ip: std::net::IpAddr,
+    int16: i16,
+    int8: i8,
+    tim: Time,
+    uid: uuid::Uuid,
+    bi: num_bigint::BigInt,
+) -> (
+    (
+        bool,
+        Vec<u8>,
+        Counter,
+        chrono::NaiveDate,
+        bigdecimal::BigDecimal,
+        f64,
+        CqlDuration,
+        f32,
+        i32,
+        i64,
+    ),
+    (
+        String,
+        Timestamp,
+        std::net::IpAddr,
+        i16,
+        i8,
+        Time,
+        uuid::Uuid,
+        num_bigint::BigInt,
+    ),
+) {
+    (
+        (b, blob, cnt, date, bd, dbl, cqldur, flt, int32, int64),
+        (s, tstamp, ip, int16, int8, tim, uid, bi),
+    )
+}

examples/commas.rs

@@ -0,0 +1,6 @@
+use scylla_bindgen::export_udf;
+
+#[export_udf]
+fn commas(strings: Option<Vec<String>>) -> Option<String> {
+    strings.map(|strings| strings.join(", "))
+}

examples/dbl.rs

@@ -0,0 +1,9 @@
+use scylla_bindgen::export_udf;
+
+#[export_udf]
+fn dbl(s: String) -> String {
+    let mut newstr = String::new();
+    newstr.push_str(&s);
+    newstr.push_str(&s);
+    newstr
+}

examples/fib.rs

@@ -0,0 +1,16 @@
+use scylla_bindgen::*;
+
+#[export_newtype]
+struct FibInputNumber(i32);
+
+#[export_newtype]
+struct FibReturnNumber(i64);
+
+#[export_udf]
+fn fib(i: FibInputNumber) -> FibReturnNumber {
+    FibReturnNumber(if i.0 <= 2 {
+        1
+    } else {
+        fib(FibInputNumber(i.0 - 1)).0 + fib(FibInputNumber(i.0 - 2)).0
+    })
+}

examples/keys.rs

@@ -0,0 +1,6 @@
+use scylla_bindgen::export_udf;
+
+#[export_udf]
+fn keys(map: std::collections::BTreeMap<String, String>) -> Vec<String> {
+    map.into_keys().collect()
+}

examples/len.rs

@@ -0,0 +1,6 @@
+use scylla_bindgen::export_udf;
+
+#[export_udf]
+fn len(strings: std::collections::BTreeSet<String>) -> i16 {
+    strings.len() as i16
+}

examples/topn.rs

@@ -0,0 +1,54 @@
+use scylla_bindgen::*;
+use std::collections::BTreeSet;
+
+#[export_newtype]
+struct StringLen(String);
+
+impl std::cmp::PartialEq for StringLen {
+    fn eq(&self, other: &Self) -> bool {
+        self.0.len() == other.0.len()
+    }
+}
+
+impl std::cmp::Eq for StringLen {}
+
+impl std::cmp::PartialOrd for StringLen {
+    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
+        Some(self.0.len().cmp(&other.0.len()))
+    }
+}
+
+impl std::cmp::Ord for StringLen {
+    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
+        self.0.len().cmp(&other.0.len())
+    }
+}
+
+// Store the top N strings by length, without repetitions.
+#[export_udf]
+fn topn_row((n, mut acc): (i32, BTreeSet<StringLen>), v: StringLen) -> (i32, BTreeSet<StringLen>) {
+    acc.insert(v);
+    while acc.len() > n as usize {
+        acc.pop_first();
+    }
+
+    (n, acc)
+}
+
+#[export_udf]
+fn topn_reduce(
+    (n1, mut acc1): (i32, BTreeSet<StringLen>),
+    (n2, mut acc2): (i32, BTreeSet<StringLen>),
+) -> (i32, BTreeSet<StringLen>) {
+    assert!(n1 == n2);
+    acc1.append(&mut acc2);
+    while acc1.len() > n1 as usize {
+        acc1.pop_first();
+    }
+    (n1, acc1)
+}
+
+#[export_udf]
+fn topn_final((_, acc): (i32, BTreeSet<StringLen>)) -> BTreeSet<StringLen> {
+    acc
+}

examples/udt.rs

@@ -0,0 +1,19 @@
+use scylla_bindgen::*;
+
+#[export_udt]
+struct Udt {
+    a: i32,
+    b: i32,
+    c: String,
+    d: String,
+}
+
+#[export_udf]
+fn udt(arg: Udt) -> Udt {
+    Udt {
+        a: arg.b,
+        b: arg.a,
+        c: arg.d,
+        d: arg.c,
+    }
+}

examples/wordcount.rs

@@ -0,0 +1,6 @@
+use scylla_bindgen::export_udf;
+
+#[export_udf]
+fn wordcount(text: String) -> i32 {
+    text.split(' ').count() as i32
+}