diff --git a/.cursorrules b/.cursorrules new file mode 100644 index 000000000..c063a7a60 --- /dev/null +++ b/.cursorrules @@ -0,0 +1,32 @@ +# C2PA Language Bindings Documentation + +## Update Bindings.md Task + +When asked to "update the bindings comparison" or similar, perform the following task: + +1. **Examine the current Reader and Builder methods** in `sdk/src/reader.rs` and `sdk/src/builder.rs` +2. **Check each language binding** for method availability: + - `../c2pa-node-v2` - Node.js binding + - `../c2pa-js/packages/c2pa-web` - Web JavaScript binding + - `../c2pa-c` - C++ binding + - `./c2pa_c_ffi` - C FFI binding + - `../c2pa-python` - Python binding + +3. **Update the comparison tables** in `docs/Bindings.md` with: + - ✅ = Method available + - ❌ = Method not available + - N/A = Not applicable (e.g., file system access in browser environments) + +4. **Key considerations**: + - Web JS SDK cannot access files directly, so file-based methods should be N/A + - Archive methods (`to_archive`, `from_archive`) can work with buffers in web environments + - Different bindings may use different method names (e.g., `fromAsset` vs `from_stream`) + - Update coverage statistics and method notes accordingly + +5. **Focus on**: + - Reader methods from the Reader struct + - Builder methods from the Builder struct + - Accurate representation of what's actually available in each binding + - Clear distinction between unavailable vs not applicable methods + +This ensures the docs/Bindings.md document stays current with the evolving C2PA language bindings. \ No newline at end of file diff --git a/docs/Bindings.md b/docs/Bindings.md new file mode 100644 index 000000000..e9aa1623d --- /dev/null +++ b/docs/Bindings.md @@ -0,0 +1,112 @@ +# C2PA Language Bindings Comparison + +This document provides a comprehensive comparison of Reader and Builder methods across the different language bindings for the C2PA Rust SDK. + +## Reader Methods Comparison + +| Method | c2pa-node-v2 | c2pa-js/c2pa-web | c2pa-c | c2pa-c-ffi | c2pa-python | +|--------|--------------|------------------|--------|-------------|-------------| +| `from_stream` | ❌ | ❌ | ✅ | ✅ | ✅ | +| `from_file` | ❌ | N/A | ✅ | ✅ | ✅ | +| `from_json` | ❌ | ❌ | ❌ | ❌ | ❌ | +| `from_manifest_data_and_stream` | ✅ | ❌ | ❌ | ✅ | ✅ | +| `from_fragment` | ❌ | ✅ | ❌ | ❌ | ❌ | +| `from_fragmented_files` | ❌ | N/A | ❌ | ❌ | ❌ | +| `supported_mime_types` | ❌ | ❌ | ✅ | ✅ | ✅ | +| `json` | ✅ | ✅ | ✅ | ✅ | ✅ | +| `detailed_json` | ❌ | ❌ | ❌ | ✅ | ❌ | +| `remote_url` | ✅ | ❌ | ✅ | ✅ | ✅ | +| `is_embedded` | ✅ | ❌ | ✅ | ✅ | ✅ | +| `validation_status` | ❌ | ❌ | ❌ | ❌ | ❌ | +| `validation_results` | ❌ | ❌ | ❌ | ❌ | ✅ | +| `validation_state` | ❌ | ❌ | ❌ | ❌ | ✅ | +| `active_manifest` | ✅ | ✅ | ❌ | ❌ | ✅ | +| `active_label` | ✅ | ✅ | ❌ | ❌ | ❌ | +| `iter_manifests` | ❌ | ❌ | ❌ | ❌ | ❌ | +| `manifests` | ❌ | ❌ | ❌ | ❌ | ❌ | +| `get_manifest` | ❌ | ❌ | ❌ | ❌ | ✅ | +| `resource_to_stream` | ✅ | ✅ | ✅ | ✅ | ✅ | +| `to_folder` | ❌ | N/A | ❌ | ❌ | ❌ | +| `post_validate` | ✅ | ❌ | ❌ | ❌ | ❌ | + +### Reader Method Notes + +- **c2pa-node-v2**: Uses `fromAsset` and `fromManifestDataAndAsset` instead of `from_stream` and `from_manifest_data_and_stream` +- **c2pa-js/c2pa-web**: Uses `fromBlob` and `fromBlobFragment` instead of `from_stream` and `from_fragment`. File-based methods are N/A due to browser security restrictions +- **c2pa-c**: Uses `read_file` function instead of Reader class methods for file reading +- **c2pa-c-ffi**: Provides C API functions for most Reader operations, including `c2pa_reader_from_stream`, `c2pa_reader_from_file`, `c2pa_reader_json`, etc. +- **c2pa-python**: Has comprehensive Reader class with most methods available + +## Builder Methods Comparison + +| Method | c2pa-node-v2 | c2pa-js/c2pa-web | c2pa-c | c2pa-c-ffi | c2pa-python | +|--------|--------------|------------------|--------|-------------|-------------| +| `new` | ✅ | ❌ | ❌ | ❌ | ❌ | +| `set_intent` | ✅ | ❌ | ❌ | ❌ | ❌ | +| `from_json` | ✅ | ✅ | ✅ | ✅ | ✅ | +| `supported_mime_types` | ❌ | ❌ | ✅ | ✅ | ✅ | +| `claim_version` | ❌ | ❌ | ❌ | ❌ | ❌ | +| `set_claim_generator_info` | ❌ | ❌ | ❌ | ❌ | ❌ | +| `set_format` | ❌ | ❌ | ❌ | ❌ | ❌ | +| `set_base_path` | ❌ | N/A | ✅ | ✅ | ❌ | +| `set_remote_url` | ✅ | ✅ | ✅ | ✅ | ✅ | +| `set_no_embed` | ✅ | ✅ | ✅ | ✅ | ✅ | +| `set_thumbnail` | ❌ | ✅ | ❌ | ❌ | ❌ | +| `add_assertion` | ✅ | ❌ | ❌ | ❌ | ❌ | +| `add_assertion_json` | ❌ | ❌ | ❌ | ❌ | ❌ | +| `add_action` | ❌ | ❌ | ✅ | ✅ | ✅ | +| `add_ingredient_from_stream` | ✅ | ✅ | ✅ | ✅ | ✅ | +| `add_ingredient` | ✅ | ✅ | ❌ | ❌ | ✅ | +| `add_resource` | ✅ | ✅ | ✅ | ✅ | ✅ | +| `to_archive` | ✅ | ❌ | ✅ | ✅ | ✅ | +| `from_archive` | ✅ | ❌ | ✅ | ✅ | ✅ | +| `data_hashed_placeholder` | ❌ | ❌ | ✅ | ✅ | ❌ | +| `sign_data_hashed_embeddable` | ❌ | ❌ | ✅ | ✅ | ❌ | +| `sign_box_hashed_embeddable` | ❌ | ❌ | ❌ | ❌ | ❌ | +| `sign` | ✅ | ✅ | ✅ | ✅ | ✅ | +| `sign_fragmented_files` | ❌ | N/A | ❌ | ❌ | ❌ | +| `sign_file` | ✅ | N/A | ✅ | ✅ | ✅ | +| `composed_manifest` | ❌ | ❌ | ❌ | ❌ | ❌ | + +### Builder Method Notes + +- **c2pa-node-v2**: Uses `withJson` instead of `from_json`, has comprehensive Builder class +- **c2pa-js/c2pa-web**: Uses `fromDefinition` instead of `from_json`, has `setThumbnailFromBlob` instead of `set_thumbnail`. File-based methods are N/A due to browser security restrictions, but archive methods can work with buffers +- **c2pa-c**: Uses `Builder(const std::string &manifest_json)` constructor instead of `from_json` +- **c2pa-c-ffi**: Provides C API functions for Builder operations, including `c2pa_builder_from_json`, `c2pa_builder_sign`, etc. +- **c2pa-python**: Has comprehensive Builder class with most methods available + +## Summary + +### Reader Coverage +- **c2pa-python**: 15/22 methods (68%) ✅ +- **c2pa-c-ffi**: 12/22 methods (55%) ✅ +- **c2pa-c**: 8/22 methods (36%) ⚠️ +- **c2pa-node-v2**: 7/22 methods (32%) ⚠️ +- **c2pa-js/c2pa-web**: 4/22 methods (18%) - Note: 3 methods N/A due to browser limitations + +### Builder Coverage +- **c2pa-python**: 12/25 methods (48%) ✅ +- **c2pa-c-ffi**: 12/25 methods (48%) ✅ +- **c2pa-c**: 10/25 methods (40%) ⚠️ +- **c2pa-node-v2**: 9/25 methods (36%) ⚠️ +- **c2pa-js/c2pa-web**: 6/25 methods (24%) - Note: 2 methods N/A due to browser limitations + +### Key Observations + +1. **c2pa-python** has the most comprehensive implementation with the highest method coverage +2. **c2pa-c** provides good coverage for core functionality but lacks some advanced features +3. **c2pa-node-v2** has good coverage for Builder operations but limited Reader functionality +4. **c2pa-js/c2pa-web** has the most limited coverage, focusing on web-specific use cases + +### Missing Critical Methods + +- **Validation methods**: Most bindings lack `validation_status`, `validation_results`, and `validation_state` +- **Advanced Reader methods**: `detailed_json`, `iter_manifests`, `manifests`, `to_folder` +- **Advanced Builder methods**: `data_hashed_placeholder`, `sign_data_hashed_embeddable`, `composed_manifest` + +### Legend +- ✅ = Method available +- ❌ = Method not available +- N/A = Not applicable (e.g., file system access in browser environments) +- ⚠️ = Partial coverage \ No newline at end of file