binding-crate-architecture-patterns
maintained by kreuzberg-dev
star
560
account_tree
50
verified_user
MIT License
name: binding-crate-architecture-patterns description: "Instructions for binding crate architecture patterns."
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)
chat Comments (0)
Sign in to join the discussion and leave a comment.
Skill Details
GitHub Stars
560
GitHub Forks
50
Created
Mar 2026
Last Updated
4个月前
development
development architecture patterns
Related Skills
Build your own?
Join 12,000+ developers contributing to the Claude ecosystem.
No comments yet. Be the first to share your thoughts!