app_bridge 3.0.0 → 4.1.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,279 @@ 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.
+
+### Multipart Form Data
+
+For `multipart/form-data`, you must build the body manually and set the `Content-Type` header with a boundary. In `standout:app@4.1.0` you can send raw bytes via `body-bytes`; earlier versions only support a string body.
+
+#### In your WASM connector (Rust):
+
+```rust
+let boundary = "----app-bridge-boundary";
+
+let mut body = Vec::new();
+body.extend_from_slice(format!(
+    "--{b}\r\n\
+Content-Disposition: form-data; name=\"metadata\"\r\n\r\n\
+{metadata}\r\n\
+--{b}\r\n\
+Content-Disposition: form-data; name=\"file\"; filename=\"invoice.pdf\"\r\n\
+Content-Type: application/pdf\r\n\r\n",
+    b = boundary,
+    metadata = metadata_json,
+).as_bytes());
+body.extend_from_slice(&file_bytes);
+body.extend_from_slice(format!("\r\n--{b}--\r\n", b = boundary).as_bytes());
+
+let response = RequestBuilder::new()
+    .method(Method::Post)
+    .url(upload_url)
+    .header("Content-Type", format!("multipart/form-data; boundary={}", boundary))
+    .body_bytes(body)
+    .send()?;
+```
+
+If you are targeting `standout:app@4.0.0` or earlier, you can only send a string body. That means multipart uploads must be base64-encoded and the receiving API must support `Content-Transfer-Encoding: base64`.
+
+## Retry With Reference
+
+`standout:app@4.1.0` introduces a structured retry error for actions. Connectors can return a retry error with a reference and status, and the platform can pass that back on subsequent retries via `action-context.reference-object`.
+
+### In your WASM connector (Rust)
+
+```rust
+return Err(AppError {
+    code: ErrorCode::RetryWithReference(ReferenceObject {
+        reference: request_id.to_string(),
+        status: status.to_string(),
+    }),
+    message: "Background request still processing".to_string(),
+});
+```
+
+### In the Ruby platform
+
+When the connector returns `retry-with-reference`, the bridge raises `AppBridge::RetryWithReferenceError`. You can access the structured fields:
+
+```ruby
+rescue AppBridge::RetryWithReferenceError => e
+  e.reference # => "ref-123"
+  e.status    # => "queued"
+  e.message   # => "Background request still processing after 1 attempts."
+end
+```
+
+## 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.1.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,16 +1,17 @@
-use crate::component::standout;
-use crate::component::standout::app::http::Request;
+use crate::component::{v3, v4, v4_1};
+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,
     table: ResourceTable,
     pub client: Arc<Mutex<Client>>,
     pub request_list: HashMap<u32, Request>,
+    pub request_body_bytes: HashMap<u32, Vec<u8>>,
     pub next_request_id: u32,
     pub environment_variables: HashMap<String, String>,
 }
@@ -22,26 +23,44 @@ impl AppState {
             table: ResourceTable::new(),
             client: Arc::new(Mutex::new(Client::new())),
             request_list: HashMap::new(),
+            request_body_bytes: HashMap::new(),
             next_request_id: 0,
             environment_variables: env_vars.unwrap_or_default(),
         }
     }
 }
 
-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);
+impl_host_for_version!(v4_1);
+
+// ============================================================================
+// WASI implementations
+// ============================================================================
+
 impl IoView for AppState {
     fn table(&mut self) -> &mut ResourceTable {
         &mut self.table