octra_sqlite/
lib.rs

1#![warn(missing_docs)]
2
3//! Real SQLite inside an Octra Circle.
4//!
5//! `octra-sqlite` provides a small Rust client for querying and writing to a
6//! SQLite database whose engine runs inside an Octra `wasm_v1` Circle. The
7//! crate keeps the first story deliberately small: create a [`Client`], open a
8//! [`Database`], then run SQL.
9//!
10//! # Start here
11//!
12//! Public-read databases need no local wallet or config:
13//!
14//! ```no_run
15//! use octra_sqlite::{Client, Result};
16//!
17//! fn main() -> Result<()> {
18//!     let client = Client::default();
19//!     let db = client.database(
20//!         "oct://devnet/octQfYK2fE9RvR9kfj8FJfMBQw1e4EzfHB8Q5Z9J2DCnRBQ",
21//!     )?;
22//!     let rows = db.query("select id, name from artist order by id;")?;
23//!     println!("{} rows", rows.row_count);
24//!     Ok(())
25//! }
26//! ```
27//!
28//! # Configured databases and writes
29//!
30//! [`Client::from_default_config`] loads the same saved database and wallet
31//! configuration used by the CLI. Writes are owner-signed and confirmed by
32//! default:
33//!
34//! ```no_run
35//! use octra_sqlite::{Client, Result};
36//!
37//! fn main() -> Result<()> {
38//!     let client = Client::from_default_config()?;
39//!     let db = client.database("art")?;
40//!     let result = db.execute("insert into artist(name) values ('Hokusai');")?;
41//!     println!("confirmed: {}", result.submitted.tx_hash.is_some());
42//!     Ok(())
43//! }
44//! ```
45//!
46//! Use [`Database::execute_no_wait`] when submission and confirmation must be
47//! separate, then complete the lifecycle with [`Database::wait`].
48//!
49//! # Read and write model
50//!
51//! Sealed databases use signed Octra view auth for reads. Public-read
52//! databases use unsigned Octra Circle views for SQL reads while keeping writes
53//! owner-signed through OSW1 owner write intent. Pass a saved database name or a
54//! full `oct://NETWORK/<circle>` URI to [`Client::database`]. The client
55//! detects the Circle's Octra read surface unless `read_mode` is explicitly set.
56//! Sealed authenticates reads; it does not encrypt data or make reads owner-only.
57//! Write SQL and values are visible in Octra transaction history.
58//!
59//! # API map
60//!
61//! - [`Client`] owns configuration and transport; [`Database`] owns one opened
62//!   SQL data plane.
63//! - [`QueryResult`], [`ExecuteResult`], and [`SubmittedTransaction`] model the
64//!   query, confirmed-write, and submitted-write lifecycles.
65//! - [`AuthInfo`], [`ProgramInfo`], and [`ReadMode`] expose database and Circle
66//!   state without leaking raw RPC details into the first story.
67//! - [`client`] contains advanced transport, config, and signing types.
68//! - [`client::raw`] contains lower-level Octra RPC plumbing for adapters and
69//!   operational tooling.
70//! - [`protocol`] contains the transport-independent OSR1, OSW1, target, and
71//!   transaction wire formats.
72//!
73//! # Errors
74//!
75//! [`Error::kind`] is the stable broad category for application handling.
76//! [`Error::code`] preserves a more precise machine-readable code supplied by
77//! the RPC, Circle, or receipt, or assigned at a local protocol boundary.
78//! Human error text is not an automation contract.
79//!
80//! # Build configuration
81//!
82//! - `cli`: build the `octra-sqlite` command line interface.
83//! - `http`: include the default blocking HTTP RPC transport.
84//! - `wasm-behavior`: enable host-harness tests for the bundled Circle WASM.
85//!
86//! docs.rs builds the library with `http` and without the CLI. The default
87//! crate configuration includes both `cli` and `http`.
88//!
89//! # Stability
90//!
91//! The CLI JSON envelopes and OSR1/OSW1 wire formats are treated as public
92//! surfaces. The Rust API is still `0.x`; breaking Rust API cleanup happens in
93//! minor versions.
94
95pub mod client;
96mod private_file;
97pub mod protocol;
98
99pub use client::{
100    AuthInfo, Client, ClientOptions, Database, Error, ErrorKind, ExecuteResult, ProgramInfo,
101    QueryResult, Result, SubmittedTransaction,
102};
103pub use protocol::target::ReadMode;
104pub use serde_json::Value;
105
106#[cfg(feature = "cli")]
107#[path = "cli/mod.rs"]
108/// Human and automation CLI entrypoints.
109pub mod cli;
octra_sqlite/lib.rs

octra_sqlite/
lib.rs
