a3s_flow/
protocol.rs

1use serde::{Deserialize, Serialize};
2
3use crate::model::JsonValue;
4
5/// Wire protocol implemented by native TypeScript workflow executables.
6pub const NATIVE_RUNTIME_PROTOCOL: &str = "a3s.flow.native_ts.v1";
7/// Command protocol implemented by the installable native TypeScript compiler.
8pub const NATIVE_COMPILER_PROTOCOL: &str = "a3s.flow.native_ts.compiler.v1";
9/// Dependency-manifest protocol emitted by the native TypeScript compiler.
10pub const NATIVE_DEPENDENCY_MANIFEST_PROTOCOL: &str = "a3s.flow.native_ts.dependencies.v1";
11
12/// Capabilities reported by the installable native TypeScript compiler.
13#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
14pub struct NativeTsCompilerCapabilities {
15    /// Compiler command protocol version.
16    pub protocol: String,
17    /// Whether dependency-manifest extraction is supported.
18    #[serde(rename = "dependencyManifest")]
19    pub dependency_manifest: bool,
20}
21
22impl NativeTsCompilerCapabilities {
23    /// Returns capabilities implemented by this crate's compiler binary.
24    pub fn current() -> Self {
25        Self {
26            protocol: NATIVE_COMPILER_PROTOCOL.to_string(),
27            dependency_manifest: true,
28        }
29    }
30}
31
32/// Compiler-owned source graph used to bind native artifacts to every input.
33#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
34pub struct NativeTsDependencyManifest {
35    /// Dependency-manifest protocol version.
36    pub protocol: String,
37    /// Stable identity of the compiler environment that resolved the graph.
38    #[serde(rename = "compilerIdentity")]
39    pub compiler_identity: String,
40    /// Canonical source files that contribute to the compiled artifact.
41    pub files: Vec<String>,
42}
43
44impl NativeTsDependencyManifest {
45    /// Creates a dependency manifest using the current protocol version.
46    pub fn new(compiler_identity: impl Into<String>, files: Vec<String>) -> Self {
47        Self {
48            protocol: NATIVE_DEPENDENCY_MANIFEST_PROTOCOL.to_string(),
49            compiler_identity: compiler_identity.into(),
50            files,
51        }
52    }
53}
54
55/// Kind of invocation sent to a native TypeScript runtime.
56#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
57#[serde(rename_all = "snake_case")]
58pub enum NativeRuntimeKind {
59    /// Replay a workflow function.
60    Workflow,
61    /// Execute a registered step function.
62    Step,
63}
64
65impl NativeRuntimeKind {
66    /// Returns the stable wire representation.
67    pub fn as_str(self) -> &'static str {
68        match self {
69            Self::Workflow => "workflow",
70            Self::Step => "step",
71        }
72    }
73}
74
75/// Versioned request envelope sent to a native TypeScript executable.
76#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
77pub struct NativeRuntimeRequest<T> {
78    /// Native runtime protocol version.
79    pub protocol: String,
80    /// Kind of function being invoked.
81    pub kind: NativeRuntimeKind,
82    /// Exported function name within the compiled entrypoint.
83    #[serde(rename = "exportName")]
84    pub export_name: String,
85    /// Digest binding the request to its complete source graph.
86    #[serde(rename = "sourceHash")]
87    pub source_hash: String,
88    /// Invocation-specific request payload.
89    pub payload: T,
90}
91
92impl<T> NativeRuntimeRequest<T> {
93    /// Creates a request using the current native runtime protocol.
94    pub fn new(
95        kind: NativeRuntimeKind,
96        export_name: impl Into<String>,
97        source_hash: impl Into<String>,
98        payload: T,
99    ) -> Self {
100        Self {
101            protocol: NATIVE_RUNTIME_PROTOCOL.to_string(),
102            kind,
103            export_name: export_name.into(),
104            source_hash: source_hash.into(),
105            payload,
106        }
107    }
108}
109
110/// Versioned response envelope returned by a native TypeScript executable.
111#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
112pub struct NativeRuntimeResponse {
113    /// Native runtime protocol version.
114    pub protocol: String,
115    /// Kind copied from the matching request.
116    pub kind: NativeRuntimeKind,
117    /// Whether execution completed without a runtime error.
118    pub ok: bool,
119    /// Successful JSON output.
120    #[serde(default)]
121    pub output: Option<JsonValue>,
122    /// Runtime or protocol error description.
123    #[serde(default)]
124    pub error: Option<String>,
125}
a3s_flow/protocol.rs

a3s_flow/
protocol.rs
