Skip to main content

type_bridge_server/typedb/
client.rs

1use super::ExecuteError;
2use super::backend::{DriverBackend, QueryResultKind, TransactionType};
3#[cfg(feature = "v2-query")]
4use super::real_driver::sanitize_prepared_connect_error;
5use super::real_driver::{RealTypeDBBackend, prepare_secure_connect_options};
6use crate::config::{SecureTypeDBSection, TypeDBSection};
7use crate::error::PipelineError;
8use crate::executor::QueryExecutor;
9use type_bridge_typedb_runtime::PreparedSecureConnectOptions;
10
11/// One immutable server connection identity bound to one prepared transport.
12///
13/// The fields are intentionally private: a caller cannot pair trust material,
14/// HTTP discovery settings, or a selected driver band with a different host or
15/// credential set after preparation.
16#[doc(hidden)]
17pub struct PreparedSecureTypeDBConnection {
18    address: String,
19    #[cfg(feature = "v2-query")]
20    database: String,
21    username: String,
22    password: String,
23    options: PreparedSecureConnectOptions,
24}
25
26impl PreparedSecureTypeDBConnection {
27    /// Connect the V2 ORM authority through this exact prepared identity.
28    #[cfg(feature = "v2-query")]
29    #[doc(hidden)]
30    pub async fn connect_database(&self) -> Result<type_bridge_orm::Database, PipelineError> {
31        type_bridge_orm::Database::connect_prepared_secure_with_options(
32            &self.address,
33            &self.database,
34            &self.username,
35            &self.password,
36            self.options.clone(),
37        )
38        .await
39        .map_err(sanitize_prepared_connect_error)
40    }
41}
42
43/// Wrapper around the TypeDB Rust driver providing a clean async API
44/// for query execution and schema retrieval.
45pub struct TypeDBClient {
46    backend: Box<dyn DriverBackend>,
47}
48
49impl TypeDBClient {
50    /// Connect to a TypeDB server using the provided configuration.
51    #[cfg_attr(coverage_nightly, coverage(off))]
52    pub async fn connect(config: &TypeDBSection) -> Result<Self, PipelineError> {
53        let backend = RealTypeDBBackend::connect(config).await?;
54        Ok(Self {
55            backend: Box::new(backend),
56        })
57    }
58
59    /// Connect using the standalone server's validated secure configuration.
60    #[cfg_attr(coverage_nightly, coverage(off))]
61    pub async fn connect_secure(config: &SecureTypeDBSection) -> Result<Self, PipelineError> {
62        let prepared = Self::prepare_secure_transport(config)?;
63        Self::connect_prepared_secure(&prepared).await
64    }
65
66    /// Validate and snapshot one secure transport policy for reuse.
67    pub fn prepare_secure_transport(
68        config: &SecureTypeDBSection,
69    ) -> Result<PreparedSecureTypeDBConnection, PipelineError> {
70        // Resolve trust before retaining any credential-bearing connection
71        // identity, then bind both into one opaque value.
72        let options = prepare_secure_connect_options(config)?;
73        let connection = &config.connection;
74        Ok(PreparedSecureTypeDBConnection {
75            address: connection.address.clone(),
76            #[cfg(feature = "v2-query")]
77            database: connection.database.clone(),
78            username: connection.username.clone(),
79            password: connection.password.clone(),
80            options,
81        })
82    }
83
84    /// Connect through an already prepared immutable transport snapshot.
85    pub async fn connect_prepared_secure(
86        prepared: &PreparedSecureTypeDBConnection,
87    ) -> Result<Self, PipelineError> {
88        let backend = RealTypeDBBackend::connect_prepared_secure(
89            &prepared.address,
90            &prepared.username,
91            &prepared.password,
92            prepared.options.clone(),
93        )
94        .await?;
95        Ok(Self {
96            backend: Box::new(backend),
97        })
98    }
99
100    /// Create a TypeDBClient with a custom backend (for testing).
101    #[cfg(test)]
102    pub(crate) fn with_backend(backend: Box<dyn DriverBackend>) -> Self {
103        Self { backend }
104    }
105
106    /// Execute a TypeQL query and return results as JSON.
107    ///
108    /// For read transactions, the transaction is used directly.
109    /// For write and schema transactions, the transaction is committed after execution.
110    pub async fn execute(
111        &self,
112        database: &str,
113        typeql: &str,
114        tx_type: &str,
115    ) -> Result<serde_json::Value, PipelineError> {
116        self.execute_classified(database, typeql, tx_type)
117            .await
118            .map_err(PipelineError::from)
119    }
120
121    /// Execute a query while retaining driver commit certainty and a value-free description.
122    ///
123    /// Only known pre-commit rejection codes prove that no changes were stored.
124    /// A server error alone does not prove rejection. An indeterminate commit may have
125    /// succeeded, so callers must establish its outcome before retrying.
126    pub async fn execute_classified(
127        &self,
128        database: &str,
129        typeql: &str,
130        tx_type: &str,
131    ) -> Result<serde_json::Value, ExecuteError> {
132        let transaction_type = parse_transaction_type(tx_type)?;
133
134        use type_bridge_orm::session::backend::BoundedAnswerLimits;
135        use type_bridge_orm::session::staged::{TransactionKind, TransactionOptions};
136        let kind = match transaction_type {
137            TransactionType::Read => TransactionKind::Read,
138            TransactionType::Write => TransactionKind::Write,
139            TransactionType::Schema => TransactionKind::Schema,
140        };
141        let options = TransactionOptions::default()
142            .with_kind(kind)
143            .with_never_commit(kind == TransactionKind::Read)
144            .with_answer_limits(BoundedAnswerLimits {
145                max_items: u64::MAX,
146                max_bytes: u64::MAX,
147                ..Default::default()
148            });
149        let answer = self.backend.execute(database, typeql, options).await?;
150        let results = match answer {
151            QueryResultKind::Ok => serde_json::json!({ "ok": true }),
152            QueryResultKind::Rows(rows) | QueryResultKind::Documents(rows) => {
153                serde_json::Value::Array(rows)
154            }
155        };
156
157        Ok(results)
158    }
159
160    /// Return whether a TypeDB database exists on the connected server.
161    pub async fn database_exists(&self, database: &str) -> Result<bool, PipelineError> {
162        self.backend.database_exists(database).await
163    }
164
165    /// Create a TypeDB database.
166    pub async fn create_database(&self, database: &str) -> Result<(), PipelineError> {
167        self.backend.create_database(database).await
168    }
169
170    /// Delete a TypeDB database.
171    pub async fn delete_database(&self, database: &str) -> Result<(), PipelineError> {
172        self.backend.delete_database(database).await
173    }
174
175    /// Delete a TypeDB database if it exists, then create it.
176    pub async fn reset_database(&self, database: &str) -> Result<(), PipelineError> {
177        if self.database_exists(database).await? {
178            self.delete_database(database).await?;
179        }
180        self.create_database(database).await
181    }
182
183    /// Check if the driver connection is open.
184    pub fn is_connected(&self) -> bool {
185        self.backend.is_open()
186    }
187}
188
189impl QueryExecutor for TypeDBClient {
190    fn execute<'a>(
191        &'a self,
192        database: &'a str,
193        typeql: &'a str,
194        transaction_type: &'a str,
195    ) -> std::pin::Pin<
196        Box<dyn std::future::Future<Output = Result<serde_json::Value, PipelineError>> + Send + 'a>,
197    > {
198        Box::pin(async move { self.execute(database, typeql, transaction_type).await })
199    }
200
201    fn is_connected(&self) -> bool {
202        self.is_connected()
203    }
204}
205
206/// Parse a transaction type string into a TypeDB TransactionType.
207pub(crate) fn parse_transaction_type(tx_type: &str) -> Result<TransactionType, PipelineError> {
208    match tx_type {
209        "read" => Ok(TransactionType::Read),
210        "write" => Ok(TransactionType::Write),
211        "schema" => Ok(TransactionType::Schema),
212        other => Err(PipelineError::QueryExecution(format!(
213            "Unknown transaction type: {other}"
214        ))),
215    }
216}
217
218#[cfg(test)]
219#[cfg(feature = "band8")]
220#[cfg_attr(coverage_nightly, coverage(off))]
221mod tests {
222    use std::collections::VecDeque;
223    use std::error::Error as _;
224    use std::future::Future;
225    use std::pin::Pin;
226    use std::sync::Arc;
227    use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
228
229    use super::*;
230    use crate::error::PipelineError;
231
232    // =============================================
233    // Mock infrastructure
234    // =============================================
235
236    struct MockTransaction {
237        query_result: Option<QueryResultKind>,
238        query_error: Option<String>,
239        commit_error: Option<ExecuteError>,
240        committed: Arc<AtomicBool>,
241        query_called: Arc<AtomicBool>,
242    }
243
244    impl MockTransaction {
245        fn new(result: QueryResultKind) -> Self {
246            Self {
247                query_result: Some(result),
248                query_error: None,
249                commit_error: None,
250                committed: Arc::new(AtomicBool::new(false)),
251                query_called: Arc::new(AtomicBool::new(false)),
252            }
253        }
254
255        fn failing_query(msg: &str) -> Self {
256            Self {
257                query_result: None,
258                query_error: Some(msg.to_string()),
259                commit_error: None,
260                committed: Arc::new(AtomicBool::new(false)),
261                query_called: Arc::new(AtomicBool::new(false)),
262            }
263        }
264
265        fn with_commit_error(mut self, msg: &str) -> Self {
266            self.commit_error = Some(
267                super::super::CommitFailure {
268                    failure: None,
269                    certainty: super::super::CommitCertainty::Indeterminate,
270                    message: msg.to_string(),
271                }
272                .into(),
273            );
274            self
275        }
276    }
277
278    impl MockTransaction {
279        fn query(
280            &mut self,
281            _typeql: &str,
282        ) -> Pin<Box<dyn Future<Output = Result<QueryResultKind, PipelineError>> + Send + '_>>
283        {
284            self.query_called.store(true, Ordering::SeqCst);
285            let result = self.query_result.take();
286            let error = self.query_error.take();
287            Box::pin(async move {
288                if let Some(msg) = error {
289                    return Err(PipelineError::QueryExecution(msg));
290                }
291                Ok(result.expect("MockTransaction::query called more than once"))
292            })
293        }
294
295        fn commit(
296            &mut self,
297        ) -> Pin<Box<dyn Future<Output = Result<(), ExecuteError>> + Send + '_>> {
298            self.committed.store(true, Ordering::SeqCst);
299            let error = self.commit_error.take();
300            Box::pin(async move {
301                if let Some(msg) = error {
302                    return Err(msg);
303                }
304                Ok(())
305            })
306        }
307    }
308
309    #[derive(Default)]
310    struct MockDatabaseAdmin {
311        exists_results: std::sync::Mutex<VecDeque<Result<bool, String>>>,
312        create_errors: std::sync::Mutex<VecDeque<String>>,
313        delete_errors: std::sync::Mutex<VecDeque<String>>,
314        exists_called: AtomicUsize,
315        create_called: AtomicUsize,
316        delete_called: AtomicUsize,
317        operations: std::sync::Mutex<Vec<String>>,
318    }
319
320    struct MockBackend {
321        transaction: std::sync::Mutex<Option<MockTransaction>>,
322        open_error: Option<String>,
323        is_open: bool,
324        open_called: Arc<AtomicUsize>,
325        database_admin: Arc<MockDatabaseAdmin>,
326    }
327
328    impl MockBackend {
329        fn new(tx: MockTransaction) -> Self {
330            Self {
331                transaction: std::sync::Mutex::new(Some(tx)),
332                open_error: None,
333                is_open: true,
334                open_called: Arc::new(AtomicUsize::new(0)),
335                database_admin: Arc::new(MockDatabaseAdmin::default()),
336            }
337        }
338
339        fn failing(msg: &str) -> Self {
340            Self {
341                transaction: std::sync::Mutex::new(None),
342                open_error: Some(msg.to_string()),
343                is_open: true,
344                open_called: Arc::new(AtomicUsize::new(0)),
345                database_admin: Arc::new(MockDatabaseAdmin::default()),
346            }
347        }
348
349        fn with_database_exists_results(self, results: Vec<Result<bool, String>>) -> Self {
350            *self.database_admin.exists_results.lock().unwrap() = results.into();
351            self
352        }
353
354        fn with_create_errors(self, errors: Vec<&str>) -> Self {
355            *self.database_admin.create_errors.lock().unwrap() =
356                errors.into_iter().map(str::to_string).collect();
357            self
358        }
359
360        fn with_delete_errors(self, errors: Vec<&str>) -> Self {
361            *self.database_admin.delete_errors.lock().unwrap() =
362                errors.into_iter().map(str::to_string).collect();
363            self
364        }
365
366        fn database_admin_state(&self) -> Arc<MockDatabaseAdmin> {
367            Arc::clone(&self.database_admin)
368        }
369    }
370
371    impl DriverBackend for MockBackend {
372        fn execute(
373            &self,
374            _database: &str,
375            typeql: &str,
376            options: type_bridge_orm::session::staged::TransactionOptions,
377        ) -> Pin<Box<dyn Future<Output = Result<QueryResultKind, ExecuteError>> + Send + '_>>
378        {
379            self.open_called.fetch_add(1, Ordering::SeqCst);
380            let tx = self.transaction.lock().unwrap().take();
381            let error = self.open_error.clone();
382            let typeql = typeql.to_owned();
383            Box::pin(async move {
384                if let Some(message) = error {
385                    return Err(PipelineError::QueryExecution(message).into());
386                }
387                let mut tx = tx.expect("MockBackend: no transaction configured");
388                let result = tx.query(&typeql).await?;
389                if !options.never_commit {
390                    tx.commit().await?;
391                }
392                Ok(result)
393            })
394        }
395
396        fn is_open(&self) -> bool {
397            self.is_open
398        }
399
400        fn database_exists(
401            &self,
402            database: &str,
403        ) -> Pin<Box<dyn Future<Output = Result<bool, PipelineError>> + Send + '_>> {
404            self.database_admin
405                .exists_called
406                .fetch_add(1, Ordering::SeqCst);
407            self.database_admin
408                .operations
409                .lock()
410                .unwrap()
411                .push(format!("exists:{database}"));
412            let result = self
413                .database_admin
414                .exists_results
415                .lock()
416                .unwrap()
417                .pop_front()
418                .unwrap_or(Ok(false));
419            Box::pin(async move { result.map_err(PipelineError::Connection) })
420        }
421
422        fn create_database(
423            &self,
424            database: &str,
425        ) -> Pin<Box<dyn Future<Output = Result<(), PipelineError>> + Send + '_>> {
426            self.database_admin
427                .create_called
428                .fetch_add(1, Ordering::SeqCst);
429            self.database_admin
430                .operations
431                .lock()
432                .unwrap()
433                .push(format!("create:{database}"));
434            let error = self
435                .database_admin
436                .create_errors
437                .lock()
438                .unwrap()
439                .pop_front();
440            Box::pin(async move {
441                if let Some(msg) = error {
442                    return Err(PipelineError::Connection(msg));
443                }
444                Ok(())
445            })
446        }
447
448        fn delete_database(
449            &self,
450            database: &str,
451        ) -> Pin<Box<dyn Future<Output = Result<(), PipelineError>> + Send + '_>> {
452            self.database_admin
453                .delete_called
454                .fetch_add(1, Ordering::SeqCst);
455            self.database_admin
456                .operations
457                .lock()
458                .unwrap()
459                .push(format!("delete:{database}"));
460            let error = self
461                .database_admin
462                .delete_errors
463                .lock()
464                .unwrap()
465                .pop_front();
466            Box::pin(async move {
467                if let Some(msg) = error {
468                    return Err(PipelineError::Connection(msg));
469                }
470                Ok(())
471            })
472        }
473    }
474
475    fn make_client(backend: MockBackend) -> TypeDBClient {
476        TypeDBClient::with_backend(Box::new(backend))
477    }
478
479    // =============================================
480    // parse_transaction_type tests
481    // =============================================
482
483    #[test]
484    fn parse_transaction_type_read() {
485        let result = parse_transaction_type("read").unwrap();
486        assert_eq!(result, TransactionType::Read);
487    }
488
489    #[test]
490    fn parse_transaction_type_write() {
491        let result = parse_transaction_type("write").unwrap();
492        assert_eq!(result, TransactionType::Write);
493    }
494
495    #[test]
496    fn parse_transaction_type_schema() {
497        let result = parse_transaction_type("schema").unwrap();
498        assert_eq!(result, TransactionType::Schema);
499    }
500
501    #[test]
502    fn parse_transaction_type_unknown() {
503        let result = parse_transaction_type("unknown");
504        let err = result.unwrap_err();
505        assert!(
506            matches!(&err, PipelineError::QueryExecution(msg) if msg.contains("Unknown transaction type: unknown"))
507        );
508    }
509
510    #[test]
511    fn parse_transaction_type_empty() {
512        let result = parse_transaction_type("");
513        assert!(result.is_err());
514    }
515
516    #[test]
517    fn parse_transaction_type_case_sensitive() {
518        let result = parse_transaction_type("Read");
519        assert!(result.is_err());
520    }
521
522    // =============================================
523    // execute tests (via MockBackend)
524    // =============================================
525
526    #[tokio::test]
527    async fn execute_ok_read_no_commit() {
528        let tx = MockTransaction::new(QueryResultKind::Ok);
529        let committed = tx.committed.clone();
530        let client = make_client(MockBackend::new(tx));
531
532        let result = client
533            .execute("db", "match $x isa thing;", "read")
534            .await
535            .unwrap();
536        assert_eq!(result, serde_json::json!({"ok": true}));
537        assert!(!committed.load(Ordering::SeqCst));
538    }
539
540    #[tokio::test]
541    async fn execute_ok_write_commits() {
542        let tx = MockTransaction::new(QueryResultKind::Ok);
543        let committed = tx.committed.clone();
544        let client = make_client(MockBackend::new(tx));
545
546        let result = client
547            .execute("db", "insert $x isa thing;", "write")
548            .await
549            .unwrap();
550        assert_eq!(result, serde_json::json!({"ok": true}));
551        assert!(committed.load(Ordering::SeqCst));
552    }
553
554    #[tokio::test]
555    async fn execute_ok_schema_commits() {
556        let tx = MockTransaction::new(QueryResultKind::Ok);
557        let committed = tx.committed.clone();
558        let client = make_client(MockBackend::new(tx));
559
560        let result = client
561            .execute("db", "define entity thing;", "schema")
562            .await
563            .unwrap();
564        assert_eq!(result, serde_json::json!({"ok": true}));
565        assert!(committed.load(Ordering::SeqCst));
566    }
567
568    #[tokio::test]
569    async fn execute_rows_read_no_commit() {
570        let rows = vec![
571            serde_json::json!({"name": "Alice"}),
572            serde_json::json!({"name": "Bob"}),
573        ];
574        let tx = MockTransaction::new(QueryResultKind::Rows(rows.clone()));
575        let committed = tx.committed.clone();
576        let client = make_client(MockBackend::new(tx));
577
578        let result = client
579            .execute("db", "match $p isa person;", "read")
580            .await
581            .unwrap();
582        assert_eq!(result, serde_json::Value::Array(rows));
583        assert!(!committed.load(Ordering::SeqCst));
584    }
585
586    #[tokio::test]
587    async fn execute_rows_write_commits() {
588        let rows = vec![serde_json::json!({"id": 1})];
589        let tx = MockTransaction::new(QueryResultKind::Rows(rows));
590        let committed = tx.committed.clone();
591        let client = make_client(MockBackend::new(tx));
592
593        let result = client
594            .execute("db", "insert $x isa thing;", "write")
595            .await
596            .unwrap();
597        assert!(result.is_array());
598        assert!(committed.load(Ordering::SeqCst));
599    }
600
601    #[tokio::test]
602    async fn execute_rows_data_preserved() {
603        let rows = vec![
604            serde_json::json!({"name": "Alice", "age": 30}),
605            serde_json::json!({"name": "Bob", "age": 25}),
606        ];
607        let tx = MockTransaction::new(QueryResultKind::Rows(rows.clone()));
608        let client = make_client(MockBackend::new(tx));
609
610        let result = client
611            .execute("db", "match $p isa person;", "read")
612            .await
613            .unwrap();
614        let arr = result.as_array().unwrap();
615        assert_eq!(arr.len(), 2);
616        assert_eq!(arr[0]["name"], "Alice");
617        assert_eq!(arr[1]["age"], 25);
618    }
619
620    #[tokio::test]
621    async fn execute_docs_read_no_commit() {
622        let docs = vec![serde_json::json!({"doc": "data"})];
623        let tx = MockTransaction::new(QueryResultKind::Documents(docs.clone()));
624        let committed = tx.committed.clone();
625        let client = make_client(MockBackend::new(tx));
626
627        let result = client
628            .execute("db", "match $p isa person; fetch {};", "read")
629            .await
630            .unwrap();
631        assert_eq!(result, serde_json::Value::Array(docs));
632        assert!(!committed.load(Ordering::SeqCst));
633    }
634
635    #[tokio::test]
636    async fn execute_docs_write_commits() {
637        let docs = vec![serde_json::json!({"doc": "data"})];
638        let tx = MockTransaction::new(QueryResultKind::Documents(docs));
639        let committed = tx.committed.clone();
640        let client = make_client(MockBackend::new(tx));
641
642        let result = client
643            .execute("db", "insert $x isa thing;", "write")
644            .await
645            .unwrap();
646        assert!(result.is_array());
647        assert!(committed.load(Ordering::SeqCst));
648    }
649
650    #[tokio::test]
651    async fn execute_docs_commit_error_propagated() {
652        let docs = vec![serde_json::json!({"doc": "data"})];
653        let tx = MockTransaction::new(QueryResultKind::Documents(docs))
654            .with_commit_error("commit failed");
655        let client = make_client(MockBackend::new(tx));
656
657        let result = client
658            .execute("db", "insert $x isa thing;", "write")
659            .await
660            .unwrap_err();
661        assert!(
662            matches!(result, PipelineError::QueryExecution(msg) if msg == "Commit failed: commit failed")
663        );
664    }
665
666    #[tokio::test]
667    async fn execute_transaction_open_failure() {
668        let client = make_client(MockBackend::failing("connection refused"));
669
670        let result = client.execute("db", "match $x isa thing;", "read").await;
671        let err = result.unwrap_err();
672        assert!(
673            matches!(&err, PipelineError::QueryExecution(msg) if msg.contains("connection refused"))
674        );
675    }
676
677    #[tokio::test]
678    async fn execute_query_failure() {
679        let tx = MockTransaction::failing_query("syntax error");
680        let client = make_client(MockBackend::new(tx));
681
682        let result = client.execute("db", "bad query", "read").await;
683        let err = result.unwrap_err();
684        assert!(matches!(&err, PipelineError::QueryExecution(msg) if msg.contains("syntax error")));
685    }
686
687    #[tokio::test]
688    async fn execute_commit_failure_ok_propagated() {
689        let tx = MockTransaction::new(QueryResultKind::Ok).with_commit_error("commit failed");
690        let client = make_client(MockBackend::new(tx));
691
692        // Ok + write: commit error IS propagated
693        let result = client.execute("db", "insert $x isa thing;", "write").await;
694        let err = result.unwrap_err();
695        assert!(
696            matches!(&err, PipelineError::QueryExecution(msg) if msg.contains("commit failed"))
697        );
698    }
699
700    #[tokio::test]
701    async fn execute_commit_failure_rows_propagated() {
702        let tx =
703            MockTransaction::new(QueryResultKind::Rows(vec![])).with_commit_error("commit failed");
704        let client = make_client(MockBackend::new(tx));
705
706        // Rows + write: commit error IS propagated
707        let result = client.execute("db", "insert $x isa thing;", "write").await;
708        let err = result.unwrap_err();
709        assert!(
710            matches!(&err, PipelineError::QueryExecution(msg) if msg.contains("commit failed"))
711        );
712    }
713
714    const STC2: &str = "[STC2] Commit in database 'bench' failed with isolation conflict: Transaction uses a lock held by a concurrent commit.";
715
716    #[tokio::test]
717    async fn classified_and_legacy_execute_preserve_commit_contracts() {
718        use crate::typedb::{CommitCertainty, CommitFailure};
719        for certainty in [CommitCertainty::Rejected, CommitCertainty::Indeterminate] {
720            for result in [
721                QueryResultKind::Ok,
722                QueryResultKind::Rows(vec![]),
723                QueryResultKind::Documents(vec![]),
724            ] {
725                for classified in [true, false] {
726                    let mut tx = MockTransaction::new(result.clone());
727                    tx.commit_error = Some(
728                        CommitFailure {
729                            failure: None,
730                            certainty,
731                            message: STC2.into(),
732                        }
733                        .into(),
734                    );
735                    let client = make_client(MockBackend::new(tx));
736                    if classified {
737                        let error = client
738                            .execute_classified("bench", "update", "write")
739                            .await
740                            .unwrap_err();
741                        assert!(matches!(error, ExecuteError::Commit(failure)
742                            if failure.certainty == certainty && failure.message == STC2));
743                    } else {
744                        let error = client
745                            .execute("bench", "update", "write")
746                            .await
747                            .unwrap_err();
748                        assert!(matches!(error, PipelineError::QueryExecution(message)
749                            if message == format!("Commit failed: {STC2}")));
750                    }
751                }
752            }
753        }
754    }
755
756    #[tokio::test]
757    async fn classified_execute_preserves_pipeline_errors() {
758        let client = make_client(MockBackend::failing("open failed"));
759        assert!(
760            matches!(client.execute_classified("db", "match", "read").await,
761            Err(ExecuteError::Pipeline(PipelineError::QueryExecution(message))) if message == "open failed")
762        );
763        let client = make_client(MockBackend::new(MockTransaction::failing_query(
764            "query failed",
765        )));
766        assert!(
767            matches!(client.execute_classified("db", "match", "read").await,
768            Err(ExecuteError::Pipeline(PipelineError::QueryExecution(message))) if message == "query failed")
769        );
770        assert!(matches!(
771            client.execute_classified("db", "match", "invalid").await,
772            Err(ExecuteError::Pipeline(PipelineError::QueryExecution(_)))
773        ));
774    }
775
776    #[tokio::test]
777    async fn execute_invalid_transaction_type() {
778        let tx = MockTransaction::new(QueryResultKind::Ok);
779        let backend = MockBackend::new(tx);
780        let open_called = backend.open_called.clone();
781        let client = make_client(backend);
782
783        let result = client.execute("db", "match $x;", "invalid").await;
784        assert!(result.is_err());
785        // Backend should never be called if transaction type is invalid
786        assert_eq!(open_called.load(Ordering::SeqCst), 0);
787    }
788
789    #[test]
790    fn is_connected_delegates_to_backend() {
791        let mut backend = MockBackend::new(MockTransaction::new(QueryResultKind::Ok));
792        backend.is_open = true;
793        let client = make_client(backend);
794        assert!(client.is_connected());
795    }
796
797    #[test]
798    fn is_connected_false_when_backend_closed() {
799        let mut backend = MockBackend::new(MockTransaction::new(QueryResultKind::Ok));
800        backend.is_open = false;
801        let client = make_client(backend);
802        assert!(!client.is_connected());
803    }
804
805    // =============================================
806    // database admin tests (via MockBackend)
807    // =============================================
808
809    #[tokio::test]
810    async fn database_exists_true_delegates_to_backend() {
811        let backend = MockBackend::new(MockTransaction::new(QueryResultKind::Ok))
812            .with_database_exists_results(vec![Ok(true)]);
813        let admin = backend.database_admin_state();
814        let client = make_client(backend);
815
816        assert!(client.database_exists("admin_db").await.unwrap());
817        assert_eq!(admin.exists_called.load(Ordering::SeqCst), 1);
818        assert_eq!(
819            admin.operations.lock().unwrap().clone(),
820            vec!["exists:admin_db".to_string()]
821        );
822    }
823
824    #[tokio::test]
825    async fn database_exists_false_delegates_to_backend() {
826        let backend = MockBackend::new(MockTransaction::new(QueryResultKind::Ok))
827            .with_database_exists_results(vec![Ok(false)]);
828        let admin = backend.database_admin_state();
829        let client = make_client(backend);
830
831        assert!(!client.database_exists("missing_db").await.unwrap());
832        assert_eq!(admin.exists_called.load(Ordering::SeqCst), 1);
833        assert_eq!(
834            admin.operations.lock().unwrap().clone(),
835            vec!["exists:missing_db".to_string()]
836        );
837    }
838
839    #[tokio::test]
840    async fn create_database_delegates_to_backend() {
841        let backend = MockBackend::new(MockTransaction::new(QueryResultKind::Ok));
842        let admin = backend.database_admin_state();
843        let client = make_client(backend);
844
845        client.create_database("new_db").await.unwrap();
846        assert_eq!(admin.create_called.load(Ordering::SeqCst), 1);
847        assert_eq!(
848            admin.operations.lock().unwrap().clone(),
849            vec!["create:new_db".to_string()]
850        );
851    }
852
853    #[tokio::test]
854    async fn delete_database_delegates_to_backend() {
855        let backend = MockBackend::new(MockTransaction::new(QueryResultKind::Ok));
856        let admin = backend.database_admin_state();
857        let client = make_client(backend);
858
859        client.delete_database("old_db").await.unwrap();
860        assert_eq!(admin.delete_called.load(Ordering::SeqCst), 1);
861        assert_eq!(
862            admin.operations.lock().unwrap().clone(),
863            vec!["delete:old_db".to_string()]
864        );
865    }
866
867    #[tokio::test]
868    async fn reset_database_deletes_existing_database_before_create() {
869        let backend = MockBackend::new(MockTransaction::new(QueryResultKind::Ok))
870            .with_database_exists_results(vec![Ok(true)]);
871        let admin = backend.database_admin_state();
872        let client = make_client(backend);
873
874        client.reset_database("reset_db").await.unwrap();
875        assert_eq!(admin.exists_called.load(Ordering::SeqCst), 1);
876        assert_eq!(admin.delete_called.load(Ordering::SeqCst), 1);
877        assert_eq!(admin.create_called.load(Ordering::SeqCst), 1);
878        assert_eq!(
879            admin.operations.lock().unwrap().clone(),
880            vec![
881                "exists:reset_db".to_string(),
882                "delete:reset_db".to_string(),
883                "create:reset_db".to_string(),
884            ]
885        );
886    }
887
888    #[tokio::test]
889    async fn reset_database_creates_when_database_is_absent() {
890        let backend = MockBackend::new(MockTransaction::new(QueryResultKind::Ok))
891            .with_database_exists_results(vec![Ok(false)]);
892        let admin = backend.database_admin_state();
893        let client = make_client(backend);
894
895        client.reset_database("reset_db").await.unwrap();
896        assert_eq!(admin.exists_called.load(Ordering::SeqCst), 1);
897        assert_eq!(admin.delete_called.load(Ordering::SeqCst), 0);
898        assert_eq!(admin.create_called.load(Ordering::SeqCst), 1);
899        assert_eq!(
900            admin.operations.lock().unwrap().clone(),
901            vec!["exists:reset_db".to_string(), "create:reset_db".to_string(),]
902        );
903    }
904
905    #[tokio::test]
906    async fn database_exists_propagates_backend_error() {
907        let backend = MockBackend::new(MockTransaction::new(QueryResultKind::Ok))
908            .with_database_exists_results(vec![Err("lookup failed".to_string())]);
909        let client = make_client(backend);
910
911        let err = client.database_exists("db").await.unwrap_err();
912        assert!(matches!(&err, PipelineError::Connection(msg) if msg.contains("lookup failed")));
913    }
914
915    #[tokio::test]
916    async fn create_database_propagates_backend_error() {
917        let backend = MockBackend::new(MockTransaction::new(QueryResultKind::Ok))
918            .with_create_errors(vec!["create failed"]);
919        let client = make_client(backend);
920
921        let err = client.create_database("db").await.unwrap_err();
922        assert!(matches!(&err, PipelineError::Connection(msg) if msg.contains("create failed")));
923    }
924
925    #[tokio::test]
926    async fn delete_database_propagates_backend_error() {
927        let backend = MockBackend::new(MockTransaction::new(QueryResultKind::Ok))
928            .with_delete_errors(vec!["delete failed"]);
929        let client = make_client(backend);
930
931        let err = client.delete_database("db").await.unwrap_err();
932        assert!(matches!(&err, PipelineError::Connection(msg) if msg.contains("delete failed")));
933    }
934
935    #[tokio::test]
936    async fn reset_database_propagates_lookup_error_without_mutating() {
937        let backend = MockBackend::new(MockTransaction::new(QueryResultKind::Ok))
938            .with_database_exists_results(vec![Err("lookup failed".to_string())]);
939        let admin = backend.database_admin_state();
940        let client = make_client(backend);
941
942        let err = client.reset_database("db").await.unwrap_err();
943        assert!(matches!(&err, PipelineError::Connection(msg) if msg.contains("lookup failed")));
944        assert_eq!(admin.delete_called.load(Ordering::SeqCst), 0);
945        assert_eq!(admin.create_called.load(Ordering::SeqCst), 0);
946        assert_eq!(
947            admin.operations.lock().unwrap().clone(),
948            vec!["exists:db".to_string()]
949        );
950    }
951
952    #[tokio::test]
953    async fn reset_database_propagates_delete_error_without_create() {
954        let backend = MockBackend::new(MockTransaction::new(QueryResultKind::Ok))
955            .with_database_exists_results(vec![Ok(true)])
956            .with_delete_errors(vec!["delete failed"]);
957        let admin = backend.database_admin_state();
958        let client = make_client(backend);
959
960        let err = client.reset_database("db").await.unwrap_err();
961        assert!(matches!(&err, PipelineError::Connection(msg) if msg.contains("delete failed")));
962        assert_eq!(admin.create_called.load(Ordering::SeqCst), 0);
963        assert_eq!(
964            admin.operations.lock().unwrap().clone(),
965            vec!["exists:db".to_string(), "delete:db".to_string()]
966        );
967    }
968
969    // =============================================
970    // QueryExecutor trait impl tests
971    // =============================================
972
973    #[test]
974    fn type_db_client_implements_query_executor() {
975        fn assert_executor<T: QueryExecutor>() {}
976        assert_executor::<TypeDBClient>();
977    }
978
979    #[tokio::test]
980    async fn query_executor_execute_delegates_to_client() {
981        let tx = MockTransaction::new(QueryResultKind::Rows(vec![serde_json::json!({"x": 1})]));
982        let client = make_client(MockBackend::new(tx));
983        let executor: Box<dyn QueryExecutor> = Box::new(client);
984
985        let result = executor
986            .execute("db", "match $x isa thing;", "read")
987            .await
988            .unwrap();
989        assert!(result.is_array());
990        assert_eq!(result.as_array().unwrap().len(), 1);
991    }
992
993    #[test]
994    fn query_executor_is_connected_delegates_to_client() {
995        let mut backend = MockBackend::new(MockTransaction::new(QueryResultKind::Ok));
996        backend.is_open = true;
997        let client = make_client(backend);
998        let executor: Box<dyn QueryExecutor> = Box::new(client);
999        assert!(executor.is_connected());
1000    }
1001
1002    #[tokio::test]
1003    async fn prepared_first_and_v2_connections_never_expose_credentials_or_provider_identity() {
1004        const ADDRESS: &str = "admin:TB_ADDRESS_SECRET@provider.invalid:1729";
1005        const USERNAME: &str = "TB_USERNAME_SECRET";
1006        const PASSWORD: &str = "TB_PASSWORD_SECRET";
1007        let config = SecureTypeDBSection::new(
1008            TypeDBSection {
1009                address: ADDRESS.to_owned(),
1010                database: "db".to_owned(),
1011                username: USERNAME.to_owned(),
1012                password: PASSWORD.to_owned(),
1013                http_port: 8000,
1014                server_version: Some("3.12.1".to_owned()),
1015            },
1016            crate::config::OutboundTlsMode::Disabled,
1017        );
1018        let prepared = TypeDBClient::prepare_secure_transport(&config).unwrap();
1019
1020        let first = match TypeDBClient::connect_prepared_secure(&prepared).await {
1021            Ok(_) => panic!("malformed provider address unexpectedly connected"),
1022            Err(error) => error,
1023        };
1024        let rendered = format!("{first}\n{first:?}");
1025        for secret in [ADDRESS, USERNAME, PASSWORD] {
1026            assert!(!rendered.contains(secret), "{secret}: {rendered}");
1027        }
1028        assert!(first.source().is_none());
1029
1030        #[cfg(feature = "v2-query")]
1031        {
1032            let second = match prepared.connect_database().await {
1033                Ok(_) => panic!("malformed V2 provider address unexpectedly connected"),
1034                Err(error) => error,
1035            };
1036            let rendered = format!("{second}\n{second:?}");
1037            for secret in [ADDRESS, USERNAME, PASSWORD] {
1038                assert!(!rendered.contains(secret), "{secret}: {rendered}");
1039            }
1040            assert!(second.source().is_none());
1041        }
1042    }
1043
1044    // =============================================
1045    // Integration tests (require running TypeDB)
1046    // =============================================
1047
1048    #[tokio::test]
1049    #[ignore = "requires running TypeDB server"]
1050    #[cfg_attr(coverage_nightly, coverage(off))]
1051    async fn integration_connect_invalid_address() {
1052        let config = TypeDBSection {
1053            address: "localhost:99999".to_string(),
1054            database: "test".to_string(),
1055            username: "admin".to_string(),
1056            password: "password".to_string(),
1057            http_port: 8000,
1058            server_version: None,
1059        };
1060        let result = TypeDBClient::connect(&config).await;
1061        assert!(result.is_err());
1062    }
1063
1064    /// Live-test target resolved from the environment so the suite can point
1065    /// at any disposable TypeDB container instead of a fixed local install.
1066    fn live_config() -> TypeDBSection {
1067        TypeDBSection {
1068            address: std::env::var("TYPEDB_ADDRESS")
1069                .unwrap_or_else(|_| "localhost:1729".to_string()),
1070            database: std::env::var("TYPEDB_DATABASE").unwrap_or_else(|_| "test".to_string()),
1071            username: "admin".to_string(),
1072            password: "password".to_string(),
1073            http_port: std::env::var("TYPEDB_HTTP_PORT")
1074                .ok()
1075                .and_then(|port| port.parse().ok())
1076                .unwrap_or(8000),
1077            server_version: std::env::var("TYPEDB_SERVER_VERSION").ok(),
1078        }
1079    }
1080
1081    #[tokio::test]
1082    #[ignore = "requires running TypeDB server"]
1083    #[cfg_attr(coverage_nightly, coverage(off))]
1084    async fn integration_connect_success() {
1085        let result = TypeDBClient::connect(&live_config()).await;
1086        assert!(result.is_ok());
1087        assert!(result.unwrap().is_connected());
1088    }
1089
1090    #[tokio::test]
1091    #[ignore = "requires running TypeDB server"]
1092    #[cfg_attr(coverage_nightly, coverage(off))]
1093    async fn integration_database_admin_roundtrip() {
1094        let config = live_config();
1095        let client = TypeDBClient::connect(&config)
1096            .await
1097            .expect("connect failed");
1098        let database = format!("type_bridge_server_admin_{}", uuid::Uuid::new_v4().simple());
1099
1100        if client.database_exists(&database).await.unwrap_or(false) {
1101            let _ = client.delete_database(&database).await;
1102        }
1103
1104        assert!(!client.database_exists(&database).await.unwrap());
1105        client
1106            .create_database(&database)
1107            .await
1108            .expect("create failed");
1109        assert!(client.database_exists(&database).await.unwrap());
1110
1111        client
1112            .reset_database(&database)
1113            .await
1114            .expect("reset existing database failed");
1115        assert!(client.database_exists(&database).await.unwrap());
1116
1117        client
1118            .delete_database(&database)
1119            .await
1120            .expect("delete failed");
1121        assert!(!client.database_exists(&database).await.unwrap());
1122
1123        client
1124            .reset_database(&database)
1125            .await
1126            .expect("reset absent database failed");
1127        assert!(client.database_exists(&database).await.unwrap());
1128
1129        client
1130            .delete_database(&database)
1131            .await
1132            .expect("cleanup delete failed");
1133    }
1134
1135    #[tokio::test]
1136    #[ignore = "requires running TypeDB server"]
1137    async fn integration_classified_commit_isolation_conflict() {
1138        use crate::typedb::CommitCertainty;
1139        let config = live_config();
1140        let client = TypeDBClient::connect(&config).await.unwrap();
1141        let database = format!("commit_certainty_{}", uuid::Uuid::new_v4().simple());
1142        client.create_database(&database).await.unwrap();
1143        client.execute(&database,
1144            "define attribute id, value string; attribute score, value integer; entity item, owns id @key, owns score;",
1145            "schema").await.unwrap();
1146        client
1147            .execute(
1148                &database,
1149                "insert $x isa item, has id \"ITEM-1\", has score 0;",
1150                "write",
1151            )
1152            .await
1153            .unwrap();
1154        // Overlap two eager ORM facades to obtain an actual provider conflict.
1155        let real = RealTypeDBBackend::connect(&config).await.unwrap();
1156        let orm = real.database_handle(&database);
1157        let mut a = orm.write_transaction().await.unwrap();
1158        let mut b = orm.write_transaction().await.unwrap();
1159        let update = "match $x isa item, has id \"ITEM-1\"; update $x has score 2;";
1160        a.query("match $x isa item, has id \"ITEM-1\"; update $x has score 1;")
1161            .await
1162            .unwrap();
1163        b.query(update).await.unwrap();
1164        a.commit().await.unwrap();
1165        let failure = ExecuteError::from(b.commit_classified().await.unwrap_err());
1166        let mut transaction = MockTransaction::new(QueryResultKind::Ok);
1167        transaction.commit_error = Some(failure);
1168        let backend = MockBackend::new(transaction);
1169        let conflict_client = make_client(backend);
1170        let error = conflict_client
1171            .execute_classified(&database, update, "write")
1172            .await
1173            .unwrap_err();
1174        match error {
1175            ExecuteError::Commit(failure) => {
1176                assert_eq!(failure.certainty, CommitCertainty::Rejected);
1177                assert!(failure.message.contains("[STC2]"), "{}", failure.message);
1178                assert!(matches!(
1179                    failure.failure,
1180                    Some(type_bridge_contract::failure::Failure::Rejected {
1181                        phase: type_bridge_contract::failure::Phase::Commit,
1182                        reason: type_bridge_contract::failure::Reason::Conflict {
1183                            lock: type_bridge_contract::failure::LockKind::Exclusive,
1184                        },
1185                        ..
1186                    })
1187                ));
1188                assert!(!failure.message.contains("ITEM-1"));
1189                println!("Rejected: {}", failure.message);
1190            }
1191            other => panic!("expected classified STC2 commit failure: {other:?}"),
1192        }
1193        drop(conflict_client);
1194        drop(a);
1195        client.delete_database(&database).await.unwrap();
1196    }
1197
1198    #[tokio::test]
1199    #[ignore = "requires running TypeDB server"]
1200    #[cfg_attr(coverage_nightly, coverage(off))]
1201    async fn integration_execute_roundtrip() {
1202        let config = live_config();
1203        let client = TypeDBClient::connect(&config)
1204            .await
1205            .expect("connect failed");
1206
1207        client
1208            .execute(&config.database, "define entity smoke_marker;", "schema")
1209            .await
1210            .expect("schema define failed");
1211
1212        let rows = client
1213            .execute(&config.database, "match entity $t;", "read")
1214            .await
1215            .expect("read query failed");
1216        let rows = rows.as_array().expect("read result must be a JSON array");
1217        assert!(
1218            !rows.is_empty(),
1219            "expected at least the smoke_marker entity type"
1220        );
1221    }
1222}