Skip to main content

sylphx_sdk/
lib.rs

1//! Sylphx Platform SDK — **default app client** for the runtime API.
2//!
3//! ```no_run
4//! use sylphx_sdk::Client;
5//! # async fn demo() -> Result<(), sylphx_sdk::SdkError> {
6//! let client = Client::new(std::env::var("SYLPHX_SECRET_KEY").unwrap(), "my-app")?;
7//! client.kv_set("k", &serde_json::json!(1), None).await?;
8//! # Ok(())
9//! # }
10//! ```
11
12#![forbid(unsafe_code)]
13#![deny(missing_docs)]
14
15use std::time::Duration;
16
17use serde_json::Value;
18use sylphx_api_types::{
19    KvDeleteResponse, KvExistsResponse, KvExpireResponse, KvGetResponse, KvIncrRequest,
20    KvIncrResponse, KvSetRequest, KvSetResponse,
21};
22
23pub use sylphx_sdk_core::{
24    auth_header_pair, baas_base_url, build_connection_url, parse_connection_url,
25    BuildConnectionUrlInput, ConnectionCredentialType, ConnectionEnv, Credential,
26    ParsedConnectionUrl, RetryConfig, SdkError, Transport, TransportConfig, API_TYPES_CONTRACT_PACKAGE,
27    API_TYPES_CONTRACT_REVISION,
28    VerifiedBindingContext, VerifiedBindingContextError, VERIFIED_BINDING_CONTEXT_REVISION,
29    WIRE_CONTRACT_PACKAGE,
30    WIRE_CONTRACT_REVISION,
31};
32
33/// Generated API types (Protobuf → buffa/connectrpc). Prefer this over depending on `sylphx-api-types` directly.
34///
35/// Industry packaging: applications depend on **`sylphx-sdk`**; types are a support projection of schema.
36pub mod types {
37    pub use sylphx_api_types::*;
38}
39
40/// Deprecated alias for [`types`] — prefer `sylphx_sdk::types`.
41#[deprecated(note = "use sylphx_sdk::types")]
42pub mod wire {
43    pub use sylphx_api_types::*;
44}
45
46/// Default Sylphx app client (runtime API).
47#[derive(Debug, Clone)]
48pub struct Client {
49    transport: Transport,
50}
51
52/// Builder for [`Client`].
53#[derive(Debug, Clone)]
54pub struct ClientBuilder {
55    key: String,
56    tenant_slug: String,
57    base_url: Option<String>,
58    timeout: Duration,
59    retry: RetryConfig,
60}
61
62mod baas_surface;
63
64/// Full email send options ([`Client::email_send_with`]).
65pub use baas_surface::EmailSendOptions;
66
67mod rest {
68    use serde_json::{json, Value};
69    use sylphx_sdk_core::SdkError;
70    use sylphx_api_types::{KvGetResponse, KvSetRequest};
71
72    pub fn kv_set_to_rest(req: &KvSetRequest) -> Result<Value, SdkError> {
73        let value: Value = serde_json::from_str(&req.value_json).map_err(|e| {
74            SdkError::Decode(format!("KvSetRequest.value_json is not valid JSON: {e}"))
75        })?;
76        let mut body = json!({"key": req.key, "value": value});
77        if let Some(ex) = req.ex {
78            body["ex"] = json!(ex);
79        }
80        Ok(body)
81    }
82
83    pub fn kv_get_from_rest(body: Value) -> Result<KvGetResponse, SdkError> {
84        let value = body.get("value").cloned().unwrap_or(Value::Null);
85        Ok(KvGetResponse {
86            value_json: serde_json::to_string(&value)
87                .map_err(|e| SdkError::Decode(e.to_string()))?,
88            ttl: body.get("ttl").and_then(|v| v.as_f64()),
89            ..Default::default()
90        })
91    }
92}
93
94impl Client {
95    /// Start a builder with an app secret (`sk_…` / `pk_…`) and tenant slug.
96    pub fn builder(key: impl Into<String>, tenant_slug: impl Into<String>) -> ClientBuilder {
97        ClientBuilder {
98            key: key.into(),
99            tenant_slug: tenant_slug.into(),
100            base_url: None,
101            timeout: Duration::from_secs(30),
102            retry: RetryConfig::default(),
103        }
104    }
105
106    /// Convenience constructor with defaults.
107    pub fn new(key: impl Into<String>, tenant_slug: impl Into<String>) -> Result<Self, SdkError> {
108        Self::builder(key, tenant_slug).build()
109    }
110
111    /// Build from product SSOT connection URL
112    /// (`sylphx://sk_…@<slug>.api.sylphx.com[/v1]`).
113    ///
114    /// Dual-oracle of TS `createServerClient(connectionUrl)` / `parseConnectionUrl`.
115    pub fn from_connection_url(url: &str) -> Result<Self, SdkError> {
116        let parsed = parse_connection_url(url)?;
117        Self::builder(parsed.credential, parsed.slug)
118            .base_url(parsed.api_base_url)
119            .build()
120    }
121
122    /// Build from `SYLPHX_SECRET_URL` when it is a `sylphx://` connection URL.
123    ///
124    /// Returns `Ok(None)` when the env var is unset/empty (fail-closed: no invent).
125    /// Returns `Err` when set but not a valid product connection URL.
126    pub fn try_from_secret_url_env() -> Result<Option<Self>, SdkError> {
127        match std::env::var("SYLPHX_SECRET_URL") {
128            Ok(raw) => {
129                let trimmed = raw.trim();
130                if trimmed.is_empty() {
131                    return Ok(None);
132                }
133                if !trimmed.starts_with("sylphx://") {
134                    return Ok(None);
135                }
136                Ok(Some(Self::from_connection_url(trimmed)?))
137            }
138            Err(_) => Ok(None),
139        }
140    }
141
142    /// KV set.
143    pub async fn kv_set(
144        &self,
145        key: &str,
146        value: &Value,
147        ex: Option<u32>,
148    ) -> Result<KvSetResponse, SdkError> {
149        let req = KvSetRequest {
150            key: key.to_string(),
151            value_json: serde_json::to_string(value)
152                .map_err(|e| SdkError::Decode(e.to_string()))?,
153            ex,
154            ..Default::default()
155        };
156        let body = rest::kv_set_to_rest(&req)?;
157        self.transport
158            .post_json::<Value, KvSetResponse>("/kv", &body, &[])
159            .await
160    }
161
162    /// Get as wire response.
163    pub async fn kv_get_wire(&self, key: &str) -> Result<KvGetResponse, SdkError> {
164        let path = format!("/kv/{}", encode_path_segment(key));
165        let body: Value = self.transport.get_json(&path, &[]).await?;
166        rest::kv_get_from_rest(body)
167    }
168
169    /// Get decoded JSON value.
170    pub async fn kv_get(&self, key: &str) -> Result<Value, SdkError> {
171        let wire = self.kv_get_wire(key).await?;
172        serde_json::from_str(&wire.value_json).map_err(|e| SdkError::Decode(e.to_string()))
173    }
174
175    /// Get with TTL.
176    pub async fn kv_get_with_ttl(&self, key: &str) -> Result<(Value, Option<f64>), SdkError> {
177        let wire = self.kv_get_wire(key).await?;
178        Ok((
179            serde_json::from_str(&wire.value_json).map_err(|e| SdkError::Decode(e.to_string()))?,
180            wire.ttl,
181        ))
182    }
183
184    /// Delete.
185    pub async fn kv_delete(&self, key: &str) -> Result<KvDeleteResponse, SdkError> {
186        let path = format!("/kv/{}", encode_path_segment(key));
187        self.transport
188            .delete_json::<KvDeleteResponse>(&path, &[])
189            .await
190    }
191
192    /// Atomic counter increment (`POST /kv/incr`) — wire [`KvIncrRequest`]/[`KvIncrResponse`].
193    pub async fn kv_incr(&self, key: &str, by: Option<i64>) -> Result<KvIncrResponse, SdkError> {
194        let req = KvIncrRequest {
195            key: key.to_string(),
196            by: by.unwrap_or(1),
197            ..Default::default()
198        };
199        let body = serde_json::json!({
200            "key": req.key,
201            "by": if req.by == 0 { 1 } else { req.by },
202        });
203        self.transport
204            .post_json::<Value, KvIncrResponse>("/kv/incr", &body, &[])
205            .await
206    }
207
208    /// Existence check (`GET /kv/{key}/exists`).
209    pub async fn kv_exists(&self, key: &str) -> Result<KvExistsResponse, SdkError> {
210        let path = format!("/kv/{}/exists", encode_path_segment(key));
211        self.transport
212            .get_json::<KvExistsResponse>(&path, &[])
213            .await
214    }
215
216    /// Set TTL without rewriting value (`POST /kv/expire`).
217    pub async fn kv_expire(&self, key: &str, ex: u32) -> Result<KvExpireResponse, SdkError> {
218        let body = serde_json::json!({ "key": key, "ex": ex });
219        self.transport
220            .post_json::<Value, KvExpireResponse>("/kv/expire", &body, &[])
221            .await
222    }
223}
224
225impl ClientBuilder {
226    /// Base URL override (include `/v1`).
227    pub fn base_url(mut self, url: impl Into<String>) -> Self {
228        self.base_url = Some(url.into());
229        self
230    }
231    /// Timeout.
232    pub fn timeout(mut self, timeout: Duration) -> Self {
233        self.timeout = timeout;
234        self
235    }
236    /// Retry.
237    pub fn retry(mut self, retry: RetryConfig) -> Self {
238        self.retry = retry;
239        self
240    }
241    /// Build client.
242    pub fn build(self) -> Result<Client, SdkError> {
243        let base_url = self
244            .base_url
245            .unwrap_or_else(|| baas_base_url(&self.tenant_slug));
246        Ok(Client {
247            transport: Transport::new(TransportConfig {
248                base_url,
249                credential: Credential::app_secret(self.key)?,
250                timeout: self.timeout,
251                retry: self.retry,
252            })?,
253        })
254    }
255}
256
257/// Percent-encode a path segment using **UTF-8 bytes** (RFC 3986 unreserved).
258///
259/// Public so consumers and tests can assert dual-language parity with TS
260/// `encodePathSegment` (e.g. `"中文"` → `"%E4%B8%AD%E6%96%87"`).
261pub fn encode_path_segment(s: &str) -> String {
262    let mut out = String::with_capacity(s.len());
263    for b in s.bytes() {
264        match b {
265            b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' | b'~' => {
266                out.push(b as char)
267            }
268            _ => out.push_str(&format!("%{b:02X}")),
269        }
270    }
271    out
272}
273
274#[cfg(test)]
275mod tests {
276    use super::*;
277    use sylphx_sdk_mock::WireMockServer;
278
279    #[test]
280    fn from_connection_url_builds_product_client() {
281        let hex = "e".repeat(32);
282        let url = format!("sylphx://sk_prod_{hex}@unit-sdk.api.sylphx.com/v1");
283        let client = Client::from_connection_url(&url).expect("from connection url");
284        // Smoke: construction succeeds for product SSOT shape (slug + base from URL).
285        let _ = client;
286        let parsed = parse_connection_url(&url).unwrap();
287        assert_eq!(parsed.slug, "unit-sdk");
288        assert_eq!(
289            parsed.api_base_url,
290            "https://unit-sdk.api.sylphx.com/v1"
291        );
292    }
293
294    #[test]
295    fn rest_codec_roundtrips_value_json() {
296        let req = KvSetRequest {
297            key: "k".into(),
298            value_json: r#"{"name":"Ada"}"#.into(),
299            ex: Some(60),
300            ..Default::default()
301        };
302        let body = rest::kv_set_to_rest(&req).unwrap();
303        assert_eq!(body["value"]["name"], "Ada");
304    }
305
306    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
307    async fn kv_set_get_delete_against_wire_mock() {
308        let mock = WireMockServer::start().await;
309        let client = Client::builder("sk_test_deadbeef", "demo")
310            .base_url(mock.baas_base_url())
311            .retry(RetryConfig {
312                max_attempts: 1,
313                base_delay: Duration::from_millis(1),
314            })
315            .build()
316            .unwrap();
317        assert_eq!(
318            client
319                .kv_set("user:1", &serde_json::json!({"name": "Ada"}), Some(60))
320                .await
321                .unwrap()
322                .operation
323                .into_option()
324                .expect("operation")
325                .state
326                .to_i32(),
327            5
328        );
329        assert_eq!(client.kv_get("user:1").await.unwrap()["name"], "Ada");
330        assert_eq!(
331            client
332                .kv_delete("user:1")
333                .await
334                .unwrap()
335                .operation
336                .into_option()
337                .expect("operation")
338                .state
339                .to_i32(),
340            5
341        );
342        mock.shutdown().await;
343    }
344
345    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
346    async fn kv_incr_against_wire_mock() {
347        let mock = WireMockServer::start().await;
348        let client = Client::builder("sk_test_deadbeef", "demo")
349            .base_url(mock.baas_base_url())
350            .retry(RetryConfig {
351                max_attempts: 1,
352                base_delay: Duration::from_millis(1),
353            })
354            .build()
355            .unwrap();
356        for expected in [2, 3] {
357            let by = if expected == 2 { Some(2) } else { None };
358            assert_eq!(
359                client
360                    .kv_incr("counter", by)
361                    .await
362                    .unwrap()
363                    .operation
364                    .into_option()
365                    .expect("operation")
366                    .state
367                    .to_i32(),
368                5
369            );
370        }
371        mock.shutdown().await;
372    }
373
374    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
375    async fn kv_exists_and_expire_against_wire_mock() {
376        let mock = WireMockServer::start().await;
377        let client = Client::builder("sk_test_deadbeef", "demo")
378            .base_url(mock.baas_base_url())
379            .retry(RetryConfig {
380                max_attempts: 1,
381                base_delay: Duration::from_millis(1),
382            })
383            .build()
384            .unwrap();
385        assert!(!client.kv_exists("missing").await.unwrap().exists);
386        assert_eq!(
387            client
388                .kv_set("k", &serde_json::json!(1), None)
389                .await
390                .unwrap()
391                .operation
392                .into_option()
393                .expect("operation")
394                .state
395                .to_i32(),
396            5
397        );
398        assert!(client.kv_exists("k").await.unwrap().exists);
399        assert_eq!(
400            client
401                .kv_expire("k", 30)
402                .await
403                .unwrap()
404                .operation
405                .into_option()
406                .expect("operation")
407                .state
408                .to_i32(),
409            5
410        );
411        let (_v, ttl) = client.kv_get_with_ttl("k").await.unwrap();
412        assert_eq!(ttl, Some(30.0));
413        mock.shutdown().await;
414    }
415
416    #[test]
417    fn encode_path_segment_utf8_matches_ts_and_rfc3986() {
418        // Dual-language parity with TS encodePathSegment("中文")
419        assert_eq!(encode_path_segment("中文"), "%E4%B8%AD%E6%96%87");
420        // Must not be UTF-16 unit encoding (%4E2D%6587)
421        assert_ne!(encode_path_segment("中文"), "%4E2D%6587");
422        assert_eq!(encode_path_segment("a/b c"), "a%2Fb%20c");
423        assert_eq!(encode_path_segment("user-1_ok.v~"), "user-1_ok.v~");
424    }
425
426    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
427    async fn kv_get_non_ascii_key_roundtrips_via_utf8_path_encoding() {
428        let mock = WireMockServer::start().await;
429        let client = Client::builder("sk_test_deadbeef", "demo")
430            .base_url(mock.baas_base_url())
431            .retry(RetryConfig {
432                max_attempts: 1,
433                base_delay: Duration::from_millis(1),
434            })
435            .build()
436            .unwrap();
437        // Shipped path uses encode_path_segment for GET /kv/{key}
438        assert_eq!(encode_path_segment("中文"), "%E4%B8%AD%E6%96%87");
439        assert_eq!(
440            client
441                .kv_set("中文", &serde_json::json!({"ok": true}), None)
442                .await
443                .unwrap()
444                .operation
445                .into_option()
446                .expect("operation")
447                .state
448                .to_i32(),
449            5
450        );
451        assert_eq!(client.kv_get("中文").await.unwrap()["ok"], true);
452        mock.shutdown().await;
453    }
454
455    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
456    async fn sandbox_create_against_wire_mock() {
457        let mock = WireMockServer::start().await;
458        let client = Client::builder("sk_test_deadbeef", "demo")
459            .base_url(mock.baas_base_url())
460            .retry(RetryConfig {
461                max_attempts: 1,
462                base_delay: Duration::from_millis(1),
463            })
464            .build()
465            .unwrap();
466        let body = serde_json::json!({ "idleTimeoutMs": 60_000 });
467        let first = client.sandbox_create(&body).await.unwrap();
468        let second = client.sandbox_create(&body).await.unwrap();
469        assert_eq!(first["id"], second["id"]);
470        assert_eq!(first["id"], "sbx_1");
471        assert_eq!(first["status"], "running");
472        assert!(first["endpoint"].as_str().unwrap().contains("exec"));
473        assert_eq!(first["token"], "sbx_tok_1");
474        mock.shutdown().await;
475    }
476
477    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
478    async fn objects_put_get_against_wire_mock() {
479        let mock = WireMockServer::start().await;
480        let client = Client::builder("sk_test_deadbeef", "demo")
481            .base_url(mock.baas_base_url())
482            .retry(RetryConfig {
483                max_attempts: 1,
484                base_delay: Duration::from_millis(1),
485            })
486            .build()
487            .unwrap();
488        let put = client
489            .objects_put("demo.bin", b"hello", Some("text/plain"), None)
490            .await
491            .unwrap();
492        assert_eq!(put["ok"], true);
493        assert_eq!(put["key"], "demo.bin");
494        let first = client.objects_get_bytes("demo.bin", None).await.unwrap();
495        let second = client.objects_get_bytes("demo.bin", None).await.unwrap();
496        assert_eq!(first, second);
497        assert_eq!(first, b"hello");
498        mock.shutdown().await;
499    }
500
501}