1#![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
33pub mod types {
37 pub use sylphx_api_types::*;
38}
39
40#[deprecated(note = "use sylphx_sdk::types")]
42pub mod wire {
43 pub use sylphx_api_types::*;
44}
45
46#[derive(Debug, Clone)]
48pub struct Client {
49 transport: Transport,
50}
51
52#[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
64pub 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 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 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 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 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 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 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 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 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 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 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 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 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 pub fn base_url(mut self, url: impl Into<String>) -> Self {
228 self.base_url = Some(url.into());
229 self
230 }
231 pub fn timeout(mut self, timeout: Duration) -> Self {
233 self.timeout = timeout;
234 self
235 }
236 pub fn retry(mut self, retry: RetryConfig) -> Self {
238 self.retry = retry;
239 self
240 }
241 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
257pub 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 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 assert_eq!(encode_path_segment("中文"), "%E4%B8%AD%E6%96%87");
420 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 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}