Skip to main content

sylphx_apps_sdk/
lib.rs

1//! Sylphx Platform SDK — Product Contract projection.
2//!
3//! Sole public schema: project, Binding, Service spec, optional suite door.
4//! Default client is the Platform proto (`https://api.sylphx.com/v1`), not
5//! runtime BaaS (kv/email/schedules) and not the cluster SDK.
6//!
7//! Discovery is Binding `api_base`. This crate does not compile sibling
8//! product schemas, predecessor product-API peels, or customer Schedule as
9//! Platform proto. Customer Schedule is Compute, not this SDK.
10//!
11//! ```no_run
12//! use sylphx_apps_sdk::Client;
13//! # async fn demo() -> Result<(), sylphx_apps_sdk::SdkError> {
14//! let client = Client::new(std::env::var("SYLPHX_TOKEN").unwrap())?;
15//! let _projects = client.list_projects(None, None).await?;
16//! # Ok(())
17//! # }
18//! ```
19
20#![forbid(unsafe_code)]
21#![deny(missing_docs)]
22
23pub use sylphx_apps_sdk_management::{
24    AgentComputerControlClient, AgentComputerDataClient, AgentComputerMediaClient,
25    ArtifactIngestClient, DeliveryClient, ListOptions, ManagementClient as Client,
26    ManagementClientBuilder as ClientBuilder, AGENT_COMPUTER_DESCRIPTOR_GRAPH_SHA256,
27    AGENT_COMPUTER_DESCRIPTOR_ROOT_FILE, AGENT_COMPUTER_DESCRIPTOR_ROOT_SHA256,
28};
29
30pub use sylphx_apps_sdk_core::{
31    auth_header_pair, build_connection_url, normalize_management_base_url, parse_connection_url,
32    register_wire_types,
33    BuildConnectionUrlInput, ConnectionCredentialType, ConnectionEnv, Credential,
34    ParsedConnectionUrl, RetryConfig, SdkError, Transport, TransportConfig, VerifiedBindingContext,
35    VerifiedBindingContextError, API_TYPES_CONTRACT_PACKAGE, API_TYPES_CONTRACT_REVISION,
36    DEFAULT_MANAGEMENT_BASE_URL, VERIFIED_BINDING_CONTEXT_REVISION, WIRE_CONTRACT_PACKAGE,
37    WIRE_CONTRACT_REVISION,
38};
39
40/// Product Contract wire types (Protobuf -> buffa/connectrpc).
41///
42/// Applications depend on **`sylphx-apps-sdk`**; types are a support projection.
43pub mod types {
44    pub use sylphx_apps_api_types::{
45        BindResourceResponse, CreateFlagResponse, CreateResourceResponse, DeleteEnvVarResponse,
46        DeleteResourceResponse, Deployment, EnvVar, Environment, GetProjectStatusResponse,
47        HealthResponse, ListDeploymentsResponse, ListEnvVarsResponse, ListEnvironmentsResponse,
48        ListFlagsResponse, ListLogsResponse, ListProjectDomainsResponse,
49        ListProjectServicesResponse, ListProjectsResponse, ListResourcesResponse, LogLine,
50        OrganizationRef, PageRequest, Project, ProjectDomain, ProjectService, Resource,
51        SetEnvVarResponse, WhoAmIResponse,
52    };
53    // Canonical delivery resources, operations, policy, and evidence values.
54    pub use sylphx_apps_api_types::{
55        delivery_evidence_subject, AdmissionDecision, CreateDeploymentRequest,
56        CreateDeploymentResponse, CreateDeploymentResult, CreateReleaseRequest,
57        CreateReleaseResponse, CreateReleaseResult, DeliveryArtifactEvidenceSubject,
58        DeliveryArtifactSubject, DeliveryAttemptPolicy, DeliveryBuildProvenance,
59        DeliveryDecisionOutcome, DeliveryEnvironmentSubject, DeliveryEvaluationFailureCode,
60        DeliveryEvidenceSelector, DeliveryEvidenceState, DeliveryEvidenceSubject,
61        DeliveryExecutionAttempt, DeliveryExecutionAuthorityRule, DeliveryExecutionOrdering,
62        DeliveryMemberConfiguration, DeliveryMigrationReference, DeliveryOperation, DeliveryPolicy,
63        DeliveryPolicyPatch, DeliveryProofConclusion, DeliveryProofRequirements,
64        DeliveryProofStage, DeliveryReceiptAuthentication, DeliveryRequestErrorCode,
65        DeliveryRequestErrorDetail, DeliveryRequirementFailure, DeliveryRequirementMatch,
66        DeliverySecretVersionReference, DeliverySourceSubject, DeliverySubjectKind,
67        DeliveryTrustedIdentities, EvidenceReceipt, GetDeliveryPolicyRequest,
68        GetDeliveryPolicyResponse, GetDeploymentRequest, GetDeploymentResponse, GetReleaseRequest,
69        GetReleaseResponse, ListDeploymentsRequest, ListReleaseDecisionsRequest,
70        ListReleaseDecisionsResponse, ListReleaseReceiptsRequest, ListReleaseReceiptsResponse,
71        ListReleasesRequest, ListReleasesResponse, Operation, OperationMode, OperationState,
72        PatchDeliveryPolicyRequest, PatchDeliveryPolicyResponse, PatchDeliveryPolicyResult,
73        PromoteMode, PromoteReleaseRequest, PromoteReleaseResponse, PromoteReleaseResult,
74        ProofRequirement, Release, ReleaseMember, ReleaseMemberSelection, ReleaseMemberStatus,
75        ReleaseStatus,
76    };
77}
78
79/// Build a client from a caller-discovered product API base.
80///
81/// Callers pass the discovered base. This helper does not invent a peel
82/// predecessor product-API peel hostname.
83pub fn client_from_api_base(
84    token: impl Into<String>,
85    api_base: impl Into<String>,
86) -> Result<Client, SdkError> {
87    Client::builder(token).base_url(api_base).build()
88}
89
90#[cfg(test)]
91mod tests {
92    use super::*;
93    use std::io::{Read, Write};
94    use std::net::TcpListener;
95    use std::time::{Duration, Instant};
96    use sylphx_apps_sdk_mock::WireMockServer;
97
98    fn request_target(req: &str) -> &str {
99        req.lines()
100            .next()
101            .unwrap_or("")
102            .split_whitespace()
103            .nth(1)
104            .unwrap_or("")
105    }
106
107    fn request_host(req: &str) -> &str {
108        req.lines()
109            .find_map(|line| {
110                let (name, value) = line.split_once(':')?;
111                name.eq_ignore_ascii_case("host").then(|| value.trim())
112            })
113            .unwrap_or("")
114    }
115
116    fn leftover_baas_target(target: &str) -> bool {
117        target.contains("/schedules")
118            || target.contains("/kv")
119            || target.contains("cron_list")
120            || target.contains("kv_set")
121    }
122
123    fn read_http_headers(stream: &mut std::net::TcpStream) -> String {
124        let mut buf = Vec::new();
125        let mut tmp = [0u8; 512];
126        loop {
127            match stream.read(&mut tmp) {
128                Ok(0) => break,
129                Ok(n) => {
130                    buf.extend_from_slice(&tmp[..n]);
131                    if buf.windows(4).any(|window| window == b"\r\n\r\n") {
132                        break;
133                    }
134                }
135                Err(_) => break,
136            }
137        }
138        String::from_utf8_lossy(&buf).into_owned()
139    }
140
141    fn spawn_json_server(
142        n: usize,
143        route: fn(&str) -> (u16, &'static str),
144    ) -> (
145        String,
146        std::sync::mpsc::Receiver<String>,
147        std::thread::JoinHandle<()>,
148    ) {
149        let listener = TcpListener::bind("127.0.0.1:0").unwrap();
150        listener.set_nonblocking(true).unwrap();
151        let addr = listener.local_addr().unwrap();
152        let (tx, rx) = std::sync::mpsc::channel();
153        let join = std::thread::spawn(move || {
154            let deadline = Instant::now() + Duration::from_secs(4);
155            let mut got = 0usize;
156            while got < n && Instant::now() < deadline {
157                match listener.accept() {
158                    Ok((mut stream, _)) => {
159                        let _ = stream.set_read_timeout(Some(Duration::from_secs(2)));
160                        let _ = stream.set_write_timeout(Some(Duration::from_secs(2)));
161                        let req = read_http_headers(&mut stream);
162                        let (status, body) = route(&req);
163                        let reason = match status {
164                            200 => "OK",
165                            410 => "Gone",
166                            _ => "Not Found",
167                        };
168                        let resp = format!(
169                            "HTTP/1.1 {status} {reason}\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}",
170                            body.len()
171                        );
172                        let _ = stream.write_all(resp.as_bytes());
173                        let _ = tx.send(req);
174                        got += 1;
175                    }
176                    Err(err) if err.kind() == std::io::ErrorKind::WouldBlock => {
177                        std::thread::sleep(Duration::from_millis(5));
178                    }
179                    Err(_) => break,
180                }
181            }
182        });
183        (format!("http://{addr}/v1"), rx, join)
184    }
185
186    fn management_retry() -> RetryConfig {
187        RetryConfig {
188            max_attempts: 1,
189            base_delay: Duration::from_millis(1),
190        }
191    }
192
193    #[test]
194    fn default_client_targets_platform_management_base() {
195        assert_eq!(DEFAULT_MANAGEMENT_BASE_URL, "https://api.sylphx.com/v1");
196        let client = Client::new("svc_test").expect("client");
197        let _ = client;
198    }
199
200    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
201    async fn caller_api_base_does_not_invent_peel_hostname() {
202        let mock = WireMockServer::start().await;
203        let api_base = mock.management_base_url();
204        assert!(
205            api_base.starts_with("http://127.0.0.1:"),
206            "caller api_base must be the local management mock, got {api_base}"
207        );
208        let client = client_from_api_base("svc_test", &api_base).expect("binding api_base");
209        let projects =
210            tokio::time::timeout(Duration::from_secs(3), client.list_projects(None, None))
211                .await
212                .expect("caller api_base was not used; generated client invented a peel hostname")
213                .expect("list on caller api_base");
214        assert!(
215            projects
216                .data
217                .iter()
218                .any(|p| p.id == "prj_demo" || p.slug == "demo"),
219            "expected Product Contract project row on caller api_base, got {projects:?}"
220        );
221        mock.shutdown().await;
222    }
223
224    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
225    async fn facade_reads_completed_build_provenance_through_the_delivery_client() {
226        let mock = WireMockServer::start().await;
227        let client = client_from_api_base("svc_test", mock.management_base_url()).unwrap();
228        let delivery: DeliveryClient = client.delivery();
229        let deployments = delivery
230            .list_deployments(types::ListDeploymentsRequest {
231                project_id: "prj_demo".into(),
232                service_id: Some("svc_web".into()),
233                ..Default::default()
234            })
235            .await
236            .unwrap();
237        assert_eq!(deployments.data.len(), 1);
238        let deployment = &deployments.data[0];
239        assert_eq!(deployment.id, "dep_1");
240        assert_eq!(deployment.service_id, "svc_web");
241        assert_eq!(deployment.organization_id, "org_1");
242        assert_eq!(
243            deployment.provenance.build_id,
244            "11111111-1111-4111-8111-111111111111"
245        );
246        assert_eq!(deployment.provenance.source.commit_sha, "a".repeat(40));
247        assert_eq!(
248            deployment.provenance.artifact.digest,
249            format!("sha256:{}", "c".repeat(64))
250        );
251        assert_eq!(deployment.provenance.builder_id, "builder_test");
252        assert_eq!(
253            deployment.provenance.authentication.verifier,
254            "provenance_test"
255        );
256        assert!(deployment.created_time.is_set());
257        let readback = delivery
258            .get_deployment(types::GetDeploymentRequest {
259                project_id: "prj_demo".into(),
260                deployment_id: deployment.id.clone(),
261                ..Default::default()
262            })
263            .await
264            .unwrap();
265        assert_eq!(readback.deployment.provenance, deployment.provenance);
266        let unmatched = delivery
267            .list_deployments(types::ListDeploymentsRequest {
268                project_id: "prj_demo".into(),
269                service_id: Some("svc_other".into()),
270                ..Default::default()
271            })
272            .await
273            .unwrap();
274        assert!(unmatched.data.is_empty());
275        mock.shutdown().await;
276    }
277
278    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
279    async fn default_client_lists_projects_and_services() {
280        let mock = WireMockServer::start().await;
281        let client = Client::builder("svc_test")
282            .base_url(mock.management_base_url())
283            .retry(management_retry())
284            .build()
285            .unwrap();
286        let projects = client.list_projects(None, None).await.unwrap();
287        assert!(
288            projects
289                .data
290                .iter()
291                .any(|p| p.id == "prj_demo" || p.slug == "demo"),
292            "expected Product Contract project row, got {projects:?}"
293        );
294        let project = client.get_project("prj_demo", None).await.unwrap();
295        assert_eq!(project.id, "prj_demo");
296        mock.shutdown().await;
297
298        let (base, rx, join) = spawn_json_server(1, |req| {
299            let target = request_target(req);
300            if leftover_baas_target(target) {
301                (
302                    410,
303                    r#"{"error":{"code":"gone","message":"leftover BaaS schedule/kv"}}"#,
304                )
305            } else if target.starts_with("/v1/projects/prj_demo/services") {
306                (
307                    200,
308                    r#"{"object":"list","data":[{"id":"svc_web","name":"web","slug":"web","projectId":"prj_demo"}]}"#,
309                )
310            } else {
311                (404, r#"{"error":{"code":"not_found"}}"#)
312            }
313        });
314        let client = Client::builder("svc_test")
315            .base_url(&base)
316            .timeout(Duration::from_secs(2))
317            .retry(management_retry())
318            .build()
319            .unwrap();
320        let services = tokio::time::timeout(
321            Duration::from_secs(3),
322            client.list_project_services("prj_demo", None),
323        )
324        .await
325        .expect("service list did not reach caller management api_base")
326        .expect("list project services");
327        assert!(
328            services
329                .data
330                .iter()
331                .any(|s| s.id == "svc_web" || s.slug == "web"),
332            "expected Product Contract service row, got {services:?}"
333        );
334        let req = rx
335            .recv_timeout(Duration::from_secs(2))
336            .expect("service request");
337        let target = request_target(&req);
338        let host = request_host(&req);
339        assert_eq!(target, "/v1/projects/prj_demo/services");
340        assert!(
341            host.starts_with("127.0.0.1:"),
342            "generated client invented a peel hostname, Host={host}"
343        );
344        assert!(
345            !leftover_baas_target(target),
346            "generated client targeted leftover BaaS schedule/kv: {target}"
347        );
348        join.join().expect("service server");
349    }
350}