1#![recursion_limit = "256"]
2
3#![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)]
34pub 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
57pub 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
77type Waiter = (watch::Sender<Option<WaitFor>>, watch::Receiver<Option<WaitFor>>);
79
80const SUPPORTED_VERSIONS: &str = ">=3.0.0-alpha.1, <4.0.0";
81
82pub trait Connection: conn::Sealed {}
84
85#[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 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 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 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 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
243pub 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 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 async fn verify_server_version(&self) -> Result<()> {
317 match self.version().await {
318 Ok(mut version) => {
319 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#[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}