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