arcadedb-protocol 0.4.0

A lightweight gRPC client for ArcadeDB: tonic stubs, a typed record-decode path (RecordDecode derive), and a serde_json bridge.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
//! ArcadeDB gRPC client — wraps the generated tonic service stubs.
//!
//! The server-side `GrpcAuthInterceptor` checks gRPC metadata headers
//! (`x-arcade-user`, `x-arcade-password`, `x-arcade-database`) for DATA service
//! calls, so each data request attaches these headers via `add_auth_headers`.
//! Admin service calls are skipped by the interceptor and use body credentials.

use std::ops::ControlFlow;
use std::ops::Deref;
use std::slice::Iter;
use std::time::Duration;
use std::vec::IntoIter;

use tokio_stream::{Stream, StreamExt};
use tonic::metadata::MetadataValue;
use tonic::transport::Channel;

use crate::error::{ArcadeDbError, Result};
use crate::options::ClientOptions;

// This file wraps the entire gRPC surface, so take the proto module as a
// whole instead of maintaining a hand-curated list. Local definitions (e.g.
// the owned `QueryResult` below) shadow their glob-imported names; nested
// modules (`insert_options::ConflictMode`, `update_record_request::Payload`,
// the service clients) resolve through the same glob.
pub use crate::proto::com::arcadedb::grpc::*;
use crate::proto::com::arcadedb::grpc::{
    arcade_db_admin_service_client::ArcadeDbAdminServiceClient,
    arcade_db_service_client::ArcadeDbServiceClient, insert_options::ConflictMode,
    update_record_request::Payload,
};
use crate::record::RecordDecodeError;

// Capability groups — one file per method family. `ArcadeDbClient` method
// blocks live with their group; shared helpers and the connect/auth core
// stay here. Each file opens with `use super::*;` and inherits this
// module's imports.
mod database;
mod execute;
mod query;
mod records;
mod results;
mod streaming;
mod transaction;

// Re-exported for `crate::client::` users (facades) and the crate root.
pub use database::DatabaseClient;
pub use results::{QueryResult, QueryResultBatch, StreamSummary};
pub use streaming::consume_stream;
pub use transaction::{Transaction, TxCommands};

/// Surface a gRPC RPC failure as an [`ArcadeDbError`] that includes the
/// ArcadeDB server's own message (tonic carries it in the `Status`). Without
/// this, a bare `.context("query failed")?` hides why ArcadeDB rejected the
/// request — e.g. "Index 'item[title]' was not found" — making debugging
/// near-impossible. Unlike stringifying, the typed variant keeps the tonic
/// [`tonic::Code`] and metadata inspectable via [`ArcadeDbError::code`].
///
/// The engine's "already exists" rejection is normalized here to the
/// dedicated [`ArcadeDbError::AlreadyExists`] variant: ArcadeDB reports it
/// only through the error message (or, when it does set a code, gRPC's
/// `AlreadyExists`), never a structured field, so the client detects it once
/// at this single funnel every RPC failure passes through.
pub(crate) fn map_rpc_error(what: &str, detail: &str, err: tonic::Status) -> ArcadeDbError {
    let message = err.message();
    if err.code() == tonic::Code::AlreadyExists
        || message.to_ascii_lowercase().contains("already exist")
    {
        return ArcadeDbError::AlreadyExists {
            what: what.into(),
            message: message.into(),
        };
    }
    ArcadeDbError::Rpc {
        operation: what.into(),
        detail: detail.into(),
        status: err,
    }
}

/// Construct the `success = false` error for an `ExecuteCommand` response,
/// applying the same "already exists" normalization as [`map_rpc_error`] so
/// both transport failures and rejected commands surface the same variant.
fn command_failed(operation: &str, message: String, affected: i64) -> ArcadeDbError {
    if message.to_ascii_lowercase().contains("already exist") {
        return ArcadeDbError::AlreadyExists {
            what: operation.into(),
            message,
        };
    }
    ArcadeDbError::CommandFailed {
        operation: operation.into(),
        message,
        affected: Some(affected),
    }
}

/// Auth state resolved ONCE at connect: metadata headers are re-attached to
/// every DATA request and the credentials template re-cloned into every
/// request body — pre-parsing the header values and caching the template
/// removes the per-RPC string parses/allocations.
struct AuthState {
    user_val: MetadataValue<tonic::metadata::Ascii>,
    pass_val: MetadataValue<tonic::metadata::Ascii>,
    db_val: MetadataValue<tonic::metadata::Ascii>,
    /// Database name (also surfaced via [`ArcadeDbClient::database`]).
    database: String,
    /// Body-credential template for ADMIN/body-credential requests (prost
    /// needs owned `String`s per message, so a struct clone is the floor).
    creds: DatabaseCredentials,
    /// Default per-request gRPC deadline (from
    /// [`ClientOptions::request_timeout`](crate::ClientOptions::
    /// request_timeout)); applied by [`ArcadeDbClient::add_auth_headers`].
    request_timeout: Option<Duration>,
}

/// A lightweight gRPC client for ArcadeDB.
///
/// Wraps both the data and admin service clients with convenience methods
/// for SQL commands and queries. `Clone` (cheap — shares the underlying
/// tonic `Channel`) and all methods take `&self`, so it can be held by a
/// `Clone` repo and shared across tasks.
#[derive(Clone)]
pub struct ArcadeDbClient {
    data: ArcadeDbServiceClient<Channel>,
    admin: ArcadeDbAdminServiceClient<Channel>,
    auth: std::sync::Arc<AuthState>,
}

impl ArcadeDbClient {
    /// Connect to an ArcadeDB server over gRPC.
    ///
    /// `addr` should be `host:port` (e.g. `127.0.0.1:50051`).
    /// Uses an insecure (plaintext) channel — the standard for dev setups.
    /// For TLS, deadlines, or a configurable connect/retry policy, build a
    /// [`ClientOptions`] and call [`connect_with`](Self::connect_with).
    ///
    /// The `database` parameter is used for the `x-arcade-database` metadata header,
    /// which the server-side `GrpcAuthInterceptor` checks to determine which
    /// database's user list to validate against.
    pub async fn connect(addr: &str, user: &str, pass: &str, database: &str) -> Result<Self> {
        Self::connect_with(ClientOptions::new(addr, user, pass, database)).await
    }

    /// [`connect`](Self::connect) with explicit
    /// [`ClientOptions`]: TLS, connect timeout/attempts/backoff, and the
    /// default per-request gRPC deadline.
    ///
    /// Credential validation is up front and typed: metadata-invalid
    /// credentials (e.g. non-ASCII) are an [`ArcadeDbError::InvalidInput`],
    /// never a panic.
    pub async fn connect_with(options: ClientOptions) -> Result<Self> {
        options.validate()?;
        let addr = options.addr.clone();

        // Parse the endpoint URI once — the retry loop below does not
        // rebuild (and re-parse) it per attempt.
        let scheme = if options.tls.is_some() {
            "https"
        } else {
            "http"
        };
        let mut endpoint = Channel::from_shared(format!("{scheme}://{addr}")).map_err(|e| {
            ArcadeDbError::InvalidEndpoint {
                addr: addr.clone(),
                source: e,
            }
        })?;
        if let Some(timeout) = options.connect_timeout {
            endpoint = endpoint.connect_timeout(timeout);
        }
        if let Some(tls) = options.tls {
            endpoint = endpoint
                .tls_config(tls)
                .map_err(|e| ArcadeDbError::InvalidInput {
                    message: format!("ClientOptions: TLS config rejected by the transport: {e}"),
                })?;
        }

        // Retry the TCP connect so a cold container (JVM still warming up) is
        // waited for instead of failing the caller immediately.
        let attempts = options.connect_attempts;
        let backoff = options.connect_backoff;
        let channel = {
            let mut last_err: Option<tonic::transport::Error> = None;
            let mut ch: Option<Channel> = None;
            for attempt in 0..attempts {
                match endpoint.clone().connect().await {
                    Ok(c) => {
                        ch = Some(c);
                        break;
                    }
                    Err(e) => {
                        tracing::debug!(attempt, %addr, "arcade connect retry: {e}");
                        last_err = Some(e);
                        tokio::time::sleep(backoff).await;
                    }
                }
            }
            ch.ok_or_else(|| ArcadeDbError::Connect {
                addr: addr.clone(),
                attempts,
                source: last_err,
            })?
        };

        tracing::info!(%addr, "connected to ArcadeDB gRPC");

        // open_or_create (J7): create the database if absent, tolerating the
        // create race between concurrent bootstrappers.
        if options.open_or_create {
            let mut admin = ArcadeDbAdminServiceClient::new(channel.clone());
            let creds = DatabaseCredentials {
                username: options.user.clone(),
                password: options.pass.clone(),
            };
            let exists = admin
                .clone()
                .exists_database(ExistsDatabaseRequest {
                    credentials: Some(creds.clone()),
                    name: options.database.clone(),
                })
                .await
                .map_err(|e| {
                    map_rpc_error("exists database (open_or_create)", &options.database, e)
                })?
                .into_inner()
                .exists;
            if !exists {
                match admin
                    .create_database(CreateDatabaseRequest {
                        credentials: Some(creds),
                        name: options.database.clone(),
                        r#type: "graph".into(),
                    })
                    .await
                {
                    Ok(_) => {
                        tracing::info!(db = %options.database, "database created (open_or_create)")
                    }
                    // Normalized by the map_rpc_error funnel — tolerate the
                    // concurrent-create race.
                    Err(e) => {
                        let e =
                            map_rpc_error("create database (open_or_create)", &options.database, e);
                        if !matches!(e, ArcadeDbError::AlreadyExists { .. }) {
                            return Err(e);
                        }
                    }
                }
            }
        }

        let parse_meta = |value: &str,
                          what: &str|
         -> Result<MetadataValue<tonic::metadata::Ascii>> {
            value.parse().map_err(|_| ArcadeDbError::InvalidInput {
                message: format!(
                    "ClientOptions: {what} contains characters invalid in a gRPC metadata value (visible ASCII only)"
                ),
            })
        };

        Ok(Self {
            data: ArcadeDbServiceClient::new(channel.clone()),
            admin: ArcadeDbAdminServiceClient::new(channel),
            auth: std::sync::Arc::new(AuthState {
                user_val: parse_meta(&options.user, "user")?,
                pass_val: parse_meta(&options.pass, "password")?,
                db_val: parse_meta(&options.database, "database")?,
                database: options.database.clone(),
                creds: DatabaseCredentials {
                    username: options.user,
                    password: options.pass,
                },
                request_timeout: options.request_timeout,
            }),
        })
    }

    /// The database name this client is authenticated against.
    pub fn database(&self) -> &str {
        &self.auth.database
    }

    /// Attach ArcadeDB auth metadata headers (and the default request
    /// deadline, when configured) to a gRPC request.
    ///
    /// The server-side `GrpcAuthInterceptor` reads credentials from metadata
    /// headers (`x-arcade-user`, `x-arcade-password`, `x-arcade-database`)
    /// for DATA service calls. Admin service is skipped by the interceptor
    /// and uses body credentials directly.
    pub(crate) fn add_auth_headers<T>(&self, mut req: tonic::Request<T>) -> tonic::Request<T> {
        let auth = &self.auth;
        req.metadata_mut()
            .insert("x-arcade-user", auth.user_val.clone());
        req.metadata_mut()
            .insert("x-arcade-password", auth.pass_val.clone());
        req.metadata_mut()
            .insert("x-arcade-database", auth.db_val.clone());
        if let Some(timeout) = auth.request_timeout {
            req.set_timeout(timeout);
        }

        req
    }

    /// The admin-service stub — for the [`admin`](crate::admin) facade.
    pub(crate) fn admin_stub(&self) -> ArcadeDbAdminServiceClient<Channel> {
        self.admin.clone()
    }

    /// The body-credential template — for the [`admin`](crate::admin) facade.
    pub(crate) fn creds(&self) -> DatabaseCredentials {
        self.auth.creds.clone()
    }

    /// Domain facades ([`admin`](crate::admin) / [`scan`](crate::scan) /
    /// [`batch`](crate::batch) / [`cache`](crate::cache)) — capability
    /// groups off the root client. Cheap: each wraps a clone of this
    /// client's shared channel.
    pub fn admin(&self) -> crate::admin::Admin {
        crate::admin::Admin::new(self.clone())
    }

    /// [`scan`](crate::scan) facade — full-type/bucket iteration.
    pub fn scan(&self) -> crate::scan::Scan {
        crate::scan::Scan::new(self.clone())
    }

    /// [`batch`](crate::batch) facade — `sqlscript` batches, edge upserts,
    /// idempotent DDL apply.
    pub fn batch(&self) -> crate::batch::Batch {
        crate::batch::Batch::new(self.clone())
    }

    /// [`cache`](crate::cache) facade (`cache` feature) — transient KV over
    /// the Redis plugin: GET/SET/GETDEL with hex-safe values and a
    /// client-enforced TTL.
    #[cfg(feature = "cache")]
    pub fn cache(&self) -> crate::cache::Cache {
        crate::cache::Cache::new(self.clone())
    }
}

/// Property/type names interpolated into generated SQL (lookup_by_key,
/// count_type, scan, batch) must be plain identifiers — anything else is a
/// client-side [`ArcadeDbError::InvalidInput`], never a quoting game.
pub(crate) fn validate_identifier(name: &str, what: &str) -> Result<String> {
    if !name.is_empty() && name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_') {
        Ok(name.to_string())
    } else {
        Err(ArcadeDbError::InvalidInput {
            message: format!(
                "invalid {what} `{name}`: expected non-empty ASCII letters, digits, or `_`"
            ),
        })
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use super::{query::single_column_value, transaction::is_retryable_conflict};

    #[test]
    fn already_exists_rejections_normalize_to_the_dedicated_variant() {
        // By message (the engine's actual shape today — no structured code):
        // both the "already exists" and "already existing" spellings.
        for msg in [
            "Database 'oak' already exists",
            "Type 'item' already existing in database",
        ] {
            let err = map_rpc_error("create database", "oak", tonic::Status::internal(msg));
            assert!(
                matches!(err, ArcadeDbError::AlreadyExists { .. }),
                "message {msg:?} should normalize"
            );
            assert_eq!(err.server_message(), Some(msg));
        }

        // By gRPC code, when the server does set it.
        let err = map_rpc_error(
            "create database",
            "oak",
            tonic::Status::already_exists("Database 'oak' already exists"),
        );
        assert!(matches!(err, ArcadeDbError::AlreadyExists { .. }));

        // Everything else stays a plain Rpc error.
        let err = map_rpc_error("query", "SELECT 1", tonic::Status::unavailable("boom"));
        assert!(matches!(err, ArcadeDbError::Rpc { .. }));

        // And the success=false path normalizes identically.
        let err = command_failed(
            "execute command",
            "Error: Type 'item' already exists".into(),
            0,
        );
        assert!(matches!(err, ArcadeDbError::AlreadyExists { .. }));
        let err = command_failed("execute command", "syntax error".into(), 0);
        assert!(matches!(err, ArcadeDbError::CommandFailed { .. }));
    }

    #[test]
    fn identifier_validation_accepts_only_plain_names() {
        assert_eq!(validate_identifier("item", "type name").unwrap(), "item");
        assert_eq!(
            validate_identifier("user_shelf_v2", "type name").unwrap(),
            "user_shelf_v2"
        );
        for bad in [
            "",
            "item; DROP",
            "has space",
            "has-dash",
            "schema:types",
            "a.b",
        ] {
            assert!(
                validate_identifier(bad, "type name").is_err(),
                "`{bad}` must be rejected"
            );
        }
    }

    #[test]
    fn mvcc_conflicts_are_detected_from_the_server_message() {
        for msg in [
            "The record was changed by concurrent transaction",
            "MVCC conflict on update",
            "NeedRetryException: please retry the transaction",
        ] {
            let err = map_rpc_error("commit transaction", "", tonic::Status::aborted(msg));
            assert!(is_retryable_conflict(&err), "`{msg}` must be retryable");
        }
        let err = map_rpc_error("query", "", tonic::Status::internal("syntax error"));
        assert!(!is_retryable_conflict(&err));
        // A plain Rpc error without a message-ish content is not retryable.
        let err = ArcadeDbError::NotFound {
            operation: "x".into(),
            detail: "y".into(),
        };
        assert!(!is_retryable_conflict(&err));
    }

    #[test]
    fn one_row_accessors_decode_or_report_not_found() {
        let row = crate::rec("t", vec![("name", crate::encode::str_v("oak"))]);

        let empty = QueryResult {
            records: vec![],
            execution_time_ms: 0,
        };
        assert!(empty.first::<ItemRow>().unwrap().is_none());
        assert!(matches!(
            empty.one::<ItemRow>(),
            Err(ArcadeDbError::NotFound { .. })
        ));

        let single = QueryResult {
            records: vec![row],
            execution_time_ms: 0,
        };
        let row = single.first::<ItemRow>().unwrap().unwrap();
        assert_eq!(row.name, "oak");
        assert_eq!(single.one::<ItemRow>().unwrap().name, "oak");

        // Multi-column rows are rejected for scalars — map order is not
        // "first column" order.
        let wide = crate::rec(
            "t",
            vec![
                ("a", crate::encode::str_v("1")),
                ("b", crate::encode::str_v("2")),
            ],
        );
        assert!(single_column_value(&wide, "SELECT a, b FROM t").is_err());
        let lone = crate::rec("t", vec![("count", crate::encode::i64_v(7))]);
        let scalar = single_column_value(&lone, "SELECT count(*) AS count FROM t")
            .unwrap()
            .clone();
        assert!(matches!(scalar.kind, Some(grpc_value::Kind::Int64Value(7))));
    }

    #[derive(Clone)]
    struct ItemRow {
        name: String,
    }

    impl<'a> TryFrom<&'a GrpcRecord> for ItemRow {
        type Error = RecordDecodeError;

        fn try_from(rec: &'a GrpcRecord) -> Result<Self, Self::Error> {
            let name = rec
                .properties
                .get("name")
                .ok_or_else(|| RecordDecodeError::missing_field("name"))?;
            let Some(grpc_value::Kind::StringValue(s)) = &name.kind else {
                return Err(RecordDecodeError::conversion("name: expected string"));
            };
            Ok(ItemRow { name: s.clone() })
        }
    }
}