Skip to main content

sylphx_apps_api_types/
lib.rs

1//! Sylphx Platform wire contract types.
2//!
3//! **Authority:** `api/proto/sylphx/app/v1/*.proto` via Protobuf + Buf.
4//! These types are generated by `build.rs` (**buffa + connectrpc-build**) from
5//! that SSOT. Do not add hand-written request/response structs for the same
6//! payloads elsewhere.
7
8#![forbid(unsafe_code)]
9#![deny(missing_docs)]
10
11/// Generated buffa + connectrpc types for `sylphx.app.v1`.
12#[allow(missing_docs, clippy::all, refining_impl_trait)]
13pub mod proto {
14    connectrpc::include_generated!();
15}
16
17/// Stable re-export for `sylphx_apps_api_types::app::v1`..
18pub mod app {
19    /// Versioned wire package `sylphx.app.v1`.
20    pub mod v1 {
21        pub use crate::proto::sylphx::app::v1::*;
22    }
23}
24
25pub use app::v1::*;
26
27/// Canonical ProtoJSON well-known types used by generated wire messages.
28pub mod protojson_wkt;
29
30/// Explicit ProtoJSON helpers for public project manifests (ADR-3927).
31pub mod manifest_protojson;
32
33/// Exact Rust request-extension type shared by Platform admission middleware
34/// and product Connect handlers. Do not define a local lookalike.
35pub mod verified_binding_context;
36pub use verified_binding_context::{
37    VerifiedBindingContext, VerifiedBindingContextError, VERIFIED_BINDING_CONTEXT_REVISION,
38};
39
40mod generated_agent_computer_validation;
41pub use generated_agent_computer_validation::{
42    decode_and_validate_computer_lease_protojson,
43    decode_and_validate_computer_profile_protojson, validate_computer_lease,
44    validate_computer_profile, AgentComputerValidationContext, AgentComputerValidationError,
45    AgentComputerValidationViolation, AgentComputerValueError,
46    AGENT_COMPUTER_VALIDATION_IDENTITY_SHA256, AGENT_COMPUTER_VALIDATION_TARGETS,
47};
48
49/// Schema identity for publish/admission evidence.
50pub const CONTRACT_PACKAGE: &str = "sylphx.app.v1";
51
52/// Human-readable contract revision for this crate release.
53pub const CONTRACT_REVISION: &str = env!("SYLPHX_AGENT_COMPUTER_CONTRACT_REVISION");
54
55/// SHA-256 identity binding the semantic revision, crate artifact, descriptors,
56/// and management-rooted module graph.
57pub const AGENT_COMPUTER_CONTRACT_IDENTITY_SHA256: &str =
58    env!("SYLPHX_AGENT_COMPUTER_CONTRACT_IDENTITY_SHA256");
59
60/// SHA-256 identity of the Buf descriptor that generated Agent Computer wire types.
61pub const AGENT_COMPUTER_DESCRIPTOR_SHA256: &str = env!("SYLPHX_AGENT_COMPUTER_DESCRIPTOR_SHA256");
62
63/// Canonical aggregate descriptor root for the public management wire.
64pub const AGENT_COMPUTER_DESCRIPTOR_ROOT_FILE: &str =
65    env!("SYLPHX_AGENT_COMPUTER_DESCRIPTOR_ROOT_FILE");
66
67/// SHA-256 identity of the canonical management root file descriptor.
68pub const AGENT_COMPUTER_DESCRIPTOR_ROOT_SHA256: &str =
69    env!("SYLPHX_AGENT_COMPUTER_DESCRIPTOR_ROOT_SHA256");
70
71/// SHA-256 identity of the allowlisted management-rooted descriptor graph.
72pub const AGENT_COMPUTER_DESCRIPTOR_GRAPH_SHA256: &str =
73    env!("SYLPHX_AGENT_COMPUTER_DESCRIPTOR_GRAPH_SHA256");
74
75#[cfg(test)]
76mod agent_computer_protojson_tests {
77    use super::*;
78    use serde_json::json;
79
80    #[test]
81    fn packaged_contract_identity_is_generator_owned() {
82        assert_eq!(CONTRACT_REVISION, "0.5.0");
83        assert_eq!(AGENT_COMPUTER_CONTRACT_IDENTITY_SHA256.len(), 71);
84        assert!(AGENT_COMPUTER_CONTRACT_IDENTITY_SHA256.starts_with("sha256:"));
85        assert_eq!(AGENT_COMPUTER_DESCRIPTOR_SHA256.len(), 71);
86        assert!(AGENT_COMPUTER_DESCRIPTOR_SHA256.starts_with("sha256:"));
87        assert_eq!(
88            AGENT_COMPUTER_DESCRIPTOR_ROOT_FILE,
89            "sylphx/app/v1/management.proto"
90        );
91        assert_eq!(AGENT_COMPUTER_DESCRIPTOR_ROOT_SHA256.len(), 71);
92        assert!(AGENT_COMPUTER_DESCRIPTOR_ROOT_SHA256.starts_with("sha256:"));
93        assert_eq!(AGENT_COMPUTER_DESCRIPTOR_GRAPH_SHA256.len(), 71);
94        assert!(AGENT_COMPUTER_DESCRIPTOR_GRAPH_SHA256.starts_with("sha256:"));
95    }
96
97    #[test]
98    fn protojson_matches_typescript_scalar_and_presence_semantics() {
99        let artifact = ReadComputerArtifactResponse {
100            data: Some(vec![0, 255]),
101            offset: 9_007_199_254_740_993,
102            next_offset: Some(9_007_199_254_740_995),
103            eof: false,
104            chunk_digest: "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
105                .into(),
106            total_size_bytes: 9_007_199_254_741_000,
107            artifact_digest:
108                "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb".into(),
109            requested_max_bytes: 2,
110            ..Default::default()
111        };
112        assert_eq!(
113            serde_json::to_value(artifact).expect("artifact ProtoJSON"),
114            json!({
115                "data": "AP8=",
116                "offset": "9007199254740993",
117                "nextOffset": "9007199254740995",
118                "chunkDigest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
119                "totalSizeBytes": "9007199254741000",
120                "artifactDigest": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
121                "requestedMaxBytes": 2
122            })
123        );
124    }
125
126    #[test]
127    fn protojson_matches_typescript_enum_oneof_and_well_known_types() {
128        let termination = ComputerObservedTermination {
129            kind: ComputerObservedTerminationKind::PosixSignal.into(),
130            cause: Some(computer_observed_termination::Cause::PosixSignal(Box::new(
131                ComputerPosixSignalDetail {
132                    signal_number: 65,
133                    canonical_name: Some("SIGRTMIN+31".into()),
134                    ..Default::default()
135                },
136            ))),
137            ..Default::default()
138        };
139        assert_eq!(
140            serde_json::to_value(termination).expect("termination ProtoJSON"),
141            json!({
142                "kind": "COMPUTER_OBSERVED_TERMINATION_KIND_POSIX_SIGNAL",
143                "posixSignal": { "signalNumber": 65, "canonicalName": "SIGRTMIN+31" }
144            })
145        );
146
147        let location = WorkspaceLocation {
148            location: Some(workspace_location::Location::Root(true)),
149            ..Default::default()
150        };
151        assert_eq!(
152            serde_json::to_value(location).expect("location ProtoJSON"),
153            json!({ "root": true })
154        );
155
156        let heartbeat = ComputerLeaseHeartbeat {
157            emitted_at: protojson_wkt::Timestamp {
158                seconds: 0,
159                nanos: 500_000_000,
160                ..Default::default()
161            }
162            .into(),
163            ..Default::default()
164        };
165        assert_eq!(
166            serde_json::to_value(heartbeat).expect("timestamp ProtoJSON"),
167            json!({ "emittedAt": "1970-01-01T00:00:00.500Z" })
168        );
169
170        let request = CreateComputerMediaAttachmentRequest {
171            requested_ttl: buffa_types::google::protobuf::Duration { seconds: 1, nanos: 500_000_000, ..Default::default() }.into(),
172            ..Default::default()
173        };
174        assert_eq!(
175            serde_json::to_value(request).expect("duration ProtoJSON"),
176            json!({ "requestedTtl": "1.500s" })
177        );
178    }
179}
180
181#[cfg(test)]
182mod tests {
183    use super::*;
184
185    #[test]
186    fn project_json_roundtrip_uses_camel_case_wire_names() {
187        let project = Project {
188            id: "prj_1".into(),
189            slug: "demo".into(),
190            name: "Demo".into(),
191            description: Some("d".into()),
192            org_id: "org_1".into(),
193            is_active: true,
194            r#ref: Some("main".into()),
195            sdk_url: None,
196            infra_status: Some("ready".into()),
197            domains: vec!["example.com".into()],
198            build_machine_type: Some("standard".into()),
199            region: Some("fsn1".into()),
200            created_at: Default::default(),
201            updated_at: Default::default(),
202            preview_max_active: None,
203            preview_tier_policy: None,
204            webhook_url: None,
205            webhook_events: vec![],
206            enabled_oauth_providers: vec![],
207            environments: vec![],
208            ..Default::default()
209        };
210        let json = serde_json::to_value(&project).expect("serialize");
211        assert_eq!(json["id"], "prj_1");
212        assert_eq!(json["orgId"], "org_1");
213        assert_eq!(json["isActive"], true);
214        let back: Project = serde_json::from_value(json).expect("deserialize");
215        assert_eq!(back.org_id, "org_1");
216        assert!(back.is_active);
217    }
218
219    #[test]
220    fn error_envelope_matches_public_shape() {
221        let env = ErrorEnvelope {
222            error: ErrorDetail {
223                status: Some(crate::proto::google::rpc::Status {
224                    code: 5,
225                    message: "nope".into(),
226                    details: vec![],
227                    ..Default::default()
228                })
229                .into(),
230                code: "not_found".into(),
231                ..Default::default()
232            }
233            .into(),
234            ..Default::default()
235        };
236        let v = serde_json::to_value(&env).unwrap();
237        assert_eq!(v["error"]["status"]["message"], "nope");
238        assert_eq!(v["error"]["status"]["code"], 5);
239        assert_eq!(v["error"]["code"], "not_found");
240    }
241
242    #[test]
243    fn list_projects_response_object_marker() {
244        let resp = ListProjectsResponse {
245            object: "list".into(),
246            data: vec![Project {
247                id: "prj_1".into(),
248                slug: "a".into(),
249                name: "A".into(),
250                description: None,
251                org_id: "org_1".into(),
252                is_active: true,
253                r#ref: None,
254                sdk_url: None,
255                infra_status: None,
256                domains: vec![],
257                build_machine_type: None,
258                region: None,
259                created_at: Default::default(),
260                updated_at: Default::default(),
261                preview_max_active: None,
262                preview_tier_policy: None,
263                webhook_url: None,
264                webhook_events: vec![],
265                enabled_oauth_providers: vec![],
266                environments: vec![],
267                ..Default::default()
268            }],
269            page: PageInfo {
270                next_page_token: String::new(),
271                total_size: Some(1),
272                ..Default::default()
273            }
274            .into(),
275            transport: Some("native_postgres".into()),
276            ..Default::default()
277        };
278        let v = serde_json::to_value(&resp).unwrap();
279        assert_eq!(v["object"], "list");
280        assert_eq!(v["data"][0]["slug"], "a");
281        assert_eq!(v["page"]["totalSize"], "1");
282    }
283}
284
285
286#[cfg(test)]
287mod deployment_honesty_tests {
288    use crate::Deployment;
289    use serde_json::json;
290
291    #[test]
292    fn deployment_preserves_immutable_build_provenance_without_release_status() {
293        // Synthetic canonical response: Deployment is a completed build result.
294        // Environment selection and delivery progress belong to Release.
295        let row = json!({
296            "id": "dep_fixture", "projectId": "proj_fixture", "serviceId": "svc_fixture",
297            "organizationId": "org_fixture", "createdTime": "2026-09-09T07:00:00Z",
298            "provenance": {
299                "buildId": "00000000-0000-4000-8000-000000000001",
300                "source": {"provider": "github", "repositoryId": "1117000933", "commitSha": "a".repeat(40)},
301                "buildInputsDigest": format!("sha256:{}", "b".repeat(64)),
302                "artifact": {"digest": format!("sha256:{}", "c".repeat(64))},
303                "builderId": "builder-fixture",
304                "authentication": {"verificationId": "receipt-fixture", "verifier": "hands-fixture",
305                    "evidenceHash": format!("sha256:{}", "d".repeat(64)), "verifiedAt": "2026-09-09T07:00:00Z"}
306            }
307        });
308        let d: Deployment = serde_json::from_value(row.clone()).expect("canonical ProtoJSON");
309        assert_eq!(d.service_id, "svc_fixture");
310        let provenance = d.provenance.as_option().expect("immutable provenance");
311        assert_eq!(provenance.source.as_option().unwrap().commit_sha, "a".repeat(40));
312        assert_eq!(provenance.artifact.as_option().unwrap().digest, format!("sha256:{}", "c".repeat(64)));
313        assert_eq!(provenance.authentication.as_option().unwrap().verification_id, "receipt-fixture");
314        let serialized = serde_json::to_value(&d).expect("serialize canonical response");
315        assert_eq!(serialized, row);
316        for retired in ["status", "environmentId", "gitSha", "imageDigest", "startedAt", "finishedAt"] {
317            assert!(serialized.get(retired).is_none(), "retired delivery status leaked: {retired}");
318        }
319    }
320
321    #[test]
322    fn deployment_protojson_omission_defaults_before_contract_validation() {
323        let missing = json!({
324            "id": "dep_fixture"
325        });
326        let decoded = serde_json::from_value::<Deployment>(missing).expect("valid ProtoJSON shape");
327        // ProtoJSON decoding preserves protobuf default/omission semantics.
328        // Descriptor-derived request/response validators own requiredness.
329        assert!(decoded.project_id.is_empty());
330    }
331}