Skip to main content

arcadedb_protocol/
lib.rs

1//! A lightweight gRPC client for [ArcadeDB](https://arcadedb.com).
2//!
3//! Generated tonic stubs for `com.arcadedb.grpc`, a typed record-decode path
4//! (`RecordDecode` derive + runtime), a `serde_json` bridge for dynamic
5//! access, and nothing else.
6//!
7//! ## What's here
8//!
9//! - [`client::ArcadeDbClient`] — wraps the data + admin gRPC services
10//!   (connect with retry, auth headers, `execute`/`query`/`create_database`/
11//!   `bulk_insert`, …). `Clone` (shares one tonic `Channel`).
12//! - [`error::ArcadeDbError`] — the typed error for every fallible client
13//!   call: match on the failure category (transport, server-rejected command,
14//!   decode, invalid input) and inspect the gRPC code/metadata.
15//! - JSON bridge ([`grpc_record_to_json`]):
16//!   `GrpcRecord` → `serde_json::Value` for callers that need dynamic
17//!   access. The *typed* decode path is
18//!   [`RecordDecode`] (see below) — there is no serde `Deserializer` anymore.
19//! - [`record`] — the typed-decode runtime: [`record::FromGrpcValue`],
20//!   [`record::RecordDecodeError`], and the property-access helpers used by the
21//!   generated code.
22//! - [`RecordDecode`] (re-exported derive) — `#[derive(RecordDecode)]` turns a
23//!   model struct into [`TryFrom<&GrpcRecord>`]` + `FromGrpcValue` with
24//!   per-field type coercion, honoring `#[serde(rename/default/flatten)]` for
25//!   drop-in adoption. Custom types plug in via the `#[record(with = "...")]`
26//!   attribute or by implementing `FromGrpcValue` directly.
27//! - [`RecordEncode`] (re-exported derive) — the write-side mirror: derives
28//!   [`record::ToGrpcRecord`] so bulk writers call `dto.to_grpc_record(class)`
29//!   instead of hand-assembling `GrpcValue`/`GrpcRecord` protos.
30//! - Value builders ([`Params`], [`IntoGrpcValue`]) for fixture/test code.
31//!
32//! ## Optional features
33//!
34//! - `ahash` — aHash maps as first-class wire maps:
35//!   `ahash::AHashMap<String, V>` binds as the wire `Map` (encode) and
36//!   decodes back into an `AHashMap` (decode), so a DTO field or a
37//!   `params!` value can be an aHash map with no std↔aHash conversion.
38//! - `cache` — transient KV facade over the Redis plugin (`client.cache()`).
39//! - `decimal` — exact `rust_decimal::Decimal` mapping for `DECIMAL` columns.
40//! - `fxhash` — rustc's FxHash maps as first-class wire maps
41//!   (`rustc_hash::FxHashMap<String, V>`), same as the `ahash` feature.
42//! - `rayon` — parallel decode of large batches.
43//! - `serde` — serde impls for wire-identity types (`Link` ↔ rid string).
44//!
45//! ## What's NOT here
46//!
47//! Identity types and query/repository layers. ArcadeDB's native RID
48//! (`#bucket:pos`) is the only identifier this crate deals with; apps choose
49//! their own logical identity scheme (e.g. `table:key` or an external id)
50//! and build their repo + query functions on top of [`ArcadeDbClient`].
51//!
52//! ```no_run
53//! # async fn demo() -> arcadedb_protocol::Result<()> {
54//! use arcadedb_protocol::ArcadeDbClient;
55//! let client = ArcadeDbClient::connect("127.0.0.1:50051", "root", "password", "mydb").await?;
56//! let res = client.query("mydb", "SELECT FROM item LIMIT 10").await?;
57//! println!("{} rows in {} ms", res.len(), res.execution_time_ms);
58//! # Ok(()) }
59//! ```
60
61// ---------------------------------------------------------------------------
62// Generated proto types (package `com.arcadedb.grpc`)
63// ---------------------------------------------------------------------------
64pub mod proto {
65    pub mod com {
66        pub mod arcadedb {
67            pub mod grpc {
68                tonic::include_proto!("com.arcadedb.grpc");
69            }
70        }
71    }
72}
73
74mod client;
75mod decode;
76mod encode;
77pub mod error;
78mod filter;
79pub mod options;
80pub mod record;
81
82// Domain facades: capability groups off the root client. The canonical
83// spelling is the module path; the `ArcadeDbClient::admin`/`scan`/`batch`
84// accessors are discovery sugar over the same implementations.
85pub mod admin;
86pub mod batch;
87pub use batch::{Batch, ScriptBuffer};
88#[cfg(feature = "cache")]
89pub mod cache;
90pub mod scan;
91pub mod stream;
92pub mod testutil;
93
94pub use arcadedb_record_macros::{sql, RecordDecode, RecordEncode};
95pub use client::{
96    consume_stream, ArcadeDbClient, DatabaseClient, QueryResult, QueryResultBatch, StreamSummary,
97    Transaction, TxCommands,
98};
99pub use decode::{grpc_record_to_json, grpc_value_to_json, json_to_grpc_value};
100pub use encode::{rec, IntoGrpcValue, Params, SetClause};
101pub use filter::FilterClause;
102pub use options::ClientOptions;
103pub use stream::StreamOptions;
104
105/// Value constructors for generated code (`RecordEncode` derives) — NOT a
106/// public API. The fns stay `pub` in `encode` (macro codegen must name
107/// them cross-crate) but are re-exported ONLY here, doc-hidden: the public
108/// binding surface is `params!` / `rec()` / `SetClause` / `IntoGrpcValue`,
109/// where the Rust types disambiguate the wire kinds.
110#[doc(hidden)]
111pub mod __private {
112    #[cfg(feature = "decimal")]
113    pub use crate::encode::decimal_v;
114    pub use crate::encode::{
115        bool_v, bytes_v, date_v, embedded_v, f32_v, f64_v, i32_v, i64_v, link_v, list_v, map_v,
116        str_v, timestamp_v,
117    };
118}
119pub use error::{ArcadeDbError, Result};
120/// The protobuf well-known `Timestamp` — the wire shape for date/datetime
121/// values (`Kind::TimestampValue`), re-exported for `RecordEncode` DTOs.
122pub use prost_types::Timestamp;
123pub use proto::com::arcadedb::grpc::GrpcRecord;
124pub use proto::com::arcadedb::grpc::{GrpcEmbedded, GrpcLink, GrpcList, GrpcMap, GrpcValue};
125// And the grpc_value::Kind enum, for assembling list/map parameter values.
126pub use proto::com::arcadedb::grpc::grpc_value::Kind;
127pub use record::{
128    changed_param_map, from_map_via_value, props_diff, DecodeFromMap, FromGrpcValue, Link,
129    RecordDecodeError, ToGrpcRecord,
130};
131
132/// The `ahash` crate, re-exported for the `ahash` feature — so callers can
133/// name the map type the crate's conversions accept
134/// (`arcadedb_protocol::ahash::AHashMap`) without pinning their own
135/// `ahash` version.
136#[cfg(feature = "ahash")]
137pub use ahash;
138
139/// The `rustc-hash` crate, re-exported for the `fxhash` feature — so
140/// callers can name `arcadedb_protocol::rustc_hash::FxHashMap` without
141/// pinning their own `rustc-hash` version.
142#[cfg(feature = "fxhash")]
143pub use rustc_hash;
144
145/// Implement [`DecodeFromMap`](record::DecodeFromMap) for a manual
146/// [`FromGrpcValue`](record::FromGrpcValue) type through the clone-based
147/// [`from_map_via_value`](record::from_map_via_value) path — for manual types
148/// used as `#[serde(flatten)]` targets. Prefer deriving `RecordDecode` on
149/// flatten targets (zero-copy).
150#[macro_export]
151macro_rules! impl_decode_from_map_via_value {
152    ($ty:ty) => {
153        impl<'de> $crate::record::DecodeFromMap<'de> for $ty {
154            fn from_map(
155                props: &'de ::std::collections::HashMap<::std::string::String, $crate::GrpcValue>,
156                taken: &[&str],
157                _syn_rid: ::core::option::Option<&::std::string::String>,
158                _syn_type: ::core::option::Option<&::std::string::String>,
159            ) -> ::std::result::Result<Self, $crate::record::RecordDecodeError> {
160                $crate::record::from_map_via_value(props, taken)
161            }
162        }
163    };
164}
165
166// Re-export proto service handles + types that downstream query code commonly
167// needs when building typed wrappers around the client.
168pub use proto::com::arcadedb::grpc::{
169    arcade_db_admin_service_client::ArcadeDbAdminServiceClient,
170    arcade_db_service_client::ArcadeDbServiceClient, ExecuteCommandResponse, InsertSummary,
171};