Experimental capabilities in the Rust SDK (#1197)

src/content/doc-sdk-rust/methods/new.mdx

@@ -35,6 +35,8 @@ Surreal::new::<T>(address)
 
 ### Example usage
 
+#### Basic example
+
 ```rust
 use surrealdb::engine::remote::ws::Ws;
 use surrealdb::Surreal;
@@ -46,6 +48,29 @@ async fn main() -> surrealdb::Result<()> {
 }
 ```
 
+#### Configuring the database
+
+The `new()` function takes an argument of [`impl IntoEndpoint`](https://docs.rs/surrealdb/latest/surrealdb/opt/trait.IntoEndpoint.html#foreign-impls), which is implemented not only for strings and string-like structs like [`PathBuf`](https://doc.rust-lang.org/std/path/struct.PathBuf.html) and [`SocketAddr`](https://doc.rust-lang.org/std/net/enum.SocketAddr.html), but also a tuple of one of these types for the address along with a second [`Config`](https://docs.rs/surrealdb/latest/surrealdb/opt/struct.Config.html) struct for the configuration.
+
+```rust title="Example with all capabilities enabled except one function"
+#[tokio::main]
+async fn main() -> Result<(), Error> {
+    let config = Config::default()
+        .capabilities(Capabilities::all().with_deny_function("math::abs")?);
+    let db = connect(("mem://", config)).await?;
+
+    db.use_ns("ns").use_db("db").await?;
+
+    // Result: Err(Db(FunctionNotAllowed("math::abs")))
+    println!("{:?}", db.query("math::abs(-10)").await?);
+    println!("{:?}", db.run::<i32>("math::abs").args(-10).await);
+
+    Ok(())
+}
+```
+
+#### Using SurrealKV with versioning
+
 To make a new connection that includes SurrealKV versioning, add the "surreal-kv" feature flag to the `surrealdb` dependency in `Cargo.toml`, add the path to the folder containing the database inside `new()`, and call the `.versioned()` method.
 
 ```rust

src/content/doc-sdk-rust/setup.mdx

@@ -310,3 +310,43 @@ Here is the last query in the example above to get started:
 ```surql
 SELECT marketing, count() FROM person GROUP BY marketing;
 ```
+
+### Using capabilities and experimental capabilities
+
+The Rust SDK has a single [`Capabilities`](https://docs.rs/surrealdb/latest/surrealdb/opt/capabilities/struct.Capabilities.html) struct that is used to allow or limit what users are allowed to do using queries. Each method on this struct is used to configure the capabilities for the database in the same way that [capabilities flags](/docs/surrealdb/security/capabilities#list) are passed in to the [`surreal start`](/docs/surrealdb/cli/start) command.
+
+```bash
+surreal start --allow-all --deny-funcs "http"
+surreal sql --ns ns --db db
+```
+
+```rust
+#[tokio::main]
+async fn main() -> Result<(), Error> {
+    let config = Config::default().capabilities(Capabilities::all().with_deny_function("http")?);
+    let db = connect(("mem://", config)).await?;
+
+    db.use_ns("ns").use_db("db").await?;
+
+    println!("{:?}", db.query("http::get('http://www.surrealdb.com')").await);
+
+    Ok(())
+}
+```
+
+SurrealDB also has a number of experimental capabilities which need to be specifically opted into and are not included inside an `--allow-all` flag or struct created by the `Capabilities::all()` function. These can be passed in individually using a slice of the [`ExperimentalFeature`](https://docs.rs/surrealdb/latest/surrealdb/opt/capabilities/enum.ExperimentalFeature.html) enum inside the [`.with_experimental_features_allowed`](https://docs.rs/surrealdb/latest/surrealdb/opt/capabilities/struct.Capabilities.html#method.with_experimental_features_allowed) method, or all at once with [`.with_all_experimental_features_allowed()`](https://docs.rs/surrealdb/latest/surrealdb/opt/capabilities/struct.Capabilities.html#method.with_all_experimental_features_allowed).
+
+```rust
+#[tokio::main]
+async fn main() -> Result<(), Error> {
+
+    let config = Config::default().capabilities(Capabilities::all().with_all_experimental_features_allowed());
+    let db = connect(("mem://", config)).await?;
+
+    db.use_ns("ns").use_db("db").await?;
+
+    println!("{:?}", db.query("DEFINE FIELD comics ON person TYPE option<array<record<comic_book>>> REFERENCE"));
+
+    Ok(())
+}
+```