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