arcadedb_protocol/client/
mod.rs1use 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
21pub 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
34mod database;
39mod execute;
40mod query;
41mod records;
42mod results;
43mod streaming;
44mod transaction;
45
46pub use database::DatabaseClient;
48pub use results::{QueryResult, QueryResultBatch, StreamSummary};
49pub use streaming::consume_stream;
50pub use transaction::{Transaction, TxCommands};
51
52pub(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
81fn 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
98struct AuthState {
103 user_val: MetadataValue<tonic::metadata::Ascii>,
104 pass_val: MetadataValue<tonic::metadata::Ascii>,
105 db_val: MetadataValue<tonic::metadata::Ascii>,
106 database: String,
108 creds: DatabaseCredentials,
111 request_timeout: Option<Duration>,
115}
116
117#[derive(Clone)]
124pub struct ArcadeDbClient {
125 data: ArcadeDbServiceClient<Channel>,
126 admin: ArcadeDbAdminServiceClient<Channel>,
127 auth: std::sync::Arc<AuthState>,
128}
129
130impl ArcadeDbClient {
131 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 pub async fn connect_with(options: ClientOptions) -> Result<Self> {
153 options.validate()?;
154 let addr = options.addr.clone();
155
156 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 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 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 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 pub fn database(&self) -> &str {
283 &self.auth.database
284 }
285
286 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 pub(crate) fn admin_stub(&self) -> ArcadeDbAdminServiceClient<Channel> {
310 self.admin.clone()
311 }
312
313 pub(crate) fn creds(&self) -> DatabaseCredentials {
315 self.auth.creds.clone()
316 }
317
318 pub fn admin(&self) -> crate::admin::Admin {
323 crate::admin::Admin::new(self.clone())
324 }
325
326 pub fn scan(&self) -> crate::scan::Scan {
328 crate::scan::Scan::new(self.clone())
329 }
330
331 pub fn batch(&self) -> crate::batch::Batch {
334 crate::batch::Batch::new(self.clone())
335 }
336
337 #[cfg(feature = "cache")]
341 pub fn cache(&self) -> crate::cache::Cache {
342 crate::cache::Cache::new(self.clone())
343 }
344}
345
346pub(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 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 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 let err = map_rpc_error("query", "SELECT 1", tonic::Status::unavailable("boom"));
392 assert!(matches!(err, ArcadeDbError::Rpc { .. }));
393
394 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 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 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}