Skip to main content

surrealdb_sdk/
lib.rs

1#![recursion_limit = "256"]
2
3//! Lightweight, standalone remote client SDK for [SurrealDB](https://surrealdb.com).
4//!
5//! This SDK connects to remote SurrealDB instances using high-performance protocols:
6//! - **WebSocket** (`ws://` / `wss://`): Default interactive and live-query protocol.
7//! - **HTTP** (`http://` / `https://`): REST-compatible HTTP protocol.
8//! - **Raw TCP** (`tcp://`): High-performance, zero-HTTP-overhead binary stream protocol for backend microservices.
9//!
10//! Unlike the full `surrealdb` crate, `surrealdb-sdk` excludes all embedded KV storage engines (RocksDB, TiKV, IndexDB),
11//! reducing compilation footprint and build times for client applications.
12
13#![doc(html_favicon_url = "https://surrealdb.s3.amazonaws.com/favicon.png")]
14#![doc(html_logo_url = "https://surrealdb.s3.amazonaws.com/icon.png")]
15#![cfg_attr(docsrs, feature(doc_cfg))]
16
17#[cfg(all(target_family = "wasm", feature = "ml"))]
18compile_error!("The `ml` feature is not supported on Wasm.");
19
20#[macro_use]
21extern crate tracing;
22
23pub mod engine;
24#[doc(hidden)]
25#[cfg(feature = "protocol-http")]
26pub mod headers;
27pub mod method;
28pub mod opt;
29
30mod conn;
31mod notification;
32
33#[doc(hidden)]
34/// Channels for receiving a SurrealQL database export
35pub mod channel {
36	pub use async_channel::{Receiver, Sender, bounded, unbounded};
37}
38
39pub mod query_result;
40pub use query_result::{QueryResult, QueryType, Status};
41pub mod export_config;
42pub mod token;
43pub use token::Token;
44
45#[doc(inline)]
46pub use method::Stats;
47#[doc(inline)]
48pub use method::Stream;
49#[doc(inline)]
50pub use method::query::IndexedResults;
51#[doc(inline)]
52pub use surrealdb_types as types;
53
54#[doc(inline)]
55pub use crate::notification::Notification;
56
57/// A specialized `Result` type
58pub type Result<T> = std::result::Result<T, Error>;
59use std::fmt;
60use std::fmt::Debug;
61use std::future::IntoFuture;
62use std::marker::PhantomData;
63use std::sync::{Arc, OnceLock};
64
65use async_channel::{Receiver, Sender};
66use method::BoxFuture;
67use semver::{Version, VersionReq};
68#[doc(inline)]
69pub use surrealdb_types::Error;
70use surrealdb_types::NotAllowedError;
71use tokio::sync::watch;
72use uuid::Uuid;
73
74use self::conn::Router;
75use self::opt::{Endpoint, EndpointKind, WaitFor};
76
77// Channel for waiters
78type Waiter = (watch::Sender<Option<WaitFor>>, watch::Receiver<Option<WaitFor>>);
79
80const SUPPORTED_VERSIONS: &str = ">=3.0.0-alpha.1, <4.0.0";
81
82/// Connection trait implemented by supported engines
83pub trait Connection: conn::Sealed {}
84
85/// The future returned when creating a new SurrealDB instance
86#[derive(Debug)]
87#[must_use = "futures do nothing unless you `.await` or poll them"]
88pub struct Connect<C: Connection, Response> {
89	surreal: Surreal<C>,
90	address: Result<Endpoint>,
91	capacity: usize,
92	response_type: PhantomData<Response>,
93}
94
95impl<C, R> Connect<C, R>
96where
97	C: Connection,
98{
99	/// Sets the maximum capacity of the connection
100	///
101	/// This is used to set bounds of the channels used internally
102	/// as well set the capacity of the `HashMap` used for routing
103	/// responses in case of the WebSocket client.
104	///
105	/// Setting this capacity to `0` (the default) means that
106	/// unbounded channels will be used. If your queries per second
107	/// are so high that the client is running out of memory,
108	/// it might be helpful to set this to a number that works best
109	/// for you.
110	///
111	/// # Examples
112	///
113	/// ```no_run
114	/// # #[tokio::main]
115	/// # async fn main() -> surrealdb::Result<()> {
116	/// use surrealdb::engine::remote::ws::Ws;
117	/// use surrealdb::Surreal;
118	///
119	/// let db = Surreal::new::<Ws>("localhost:8000")
120	///     .with_capacity(100_000)
121	///     .await?;
122	/// # Ok(())
123	/// # }
124	/// ```
125	pub const fn with_capacity(mut self, capacity: usize) -> Self {
126		self.capacity = capacity;
127		self
128	}
129}
130
131impl<Client> IntoFuture for Connect<Client, Surreal<Client>>
132where
133	Client: Connection,
134{
135	type Output = Result<Surreal<Client>>;
136	type IntoFuture = BoxFuture<'static, Self::Output>;
137
138	fn into_future(self) -> Self::IntoFuture {
139		Box::pin(async move {
140			let endpoint = self.address?;
141			let endpoint_kind = EndpointKind::from(endpoint.url.scheme());
142			let client = Client::connect(endpoint, self.capacity, None).await?;
143			if endpoint_kind.is_remote() {
144				client.verify_server_version().await?;
145			}
146			// Both ends of the channel are still alive at this point
147			client.inner.waiter.0.send(Some(WaitFor::Connection)).ok();
148			Ok(client)
149		})
150	}
151}
152
153impl<Client> IntoFuture for Connect<Client, ()>
154where
155	Client: Connection,
156{
157	type Output = Result<()>;
158	type IntoFuture = BoxFuture<'static, Self::Output>;
159
160	fn into_future(self) -> Self::IntoFuture {
161		Box::pin(async move {
162			// Avoid establishing another connection if already connected
163			if self.surreal.inner.router.get().is_some() {
164				return Err(Error::connection(
165					"Already connected".to_string(),
166					Some(crate::types::ConnectionError::AlreadyConnected),
167				));
168			}
169			let endpoint = self.address?;
170			let endpoint_kind = EndpointKind::from(endpoint.url.scheme());
171			let session_clone = self.surreal.inner.session_clone.clone();
172			let client = Client::connect(endpoint, self.capacity, Some(session_clone)).await?;
173			if endpoint_kind.is_remote() {
174				client.verify_server_version().await?;
175			}
176			let router = client.inner.router.wait().clone();
177			self.surreal.inner.router.set(router).map_err(|_| {
178				Error::connection(
179					"Already connected".to_string(),
180					Some(crate::types::ConnectionError::AlreadyConnected),
181				)
182			})?;
183			// Both ends of the channel are still alive at this point
184			self.surreal.inner.waiter.0.send(Some(WaitFor::Connection)).ok();
185			Ok(())
186		})
187	}
188}
189
190#[derive(Debug, Clone, Copy, Eq, PartialEq, Ord, PartialOrd, Hash)]
191pub(crate) enum ExtraFeatures {
192	Backup,
193	LiveQueries,
194}
195
196#[derive(Debug)]
197#[allow(dead_code)]
198enum SessionId {
199	Initial(Uuid),
200	Clone {
201		old: Uuid,
202		new: Uuid,
203	},
204	Drop(Uuid),
205}
206
207#[derive(Debug, Clone)]
208pub(crate) struct SessionClone {
209	sender: Sender<SessionId>,
210	#[allow(dead_code)]
211	receiver: Receiver<SessionId>,
212}
213
214impl SessionClone {
215	fn new() -> Self {
216		let (sender, receiver) = async_channel::unbounded();
217		Self {
218			sender,
219			receiver,
220		}
221	}
222}
223
224#[derive(Debug)]
225struct Inner {
226	router: OnceLock<Router>,
227	waiter: Waiter,
228	session_clone: SessionClone,
229}
230
231impl Inner {
232	fn clone_session(&self, old: Uuid, new: Uuid) {
233		self.session_clone
234			.sender
235			.try_send(SessionId::Clone {
236				old,
237				new,
238			})
239			.ok();
240	}
241}
242
243/// A database client instance for embedded or remote databases.
244///
245/// See [Running SurrealDB embedded in
246/// Rust](crate#running-surrealdb-embedded-in-rust) for tips on how to optimize
247/// performance for the client when working with embedded instances.
248pub struct Surreal<C: Connection> {
249	inner: Arc<Inner>,
250	session_id: Uuid,
251	engine: PhantomData<C>,
252}
253
254#[doc(hidden)]
255impl<C> From<Arc<Inner>> for Surreal<C>
256where
257	C: Connection,
258{
259	fn from(inner: Arc<Inner>) -> Self {
260		let session_id = Uuid::new_v4();
261		inner.session_clone.sender.try_send(SessionId::Initial(session_id)).ok();
262		Surreal {
263			inner,
264			session_id,
265			engine: PhantomData,
266		}
267	}
268}
269
270#[doc(hidden)]
271impl<C> From<(OnceLock<Router>, Waiter, SessionClone)> for Surreal<C>
272where
273	C: Connection,
274{
275	fn from((router, waiter, session_clone): (OnceLock<Router>, Waiter, SessionClone)) -> Self {
276		Arc::new(Inner {
277			router,
278			waiter,
279			session_clone,
280		})
281		.into()
282	}
283}
284
285#[doc(hidden)]
286impl<C> From<(Router, Waiter, SessionClone)> for Surreal<C>
287where
288	C: Connection,
289{
290	fn from((router, waiter, session_clone): (Router, Waiter, SessionClone)) -> Self {
291		let oncelock = OnceLock::with_value(router);
292		(oncelock, waiter, session_clone).into()
293	}
294}
295
296impl<C> Surreal<C>
297where
298	C: Connection,
299{
300	async fn check_server_version(&self, version: &Version) -> Result<()> {
301		// invalid version requirements should be caught during development
302		let req = VersionReq::parse(SUPPORTED_VERSIONS).expect("valid supported versions");
303		if !req.matches(version) {
304			return Err(Error::internal(format!(
305				"server version `{version}` does not match the range supported by the client `{SUPPORTED_VERSIONS}`"
306			)));
307		}
308
309		Ok(())
310	}
311
312	// If the server denies the `version` RPC method via its capabilities, skip
313	// the version check rather than failing to connect — the operator has
314	// explicitly opted out of exposing the version, and the rest of the
315	// connection is still usable.
316	async fn verify_server_version(&self) -> Result<()> {
317		match self.version().await {
318			Ok(mut version) => {
319				// we would like to be able to connect to pre-releases too
320				version.pre = Default::default();
321				self.check_server_version(&version).await
322			}
323			Err(e) if matches!(e.not_allowed_details(), Some(NotAllowedError::Method { .. })) => {
324				debug!(
325					"Skipping server version check; the `version` RPC method is denied by server capabilities"
326				);
327				Ok(())
328			}
329			Err(e) => Err(e),
330		}
331	}
332}
333
334impl<C> Clone for Surreal<C>
335where
336	C: Connection,
337{
338	fn clone(&self) -> Self {
339		let session_id = Uuid::new_v4();
340		self.inner.clone_session(self.session_id, session_id);
341		Self {
342			inner: Arc::clone(&self.inner),
343			session_id,
344			engine: self.engine,
345		}
346	}
347}
348
349impl<C> Drop for Surreal<C>
350where
351	C: Connection,
352{
353	fn drop(&mut self) {
354		self.inner.session_clone.sender.try_send(SessionId::Drop(self.session_id)).ok();
355	}
356}
357
358impl<C> Debug for Surreal<C>
359where
360	C: Connection,
361{
362	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
363		f.debug_struct("Surreal")
364			.field("router", &self.inner.router)
365			.field("session_id", &self.session_id)
366			.field("engine", &self.engine)
367			.finish()
368	}
369}
370
371trait OnceLockExt {
372	fn with_value(value: Router) -> OnceLock<Router> {
373		let cell = OnceLock::new();
374		match cell.set(value) {
375			Ok(()) => cell,
376			Err(_) => unreachable!("don't have exclusive access to `cell`"),
377		}
378	}
379
380	fn extract(&self) -> Result<&Router>;
381}
382
383impl OnceLockExt for OnceLock<Router> {
384	fn extract(&self) -> Result<&Router> {
385		let router = self.get().ok_or_else(|| {
386			Error::connection(
387				"Connection uninitialised".to_string(),
388				Some(crate::types::ConnectionError::Uninitialised),
389			)
390		})?;
391		Ok(router)
392	}
393}
394
395/// Used by engine code (HTTP, local, any, and WS on wasm) when converting std/io errors.
396#[allow(dead_code)]
397fn std_error_to_types_error(error: impl std::fmt::Display) -> Error {
398	Error::internal(error.to_string())
399}
400
401#[cfg(test)]
402mod tests {
403	use super::*;
404
405	#[test]
406	fn test_supported_versions() {
407		let req = VersionReq::parse(SUPPORTED_VERSIONS).expect("valid supported versions");
408		assert!(req.matches(&Version::parse("3.0.0-alpha.1").unwrap()));
409		assert!(req.matches(&Version::parse("3.0.0-beta.3").unwrap()));
410		assert!(req.matches(&Version::parse("3.0.0-rc.2").unwrap()));
411		assert!(req.matches(&Version::parse("3.0.0").unwrap()));
412		assert!(req.matches(&Version::parse("3.0.1").unwrap()));
413		assert!(req.matches(&Version::parse("3.9.0").unwrap()));
414
415		assert!(!req.matches(&Version::parse("2.9.0").unwrap()));
416		assert!(!req.matches(&Version::parse("4.0.0").unwrap()));
417	}
418}