Skip to main content

skybase/
lib.rs

1//! # `skybase`
2//!
3//! **The Turn-Key Micro-AppView Engine & Developer Platform for the AT Protocol.**
4//!
5//! `skybase` brings Firebase-like developer ergonomics to the decentralized AT Protocol ecosystem.
6//! Rather than forcing developers to hand-roll custom firehose consumers, backfill pipelines, and
7//! database schemas, `skybase` provides a turn-key, single-binary Micro-AppView engine that ingests
8//! Bluesky Jetstream commits, indexes them into embedded SQLite WAL with JSON1 virtual columns and
9//! FTS5 full-text search, and serves real-time REST and WebSocket live queries down to clients.
10//!
11//! Powered by [`skyauth`], `skybase` supports three distinct operating topologies:
12//! - **Topology A (Client-Sovereign / Zero Custody)**: Client applications write directly to user PDSs;
13//!   `skybase` acts as a zero-custody read and indexing engine holding zero private credentials.
14//! - **Topology B (Daemon-Managed / Bots)**: Server-side daemons hold DPoP sessions with AES-256-GCM encryption at rest.
15//! - **Topology C (Token-Mediated Session Proxy)**: Mediates confidential OAuth sessions for static frontends
16//!   (GitHub Pages, Wisp, Tangled) to prevent 2-week session dropouts.
17
18#![forbid(unsafe_code)]
19#![deny(
20    clippy::all,
21    clippy::unwrap_used,
22    clippy::expect_used,
23    clippy::panic,
24    clippy::todo,
25    clippy::unimplemented,
26    missing_docs,
27    rust_2018_idioms
28)]
29
30pub mod error;
31pub mod index;
32pub mod ingest;
33pub mod repo;
34
35pub use error::{Result, SkybaseError};
36pub use index::{
37    parse_at_uri, BatchStats, BroadcastBus, ChangeNotification, QueryBuilder, QueryOp, RecordInput,
38    RecordRow, RecordStore, RecordStoreConfig, SortDirection, StoreOperation,
39    DEFAULT_BROADCAST_CAPACITY,
40};
41pub use ingest::{
42    build_subscription_url, build_subscription_url_full, normalize_indexed_at,
43    parse_frame_timestamp, parse_jetstream_commit, parse_jetstream_frame, sync_commit_to_store,
44    BackoffManager, CommitOperation, ConsumerStats, CursorTracker, IngesterConfig, JetstreamCommit,
45    JetstreamConsumer, JetstreamConsumerHandle, JetstreamEvent, MockJetstreamServer,
46    MockServerCommand, RawJetstreamCommit, RawJetstreamMessage,
47};
48pub use repo::{
49    format_at_uri, generate_tid, validate_rkey, CreateRecordRequest, CreateRecordResult,
50    DeleteRecordRequest, PdsRepoClient, TidGenerator, XrpcErrorResponse,
51};
52pub use skyauth;
53pub use tokio_util::sync::CancellationToken;
54
55use std::path::{Path, PathBuf};
56use std::sync::Arc;
57
58/// Configuration options for initializing a [`Skybase`] engine instance.
59#[derive(Debug, Clone)]
60pub struct SkybaseConfig {
61    /// OAuth Client ID URI (e.g., `<https://app.example.com/oauth/client-metadata.json>`).
62    pub client_id: String,
63    /// OAuth callback redirect URI (e.g., `<https://app.example.com/oauth/callback>`).
64    pub redirect_uri: String,
65    /// Application display name presented during consent dialogs.
66    pub app_name: String,
67    /// Optional Jetstream WebSocket endpoint for real-time firehose subscription.
68    pub jetstream_endpoint: Option<String>,
69    /// Optional filesystem path to SQLite database. If set, opens a persistent WAL store.
70    pub storage_path: Option<PathBuf>,
71    /// Whether to open an isolated in-memory SQLite database upon initialization.
72    pub in_memory_store: bool,
73    /// Optional explicit configuration for the embedded record store.
74    pub store_config: Option<RecordStoreConfig>,
75    /// Target collection NSIDs to filter for at the edge during Jetstream ingestion.
76    pub wanted_collections: Vec<String>,
77    /// Target repository DIDs to filter for at the edge during Jetstream ingestion.
78    pub wanted_dids: Vec<String>,
79}
80
81impl SkybaseConfig {
82    /// Creates a new [`SkybaseConfig`] with required OAuth parameters.
83    pub fn new(
84        client_id: impl Into<String>,
85        redirect_uri: impl Into<String>,
86        app_name: impl Into<String>,
87    ) -> Self {
88        Self {
89            client_id: client_id.into(),
90            redirect_uri: redirect_uri.into(),
91            app_name: app_name.into(),
92            jetstream_endpoint: None,
93            storage_path: None,
94            in_memory_store: false,
95            store_config: None,
96            wanted_collections: Vec::new(),
97            wanted_dids: Vec::new(),
98        }
99    }
100
101    /// Sets a custom Jetstream WebSocket endpoint for event subscription.
102    pub fn with_jetstream_endpoint(mut self, endpoint: impl Into<String>) -> Self {
103        self.jetstream_endpoint = Some(endpoint.into());
104        self
105    }
106
107    /// Configures a persistent SQLite database file path.
108    pub fn with_storage_path(mut self, path: impl Into<PathBuf>) -> Self {
109        self.storage_path = Some(path.into());
110        self
111    }
112
113    /// Configures an isolated in-memory SQLite database.
114    pub fn with_in_memory_store(mut self) -> Self {
115        self.in_memory_store = true;
116        self
117    }
118
119    /// Sets an explicit [`RecordStoreConfig`].
120    pub fn with_store_config(mut self, config: RecordStoreConfig) -> Self {
121        self.store_config = Some(config);
122        self
123    }
124
125    /// Appends a target collection NSID to filter for at the edge.
126    pub fn with_wanted_collection(mut self, collection: impl Into<String>) -> Self {
127        self.wanted_collections.push(collection.into());
128        self
129    }
130
131    /// Sets target collection NSIDs to filter for at the edge.
132    pub fn with_wanted_collections<I, S>(mut self, collections: I) -> Self
133    where
134        I: IntoIterator<Item = S>,
135        S: Into<String>,
136    {
137        self.wanted_collections = collections.into_iter().map(Into::into).collect();
138        self
139    }
140
141    /// Appends a target DID to filter for at the edge.
142    pub fn with_wanted_did(mut self, did: impl Into<String>) -> Self {
143        self.wanted_dids.push(did.into());
144        self
145    }
146
147    /// Sets target DIDs to filter for at the edge.
148    pub fn with_wanted_dids<I, S>(mut self, dids: I) -> Self
149    where
150        I: IntoIterator<Item = S>,
151        S: Into<String>,
152    {
153        self.wanted_dids = dids.into_iter().map(Into::into).collect();
154        self
155    }
156}
157
158/// The unified Skybase backend engine and client facade.
159#[derive(Clone)]
160pub struct Skybase {
161    config: Arc<SkybaseConfig>,
162    auth_client: Arc<skyauth::client::AtprotoOAuthClient>,
163    store: Option<RecordStore>,
164}
165
166impl Skybase {
167    /// Initializes a new [`Skybase`] engine instance with the given configuration.
168    ///
169    /// If `storage_path`, `in_memory_store`, or `store_config` is configured, initializes
170    /// the embedded SQLite [`RecordStore`] with canonical WAL schemas and indexes.
171    ///
172    /// # Errors
173    /// Returns [`SkybaseError::Config`] if metadata is invalid, [`SkybaseError::Auth`] on OAuth
174    /// client failure, or [`SkybaseError::Storage`] if SQLite initialization fails.
175    pub fn new(config: SkybaseConfig) -> Result<Self> {
176        if config.client_id.trim().is_empty() {
177            return Err(SkybaseError::Config("client_id cannot be empty".into()));
178        }
179        if config.redirect_uri.trim().is_empty() {
180            return Err(SkybaseError::Config("redirect_uri cannot be empty".into()));
181        }
182
183        let metadata =
184            skyauth::client::OAuthClientMetadata::new(&config.client_id, &config.redirect_uri)
185                .with_client_name(&config.app_name);
186
187        let auth_client = skyauth::client::AtprotoOAuthClient::builder()
188            .client_metadata(metadata)
189            .build()
190            .map_err(SkybaseError::Auth)?;
191
192        let store = if let Some(ref store_cfg) = config.store_config {
193            Some(RecordStore::with_config(store_cfg.clone())?)
194        } else if let Some(ref path) = config.storage_path {
195            Some(RecordStore::open(path)?)
196        } else if config.in_memory_store {
197            Some(RecordStore::open_in_memory()?)
198        } else {
199            None
200        };
201
202        Ok(Self {
203            config: Arc::new(config),
204            auth_client: Arc::new(auth_client),
205            store,
206        })
207    }
208
209    /// Convenience constructor initializing [`Skybase`] with an in-memory SQLite store.
210    ///
211    /// # Errors
212    /// Returns [`SkybaseError::Config`] or [`SkybaseError::Auth`] if client metadata is invalid,
213    /// or [`SkybaseError::Storage`] if in-memory database initialization fails.
214    pub fn in_memory(config: SkybaseConfig) -> Result<Self> {
215        Self::new(config.with_in_memory_store())
216    }
217
218    /// Attaches an existing [`RecordStore`] to this [`Skybase`] instance.
219    #[must_use]
220    pub fn with_store(mut self, store: RecordStore) -> Self {
221        self.store = Some(store);
222        self
223    }
224
225    /// Opens or replaces the active persistent [`RecordStore`] at the specified path.
226    ///
227    /// # Errors
228    /// Returns [`SkybaseError::Storage`] if opening the database fails.
229    pub fn open_store(&mut self, path: impl AsRef<Path>) -> Result<RecordStore> {
230        let store = RecordStore::open(path)?;
231        self.store = Some(store.clone());
232        Ok(store)
233    }
234
235    /// Opens or replaces the active [`RecordStore`] with an isolated in-memory database.
236    ///
237    /// # Errors
238    /// Returns [`SkybaseError::Storage`] if opening the in-memory database fails.
239    pub fn open_in_memory_store(&mut self) -> Result<RecordStore> {
240        let store = RecordStore::open_in_memory()?;
241        self.store = Some(store.clone());
242        Ok(store)
243    }
244
245    /// Returns a reference to the active [`SkybaseConfig`].
246    #[must_use]
247    pub fn config(&self) -> &SkybaseConfig {
248        &self.config
249    }
250
251    /// Accesses the underlying [`skyauth::client::AtprotoOAuthClient`] identity and authentication engine.
252    #[must_use]
253    pub fn auth(&self) -> &skyauth::client::AtprotoOAuthClient {
254        &self.auth_client
255    }
256
257    /// Returns a reference to the active [`RecordStore`], if initialized.
258    #[must_use]
259    pub fn store(&self) -> Option<&RecordStore> {
260        self.store.as_ref()
261    }
262
263    /// Returns a reference to the active [`RecordStore`] or returns [`SkybaseError::Config`].
264    ///
265    /// # Errors
266    /// Returns [`SkybaseError::Config`] if no record store is attached.
267    pub fn require_store(&self) -> Result<&RecordStore> {
268        self.store.as_ref().ok_or_else(|| {
269            SkybaseError::Config("RecordStore is not initialized on this Skybase instance".into())
270        })
271    }
272
273    /// Initiates a structured [`QueryBuilder`] scoped to the given collection NSID.
274    ///
275    /// # Errors
276    /// Returns [`SkybaseError::Config`] if no record store is attached.
277    pub fn query(&self, collection: impl Into<String>) -> Result<QueryBuilder<'_>> {
278        Ok(self.require_store()?.query(collection))
279    }
280
281    /// Initiates a structured [`QueryBuilder`] scoped to the given collection NSID (alias for [`query`](Self::query)).
282    ///
283    /// # Errors
284    /// Returns [`SkybaseError::Config`] if no record store is attached.
285    pub fn collection(&self, collection: impl Into<String>) -> Result<QueryBuilder<'_>> {
286        self.query(collection)
287    }
288
289    /// Subscribes to the live [`ChangeNotification`] broadcast stream.
290    ///
291    /// # Errors
292    /// Returns [`SkybaseError::Config`] if no record store is attached.
293    pub fn subscribe(&self) -> Result<tokio::sync::broadcast::Receiver<ChangeNotification>> {
294        Ok(self.require_store()?.subscribe())
295    }
296
297    /// Builds a [`JetstreamConsumer`] using the configured `jetstream_endpoint` and `wanted_collections`.
298    ///
299    /// # Errors
300    /// Returns [`SkybaseError::Config`] if `jetstream_endpoint` or `RecordStore` is not configured.
301    pub fn consumer(&self) -> Result<JetstreamConsumer> {
302        let endpoint = self.config.jetstream_endpoint.as_ref().ok_or_else(|| {
303            SkybaseError::Config(
304                "Cannot build JetstreamConsumer: 'jetstream_endpoint' is not configured".into(),
305            )
306        })?;
307
308        let mut config = IngesterConfig::new(endpoint);
309        if !self.config.wanted_collections.is_empty() {
310            config = config.with_collections(self.config.wanted_collections.clone());
311        }
312        if !self.config.wanted_dids.is_empty() {
313            config = config.with_dids(self.config.wanted_dids.clone());
314        }
315
316        self.consumer_with_config(config)
317    }
318
319    /// Builds a [`JetstreamConsumer`] with custom [`IngesterConfig`] bound to the internal [`RecordStore`].
320    ///
321    /// # Errors
322    /// Returns [`SkybaseError::Config`] if no record store is attached.
323    pub fn consumer_with_config(&self, config: IngesterConfig) -> Result<JetstreamConsumer> {
324        let store = self.require_store()?.clone();
325        Ok(JetstreamConsumer::new(config, store))
326    }
327
328    /// Spawns the default [`JetstreamConsumer`] as a managed background task.
329    ///
330    /// # Errors
331    /// Returns [`SkybaseError::Config`] if `jetstream_endpoint` or `RecordStore` is not configured.
332    pub fn start_consumer(
333        &self,
334        cancel: tokio_util::sync::CancellationToken,
335    ) -> Result<JetstreamConsumerHandle> {
336        let consumer = self.consumer()?;
337        Ok(consumer.start(cancel))
338    }
339
340    /// Spawns a [`JetstreamConsumer`] with custom configuration as a managed background task.
341    ///
342    /// # Errors
343    /// Returns [`SkybaseError::Config`] if no record store is attached.
344    pub fn start_consumer_with_config(
345        &self,
346        config: IngesterConfig,
347        cancel: tokio_util::sync::CancellationToken,
348    ) -> Result<JetstreamConsumerHandle> {
349        let consumer = self.consumer_with_config(config)?;
350        Ok(consumer.start(cancel))
351    }
352
353    /// Creates a sovereign PDS repository client bound to the provided OAuth session.
354    ///
355    /// # Errors
356    /// Returns [`SkybaseError::Network`] if HTTP client initialization fails.
357    pub fn repo_client(
358        &self,
359        session: Arc<skyauth::session::OAuthSession>,
360    ) -> Result<PdsRepoClient> {
361        PdsRepoClient::new(session, Arc::clone(&self.auth_client))
362    }
363
364    /// Creates a sovereign PDS repository client from explicit credentials or mock endpoint tokens.
365    ///
366    /// Leverages the facade's internal OAuth client for DPoP proof generation and nonce caching.
367    ///
368    /// # Errors
369    /// Returns [`SkybaseError::Auth`] if session creation fails, or [`SkybaseError::Network`]
370    /// if HTTP client creation fails.
371    pub fn repo_client_from_credentials(
372        &self,
373        pds_endpoint: impl Into<String>,
374        repo_did: impl Into<String>,
375        access_token: impl Into<String>,
376    ) -> Result<PdsRepoClient> {
377        let endpoint = pds_endpoint.into();
378        let did = repo_did.into();
379        let token = access_token.into();
380
381        let session = skyauth::session::OAuthSession::new(
382            did,
383            token,
384            None,
385            "DPoP",
386            None,
387            None,
388            skyauth::dpop::DPoPKey::generate(),
389            Some(endpoint),
390            None,
391            None,
392        )
393        .map_err(SkybaseError::Auth)?;
394
395        PdsRepoClient::new(Arc::new(session), Arc::clone(&self.auth_client))
396    }
397}
398
399#[cfg(test)]
400#[allow(clippy::unwrap_used, clippy::expect_used, clippy::panic, missing_docs)]
401mod tests {
402    use super::*;
403
404    #[test]
405    fn test_skybase_initialization() {
406        let config = SkybaseConfig::new(
407            "https://app.example.com/oauth/client-metadata.json",
408            "https://app.example.com/oauth/callback",
409            "Test App",
410        );
411
412        let skybase = Skybase::new(config).expect("Skybase should initialize successfully");
413        assert_eq!(skybase.config().app_name, "Test App");
414    }
415
416    #[test]
417    fn test_skybase_config_validation() {
418        let invalid_config = SkybaseConfig::new("", "https://app.example.com/callback", "App");
419        let result = Skybase::new(invalid_config);
420        assert!(matches!(result, Err(SkybaseError::Config(_))));
421    }
422
423    #[test]
424    fn test_skybase_repo_client_creation() {
425        let config = SkybaseConfig::new(
426            "https://app.example.com/oauth/client-metadata.json",
427            "https://app.example.com/oauth/callback",
428            "Test App",
429        );
430        let skybase = Skybase::new(config).expect("Skybase init failed");
431
432        let session = skyauth::session::OAuthSession::new(
433            "did:plc:alice",
434            "access_token",
435            None,
436            "DPoP",
437            None,
438            None,
439            skyauth::dpop::DPoPKey::generate(),
440            Some("https://pds.example.com".into()),
441            None,
442            None,
443        )
444        .expect("session creation failed");
445
446        let client = skybase.repo_client(Arc::new(session)).expect("repo_client");
447        assert_eq!(client.did(), "did:plc:alice");
448        assert_eq!(
449            client.pds_endpoint().expect("endpoint"),
450            "https://pds.example.com"
451        );
452    }
453
454    #[test]
455    fn test_skybase_config_builders() {
456        let path = std::path::PathBuf::from("/tmp/skybase_test.db");
457        let store_cfg = RecordStoreConfig::in_memory();
458        let config = SkybaseConfig::new(
459            "https://app.example.com/oauth/client-metadata.json",
460            "https://app.example.com/oauth/callback",
461            "Builder Test App",
462        )
463        .with_jetstream_endpoint("wss://jetstream.example.com/subscribe")
464        .with_storage_path(&path)
465        .with_in_memory_store()
466        .with_store_config(store_cfg)
467        .with_wanted_collections(vec!["app.bsky.actor.profile", "app.bsky.feed.like"])
468        .with_wanted_collection("app.bsky.feed.post")
469        .with_wanted_dids(vec!["did:plc:bob", "did:plc:charlie"])
470        .with_wanted_did("did:plc:alice");
471
472        assert_eq!(
473            config.jetstream_endpoint.as_deref(),
474            Some("wss://jetstream.example.com/subscribe")
475        );
476        assert_eq!(config.storage_path.as_deref(), Some(path.as_path()));
477        assert!(config.in_memory_store);
478        assert!(config.store_config.is_some());
479        assert_eq!(config.wanted_collections.len(), 3);
480        assert_eq!(config.wanted_dids.len(), 3);
481    }
482
483    #[test]
484    fn test_skybase_in_memory_and_store_delegation() {
485        let config = SkybaseConfig::new(
486            "https://app.example.com/oauth/client-metadata.json",
487            "https://app.example.com/oauth/callback",
488            "In Memory App",
489        );
490
491        let skybase = Skybase::in_memory(config).expect("in_memory init failed");
492        assert!(skybase.store().is_some());
493        assert!(skybase.require_store().is_ok());
494
495        // Test query and collection builder
496        let q1 = skybase.query("app.bsky.feed.post").expect("query failed");
497        let (sql1, _) = q1.build_sql().expect("sql build failed");
498        assert!(sql1.contains("WHERE collection = ?"));
499
500        let q2 = skybase
501            .collection("app.bsky.feed.post")
502            .expect("collection failed");
503        let (sql2, _) = q2.build_sql().expect("sql build failed");
504        assert_eq!(sql1, sql2);
505
506        // Test subscribe
507        let mut rx = skybase.subscribe().expect("subscribe failed");
508        let input = RecordInput::new(
509            "did:plc:alice",
510            "app.bsky.feed.post",
511            "post_facade_1",
512            "cid_1",
513            serde_json::json!({"text": "Hello facade"}),
514            1_000,
515        );
516        skybase
517            .require_store()
518            .unwrap()
519            .upsert_record(&input)
520            .expect("upsert failed");
521
522        let event = rx.try_recv().expect("broadcast event expected");
523        match event {
524            ChangeNotification::Upsert(row) => {
525                assert_eq!(row.uri, input.uri);
526                assert_eq!(row.record_json["text"], "Hello facade");
527            }
528            _ => panic!("Expected Upsert event"),
529        }
530    }
531
532    #[test]
533    fn test_skybase_uninitialized_store_errors() {
534        let config = SkybaseConfig::new(
535            "https://app.example.com/oauth/client-metadata.json",
536            "https://app.example.com/oauth/callback",
537            "No Store App",
538        );
539        let skybase = Skybase::new(config).expect("init failed");
540        assert!(skybase.store().is_none());
541        assert!(matches!(
542            skybase.require_store(),
543            Err(SkybaseError::Config(_))
544        ));
545        assert!(matches!(skybase.query("col"), Err(SkybaseError::Config(_))));
546        assert!(matches!(
547            skybase.collection("col"),
548            Err(SkybaseError::Config(_))
549        ));
550        assert!(matches!(skybase.subscribe(), Err(SkybaseError::Config(_))));
551        assert!(matches!(skybase.consumer(), Err(SkybaseError::Config(_))));
552    }
553
554    #[test]
555    fn test_skybase_with_store_and_open_store() {
556        let config = SkybaseConfig::new(
557            "https://app.example.com/oauth/client-metadata.json",
558            "https://app.example.com/oauth/callback",
559            "Attach Store App",
560        );
561        let mut skybase = Skybase::new(config).expect("init failed");
562        assert!(skybase.store().is_none());
563
564        let store = RecordStore::open_in_memory().expect("store init failed");
565        skybase = skybase.with_store(store);
566        assert!(skybase.store().is_some());
567
568        // Replace with open_in_memory_store
569        let store2 = skybase
570            .open_in_memory_store()
571            .expect("open_in_memory_store failed");
572        assert!(skybase.store().is_some());
573        let _ = store2;
574
575        // Replace with open_store in a tempdir
576        let temp_dir = tempfile::tempdir().expect("tempdir failed");
577        let db_path = temp_dir.path().join("skybase_facade.db");
578        let store3 = skybase.open_store(&db_path).expect("open_store failed");
579        assert!(skybase.store().is_some());
580        let _ = store3;
581    }
582
583    #[tokio::test]
584    async fn test_skybase_consumer_wiring() {
585        let config = SkybaseConfig::new(
586            "https://app.example.com/oauth/client-metadata.json",
587            "https://app.example.com/oauth/callback",
588            "Consumer App",
589        )
590        .with_jetstream_endpoint("wss://jetstream.example.com/subscribe")
591        .with_in_memory_store()
592        .with_wanted_collection("app.bsky.feed.post")
593        .with_wanted_did("did:plc:alice");
594
595        let skybase = Skybase::new(config).expect("init failed");
596        let consumer = skybase.consumer().expect("consumer build failed");
597        assert_eq!(
598            consumer.config().wanted_collections,
599            vec!["app.bsky.feed.post"]
600        );
601        assert_eq!(consumer.config().wanted_dids, vec!["did:plc:alice"]);
602
603        let cancel = CancellationToken::new();
604        let handle = skybase
605            .start_consumer(cancel.clone())
606            .expect("start_consumer failed");
607        handle.stop();
608        let _ = handle.join().await;
609    }
610
611    #[test]
612    fn test_skybase_repo_client_from_credentials() {
613        let config = SkybaseConfig::new(
614            "https://app.example.com/oauth/client-metadata.json",
615            "https://app.example.com/oauth/callback",
616            "Repo App",
617        );
618        let skybase = Skybase::new(config).expect("init failed");
619        let client = skybase
620            .repo_client_from_credentials(
621                "https://pds.example.com",
622                "did:plc:bob",
623                "dpop_access_token_123",
624            )
625            .expect("repo_client_from_credentials failed");
626
627        assert_eq!(client.did(), "did:plc:bob");
628        assert_eq!(
629            client.pds_endpoint().expect("endpoint"),
630            "https://pds.example.com"
631        );
632    }
633}