binding-crate-architecture-patterns
Instructions for binding crate architecture patterns.
Installation
Follow the repository instructions for this skill and your agent. Review the files and dependencies before adding it to your workflow.
View source ↗GuidesSkill instructions
priority: high
Binding Crate Architecture Patterns
Principles
- Minimal wrapper: Bindings are glue only — call Rust core, convert types, convert errors
- Type translation: Clear Rust ↔ host language mapping
- Error conversion: Rust errors → native exceptions/error types
- Memory safety: Respect language-specific ownership models
- Testing: Language-native test suite, not just Rust tests
Crate Naming
{lib}-{language}: -py (PyO3), -node (NAPI-RS), -rb (Magnus), -php (ext-php-rs), -wasm (wasm-bindgen), -ffi (C FFI for Go/Java/C#)
Framework Patterns
| Framework | Macro | Constructor | Error Pattern |
|---|---|---|---|
| PyO3 | #[pyclass] / #[pymethods] |
#[new] |
.map_err(|e| PyException::new_err(e.to_string())) |
| NAPI-RS | #[napi] |
#[napi(constructor)] |
napi::Error::new(Status::GenericFailure, msg) |
| Magnus | #[magnus::wrap] |
define_method("new", ...) |
Into<magnus::RError> |
| ext-php-rs | #[php_class] / #[php_impl] |
pub fn new() |
Return error string |
| wasm-bindgen | #[wasm_bindgen] |
#[wasm_bindgen(constructor)] |
JsValue::from_str(&e.to_string()) |
| C FFI | #[no_mangle] extern "C" |
_new() -> Handle |
Return null + error code |
Type Mapping
| Rust | Python | Node.js | Ruby | C/FFI |
|---|---|---|---|---|
String/&str |
str |
string |
String |
char*/const char* |
u64 |
int |
BigInt |
Integer |
uint64_t |
Result<T> |
Exception | Error thrown | raises | null/error code |
Option<T> |
None/T |
null/T |
nil/T |
NULL/T |
Distribution (packages/)
python/ (PyPI), typescript/ (npm), ruby/ (RubyGems), php/ (Composer), go/ (Go module), java/ (Maven), csharp/ (.NET NuGet)
Anti-Patterns
- Exposing Rust internals to users
- Blocking in async contexts (use
spawn_blocking) - Dangling pointers in FFI returns
- Panicking instead of returning errors (
unwrap()in binding code)
Examples
Read the usage examples in the source repository.
View source ↗Source history
- Indexed on
- 2026-03-11
- Index updated
- 2026-03-11
- Branch
- main
Index and sync dates describe this directory. View the source repository for code history.
GitHub ↗chat Comments (0)
Sign in to join the discussion and leave a comment.
No comments yet. Be the first to share your thoughts!