app_bridge 3.0.0 → 4.0.0

data/Cargo.toml

@@ -5,4 +5,4 @@
 [workspace]
 members = ["./ext/app_bridge"]
 resolver = "2"
-exclude = ["./spec/fixtures/components/rust_app"]
+exclude = ["./spec/fixtures/components/rust_app", "./spec/fixtures/components/rust_app_v3"]

data/README.md

@@ -18,7 +18,7 @@ bundle install
 
 ## Usage
 
-To use this gem, you need a WebAssembly component that adheres to the specification defined in `ext/app_bridge/wit/world.wit`.
+To use this gem, you need a WebAssembly component that adheres to the specification defined in `ext/app_bridge/wit/v4/world.wit` (or an older supported version like `v3`).
 
 You can check out the example components in `spec/fixtures/components` to see how such a component should be structured.
 
@@ -31,7 +31,218 @@ app = AppBridge::App.new('path/to/your/component.wasm')
 app.triggers # => ['trigger1', 'trigger2']
 ```
 
-More documentation and features will be added as the gem evolves.
+### File Handling
+
+The gem provides a `file.normalize` function for handling files in connectors. It automatically detects the input format (URL, data URI, or base64) and returns normalized file data.
+
+#### In your WASM connector (JavaScript):
+
+```javascript
+import { normalize } from 'standout:app/file@4.0.0';
+
+// Normalize any file source - input type is auto-detected
+const fileData = normalize(
+  input.fileUrl,           // URL, data URI, or base64 string
+  [["Authorization", token]], // Optional headers for URL requests
+  "invoice.pdf"            // Optional filename override
+);
+
+// Returns: { base64, contentType, filename }
+
+// Include in your action output
+return {
+  serializedOutput: JSON.stringify({
+    document: fileData  // Will be replaced with blob ID by platform
+  })
+};
+```
+
+#### In your WASM connector (Rust):
+
+```rust
+use crate::standout::app::file::normalize;
+
+let file_data = normalize(
+    &input.file_url,
+    Some(&[("Authorization".to_string(), token)]),
+    Some("invoice.pdf"),
+)?;
+
+// file_data contains { base64, content_type, filename }
+```
+
+#### Output schema:
+
+Mark file fields with `format: "file-output"` so the platform knows to process them:
+
+```json
+{
+  "properties": {
+    "document": {
+      "type": "object",
+      "format": "file-output"
+    }
+  }
+}
+```
+
+#### Platform configuration:
+
+Configure the file uploader in your Rails app:
+
+```ruby
+AppBridge.file_uploader = ->(file_data) {
+  blob = ActiveStorage::Blob.create_and_upload!(
+    io: StringIO.new(Base64.decode64(file_data['base64'])),
+    filename: file_data['filename'],
+    content_type: file_data['content_type']
+  )
+  blob.signed_id
+}
+```
+
+The gem automatically replaces file data with the return value (in this example blob IDs) before returning the action response.
+
+## Backward Compatibility
+
+The gem supports **multi-version WIT interfaces**, allowing connectors built against older WIT versions to continue working when the gem is updated.
+
+### How it works
+
+When loading a WASM component, the gem automatically detects which WIT version it was built against:
+
+1. **V4 components** (current, `standout:app@4.0.0`): Full feature support including the `file` interface
+2. **V3 components** (`standout:app@3.0.0`): Legacy support without file interface
+
+### Adding support for new WIT versions
+
+When adding a new WIT version (e.g., v5), follow these steps:
+
+#### 1. Create the WIT file
+
+Copy the latest version and modify:
+
+```bash
+cp -r ext/app_bridge/wit/v4 ext/app_bridge/wit/v5
+```
+
+Edit `ext/app_bridge/wit/v5/world.wit`:
+- Update the package version: `package standout:app@5.0.0;`
+- Add new interfaces or modify existing ones
+
+#### 2. Add the bindgen module
+
+In `ext/app_bridge/src/component.rs`, add after the existing modules:
+
+```rust
+pub mod v5 {
+    wasmtime::component::bindgen!({
+        path: "./wit/v5",
+        world: "bridge",
+    });
+}
+```
+
+#### 3. Generate type conversions
+
+Add the conversion macro call:
+
+```rust
+impl_conversions!(v5);
+```
+
+#### 4. Add BridgeWrapper variant
+
+Update the enum:
+
+```rust
+pub enum BridgeWrapper {
+    V3(v3::Bridge),
+    V4(v4::Bridge),
+    V5(v5::Bridge),  // <-- add this
+}
+```
+
+Add an arm to each `bridge_method!` macro expansion. In the macro definitions, add:
+
+```rust
+BridgeWrapper::V5(b) => {
+    let r = b.$interface().$method(store, ...)?;
+    Ok(r.map(Into::into).map_err(Into::into))
+}
+```
+
+#### 5. Register interfaces in the linker
+
+In `build_linker()`:
+
+```rust
+// v5: http + environment + file + new_feature
+v5::standout::app::http::add_to_linker(&mut linker, |s| s)?;
+v5::standout::app::environment::add_to_linker(&mut linker, |s| s)?;
+v5::standout::app::file::add_to_linker(&mut linker, |s| s)?;
+v5::standout::app::new_feature::add_to_linker(&mut linker, |s| s)?;  // if applicable
+```
+
+#### 6. Update the instantiation chain
+
+In `app()`, add v5 at the top (newest first):
+
+```rust
+// v5 (newest)
+if let Ok(instance) = v5::Bridge::instantiate(&mut *store, &component, &linker) {
+    return Ok(BridgeWrapper::V5(instance));
+}
+
+// v4
+if let Ok(instance) = v4::Bridge::instantiate(&mut *store, &component, &linker) {
+    return Ok(BridgeWrapper::V4(instance));
+}
+
+// v3 (oldest)
+// ...
+```
+
+#### 7. Register Host implementations
+
+In `app_state.rs`:
+
+```rust
+impl_host_for_version!(v5);
+```
+
+In `request_builder.rs`:
+
+```rust
+impl_host_request_builder!(v5);
+impl_http_type_conversions!(v5);
+```
+
+#### 8. If the version has the file interface
+
+In `file_ops.rs` (only if v5 includes the `file` interface):
+
+```rust
+impl_file_host!(v5);
+```
+
+#### 9. If adding new host functions
+
+If the new version introduces entirely new interfaces (not just `file`), implement the `Host` trait:
+
+```rust
+impl v5::standout::app::new_feature::Host for AppState {
+    fn some_function(&mut self, ...) -> ... {
+        // implementation
+    }
+}
+```
+
+### Benefits
+
+- **No forced rebuilds**: Existing connectors continue to work after gem updates
+- **Gradual migration**: Update connectors to new WIT versions at your own pace
+- **Type safety**: Each version's types are converted to the latest version internally
 
 ## Development
 

data/ext/app_bridge/Cargo.toml

@@ -2,7 +2,7 @@
 name = "app_bridge"
 # When updating the version, please also update the version in the
 # lib/app_bridge/version.rb file to keep them in sync.
-version = "3.0.0"
+version = "4.0.0"
 edition = "2021"
 authors = ["Alexander Ross <ross@standout.se>"]
 publish = false
@@ -12,9 +12,13 @@ crate-type = ["cdylib"]
 
 [dependencies]
 magnus = { version = "0.7.1" }
-wasmtime = "32.0.0"
-wasmtime-wasi = "32.0.0"
+wasmtime = "33.0.2"
+wasmtime-wasi = "33.0.2"
 reqwest = { version = "0.12", features = ["blocking", "json", "native-tls-vendored"] }
+base64 = "0.22"
+infer = "0.16"
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
 
 [dev-dependencies]
-httpmock = "0.7.0"
+httpmock = "0.8.2"

data/ext/app_bridge/src/app_state.rs

@@ -1,10 +1,10 @@
-use crate::component::standout;
-use crate::component::standout::app::http::Request;
+use crate::component::{v3, v4};
+use crate::component::v4::standout::app::http::Request;
 use reqwest::blocking::Client;
 use std::collections::HashMap;
 use std::sync::{Arc, Mutex};
 use wasmtime::component::ResourceTable;
-use wasmtime_wasi::{WasiCtx, WasiCtxBuilder, WasiView, IoView};
+use wasmtime_wasi::p2::{WasiCtx, WasiCtxBuilder, WasiView, IoView};
 
 pub struct AppState {
     ctx: WasiCtx,
@@ -28,20 +28,36 @@ impl AppState {
     }
 }
 
-impl standout::app::http::Host for AppState {
-    // Impl http host methods here
-}
+// ============================================================================
+// Macro to implement identical Host traits for multiple WIT versions
+// ============================================================================
 
-impl standout::app::environment::Host for AppState {
-    fn env_vars(&mut self) -> Vec<(String, String)> {
-        self.environment_variables.clone().into_iter().collect()
-    }
+/// Implements http::Host and environment::Host for a given WIT version module.
+/// These implementations are identical across versions.
+macro_rules! impl_host_for_version {
+    ($version:ident) => {
+        impl $version::standout::app::http::Host for AppState {}
 
-    fn env_var(&mut self, name: String) -> Option<String> {
-        self.environment_variables.get(&name).cloned()
-    }
+        impl $version::standout::app::environment::Host for AppState {
+            fn env_vars(&mut self) -> Vec<(String, String)> {
+                self.environment_variables.clone().into_iter().collect()
+            }
+
+            fn env_var(&mut self, name: String) -> Option<String> {
+                self.environment_variables.get(&name).cloned()
+            }
+        }
+    };
 }
 
+// Apply to both versions
+impl_host_for_version!(v3);
+impl_host_for_version!(v4);
+
+// ============================================================================
+// WASI implementations
+// ============================================================================
+
 impl IoView for AppState {
     fn table(&mut self) -> &mut ResourceTable {
         &mut self.table

data/ext/app_bridge/src/component.rs

@@ -1,25 +1,252 @@
-use std::result::Result::Ok;
 use std::collections::HashMap;
-use wasmtime::component::{bindgen, Component, Linker};
+use std::result::Result::Ok;
+use wasmtime::component::{Component, Linker};
 use wasmtime::{Engine, Result, Store};
-use wasmtime_wasi::WasiCtxBuilder;
-
-bindgen!({
-    path: "./wit",
-    world: "bridge",
-});
+use wasmtime_wasi::p2::WasiCtxBuilder;
 
 use crate::app_state::AppState;
+use crate::types::{
+    ActionContext, ActionResponse, AppError, Connection, ErrorCode, TriggerContext,
+    TriggerEvent, TriggerResponse,
+};
+
+// ============================================================================
+// WIT version modules
+//
+// To add a new version:
+// 1. Add a new pub mod vN { bindgen!(...) }
+// 2. Add impl_conversions!(vN) below
+// 3. Add variant to BridgeWrapper enum
+// 4. Add to build_linker() and app() functions
+// 5. Add arm to each bridge_method! in BridgeWrapper impl
+// ============================================================================
+
+pub mod v3 {
+    wasmtime::component::bindgen!({
+        path: "./wit/v3",
+        world: "bridge",
+    });
+}
+
+pub mod v4 {
+    wasmtime::component::bindgen!({
+        path: "./wit/v4",
+        world: "bridge",
+    });
+}
+
+// ============================================================================
+// Version conversion macro - generates From impls for a version module
+// ============================================================================
+
+macro_rules! impl_conversions {
+    ($v:ident) => {
+        // ErrorCode: version → canonical
+        impl From<$v::standout::app::types::ErrorCode> for ErrorCode {
+            fn from(c: $v::standout::app::types::ErrorCode) -> Self {
+                use $v::standout::app::types::ErrorCode as V;
+                match c {
+                    V::Unauthenticated => Self::Unauthenticated,
+                    V::Forbidden => Self::Forbidden,
+                    V::Misconfigured => Self::Misconfigured,
+                    V::Unsupported => Self::Unsupported,
+                    V::RateLimit => Self::RateLimit,
+                    V::Timeout => Self::Timeout,
+                    V::Unavailable => Self::Unavailable,
+                    V::InternalError => Self::InternalError,
+                    V::MalformedResponse => Self::MalformedResponse,
+                    V::Other => Self::Other,
+                    V::CompleteWorkflow => Self::CompleteWorkflow,
+                    V::CompleteParent => Self::CompleteParent,
+                }
+            }
+        }
+
+        // AppError: version → canonical
+        impl From<$v::standout::app::types::AppError> for AppError {
+            fn from(e: $v::standout::app::types::AppError) -> Self {
+                Self { code: e.code.into(), message: e.message }
+            }
+        }
+
+        // TriggerEvent: version → canonical
+        impl From<$v::standout::app::types::TriggerEvent> for TriggerEvent {
+            fn from(e: $v::standout::app::types::TriggerEvent) -> Self {
+                Self { id: e.id, serialized_data: e.serialized_data }
+            }
+        }
+
+        // TriggerResponse: version → canonical
+        impl From<$v::standout::app::types::TriggerResponse> for TriggerResponse {
+            fn from(r: $v::standout::app::types::TriggerResponse) -> Self {
+                Self {
+                    store: r.store,
+                    events: r.events.into_iter().map(Into::into).collect(),
+                }
+            }
+        }
+
+        // ActionResponse: version → canonical
+        impl From<$v::standout::app::types::ActionResponse> for ActionResponse {
+            fn from(r: $v::standout::app::types::ActionResponse) -> Self {
+                Self { serialized_output: r.serialized_output }
+            }
+        }
+
+        // Connection: canonical → version (for passing to components)
+        impl From<&Connection> for $v::standout::app::types::Connection {
+            fn from(c: &Connection) -> Self {
+                Self {
+                    id: c.id.clone(),
+                    name: c.name.clone(),
+                    serialized_data: c.serialized_data.clone(),
+                }
+            }
+        }
+
+        // TriggerContext: canonical → version
+        impl From<&TriggerContext> for $v::standout::app::types::TriggerContext {
+            fn from(c: &TriggerContext) -> Self {
+                Self {
+                    trigger_id: c.trigger_id.clone(),
+                    connection: (&c.connection).into(),
+                    store: c.store.clone(),
+                    serialized_input: c.serialized_input.clone(),
+                }
+            }
+        }
+
+        // ActionContext: canonical → version
+        impl From<&ActionContext> for $v::standout::app::types::ActionContext {
+            fn from(c: &ActionContext) -> Self {
+                Self {
+                    action_id: c.action_id.clone(),
+                    connection: (&c.connection).into(),
+                    serialized_input: c.serialized_input.clone(),
+                }
+            }
+        }
+    };
+}
+
+// Generate conversions for all supported versions
+impl_conversions!(v3);
+impl_conversions!(v4);
+
+// ============================================================================
+// BridgeWrapper - unified interface for all component versions
+//
+// To add vN: add variant BridgeWrapper::VN(vN::Bridge)
+// ============================================================================
+
+pub enum BridgeWrapper {
+    V3(v3::Bridge),
+    V4(v4::Bridge),
+}
+
+impl BridgeWrapper {
+    /// Returns the WIT version this component was built against
+    pub fn wit_version(&self) -> &'static str {
+        match self {
+            BridgeWrapper::V3(_) => "3.0.0",
+            BridgeWrapper::V4(_) => "4.0.0",
+        }
+    }
+}
+
+/// Macro to implement a bridge method that works across all versions.
+/// Each version's result is converted to canonical types.
+macro_rules! bridge_method {
+    // Simple no-arg method (e.g., trigger_ids, action_ids)
+    (fn $name:ident() -> Result<$ok_type:ty> via $interface:ident . $method:ident) => {
+        pub fn $name(&self, store: &mut Store<AppState>) -> Result<std::result::Result<$ok_type, AppError>> {
+            match self {
+                BridgeWrapper::V3(b) => {
+                    let r = b.$interface().$method(store)?;
+                    Ok(r.map_err(Into::into))
+                }
+                BridgeWrapper::V4(b) => {
+                    let r = b.$interface().$method(store)?;
+                    Ok(r.map_err(Into::into))
+                }
+            }
+        }
+    };
+    // Method with TriggerContext
+    (fn $name:ident(&TriggerContext) -> Result<$ok_type:ty> via $interface:ident . $method:ident) => {
+        pub fn $name(&self, store: &mut Store<AppState>, ctx: &TriggerContext) -> Result<std::result::Result<$ok_type, AppError>> {
+            match self {
+                BridgeWrapper::V3(b) => {
+                    let r = b.$interface().$method(store, &ctx.into())?;
+                    Ok(r.map(Into::into).map_err(Into::into))
+                }
+                BridgeWrapper::V4(b) => {
+                    let r = b.$interface().$method(store, &ctx.into())?;
+                    Ok(r.map(Into::into).map_err(Into::into))
+                }
+            }
+        }
+    };
+    // Method with ActionContext
+    (fn $name:ident(&ActionContext) -> Result<$ok_type:ty> via $interface:ident . $method:ident) => {
+        pub fn $name(&self, store: &mut Store<AppState>, ctx: &ActionContext) -> Result<std::result::Result<$ok_type, AppError>> {
+            match self {
+                BridgeWrapper::V3(b) => {
+                    let r = b.$interface().$method(store, &ctx.into())?;
+                    Ok(r.map(Into::into).map_err(Into::into))
+                }
+                BridgeWrapper::V4(b) => {
+                    let r = b.$interface().$method(store, &ctx.into())?;
+                    Ok(r.map(Into::into).map_err(Into::into))
+                }
+            }
+        }
+    };
+}
+
+impl BridgeWrapper {
+    // Trigger methods
+    bridge_method!(fn call_trigger_ids() -> Result<Vec<String>> via standout_app_triggers . call_trigger_ids);
+    bridge_method!(fn call_trigger_input_schema(&TriggerContext) -> Result<String> via standout_app_triggers . call_input_schema);
+    bridge_method!(fn call_trigger_output_schema(&TriggerContext) -> Result<String> via standout_app_triggers . call_output_schema);
+    bridge_method!(fn call_fetch_events(&TriggerContext) -> Result<TriggerResponse> via standout_app_triggers . call_fetch_events);
+
+    // Action methods
+    bridge_method!(fn call_action_ids() -> Result<Vec<String>> via standout_app_actions . call_action_ids);
+    bridge_method!(fn call_action_input_schema(&ActionContext) -> Result<String> via standout_app_actions . call_input_schema);
+    bridge_method!(fn call_action_output_schema(&ActionContext) -> Result<String> via standout_app_actions . call_output_schema);
+    bridge_method!(fn call_execute(&ActionContext) -> Result<ActionResponse> via standout_app_actions . call_execute);
+}
+
+// ============================================================================
+// Builder functions
+// ============================================================================
 
 pub fn build_engine() -> Engine {
     Engine::default()
 }
 
 pub fn build_linker(engine: &Engine) -> Result<Linker<AppState>> {
-    let mut linker = Linker::<AppState>::new(&engine);
-    wasmtime_wasi::add_to_linker_sync(&mut linker)?;
-    standout::app::http::add_to_linker(&mut linker, |s| s)?;
-    standout::app::environment::add_to_linker(&mut linker, |s| s)?;
+    let mut linker = Linker::<AppState>::new(engine);
+
+    // WASI support (shared by all versions)
+    wasmtime_wasi::p2::add_to_linker_sync(&mut linker)?;
+
+    // ---- Version-specific interfaces ----
+    // v3: http + environment
+    v3::standout::app::http::add_to_linker(&mut linker, |s| s)?;
+    v3::standout::app::environment::add_to_linker(&mut linker, |s| s)?;
+
+    // v4: http + environment + file
+    v4::standout::app::http::add_to_linker(&mut linker, |s| s)?;
+    v4::standout::app::environment::add_to_linker(&mut linker, |s| s)?;
+    v4::standout::app::file::add_to_linker(&mut linker, |s| s)?;
+
+    // Add new versions here:
+    // v5::standout::app::http::add_to_linker(&mut linker, |s| s)?;
+    // v5::standout::app::environment::add_to_linker(&mut linker, |s| s)?;
+    // v5::standout::app::file::add_to_linker(&mut linker, |s| s)?;
+    // v5::standout::app::new_feature::add_to_linker(&mut linker, |s| s)?;
 
     Ok(linker)
 }
@@ -27,54 +254,37 @@ pub fn build_linker(engine: &Engine) -> Result<Linker<AppState>> {
 pub fn build_store(engine: &Engine, env_vars: Option<HashMap<String, String>>) -> Store<AppState> {
     let mut builder = WasiCtxBuilder::new();
 
-    // Add environment variables to WASI context if provided
     if let Some(env_vars) = &env_vars {
         for (key, value) in env_vars {
             builder.env(key, value);
         }
     }
 
-    let ctx = builder.build();
-
-    // Create AppState with or without environment variables
-    let app_state = AppState::new(ctx, env_vars);
-
-    Store::new(&engine, app_state)
+    Store::new(engine, AppState::new(builder.build(), env_vars))
 }
 
+/// Try to instantiate a WASM component.
+/// Attempts versions from newest to oldest until one succeeds.
 pub fn app(
     file_path: String,
     engine: Engine,
     store: &mut Store<AppState>,
     linker: Linker<AppState>,
-) -> Result<Bridge> {
-    // Load the application component from the file system.
-    let component = Component::from_file(&engine, file_path)?;
-
-    // Try to instantiate the component - if it fails due to missing interface,
-    // we'll catch that error and return a specific message
-    match Bridge::instantiate(store, &component, &linker) {
-        Ok(instance) => Ok(instance),
-        Err(e) => {
-            if e.to_string().contains("no exported instance") {
-                Err(wasmtime::Error::msg(
-                    "Incompatible WASM file version"
-                ))
-            } else {
-                Err(e)
-            }
-        }
-    }
-}
+) -> Result<BridgeWrapper> {
+    let component = Component::from_file(&engine, &file_path)?;
 
-impl Default for Bridge {
-    fn default() -> Self {
-        let file_path = "spec/fixtures/components/example_app.wasm";
-        let engine = Engine::default();
-        let mut store = build_store(&engine, None);
-        let linker = build_linker(&engine).unwrap();
-        let instant = app(file_path.to_string(), engine, &mut store, linker);
+    // Try versions newest-first. When adding vN, insert at the top.
+    // v4 (current - has file interface)
+    if let Ok(instance) = v4::Bridge::instantiate(&mut *store, &component, &linker) {
+        return Ok(BridgeWrapper::V4(instance));
+    }
 
-        instant.unwrap()
+    // v3 (legacy - no file interface)
+    if let Ok(instance) = v3::Bridge::instantiate(&mut *store, &component, &linker) {
+        return Ok(BridgeWrapper::V3(instance));
     }
+
+    Err(wasmtime::Error::msg(
+        "Failed to instantiate component: no compatible WIT version found (tried v4, v3)",
+    ))
 }