Skip to main content

arcadedb_protocol/client/
mod.rs

1//! ArcadeDB gRPC client — wraps the generated tonic service stubs.
2//!
3//! The server-side `GrpcAuthInterceptor` checks gRPC metadata headers
4//! (`x-arcade-user`, `x-arcade-password`, `x-arcade-database`) for DATA service
5//! calls, so each data request attaches these headers via `add_auth_headers`.
6//! Admin service calls are skipped by the interceptor and use body credentials.
7
8use std::ops::ControlFlow;
9use std::ops::Deref;
10use std::slice::Iter;
11use std::time::Duration;
12use std::vec::IntoIter;
13
14use tokio_stream::{Stream, StreamExt};
15use tonic::metadata::MetadataValue;
16use tonic::transport::Channel;
17
18use crate::error::{ArcadeDbError, Result};
19use crate::options::ClientOptions;
20
21// This file wraps the entire gRPC surface, so take the proto module as a
22// whole instead of maintaining a hand-curated list. Local definitions (e.g.
23// the owned `QueryResult` below) shadow their glob-imported names; nested
24// modules (`insert_options::ConflictMode`, `update_record_request::Payload`,
25// the service clients) resolve through the same glob.
26pub use crate::proto::com::arcadedb::grpc::*;
27use crate::proto::com::arcadedb::grpc::{
28    arcade_db_admin_service_client::ArcadeDbAdminServiceClient,
29    arcade_db_service_client::ArcadeDbServiceClient, insert_options::ConflictMode,
30    update_record_request::Payload,
31};
32use crate::record::RecordDecodeError;
33
34// Capability groups — one file per method family. `ArcadeDbClient` method
35// blocks live with their group; shared helpers and the connect/auth core
36// stay here. Each file opens with `use super::*;` and inherits this
37// module's imports.
38mod database;
39mod execute;
40mod query;
41mod records;
42mod results;
43mod streaming;
44mod transaction;
45
46// Re-exported for `crate::client::` users (facades) and the crate root.
47pub use database::DatabaseClient;
48pub use results::{QueryResult, QueryResultBatch, StreamSummary};
49pub use streaming::consume_stream;
50pub use transaction::{Transaction, TxCommands};
51
52/// Surface a gRPC RPC failure as an [`ArcadeDbError`] that includes the
53/// ArcadeDB server's own message (tonic carries it in the `Status`). Without
54/// this, a bare `.context("query failed")?` hides why ArcadeDB rejected the
55/// request — e.g. "Index 'item[title]' was not found" — making debugging
56/// near-impossible. Unlike stringifying, the typed variant keeps the tonic
57/// [`tonic::Code`] and metadata inspectable via [`ArcadeDbError::code`].
58///
59/// The engine's "already exists" rejection is normalized here to the
60/// dedicated [`ArcadeDbError::AlreadyExists`] variant: ArcadeDB reports it
61/// only through the error message (or, when it does set a code, gRPC's
62/// `AlreadyExists`), never a structured field, so the client detects it once
63/// at this single funnel every RPC failure passes through.
64pub(crate) fn map_rpc_error(what: &str, detail: &str, err: tonic::Status) -> ArcadeDbError {
65    let message = err.message();
66    if err.code() == tonic::Code::AlreadyExists
67        || message.to_ascii_lowercase().contains("already exist")
68    {
69        return ArcadeDbError::AlreadyExists {
70            what: what.into(),
71            message: message.into(),
72        };
73    }
74    ArcadeDbError::Rpc {
75        operation: what.into(),
76        detail: detail.into(),
77        status: err,
78    }
79}
80
81/// Construct the `success = false` error for an `ExecuteCommand` response,
82/// applying the same "already exists" normalization as [`map_rpc_error`] so
83/// both transport failures and rejected commands surface the same variant.
84fn command_failed(operation: &str, message: String, affected: i64) -> ArcadeDbError {
85    if message.to_ascii_lowercase().contains("already exist") {
86        return ArcadeDbError::AlreadyExists {
87            what: operation.into(),
88            message,
89        };
90    }
91    ArcadeDbError::CommandFailed {
92        operation: operation.into(),
93        message,
94        affected: Some(affected),
95    }
96}
97
98/// Auth state resolved ONCE at connect: metadata headers are re-attached to
99/// every DATA request and the credentials template re-cloned into every
100/// request body — pre-parsing the header values and caching the template
101/// removes the per-RPC string parses/allocations.
102struct AuthState {
103    user_val: MetadataValue<tonic::metadata::Ascii>,
104    pass_val: MetadataValue<tonic::metadata::Ascii>,
105    db_val: MetadataValue<tonic::metadata::Ascii>,
106    /// Database name (also surfaced via [`ArcadeDbClient::database`]).
107    database: String,
108    /// Body-credential template for ADMIN/body-credential requests (prost
109    /// needs owned `String`s per message, so a struct clone is the floor).
110    creds: DatabaseCredentials,
111    /// Default per-request gRPC deadline (from
112    /// [`ClientOptions::request_timeout`](crate::ClientOptions::
113    /// request_timeout)); applied by [`ArcadeDbClient::add_auth_headers`].
114    request_timeout: Option<Duration>,
115}
116
117/// A lightweight gRPC client for ArcadeDB.
118///
119/// Wraps both the data and admin service clients with convenience methods
120/// for SQL commands and queries. `Clone` (cheap — shares the underlying
121/// tonic `Channel`) and all methods take `&self`, so it can be held by a
122/// `Clone` repo and shared across tasks.
123#[derive(Clone)]
124pub struct ArcadeDbClient {
125    data: ArcadeDbServiceClient<Channel>,
126    admin: ArcadeDbAdminServiceClient<Channel>,
127    auth: std::sync::Arc<AuthState>,
128}
129
130impl ArcadeDbClient {
131    /// Connect to an ArcadeDB server over gRPC.
132    ///
133    /// `addr` should be `host:port` (e.g. `127.0.0.1:50051`).
134    /// Uses an insecure (plaintext) channel — the standard for dev setups.
135    /// For TLS, deadlines, or a configurable connect/retry policy, build a
136    /// [`ClientOptions`] and call [`connect_with`](Self::connect_with).
137    ///
138    /// The `database` parameter is used for the `x-arcade-database` metadata header,
139    /// which the server-side `GrpcAuthInterceptor` checks to determine which
140    /// database's user list to validate against.
141    pub async fn connect(addr: &str, user: &str, pass: &str, database: &str) -> Result<Self> {
142        Self::connect_with(ClientOptions::new(addr, user, pass, database)).await
143    }
144
145    /// [`connect`](Self::connect) with explicit
146    /// [`ClientOptions`]: TLS, connect timeout/attempts/backoff, and the
147    /// default per-request gRPC deadline.
148    ///
149    /// Credential validation is up front and typed: metadata-invalid
150    /// credentials (e.g. non-ASCII) are an [`ArcadeDbError::InvalidInput`],
151    /// never a panic.
152    pub async fn connect_with(options: ClientOptions) -> Result<Self> {
153        options.validate()?;
154        let addr = options.addr.clone();
155
156        // Parse the endpoint URI once — the retry loop below does not
157        // rebuild (and re-parse) it per attempt.
158        let scheme = if options.tls.is_some() {
159            "https"
160        } else {
161            "http"
162        };
163        let mut endpoint = Channel::from_shared(format!("{scheme}://{addr}")).map_err(|e| {
164            ArcadeDbError::InvalidEndpoint {
165                addr: addr.clone(),
166                source: e,
167            }
168        })?;
169        if let Some(timeout) = options.connect_timeout {
170            endpoint = endpoint.connect_timeout(timeout);
171        }
172        if let Some(tls) = options.tls {
173            endpoint = endpoint
174                .tls_config(tls)
175                .map_err(|e| ArcadeDbError::InvalidInput {
176                    message: format!("ClientOptions: TLS config rejected by the transport: {e}"),
177                })?;
178        }
179
180        // Retry the TCP connect so a cold container (JVM still warming up) is
181        // waited for instead of failing the caller immediately.
182        let attempts = options.connect_attempts;
183        let backoff = options.connect_backoff;
184        let channel = {
185            let mut last_err: Option<tonic::transport::Error> = None;
186            let mut ch: Option<Channel> = None;
187            for attempt in 0..attempts {
188                match endpoint.clone().connect().await {
189                    Ok(c) => {
190                        ch = Some(c);
191                        break;
192                    }
193                    Err(e) => {
194                        tracing::debug!(attempt, %addr, "arcade connect retry: {e}");
195                        last_err = Some(e);
196                        tokio::time::sleep(backoff).await;
197                    }
198                }
199            }
200            ch.ok_or_else(|| ArcadeDbError::Connect {
201                addr: addr.clone(),
202                attempts,
203                source: last_err,
204            })?
205        };
206
207        tracing::info!(%addr, "connected to ArcadeDB gRPC");
208
209        // open_or_create (J7): create the database if absent, tolerating the
210        // create race between concurrent bootstrappers.
211        if options.open_or_create {
212            let mut admin = ArcadeDbAdminServiceClient::new(channel.clone());
213            let creds = DatabaseCredentials {
214                username: options.user.clone(),
215                password: options.pass.clone(),
216            };
217            let exists = admin
218                .clone()
219                .exists_database(ExistsDatabaseRequest {
220                    credentials: Some(creds.clone()),
221                    name: options.database.clone(),
222                })
223                .await
224                .map_err(|e| {
225                    map_rpc_error("exists database (open_or_create)", &options.database, e)
226                })?
227                .into_inner()
228                .exists;
229            if !exists {
230                match admin
231                    .create_database(CreateDatabaseRequest {
232                        credentials: Some(creds),
233                        name: options.database.clone(),
234                        r#type: "graph".into(),
235                    })
236                    .await
237                {
238                    Ok(_) => {
239                        tracing::info!(db = %options.database, "database created (open_or_create)")
240                    }
241                    // Normalized by the map_rpc_error funnel — tolerate the
242                    // concurrent-create race.
243                    Err(e) => {
244                        let e =
245                            map_rpc_error("create database (open_or_create)", &options.database, e);
246                        if !matches!(e, ArcadeDbError::AlreadyExists { .. }) {
247                            return Err(e);
248                        }
249                    }
250                }
251            }
252        }
253
254        let parse_meta = |value: &str,
255                          what: &str|
256         -> Result<MetadataValue<tonic::metadata::Ascii>> {
257            value.parse().map_err(|_| ArcadeDbError::InvalidInput {
258                message: format!(
259                    "ClientOptions: {what} contains characters invalid in a gRPC metadata value (visible ASCII only)"
260                ),
261            })
262        };
263
264        Ok(Self {
265            data: ArcadeDbServiceClient::new(channel.clone()),
266            admin: ArcadeDbAdminServiceClient::new(channel),
267            auth: std::sync::Arc::new(AuthState {
268                user_val: parse_meta(&options.user, "user")?,
269                pass_val: parse_meta(&options.pass, "password")?,
270                db_val: parse_meta(&options.database, "database")?,
271                database: options.database.clone(),
272                creds: DatabaseCredentials {
273                    username: options.user,
274                    password: options.pass,
275                },
276                request_timeout: options.request_timeout,
277            }),
278        })
279    }
280
281    /// The database name this client is authenticated against.
282    pub fn database(&self) -> &str {
283        &self.auth.database
284    }
285
286    /// Attach ArcadeDB auth metadata headers (and the default request
287    /// deadline, when configured) to a gRPC request.
288    ///
289    /// The server-side `GrpcAuthInterceptor` reads credentials from metadata
290    /// headers (`x-arcade-user`, `x-arcade-password`, `x-arcade-database`)
291    /// for DATA service calls. Admin service is skipped by the interceptor
292    /// and uses body credentials directly.
293    pub(crate) fn add_auth_headers<T>(&self, mut req: tonic::Request<T>) -> tonic::Request<T> {
294        let auth = &self.auth;
295        req.metadata_mut()
296            .insert("x-arcade-user", auth.user_val.clone());
297        req.metadata_mut()
298            .insert("x-arcade-password", auth.pass_val.clone());
299        req.metadata_mut()
300            .insert("x-arcade-database", auth.db_val.clone());
301        if let Some(timeout) = auth.request_timeout {
302            req.set_timeout(timeout);
303        }
304
305        req
306    }
307
308    /// The admin-service stub — for the [`admin`](crate::admin) facade.
309    pub(crate) fn admin_stub(&self) -> ArcadeDbAdminServiceClient<Channel> {
310        self.admin.clone()
311    }
312
313    /// The body-credential template — for the [`admin`](crate::admin) facade.
314    pub(crate) fn creds(&self) -> DatabaseCredentials {
315        self.auth.creds.clone()
316    }
317
318    /// Domain facades ([`admin`](crate::admin) / [`scan`](crate::scan) /
319    /// [`batch`](crate::batch) / [`cache`](crate::cache)) — capability
320    /// groups off the root client. Cheap: each wraps a clone of this
321    /// client's shared channel.
322    pub fn admin(&self) -> crate::admin::Admin {
323        crate::admin::Admin::new(self.clone())
324    }
325
326    /// [`scan`](crate::scan) facade — full-type/bucket iteration.
327    pub fn scan(&self) -> crate::scan::Scan {
328        crate::scan::Scan::new(self.clone())
329    }
330
331    /// [`batch`](crate::batch) facade — `sqlscript` batches, edge upserts,
332    /// idempotent DDL apply.
333    pub fn batch(&self) -> crate::batch::Batch {
334        crate::batch::Batch::new(self.clone())
335    }
336
337    /// [`cache`](crate::cache) facade (`cache` feature) — transient KV over
338    /// the Redis plugin: GET/SET/GETDEL with hex-safe values and a
339    /// client-enforced TTL.
340    #[cfg(feature = "cache")]
341    pub fn cache(&self) -> crate::cache::Cache {
342        crate::cache::Cache::new(self.clone())
343    }
344}
345
346/// Property/type names interpolated into generated SQL (lookup_by_key,
347/// count_type, scan, batch) must be plain identifiers — anything else is a
348/// client-side [`ArcadeDbError::InvalidInput`], never a quoting game.
349pub(crate) fn validate_identifier(name: &str, what: &str) -> Result<String> {
350    if !name.is_empty() && name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_') {
351        Ok(name.to_string())
352    } else {
353        Err(ArcadeDbError::InvalidInput {
354            message: format!(
355                "invalid {what} `{name}`: expected non-empty ASCII letters, digits, or `_`"
356            ),
357        })
358    }
359}
360
361#[cfg(test)]
362mod tests {
363    use super::*;
364    use super::{query::single_column_value, transaction::is_retryable_conflict};
365
366    #[test]
367    fn already_exists_rejections_normalize_to_the_dedicated_variant() {
368        // By message (the engine's actual shape today — no structured code):
369        // both the "already exists" and "already existing" spellings.
370        for msg in [
371            "Database 'oak' already exists",
372            "Type 'item' already existing in database",
373        ] {
374            let err = map_rpc_error("create database", "oak", tonic::Status::internal(msg));
375            assert!(
376                matches!(err, ArcadeDbError::AlreadyExists { .. }),
377                "message {msg:?} should normalize"
378            );
379            assert_eq!(err.server_message(), Some(msg));
380        }
381
382        // By gRPC code, when the server does set it.
383        let err = map_rpc_error(
384            "create database",
385            "oak",
386            tonic::Status::already_exists("Database 'oak' already exists"),
387        );
388        assert!(matches!(err, ArcadeDbError::AlreadyExists { .. }));
389
390        // Everything else stays a plain Rpc error.
391        let err = map_rpc_error("query", "SELECT 1", tonic::Status::unavailable("boom"));
392        assert!(matches!(err, ArcadeDbError::Rpc { .. }));
393
394        // And the success=false path normalizes identically.
395        let err = command_failed(
396            "execute command",
397            "Error: Type 'item' already exists".into(),
398            0,
399        );
400        assert!(matches!(err, ArcadeDbError::AlreadyExists { .. }));
401        let err = command_failed("execute command", "syntax error".into(), 0);
402        assert!(matches!(err, ArcadeDbError::CommandFailed { .. }));
403    }
404
405    #[test]
406    fn identifier_validation_accepts_only_plain_names() {
407        assert_eq!(validate_identifier("item", "type name").unwrap(), "item");
408        assert_eq!(
409            validate_identifier("user_shelf_v2", "type name").unwrap(),
410            "user_shelf_v2"
411        );
412        for bad in [
413            "",
414            "item; DROP",
415            "has space",
416            "has-dash",
417            "schema:types",
418            "a.b",
419        ] {
420            assert!(
421                validate_identifier(bad, "type name").is_err(),
422                "`{bad}` must be rejected"
423            );
424        }
425    }
426
427    #[test]
428    fn mvcc_conflicts_are_detected_from_the_server_message() {
429        for msg in [
430            "The record was changed by concurrent transaction",
431            "MVCC conflict on update",
432            "NeedRetryException: please retry the transaction",
433        ] {
434            let err = map_rpc_error("commit transaction", "", tonic::Status::aborted(msg));
435            assert!(is_retryable_conflict(&err), "`{msg}` must be retryable");
436        }
437        let err = map_rpc_error("query", "", tonic::Status::internal("syntax error"));
438        assert!(!is_retryable_conflict(&err));
439        // A plain Rpc error without a message-ish content is not retryable.
440        let err = ArcadeDbError::NotFound {
441            operation: "x".into(),
442            detail: "y".into(),
443        };
444        assert!(!is_retryable_conflict(&err));
445    }
446
447    #[test]
448    fn one_row_accessors_decode_or_report_not_found() {
449        let row = crate::rec("t", vec![("name", crate::encode::str_v("oak"))]);
450
451        let empty = QueryResult {
452            records: vec![],
453            execution_time_ms: 0,
454        };
455        assert!(empty.first::<ItemRow>().unwrap().is_none());
456        assert!(matches!(
457            empty.one::<ItemRow>(),
458            Err(ArcadeDbError::NotFound { .. })
459        ));
460
461        let single = QueryResult {
462            records: vec![row],
463            execution_time_ms: 0,
464        };
465        let row = single.first::<ItemRow>().unwrap().unwrap();
466        assert_eq!(row.name, "oak");
467        assert_eq!(single.one::<ItemRow>().unwrap().name, "oak");
468
469        // Multi-column rows are rejected for scalars — map order is not
470        // "first column" order.
471        let wide = crate::rec(
472            "t",
473            vec![
474                ("a", crate::encode::str_v("1")),
475                ("b", crate::encode::str_v("2")),
476            ],
477        );
478        assert!(single_column_value(&wide, "SELECT a, b FROM t").is_err());
479        let lone = crate::rec("t", vec![("count", crate::encode::i64_v(7))]);
480        let scalar = single_column_value(&lone, "SELECT count(*) AS count FROM t")
481            .unwrap()
482            .clone();
483        assert!(matches!(scalar.kind, Some(grpc_value::Kind::Int64Value(7))));
484    }
485
486    #[derive(Clone)]
487    struct ItemRow {
488        name: String,
489    }
490
491    impl<'a> TryFrom<&'a GrpcRecord> for ItemRow {
492        type Error = RecordDecodeError;
493
494        fn try_from(rec: &'a GrpcRecord) -> Result<Self, Self::Error> {
495            let name = rec
496                .properties
497                .get("name")
498                .ok_or_else(|| RecordDecodeError::missing_field("name"))?;
499            let Some(grpc_value::Kind::StringValue(s)) = &name.kind else {
500                return Err(RecordDecodeError::conversion("name: expected string"));
501            };
502            Ok(ItemRow { name: s.clone() })
503        }
504    }
505}