diff --git a/.gitignore b/.gitignore index e710a67..3defbc7 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ node_modules/ package.json package-lock.json +target/ \ No newline at end of file diff --git a/AI_prompt.md b/AI_prompt.md index 318f4dc..8560444 100644 --- a/AI_prompt.md +++ b/AI_prompt.md @@ -143,7 +143,7 @@ Since I develop src folder before I adopt SDD_FRAMEWORK.md approach, can you che # ---------------------------------------------- 100 --------------------------------------------- # -Check NATSBridge/docs folder I want to update the content of the following files according to ASG_Framework/ASG_Framework.md: +I updated src/NATSBridge.jl. Check and NATSBridge/docs folder I want to update the content of the following files according to ASG_Framework/ASG_Framework.md: - NATSBridge/docs/requirements.md - NATSBridge/docs/specification.md - NATSBridge/docs/ui-specification.md (you'll need to create this one) @@ -153,20 +153,50 @@ I'll do the other docs not listed here later myself. -now help me update the following fileaccording to ASG_Framework/ASG_Framework.md: +now help me update the following file according to ASG_Framework/ASG_Framework.md: - NATSBridge/docs/specification.md -Check NATSBridge/docs folder. I would like to expand this package to include Dart support. -Can you update the content of the following files according to ASG_Framework/ASG_Framework.md: -- NATSBridge/docs/requirements.md -- NATSBridge/docs/specification.md -- NATSBridge/docs/walkthrough.md -- NATSBridge/docs/architecture.md +Check ./docs folder. I would like to expand this package (NATSBRIDGE) to include Rust support. +Can you update the content of the following files according to /home/ton/docker-apps/sommpanion/ASG_Framework/ASG_Framework.md: +- ./docs/requirements.md +- ./docs/specification.md +- ./docs/walkthrough.md +- ./docs/architecture.md + + +I updated ./src/NATSBridge.jl. Use it as groundtruth. Check ./docs folder I want to update the content of the following files according to /home/ton/docker-apps/sommpanion/ASG_Framework/ASG_Framework.md: +- ./docs/requirements.md +- ./docs/specification.md +- ./docs/walkthrough.md +- ./docs/architecture.md + + + + +Check the following files: +- ./docs/requirements.md +- ./docs/specification.md +- ./docs/architecture.md +- ./docs/walkthrough.md +I would like to expand this package (NATSBRIDGE) to include Rust support. +Now help me update Rust implementation of this package at ./src/natsbridge.rs. + + + + + +I want to build a client-side-rendering Dioxus-based chat webapp. +Dioxus version 0.7+ should be great. +I already populate the current folder for the project. +my server REST API endpoint is sommpanion.yiem.cc/agent-fronent/api/v1/chat but I didn't run the server yet. A message format is JSON string. +I just placed my custom package for encode and decode message at ./src/natsbridge.rs. smartsend() is for encoding and smartreceive() is for decoding. +you may also check the file /home/ton/docker-apps/sommpanion/NATSBridge/docs/walkthrough.md for more info about my package. +You can test whether Dioxus webapp can be build using this command "dx bundle --web --release --debug-symbols=false" diff --git a/Cargo.lock b/Cargo.lock new file mode 100644 index 0000000..a8bdfc5 --- /dev/null +++ b/Cargo.lock @@ -0,0 +1,1915 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +version = 4 + +[[package]] +name = "android_system_properties" +version = "0.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "819e7219dbd41043ac279b19830f2efc897156490d7fd6ea916720117ee66311" +dependencies = [ + "libc", +] + +[[package]] +name = "anyhow" +version = "1.0.102" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7f202df86484c868dbad7eaa557ef785d5c66295e41b460ef922eca0723b842c" + +[[package]] +name = "async-trait" +version = "0.1.89" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9035ad2d096bed7955a320ee7e2230574d28fd3c3a0f186cbea1ff3c7eed5dbb" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "atomic-waker" +version = "1.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1505bd5d3d116872e7271a6d4e16d81d0c8570876c8de68093a09ac269d8aac0" + +[[package]] +name = "autocfg" +version = "1.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c08606f8c3cbf4ce6ec8e28fb0014a2c086708fe954eaa885384a6165172e7e8" + +[[package]] +name = "base64" +version = "0.22.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6" + +[[package]] +name = "bitflags" +version = "2.11.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c4512299f36f043ab09a583e57bceb5a5aab7a73db1805848e8fef3c9e8c78b3" + +[[package]] +name = "bumpalo" +version = "3.20.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5d20789868f4b01b2f2caec9f5c4e0213b41e3e5702a50157d699ae31ced2fcb" + +[[package]] +name = "bytes" +version = "1.11.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1e748733b7cbc798e1434b6ac524f0c1ff2ab456fe201501e6497c8417a4fc33" + +[[package]] +name = "cc" +version = "1.2.62" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a1dce859f0832a7d088c4f1119888ab94ef4b5d6795d1ce05afb7fe159d79f98" +dependencies = [ + "find-msvc-tools", + "shlex", +] + +[[package]] +name = "cfg-if" +version = "1.0.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801" + +[[package]] +name = "chrono" +version = "0.4.44" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c673075a2e0e5f4a1dde27ce9dee1ea4558c7ffe648f576438a20ca1d2acc4b0" +dependencies = [ + "iana-time-zone", + "js-sys", + "num-traits", + "serde", + "wasm-bindgen", + "windows-link", +] + +[[package]] +name = "core-foundation" +version = "0.9.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "91e195e091a93c46f7102ec7818a2aa394e1e1771c3ab4825963fa03e45afb8f" +dependencies = [ + "core-foundation-sys", + "libc", +] + +[[package]] +name = "core-foundation" +version = "0.10.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b2a6cd9ae233e7f62ba4e9353e81a88df7fc8a5987b8d445b4d90c879bd156f6" +dependencies = [ + "core-foundation-sys", + "libc", +] + +[[package]] +name = "core-foundation-sys" +version = "0.8.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b" + +[[package]] +name = "displaydoc" +version = "0.2.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "97369cbbc041bc366949bc74d34658d6cda5621039731c6310521892a3a20ae0" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "encoding_rs" +version = "0.8.35" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "75030f3c4f45dafd7586dd6780965a8c7e8e285a5ecb86713e63a79c5b2766f3" +dependencies = [ + "cfg-if", +] + +[[package]] +name = "equivalent" +version = "1.0.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f" + +[[package]] +name = "errno" +version = "0.3.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb" +dependencies = [ + "libc", + "windows-sys 0.61.2", +] + +[[package]] +name = "fastrand" +version = "2.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9f1f227452a390804cdb637b74a86990f2a7d7ba4b7d5693aac9b4dd6defd8d6" + +[[package]] +name = "find-msvc-tools" +version = "0.1.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582" + +[[package]] +name = "fnv" +version = "1.0.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3f9eec918d3f24069decb9af1554cad7c880e2da24a9afd88aca000531ab82c1" + +[[package]] +name = "foldhash" +version = "0.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d9c4f5dac5e15c24eb999c26181a6ca40b39fe946cbe4c263c7209467bc83af2" + +[[package]] +name = "foreign-types" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f6f339eb8adc052cd2ca78910fda869aefa38d22d5cb648e6485e4d3fc06f3b1" +dependencies = [ + "foreign-types-shared", +] + +[[package]] +name = "foreign-types-shared" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "00b0228411908ca8685dba7fc2cdd70ec9990a6e753e89b6ac91a84c40fbaf4b" + +[[package]] +name = "form_urlencoded" +version = "1.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cb4cb245038516f5f85277875cdaa4f7d2c9a0fa0468de06ed190163b1581fcf" +dependencies = [ + "percent-encoding", +] + +[[package]] +name = "futures" +version = "0.3.32" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8b147ee9d1f6d097cef9ce628cd2ee62288d963e16fb287bd9286455b241382d" +dependencies = [ + "futures-channel", + "futures-core", + "futures-executor", + "futures-io", + "futures-sink", + "futures-task", + "futures-util", +] + +[[package]] +name = "futures-channel" +version = "0.3.32" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "07bbe89c50d7a535e539b8c17bc0b49bdb77747034daa8087407d655f3f7cc1d" +dependencies = [ + "futures-core", + "futures-sink", +] + +[[package]] +name = "futures-core" +version = "0.3.32" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7e3450815272ef58cec6d564423f6e755e25379b217b0bc688e295ba24df6b1d" + +[[package]] +name = "futures-executor" +version = "0.3.32" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "baf29c38818342a3b26b5b923639e7b1f4a61fc5e76102d4b1981c6dc7a7579d" +dependencies = [ + "futures-core", + "futures-task", + "futures-util", +] + +[[package]] +name = "futures-io" +version = "0.3.32" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cecba35d7ad927e23624b22ad55235f2239cfa44fd10428eecbeba6d6a717718" + +[[package]] +name = "futures-macro" +version = "0.3.32" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e835b70203e41293343137df5c0664546da5745f82ec9b84d40be8336958447b" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "futures-sink" +version = "0.3.32" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c39754e157331b013978ec91992bde1ac089843443c49cbc7f46150b0fad0893" + +[[package]] +name = "futures-task" +version = "0.3.32" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "037711b3d59c33004d3856fbdc83b99d4ff37a24768fa1be9ce3538a1cde4393" + +[[package]] +name = "futures-util" +version = "0.3.32" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "389ca41296e6190b48053de0321d02a77f32f8a5d2461dd38762c0593805c6d6" +dependencies = [ + "futures-channel", + "futures-core", + "futures-io", + "futures-macro", + "futures-sink", + "futures-task", + "memchr", + "pin-project-lite", + "slab", +] + +[[package]] +name = "getrandom" +version = "0.2.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0" +dependencies = [ + "cfg-if", + "libc", + "wasi", +] + +[[package]] +name = "getrandom" +version = "0.4.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0de51e6874e94e7bf76d726fc5d13ba782deca734ff60d5bb2fb2607c7406555" +dependencies = [ + "cfg-if", + "libc", + "r-efi", + "wasip2", + "wasip3", +] + +[[package]] +name = "h2" +version = "0.4.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "171fefbc92fe4a4de27e0698d6a5b392d6a0e333506bc49133760b3bcf948733" +dependencies = [ + "atomic-waker", + "bytes", + "fnv", + "futures-core", + "futures-sink", + "http", + "indexmap", + "slab", + "tokio", + "tokio-util", + "tracing", +] + +[[package]] +name = "hashbrown" +version = "0.15.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9229cfe53dfd69f0609a49f65461bd93001ea1ef889cd5529dd176593f5338a1" +dependencies = [ + "foldhash", +] + +[[package]] +name = "hashbrown" +version = "0.17.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a" + +[[package]] +name = "heck" +version = "0.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea" + +[[package]] +name = "http" +version = "1.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e3ba2a386d7f85a81f119ad7498ebe444d2e22c2af0b86b069416ace48b3311a" +dependencies = [ + "bytes", + "itoa", +] + +[[package]] +name = "http-body" +version = "1.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1efedce1fb8e6913f23e0c92de8e62cd5b772a67e7b3946df930a62566c93184" +dependencies = [ + "bytes", + "http", +] + +[[package]] +name = "http-body-util" +version = "0.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b021d93e26becf5dc7e1b75b1bed1fd93124b374ceb73f43d4d4eafec896a64a" +dependencies = [ + "bytes", + "futures-core", + "http", + "http-body", + "pin-project-lite", +] + +[[package]] +name = "httparse" +version = "1.10.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6dbf3de79e51f3d586ab4cb9d5c3e2c14aa28ed23d180cf89b4df0454a69cc87" + +[[package]] +name = "hyper" +version = "1.9.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6299f016b246a94207e63da54dbe807655bf9e00044f73ded42c3ac5305fbcca" +dependencies = [ + "atomic-waker", + "bytes", + "futures-channel", + "futures-core", + "h2", + "http", + "http-body", + "httparse", + "itoa", + "pin-project-lite", + "smallvec", + "tokio", + "want", +] + +[[package]] +name = "hyper-rustls" +version = "0.27.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "33ca68d021ef39cf6463ab54c1d0f5daf03377b70561305bb89a8f83aab66e0f" +dependencies = [ + "http", + "hyper", + "hyper-util", + "rustls", + "tokio", + "tokio-rustls", + "tower-service", +] + +[[package]] +name = "hyper-tls" +version = "0.6.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "70206fc6890eaca9fde8a0bf71caa2ddfc9fe045ac9e5c70df101a7dbde866e0" +dependencies = [ + "bytes", + "http-body-util", + "hyper", + "hyper-util", + "native-tls", + "tokio", + "tokio-native-tls", + "tower-service", +] + +[[package]] +name = "hyper-util" +version = "0.1.20" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "96547c2556ec9d12fb1578c4eaf448b04993e7fb79cbaad930a656880a6bdfa0" +dependencies = [ + "base64", + "bytes", + "futures-channel", + "futures-util", + "http", + "http-body", + "hyper", + "ipnet", + "libc", + "percent-encoding", + "pin-project-lite", + "socket2", + "system-configuration", + "tokio", + "tower-service", + "tracing", + "windows-registry", +] + +[[package]] +name = "iana-time-zone" +version = "0.1.65" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e31bc9ad994ba00e440a8aa5c9ef0ec67d5cb5e5cb0cc7f8b744a35b389cc470" +dependencies = [ + "android_system_properties", + "core-foundation-sys", + "iana-time-zone-haiku", + "js-sys", + "log", + "wasm-bindgen", + "windows-core", +] + +[[package]] +name = "iana-time-zone-haiku" +version = "0.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f31827a206f56af32e590ba56d5d2d085f558508192593743f16b2306495269f" +dependencies = [ + "cc", +] + +[[package]] +name = "icu_collections" +version = "2.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2984d1cd16c883d7935b9e07e44071dca8d917fd52ecc02c04d5fa0b5a3f191c" +dependencies = [ + "displaydoc", + "potential_utf", + "utf8_iter", + "yoke", + "zerofrom", + "zerovec", +] + +[[package]] +name = "icu_locale_core" +version = "2.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "92219b62b3e2b4d88ac5119f8904c10f8f61bf7e95b640d25ba3075e6cac2c29" +dependencies = [ + "displaydoc", + "litemap", + "tinystr", + "writeable", + "zerovec", +] + +[[package]] +name = "icu_normalizer" +version = "2.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c56e5ee99d6e3d33bd91c5d85458b6005a22140021cc324cea84dd0e72cff3b4" +dependencies = [ + "icu_collections", + "icu_normalizer_data", + "icu_properties", + "icu_provider", + "smallvec", + "zerovec", +] + +[[package]] +name = "icu_normalizer_data" +version = "2.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "da3be0ae77ea334f4da67c12f149704f19f81d1adf7c51cf482943e84a2bad38" + +[[package]] +name = "icu_properties" +version = "2.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bee3b67d0ea5c2cca5003417989af8996f8604e34fb9ddf96208a033901e70de" +dependencies = [ + "icu_collections", + "icu_locale_core", + "icu_properties_data", + "icu_provider", + "zerotrie", + "zerovec", +] + +[[package]] +name = "icu_properties_data" +version = "2.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8e2bbb201e0c04f7b4b3e14382af113e17ba4f63e2c9d2ee626b720cbce54a14" + +[[package]] +name = "icu_provider" +version = "2.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "139c4cf31c8b5f33d7e199446eff9c1e02decfc2f0eec2c8d71f65befa45b421" +dependencies = [ + "displaydoc", + "icu_locale_core", + "writeable", + "yoke", + "zerofrom", + "zerotrie", + "zerovec", +] + +[[package]] +name = "id-arena" +version = "2.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3d3067d79b975e8844ca9eb072e16b31c3c1c36928edf9c6789548c524d0d954" + +[[package]] +name = "idna" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3b0875f23caa03898994f6ddc501886a45c7d3d62d04d2d90788d47be1b1e4de" +dependencies = [ + "idna_adapter", + "smallvec", + "utf8_iter", +] + +[[package]] +name = "idna_adapter" +version = "1.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cb68373c0d6620ef8105e855e7745e18b0d00d3bdb07fb532e434244cdb9a714" +dependencies = [ + "icu_normalizer", + "icu_properties", +] + +[[package]] +name = "indexmap" +version = "2.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d466e9454f08e4a911e14806c24e16fba1b4c121d1ea474396f396069cf949d9" +dependencies = [ + "equivalent", + "hashbrown 0.17.1", + "serde", + "serde_core", +] + +[[package]] +name = "ipnet" +version = "2.12.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d98f6fed1fde3f8c21bc40a1abb88dd75e67924f9cffc3ef95607bad8017f8e2" + +[[package]] +name = "itoa" +version = "1.0.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682" + +[[package]] +name = "js-sys" +version = "0.3.98" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "67df7112613f8bfd9150013a0314e196f4800d3201ae742489d999db2f979f08" +dependencies = [ + "cfg-if", + "futures-util", + "once_cell", + "wasm-bindgen", +] + +[[package]] +name = "leb128fmt" +version = "0.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "09edd9e8b54e49e587e4f6295a7d29c3ea94d469cb40ab8ca70b288248a81db2" + +[[package]] +name = "libc" +version = "0.2.186" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66" + +[[package]] +name = "linux-raw-sys" +version = "0.12.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53" + +[[package]] +name = "litemap" +version = "0.8.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "92daf443525c4cce67b150400bc2316076100ce0b3686209eb8cf3c31612e6f0" + +[[package]] +name = "lock_api" +version = "0.4.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "224399e74b87b5f3557511d98dff8b14089b3dadafcab6bb93eab67d3aace965" +dependencies = [ + "scopeguard", +] + +[[package]] +name = "log" +version = "0.4.29" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897" + +[[package]] +name = "memchr" +version = "2.8.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79" + +[[package]] +name = "mime" +version = "0.3.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6877bb514081ee2a7ff5ef9de3281f14a4dd4bceac4c09388074a6b5df8a139a" + +[[package]] +name = "mime_guess" +version = "2.0.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f7c44f8e672c00fe5308fa235f821cb4198414e1c77935c1ab6948d3fd78550e" +dependencies = [ + "mime", + "unicase", +] + +[[package]] +name = "mio" +version = "1.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "50b7e5b27aa02a74bac8c3f23f448f8d87ff11f92d3aac1a6ed369ee08cc56c1" +dependencies = [ + "libc", + "wasi", + "windows-sys 0.61.2", +] + +[[package]] +name = "native-tls" +version = "0.2.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "465500e14ea162429d264d44189adc38b199b62b1c21eea9f69e4b73cb03bbf2" +dependencies = [ + "libc", + "log", + "openssl", + "openssl-probe", + "openssl-sys", + "schannel", + "security-framework", + "security-framework-sys", + "tempfile", +] + +[[package]] +name = "natsbridge" +version = "1.2.0" +dependencies = [ + "async-trait", + "base64", + "chrono", + "futures", + "reqwest", + "serde", + "serde_json", + "tempfile", + "tokio", + "uuid", +] + +[[package]] +name = "num-traits" +version = "0.2.19" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841" +dependencies = [ + "autocfg", +] + +[[package]] +name = "once_cell" +version = "1.21.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50" + +[[package]] +name = "openssl" +version = "0.10.79" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bf0b434746ee2832f4f0baf10137e1cabb18cbe6912c69e2e33263c45250f542" +dependencies = [ + "bitflags", + "cfg-if", + "foreign-types", + "libc", + "openssl-macros", + "openssl-sys", +] + +[[package]] +name = "openssl-macros" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a948666b637a0f465e8564c73e89d4dde00d72d4d473cc972f390fc3dcee7d9c" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "openssl-probe" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7c87def4c32ab89d880effc9e097653c8da5d6ef28e6b539d313baaacfbafcbe" + +[[package]] +name = "openssl-sys" +version = "0.9.115" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "158fe5b292746440aa6e7a7e690e55aeb72d41505e2804c23c6973ad0e9c9781" +dependencies = [ + "cc", + "libc", + "pkg-config", + "vcpkg", +] + +[[package]] +name = "parking_lot" +version = "0.12.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "93857453250e3077bd71ff98b6a65ea6621a19bb0f559a85248955ac12c45a1a" +dependencies = [ + "lock_api", + "parking_lot_core", +] + +[[package]] +name = "parking_lot_core" +version = "0.9.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2621685985a2ebf1c516881c026032ac7deafcda1a2c9b7850dc81e3dfcb64c1" +dependencies = [ + "cfg-if", + "libc", + "redox_syscall", + "smallvec", + "windows-link", +] + +[[package]] +name = "percent-encoding" +version = "2.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220" + +[[package]] +name = "pin-project-lite" +version = "0.2.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd" + +[[package]] +name = "pkg-config" +version = "0.3.33" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "19f132c84eca552bf34cab8ec81f1c1dcc229b811638f9d283dceabe58c5569e" + +[[package]] +name = "potential_utf" +version = "0.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0103b1cef7ec0cf76490e969665504990193874ea05c85ff9bab8b911d0a0564" +dependencies = [ + "zerovec", +] + +[[package]] +name = "prettyplease" +version = "0.2.37" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "479ca8adacdd7ce8f1fb39ce9ecccbfe93a3f1344b3d0d97f20bc0196208f62b" +dependencies = [ + "proc-macro2", + "syn", +] + +[[package]] +name = "proc-macro2" +version = "1.0.106" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "quote" +version = "1.0.45" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "41f2619966050689382d2b44f664f4bc593e129785a36d6ee376ddf37259b924" +dependencies = [ + "proc-macro2", +] + +[[package]] +name = "r-efi" +version = "6.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf" + +[[package]] +name = "redox_syscall" +version = "0.5.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d" +dependencies = [ + "bitflags", +] + +[[package]] +name = "reqwest" +version = "0.12.28" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "eddd3ca559203180a307f12d114c268abf583f59b03cb906fd0b3ff8646c1147" +dependencies = [ + "base64", + "bytes", + "encoding_rs", + "futures-core", + "futures-util", + "h2", + "http", + "http-body", + "http-body-util", + "hyper", + "hyper-rustls", + "hyper-tls", + "hyper-util", + "js-sys", + "log", + "mime", + "mime_guess", + "native-tls", + "percent-encoding", + "pin-project-lite", + "rustls-pki-types", + "serde", + "serde_json", + "serde_urlencoded", + "sync_wrapper", + "tokio", + "tokio-native-tls", + "tokio-util", + "tower", + "tower-http", + "tower-service", + "url", + "wasm-bindgen", + "wasm-bindgen-futures", + "wasm-streams", + "web-sys", +] + +[[package]] +name = "ring" +version = "0.17.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a4689e6c2294d81e88dc6261c768b63bc4fcdb852be6d1352498b114f61383b7" +dependencies = [ + "cc", + "cfg-if", + "getrandom 0.2.17", + "libc", + "untrusted", + "windows-sys 0.52.0", +] + +[[package]] +name = "rustix" +version = "1.1.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b6fe4565b9518b83ef4f91bb47ce29620ca828bd32cb7e408f0062e9930ba190" +dependencies = [ + "bitflags", + "errno", + "libc", + "linux-raw-sys", + "windows-sys 0.61.2", +] + +[[package]] +name = "rustls" +version = "0.23.40" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ef86cd5876211988985292b91c96a8f2d298df24e75989a43a3c73f2d4d8168b" +dependencies = [ + "once_cell", + "rustls-pki-types", + "rustls-webpki", + "subtle", + "zeroize", +] + +[[package]] +name = "rustls-pki-types" +version = "1.14.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "30a7197ae7eb376e574fe940d068c30fe0462554a3ddbe4eca7838e049c937a9" +dependencies = [ + "zeroize", +] + +[[package]] +name = "rustls-webpki" +version = "0.103.13" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "61c429a8649f110dddef65e2a5ad240f747e85f7758a6bccc7e5777bd33f756e" +dependencies = [ + "ring", + "rustls-pki-types", + "untrusted", +] + +[[package]] +name = "rustversion" +version = "1.0.22" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d" + +[[package]] +name = "ryu" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f" + +[[package]] +name = "schannel" +version = "0.1.29" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "91c1b7e4904c873ef0710c1f407dde2e6287de2bebc1bbbf7d430bb7cbffd939" +dependencies = [ + "windows-sys 0.61.2", +] + +[[package]] +name = "scopeguard" +version = "1.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49" + +[[package]] +name = "security-framework" +version = "3.7.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b7f4bc775c73d9a02cde8bf7b2ec4c9d12743edf609006c7facc23998404cd1d" +dependencies = [ + "bitflags", + "core-foundation 0.10.1", + "core-foundation-sys", + "libc", + "security-framework-sys", +] + +[[package]] +name = "security-framework-sys" +version = "2.17.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6ce2691df843ecc5d231c0b14ece2acc3efb62c0a398c7e1d875f3983ce020e3" +dependencies = [ + "core-foundation-sys", + "libc", +] + +[[package]] +name = "semver" +version = "1.0.28" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8a7852d02fc848982e0c167ef163aaff9cd91dc640ba85e263cb1ce46fae51cd" + +[[package]] +name = "serde" +version = "1.0.228" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e" +dependencies = [ + "serde_core", + "serde_derive", +] + +[[package]] +name = "serde_core" +version = "1.0.228" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad" +dependencies = [ + "serde_derive", +] + +[[package]] +name = "serde_derive" +version = "1.0.228" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "serde_json" +version = "1.0.149" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "83fc039473c5595ace860d8c4fafa220ff474b3fc6bfdb4293327f1a37e94d86" +dependencies = [ + "itoa", + "memchr", + "serde", + "serde_core", + "zmij", +] + +[[package]] +name = "serde_urlencoded" +version = "0.7.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d3491c14715ca2294c4d6a88f15e84739788c1d030eed8c110436aafdaa2f3fd" +dependencies = [ + "form_urlencoded", + "itoa", + "ryu", + "serde", +] + +[[package]] +name = "shlex" +version = "1.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64" + +[[package]] +name = "signal-hook-registry" +version = "1.4.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c4db69cba1110affc0e9f7bcd48bbf87b3f4fc7c61fc9155afd4c469eb3d6c1b" +dependencies = [ + "errno", + "libc", +] + +[[package]] +name = "slab" +version = "0.4.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5" + +[[package]] +name = "smallvec" +version = "1.15.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "67b1b7a3b5fe4f1376887184045fcf45c69e92af734b7aaddc05fb777b6fbd03" + +[[package]] +name = "socket2" +version = "0.6.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3a766e1110788c36f4fa1c2b71b387a7815aa65f88ce0229841826633d93723e" +dependencies = [ + "libc", + "windows-sys 0.61.2", +] + +[[package]] +name = "stable_deref_trait" +version = "1.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596" + +[[package]] +name = "subtle" +version = "2.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292" + +[[package]] +name = "syn" +version = "2.0.117" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "sync_wrapper" +version = "1.0.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0bf256ce5efdfa370213c1dabab5935a12e49f2c58d15e9eac2870d3b4f27263" +dependencies = [ + "futures-core", +] + +[[package]] +name = "synstructure" +version = "0.13.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "728a70f3dbaf5bab7f0c4b1ac8d7ae5ea60a4b5549c8a5914361c99147a709d2" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "system-configuration" +version = "0.7.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a13f3d0daba03132c0aa9767f98351b3488edc2c100cda2d2ec2b04f3d8d3c8b" +dependencies = [ + "bitflags", + "core-foundation 0.9.4", + "system-configuration-sys", +] + +[[package]] +name = "system-configuration-sys" +version = "0.6.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8e1d1b10ced5ca923a1fcb8d03e96b8d3268065d724548c0211415ff6ac6bac4" +dependencies = [ + "core-foundation-sys", + "libc", +] + +[[package]] +name = "tempfile" +version = "3.27.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd" +dependencies = [ + "fastrand", + "getrandom 0.4.2", + "once_cell", + "rustix", + "windows-sys 0.61.2", +] + +[[package]] +name = "tinystr" +version = "0.8.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c8323304221c2a851516f22236c5722a72eaa19749016521d6dff0824447d96d" +dependencies = [ + "displaydoc", + "zerovec", +] + +[[package]] +name = "tokio" +version = "1.52.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8fc7f01b389ac15039e4dc9531aa973a135d7a4135281b12d7c1bc79fd57fffe" +dependencies = [ + "bytes", + "libc", + "mio", + "parking_lot", + "pin-project-lite", + "signal-hook-registry", + "socket2", + "tokio-macros", + "windows-sys 0.61.2", +] + +[[package]] +name = "tokio-macros" +version = "2.7.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "385a6cb71ab9ab790c5fe8d67f1645e6c450a7ce006a33de03daa956cf70a496" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "tokio-native-tls" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bbae76ab933c85776efabc971569dd6119c580d8f5d448769dec1764bf796ef2" +dependencies = [ + "native-tls", + "tokio", +] + +[[package]] +name = "tokio-rustls" +version = "0.26.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1729aa945f29d91ba541258c8df89027d5792d85a8841fb65e8bf0f4ede4ef61" +dependencies = [ + "rustls", + "tokio", +] + +[[package]] +name = "tokio-util" +version = "0.7.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9ae9cec805b01e8fc3fd2fe289f89149a9b66dd16786abd8b19cfa7b48cb0098" +dependencies = [ + "bytes", + "futures-core", + "futures-sink", + "pin-project-lite", + "tokio", +] + +[[package]] +name = "tower" +version = "0.5.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ebe5ef63511595f1344e2d5cfa636d973292adc0eec1f0ad45fae9f0851ab1d4" +dependencies = [ + "futures-core", + "futures-util", + "pin-project-lite", + "sync_wrapper", + "tokio", + "tower-layer", + "tower-service", +] + +[[package]] +name = "tower-http" +version = "0.6.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "68d6fdd9f81c2819c9a8b0e0cd91660e7746a8e6ea2ba7c6b2b057985f6bcb51" +dependencies = [ + "bitflags", + "bytes", + "futures-util", + "http", + "http-body", + "pin-project-lite", + "tower", + "tower-layer", + "tower-service", + "url", +] + +[[package]] +name = "tower-layer" +version = "0.3.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "121c2a6cda46980bb0fcd1647ffaf6cd3fc79a013de288782836f6df9c48780e" + +[[package]] +name = "tower-service" +version = "0.3.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8df9b6e13f2d32c91b9bd719c00d1958837bc7dec474d94952798cc8e69eeec3" + +[[package]] +name = "tracing" +version = "0.1.44" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100" +dependencies = [ + "pin-project-lite", + "tracing-core", +] + +[[package]] +name = "tracing-core" +version = "0.1.36" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a" +dependencies = [ + "once_cell", +] + +[[package]] +name = "try-lock" +version = "0.2.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b" + +[[package]] +name = "unicase" +version = "2.9.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dbc4bc3a9f746d862c45cb89d705aa10f187bb96c76001afab07a0d35ce60142" + +[[package]] +name = "unicode-ident" +version = "1.0.24" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75" + +[[package]] +name = "unicode-xid" +version = "0.2.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ebc1c04c71510c7f702b52b7c350734c9ff1295c464a03335b00bb84fc54f853" + +[[package]] +name = "untrusted" +version = "0.9.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8ecb6da28b8a351d773b68d5825ac39017e680750f980f3a1a85cd8dd28a47c1" + +[[package]] +name = "url" +version = "2.5.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ff67a8a4397373c3ef660812acab3268222035010ab8680ec4215f38ba3d0eed" +dependencies = [ + "form_urlencoded", + "idna", + "percent-encoding", + "serde", +] + +[[package]] +name = "utf8_iter" +version = "1.0.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be" + +[[package]] +name = "uuid" +version = "1.23.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ddd74a9687298c6858e9b88ec8935ec45d22e8fd5e6394fa1bd4e99a87789c76" +dependencies = [ + "getrandom 0.4.2", + "js-sys", + "serde_core", + "wasm-bindgen", +] + +[[package]] +name = "vcpkg" +version = "0.2.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "accd4ea62f7bb7a82fe23066fb0957d48ef677f6eeb8215f372f52e48bb32426" + +[[package]] +name = "want" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bfa7760aed19e106de2c7c0b581b509f2f25d3dacaf737cb82ac61bc6d760b0e" +dependencies = [ + "try-lock", +] + +[[package]] +name = "wasi" +version = "0.11.1+wasi-snapshot-preview1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b" + +[[package]] +name = "wasip2" +version = "1.0.3+wasi-0.2.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "20064672db26d7cdc89c7798c48a0fdfac8213434a1186e5ef29fd560ae223d6" +dependencies = [ + "wit-bindgen 0.57.1", +] + +[[package]] +name = "wasip3" +version = "0.4.0+wasi-0.3.0-rc-2026-01-06" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5428f8bf88ea5ddc08faddef2ac4a67e390b88186c703ce6dbd955e1c145aca5" +dependencies = [ + "wit-bindgen 0.51.0", +] + +[[package]] +name = "wasm-bindgen" +version = "0.2.121" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "49ace1d07c165b0864824eee619580c4689389afa9dc9ed3a4c75040d82e6790" +dependencies = [ + "cfg-if", + "once_cell", + "rustversion", + "wasm-bindgen-macro", + "wasm-bindgen-shared", +] + +[[package]] +name = "wasm-bindgen-futures" +version = "0.4.71" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "96492d0d3ffba25305a7dc88720d250b1401d7edca02cc3bcd50633b424673b8" +dependencies = [ + "js-sys", + "wasm-bindgen", +] + +[[package]] +name = "wasm-bindgen-macro" +version = "0.2.121" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8e68e6f4afd367a562002c05637acb8578ff2dea1943df76afb9e83d177c8578" +dependencies = [ + "quote", + "wasm-bindgen-macro-support", +] + +[[package]] +name = "wasm-bindgen-macro-support" +version = "0.2.121" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d95a9ec35c64b2a7cb35d3fead40c4238d0940c86d107136999567a4703259f2" +dependencies = [ + "bumpalo", + "proc-macro2", + "quote", + "syn", + "wasm-bindgen-shared", +] + +[[package]] +name = "wasm-bindgen-shared" +version = "0.2.121" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c4e0100b01e9f0d03189a92b96772a1fb998639d981193d7dbab487302513441" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "wasm-encoder" +version = "0.244.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "990065f2fe63003fe337b932cfb5e3b80e0b4d0f5ff650e6985b1048f62c8319" +dependencies = [ + "leb128fmt", + "wasmparser", +] + +[[package]] +name = "wasm-metadata" +version = "0.244.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bb0e353e6a2fbdc176932bbaab493762eb1255a7900fe0fea1a2f96c296cc909" +dependencies = [ + "anyhow", + "indexmap", + "wasm-encoder", + "wasmparser", +] + +[[package]] +name = "wasm-streams" +version = "0.4.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "15053d8d85c7eccdbefef60f06769760a563c7f0a9d6902a13d35c7800b0ad65" +dependencies = [ + "futures-util", + "js-sys", + "wasm-bindgen", + "wasm-bindgen-futures", + "web-sys", +] + +[[package]] +name = "wasmparser" +version = "0.244.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "47b807c72e1bac69382b3a6fb3dbe8ea4c0ed87ff5629b8685ae6b9a611028fe" +dependencies = [ + "bitflags", + "hashbrown 0.15.5", + "indexmap", + "semver", +] + +[[package]] +name = "web-sys" +version = "0.3.98" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4b572dff8bcf38bad0fa19729c89bb5748b2b9b1d8be70cf90df697e3a8f32aa" +dependencies = [ + "js-sys", + "wasm-bindgen", +] + +[[package]] +name = "windows-core" +version = "0.62.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b8e83a14d34d0623b51dce9581199302a221863196a1dde71a7663a4c2be9deb" +dependencies = [ + "windows-implement", + "windows-interface", + "windows-link", + "windows-result", + "windows-strings", +] + +[[package]] +name = "windows-implement" +version = "0.60.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "windows-interface" +version = "0.59.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "windows-link" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5" + +[[package]] +name = "windows-registry" +version = "0.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "02752bf7fbdcce7f2a27a742f798510f3e5ad88dbe84871e5168e2120c3d5720" +dependencies = [ + "windows-link", + "windows-result", + "windows-strings", +] + +[[package]] +name = "windows-result" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7781fa89eaf60850ac3d2da7af8e5242a5ea78d1a11c49bf2910bb5a73853eb5" +dependencies = [ + "windows-link", +] + +[[package]] +name = "windows-strings" +version = "0.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7837d08f69c77cf6b07689544538e017c1bfcf57e34b4c0ff58e6c2cd3b37091" +dependencies = [ + "windows-link", +] + +[[package]] +name = "windows-sys" +version = "0.52.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d" +dependencies = [ + "windows-targets", +] + +[[package]] +name = "windows-sys" +version = "0.61.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc" +dependencies = [ + "windows-link", +] + +[[package]] +name = "windows-targets" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973" +dependencies = [ + "windows_aarch64_gnullvm", + "windows_aarch64_msvc", + "windows_i686_gnu", + "windows_i686_gnullvm", + "windows_i686_msvc", + "windows_x86_64_gnu", + "windows_x86_64_gnullvm", + "windows_x86_64_msvc", +] + +[[package]] +name = "windows_aarch64_gnullvm" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3" + +[[package]] +name = "windows_aarch64_msvc" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469" + +[[package]] +name = "windows_i686_gnu" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b" + +[[package]] +name = "windows_i686_gnullvm" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66" + +[[package]] +name = "windows_i686_msvc" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66" + +[[package]] +name = "windows_x86_64_gnu" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78" + +[[package]] +name = "windows_x86_64_gnullvm" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d" + +[[package]] +name = "windows_x86_64_msvc" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec" + +[[package]] +name = "wit-bindgen" +version = "0.51.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d7249219f66ced02969388cf2bb044a09756a083d0fab1e566056b04d9fbcaa5" +dependencies = [ + "wit-bindgen-rust-macro", +] + +[[package]] +name = "wit-bindgen" +version = "0.57.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1ebf944e87a7c253233ad6766e082e3cd714b5d03812acc24c318f549614536e" + +[[package]] +name = "wit-bindgen-core" +version = "0.51.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ea61de684c3ea68cb082b7a88508a8b27fcc8b797d738bfc99a82facf1d752dc" +dependencies = [ + "anyhow", + "heck", + "wit-parser", +] + +[[package]] +name = "wit-bindgen-rust" +version = "0.51.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b7c566e0f4b284dd6561c786d9cb0142da491f46a9fbed79ea69cdad5db17f21" +dependencies = [ + "anyhow", + "heck", + "indexmap", + "prettyplease", + "syn", + "wasm-metadata", + "wit-bindgen-core", + "wit-component", +] + +[[package]] +name = "wit-bindgen-rust-macro" +version = "0.51.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0c0f9bfd77e6a48eccf51359e3ae77140a7f50b1e2ebfe62422d8afdaffab17a" +dependencies = [ + "anyhow", + "prettyplease", + "proc-macro2", + "quote", + "syn", + "wit-bindgen-core", + "wit-bindgen-rust", +] + +[[package]] +name = "wit-component" +version = "0.244.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9d66ea20e9553b30172b5e831994e35fbde2d165325bec84fc43dbf6f4eb9cb2" +dependencies = [ + "anyhow", + "bitflags", + "indexmap", + "log", + "serde", + "serde_derive", + "serde_json", + "wasm-encoder", + "wasm-metadata", + "wasmparser", + "wit-parser", +] + +[[package]] +name = "wit-parser" +version = "0.244.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ecc8ac4bc1dc3381b7f59c34f00b67e18f910c2c0f50015669dde7def656a736" +dependencies = [ + "anyhow", + "id-arena", + "indexmap", + "log", + "semver", + "serde", + "serde_derive", + "serde_json", + "unicode-xid", + "wasmparser", +] + +[[package]] +name = "writeable" +version = "0.6.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1ffae5123b2d3fc086436f8834ae3ab053a283cfac8fe0a0b8eaae044768a4c4" + +[[package]] +name = "yoke" +version = "0.8.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "abe8c5fda708d9ca3df187cae8bfb9ceda00dd96231bed36e445a1a48e66f9ca" +dependencies = [ + "stable_deref_trait", + "yoke-derive", + "zerofrom", +] + +[[package]] +name = "yoke-derive" +version = "0.8.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "de844c262c8848816172cef550288e7dc6c7b7814b4ee56b3e1553f275f1858e" +dependencies = [ + "proc-macro2", + "quote", + "syn", + "synstructure", +] + +[[package]] +name = "zerofrom" +version = "0.1.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0ec05a11813ea801ff6d75110ad09cd0824ddba17dfe17128ea0d5f68e6c5272" +dependencies = [ + "zerofrom-derive", +] + +[[package]] +name = "zerofrom-derive" +version = "0.1.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "11532158c46691caf0f2593ea8358fed6bbf68a0315e80aae9bd41fbade684a1" +dependencies = [ + "proc-macro2", + "quote", + "syn", + "synstructure", +] + +[[package]] +name = "zeroize" +version = "1.8.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b97154e67e32c85465826e8bcc1c59429aaaf107c1e4a9e53c8d8ccd5eff88d0" + +[[package]] +name = "zerotrie" +version = "0.2.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0f9152d31db0792fa83f70fb2f83148effb5c1f5b8c7686c3459e361d9bc20bf" +dependencies = [ + "displaydoc", + "yoke", + "zerofrom", +] + +[[package]] +name = "zerovec" +version = "0.11.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "90f911cbc359ab6af17377d242225f4d75119aec87ea711a880987b18cd7b239" +dependencies = [ + "yoke", + "zerofrom", + "zerovec-derive", +] + +[[package]] +name = "zerovec-derive" +version = "0.11.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "625dc425cab0dca6dc3c3319506e6593dcb08a9f387ea3b284dbd52a92c40555" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "zmij" +version = "1.0.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa" diff --git a/Cargo.toml b/Cargo.toml new file mode 100644 index 0000000..e803e68 --- /dev/null +++ b/Cargo.toml @@ -0,0 +1,31 @@ +[package] +name = "natsbridge" +version = "1.2.0" +edition = "2021" +description = "Cross-platform bi-directional data bridge for NATS communication" + +[lib] +name = "natsbridge" +path = "src/natsbridge.rs" + +[dependencies] +serde = { version = "1", features = ["derive"] } +serde_json = "1" +tokio = { version = "1", features = ["full"] } +reqwest = { version = "0.12", features = ["json", "stream", "multipart"] } +uuid = { version = "1", features = ["v4", "serde"] } +base64 = "0.22" +chrono = { version = "0.4", features = ["serde"] } +async-trait = "0.1" +futures = "0.3" + +[dev-dependencies] +tempfile = "3" + +[[example]] +name = "smartsend_example" +path = "examples/smartsend_example.rs" + +[[example]] +name = "smartreceive_example" +path = "examples/smartreceive_example.rs" diff --git a/docs/architecture.md b/docs/architecture.md index 592fd7d..83e7241 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,7 +1,7 @@ # Architecture Documentation: NATSBridge -**Version**: 1.1.0 -**Date**: 2026-03-23 +**Version**: 1.2.0 +**Date**: 2026-05-13 **Status**: Active **Ground Truth**: [`src/NATSBridge.jl`](../src/NATSBridge.jl) **Architecture Level**: C4 Container Level @@ -10,7 +10,7 @@ ## 1. Executive Summary -This document defines the **blueprint** for NATSBridge - the cross-platform bi-directional data bridge that enables seamless communication between **Julia**, **JavaScript**, **Python**, **Dart**, and **MicroPython** applications using NATS as the message bus. +This document defines the **blueprint** for NATSBridge - the cross-platform bi-directional data bridge that enables seamless communication between **Julia**, **JavaScript**, **Python**, **Dart**, **Rust**, and **MicroPython** applications using NATS as the message bus. This architecture document serves as the single source of truth for: - **System Structure**: How components fit together and interact @@ -57,6 +57,7 @@ flowchart TD JS_App[JavaScript Application
Node.js/Browser] Python_App[Python Application
Desktop] Dart_App[Dart Application
Desktop/Flutter/Web] + Rust_App[Rust Application
Server/Desktop] MicroPython_App[MicroPython Device] end @@ -64,12 +65,14 @@ flowchart TD JS_App -->|NATS| NATS_Server Python_App -->|NATS| NATS_Server Dart_App -->|NATS| NATS_Server + Rust_App -->|NATS| NATS_Server MicroPython_App -->|NATS| NATS_Server Julia_App -->|HTTP| File_Server JS_App -->|HTTP| File_Server Python_App -->|HTTP| File_Server Dart_App -->|HTTP| File_Server + Rust_App -->|HTTP| File_Server MicroPython_App -->|HTTP| File_Server style NATS_Server fill:#fff3e0,stroke:#f57c00 @@ -78,6 +81,7 @@ flowchart TD style JS_App fill:#e3f2fd,stroke:#2196f3 style Python_App fill:#e3f2fd,stroke:#2196f3 style Dart_App fill:#fff0f6,stroke:#e91e63 + style Rust_App fill:#dea584,stroke:#e65100 style MicroPython_App fill:#fce4ec,stroke:#e91e63 ``` @@ -85,28 +89,20 @@ flowchart TD ```mermaid flowchart TD - subgraph "Client Container" + subgraph "Client Container" Julia_Module[Julia NATSBridge Module] JS_Module[JavaScript NATSBridge Module] Python_Module[Python NATSBridge Module] Dart_Module[Dart NATSBridge Module] + Rust_Module[Rust NATSBridge Module] MicroPython_Module[MicroPython NATSBridge Module] end - subgraph "NATS Container" - NATS_Client[NATS Client] - NATS_Broker[NATS Broker] - end - - subgraph "File Server Container" - File_Client[HTTP Client] - File_Server[File Server] - end - Julia_Module --> NATS_Client JS_Module --> NATS_Client Python_Module --> NATS_Client Dart_Module --> NATS_Client + Rust_Module --> NATS_Client MicroPython_Module --> NATS_Client NATS_Client --> NATS_Broker @@ -115,6 +111,7 @@ flowchart TD JS_Module --> File_Client Python_Module --> File_Client Dart_Module --> File_Client + Rust_Module --> File_Client MicroPython_Module --> File_Client File_Client --> File_Server @@ -123,6 +120,7 @@ flowchart TD style JS_Module fill:#e3f2fd,stroke:#2196f3 style Python_Module fill:#e3f2fd,stroke:#2196f3 style Dart_Module fill:#fff0f6,stroke:#e91e63 + style Rust_Module fill:#dea584,stroke:#e65100 style MicroPython_Module fill:#fce4ec,stroke:#e91e63 style NATS_Broker fill:#fff3e0,stroke:#f57c00 style File_Server fill:#f3e5f5,stroke:#9c27b4 @@ -139,36 +137,31 @@ flowchart TD Serialize[_serialize_data] Deserialize[_deserialize_data] - BuildEnvelope[build_envelope] - BuildPayload[build_payload] - - PublishMessage[publish_message] + EnvelopeToJson[envelope_to_json] FileServerUpload[fileserver_upload_handler] FileServerDownload[fileserver_download_handler] + + LogTrace[log_trace] end subgraph "Data Models" - Payload[MsgPayloadV1 Struct] - Envelope[MsgEnvelopeV1 Struct] + Payload[msg_payload_v1 Struct] + Envelope[msg_envelope_v1 Struct] end SmartSend --> Serialize - SmartSend --> BuildEnvelope - SmartSend --> BuildPayload - SmartSend --> PublishMessage + SmartSend --> EnvelopeToJson SmartSend --> FileServerUpload - + SmartReceive --> Deserialize SmartReceive --> FileServerDownload - + + EnvelopeToJson --> Envelope Serialize --> Payload - BuildEnvelope --> Envelope - BuildPayload --> Payload style SmartSend fill:#d1fae5,stroke:#10b981 style SmartReceive fill:#d1fae5,stroke:#10b981 - style PublishMessage fill:#fef3c7,stroke:#f59e0b style FileServerUpload fill:#fef3c7,stroke:#f59e0b style FileServerDownload fill:#fef3c7,stroke:#f59e0b ``` @@ -181,15 +174,14 @@ flowchart TD | Component | Purpose | Platform Support | |-----------|---------|------------------| -| **smartsend** | Send data via NATS with automatic transport selection | All | -| **smartreceive** | Receive and process NATS messages | All | +| **smartsend** | Send data via NATS with automatic transport selection, returns (envelope, json_string) for caller to publish | All | +| **smartreceive** | Receive and process NATS messages from JSON string | All | | **_serialize_data** | Serialize data according to payload type | All | | **_deserialize_data** | Deserialize bytes to native data types | All | -| **_build_envelope** | Build message envelope from payloads | All | -| **_build_payload** | Build payload object from serialized data | All | -| **publish_message** | Publish message to NATS subject | All | -| **fileserver_upload_handler** | Upload large payloads to HTTP server | Desktop (Julia/JS/Python/Dart) | -| **fileserver_download_handler** | Download payloads from HTTP server | Desktop (Julia/JS/Python/Dart) | +| **envelope_to_json** | Convert msg_envelope_v1 struct to JSON string | All | +| **log_trace** | Log trace messages with correlation ID | All | +| **fileserver_upload_handler** | Upload large payloads to HTTP server | Desktop (Julia/JS/Python/Dart/Rust) | +| **fileserver_download_handler** | Download payloads from HTTP server with exponential backoff | Desktop (Julia/JS/Python/Dart/Rust) | ### Data Flow @@ -211,7 +203,7 @@ flowchart TD H --> L[Build envelope] L --> M[Convert to JSON] - M --> N[Publish to NATS] + M --> N[Return envelope + JSON to caller] style A fill:#f9f9f9,stroke:#333 style N fill:#e0e7ff,stroke:#3b82f6 @@ -304,7 +296,7 @@ end |------|-------------|---------------|----------|-----------| | `text` | Plain text string | UTF-8 bytes | Base64 | All | | `dictionary` | JSON object | JSON string | Base64/JSON | All | -| `arrowtable` | Apache Arrow IPC | Arrow IPC stream | Base64/arrow-ipc | Desktop (Julia/Python/Node.js/Dart) | +| `arrowtable` | Apache Arrow IPC | Arrow IPC stream | Base64/arrow-ipc | Desktop (Julia/Python/Node.js/Dart/Rust) | | `jsontable` | JSON array of objects | JSON string | Base64/json | All (including Browser/Dart Web) | | `image` | Binary image data | Raw bytes | Base64 | All | | `audio` | Binary audio data | Raw bytes | Base64 | All | @@ -437,11 +429,9 @@ end JavaScript uses async/await for non-blocking I/O: -- **Class-based NATS Client**: Connection management with `keepAlive` support - **Module-level Utilities**: Serialization functions - **Native ArrayBuffer**: Binary data handling (Browser) / Buffer (Node.js) - **Fetch API**: HTTP file server communication -- **Connection Pooling**: `NATSConnectionPool` for high-throughput scenarios #### Node.js Implementation (natsbridge_ssr.js) @@ -449,36 +439,6 @@ JavaScript uses async/await for non-blocking I/O: - **Apache Arrow IPC**: Full support via `apache-arrow` - **Buffer for binary data**: Native Node.js Buffer handling -```javascript -// Class-based NATS client with keepAlive support -class NATSClient { - constructor(url, keepAlive = false) { - this.url = url; - this.connection = null; - this.keepAlive = keepAlive; - } - - async connect() { - if (this.connection) return this.connection; - this.connection = await nats.connect({ servers: this.url }); - return this.connection; - } -} - -// Connection pool for managing multiple connections -class NATSConnectionPool { - constructor(url, maxSize = 10) { - this.url = url; - this.maxSize = maxSize; - this.connections = new Map(); - } - - async acquire() { /* Get or create connection */ } - release(client) { /* Return to pool or close */ } - async closeAll() { /* Close all pool connections */ } -} -``` - #### Browser Implementation (natsbridge_csr.js) - **WebSocket NATS connections**: Uses `ws://` or `wss://` URLs via `nats.ws` @@ -486,23 +446,6 @@ class NATSConnectionPool { - **Uint8Array for binary data**: Browser-compatible binary handling - **Web Crypto API**: UUID generation via `crypto.getRandomValues()` -```javascript -// Class-based NATS client with keepAlive support -class NATSClient { - constructor(url, keepAlive = false) { - this.url = url; // ws:// or wss:// - this.connection = null; - this.keepAlive = keepAlive; - } - - async connect() { - if (this.connection) return this.connection; - this.connection = await nats.connect({ servers: this.url }); - return this.connection; - } -} -``` - ### Python Architecture Python uses classes for stateful operations: @@ -590,6 +533,62 @@ DEFAULT_SIZE_THRESHOLD = 100_000 # 100KB MAX_PAYLOAD_SIZE = 50_000 # 50KB hard limit ``` +### Rust Architecture + +Rust leverages compile-time type safety and async runtimes: + +- **Type-safe payloads**: Rust enum discriminates between `Text`, `Dictionary`, `ArrowTable`, `Binary`, etc. +- **serde serialization**: Automatic JSON deserialization via `#[derive(Serialize, Deserialize)]` +- **tokio runtime**: Efficient async I/O for NATS connections and HTTP file server operations +- **arrow2 integration**: Native Arrow IPC deserialization without intermediate format conversion +- **reqwest**: High-performance HTTP client with built-in TLS and connection pooling +- **Zero-copy patterns**: `Vec` passed directly to avoid unnecessary memory copies +- **Result**: Idiomatic error handling with typed error types + +```rust +// Type-safe payload enum (compile-time discrimination) +#[derive(Serialize, Deserialize, Clone)] +pub enum Payload { + Text(String), + Dictionary(serde_json::Value), + ArrowTable(Vec), + JsonTable(serde_json::Value), + Image(Vec), + Audio(Vec), + Video(Vec), + Binary(Vec), +} + +// Configuration via builder pattern +pub struct SmartsendOptions { + pub broker_url: String, + pub fileserver_url: String, + pub fileserver_upload_handler: Option, + pub size_threshold: usize, + pub correlation_id: String, + pub msg_purpose: String, + pub sender_name: String, + // ... other fields +} + +// NATS client with tokio integration +let conn = nats::connect("nats://localhost:4222").await?; + +// Subscribe and process messages +let mut sub = conn.subscribe("/agent/wine/api/v1/analyze")?; +for msg in sub.messages() { + let envelope: MsgEnvelopeV1 = serde_json::from_slice(&msg.payload)?; + // Type-safe access to payloads + for payload in &envelope.payloads { + match &payload.data { + Payload::ArrowTable(bytes) => { /* process */ }, + Payload::Text(text) => { /* process */ }, + _ => {} + } + } +} +``` + --- ## Scaling Architecture @@ -740,7 +739,7 @@ MAX_PAYLOAD_SIZE = 50_000 # 50KB hard limit |----------|---------|-------------| | `NATS_URL` | `nats://localhost:4222` | NATS server URL | | `FILESERVER_URL` | `http://localhost:8080` | HTTP file server URL | -| `SIZE_THRESHOLD` | `1000000` | Size threshold in bytes | +| `SIZE_THRESHOLD` | `500000` | Size threshold in bytes (0.5MB) | ### Container Deployment @@ -826,7 +825,7 @@ flowchart TD | Version | Supported Platforms | |---------|---------------------| -| v1.0.x | Julia 1.7+, Node.js 16+, Python 3.8+, Dart 2.17+, MicroPython 1.19+ | +| v1.0.x | Julia 1.7+, Node.js 16+, Python 3.8+, Dart 2.17+, Rust 1.70+, MicroPython 1.19+ | --- @@ -834,6 +833,16 @@ flowchart TD | Date | Version | Changes | |------|---------|---------| +| 2026-05-13 | 1.3.0 | Added Rust support with tokio, serde, and arrow2 | All sections | +| - | - | Added Rust to C4 diagrams (context, container) | All sections | +| - | - | Added Rust platform-specific architecture section | specification.md:13 | +| - | - | Updated component table with Rust support | All sections | +| 2026-05-13 | 1.2.0 | Aligned with ground truth implementation (src/NATSBridge.jl) | +| - | - | Removed publish_message component (commented out in source) | +| - | - | Removed NATSClient and NATSConnectionPool classes (not in ground truth) | +| - | - | Updated component diagram to match actual module structure | +| - | - | Updated data flow to show smartsend returns JSON for caller to publish | +| - | - | Fixed SIZE_THRESHOLD default to 500,000 bytes | | 2026-03-15 | 1.1.0 | JavaScript connection management | | - | - | Added NATSClient with keepAlive support | | - | - | Added NATSConnectionPool for connection reuse | @@ -865,6 +874,7 @@ flowchart TD | [`src/natsbridge_csr.js`](../src/natsbridge_csr.js) | Browser | JSON table only, WebSocket NATS | specification.md:2-19 (all sections) | FR-001 through FR-014, NFR-101 through NFR-405 | | [`src/natsbridge.py`](../src/natsbridge.py) | Python | Arrow IPC, async/await | specification.md:2-19 (all sections) | FR-001 through FR-014, NFR-101 through NFR-405 | | [`src/natsbridge.dart`](../src/natsbridge.dart) | Dart | Full feature set, Arrow IPC, async/await | specification.md:2-19 (all sections) | FR-001 through FR-014, NFR-101 through NFR-405 | +| [`src/natsbridge.rs`](../src/natsbridge.rs) | Rust | Full feature set, Arrow IPC, async/await, type-safe | specification.md:2-19 (all sections) | FR-001 through FR-014, NFR-101 through NFR-405 | | [`src/natsbridge_mpy.py`](../src/natsbridge_mpy.py) | MicroPython | Limited to direct transport | specification.md:2-19 (all sections) | FR-005, FR-006, FR-012 | ### 16.3 External Dependencies @@ -887,6 +897,13 @@ flowchart TD | Dart | http | Latest | HTTP file server | specification.md:11 | FR-008, FR-009 | | Dart | uuid | Latest | UUID generation | specification.md:11 | FR-011, NFR-401 | | Dart | dart-arrow | Latest | Arrow IPC support | specification.md:11 | FR-002, FR-012 | +| Rust | nats | Latest | NATS client | specification.md:11 | FR-013, FR-014 | +| Rust | serde | Latest | JSON serialization | specification.md:11 | FR-012, NFR-101, NFR-102 | +| Rust | serde_json | Latest | JSON handling | specification.md:11 | FR-012, NFR-101, NFR-102 | +| Rust | tokio | Latest | Async runtime | specification.md:11 | FR-013, FR-014 | +| Rust | reqwest | Latest | HTTP file server | specification.md:11 | FR-008, FR-009 | +| Rust | uuid | Latest | UUID generation | specification.md:11 | FR-011, NFR-401 | +| Rust | arrow2 | Latest | Arrow IPC support | specification.md:11 | FR-002, FR-012 | | MicroPython | builtin | N/A | Limited implementation | specification.md:11 | FR-005, FR-006, FR-012 | --- diff --git a/docs/requirements.md b/docs/requirements.md index ed178da..00b0596 100644 --- a/docs/requirements.md +++ b/docs/requirements.md @@ -1,7 +1,7 @@ # Requirements Document: NATSBridge -**Version**: 1.0.0 -**Date**: 2026-03-23 +**Version**: 1.2.0 +**Date**: 2026-05-13 **Status**: Active **Ground Truth**: [`src/NATSBridge.jl`](../src/NATSBridge.jl) @@ -11,7 +11,7 @@ ### 1.1 Business Goal -NATSBridge is a cross-platform, bi-directional data bridge that enables seamless communication between **Julia**, **JavaScript**, **Python**, **Dart**, and **MicroPython** applications using NATS as the message bus. The system implements the **Claim-Check pattern** for efficient handling of large payloads (>0.5MB) by uploading them to an HTTP file server instead of sending raw binary data over NATS. +NATSBridge is a cross-platform, bi-directional data bridge that enables seamless communication between **Julia**, **JavaScript**, **Python**, **Dart**, **Rust**, and **MicroPython** applications using NATS as the message bus. The system implements the **Claim-Check pattern** for efficient handling of large payloads (>0.5MB) by uploading them to an HTTP file server instead of sending raw binary data over NATS. ### 1.2 User Stories (with acceptance criteria) @@ -25,6 +25,7 @@ NATSBridge is a cross-platform, bi-directional data bridge that enables seamless | **As a Dart developer**, I want to send tabular data (List) to other platforms | P1 | JSON table format exchange works with Arrow IPC on desktop | | **As a Dart developer**, I want to send large files (>0.5MB) | P1 | Large files are automatically uploaded to file server and URLs are sent via NATS | | **As a MicroPython developer**, I want to send sensor data with minimal memory usage | P1 | Direct transport works for payloads <100KB on memory-constrained devices | +| **As a Rust developer**, I want to send and receive messages with type-safe APIs | P1 | Rust implementation uses serde for serialization, tokio for async, and nats-io for NATS connectivity | | **As a developer**, I want to send mixed-content messages (text + image + file) | P1 | NATSBridge accepts list of (dataname, data, type) tuples and handles each payload appropriately | | **As a developer**, I want to receive multi-payload messages | P1 | NATSBridge returns payloads as list of tuples with correct types preserved | | **As a developer**, I want to use Plik as the file server | P2 | Plik one-shot upload mode is supported with upload ID and token handling | @@ -51,7 +52,7 @@ NATSBridge is a cross-platform, bi-directional data bridge that enables seamless | Feature | Description | |---------|-------------| -| Cross-platform interoperability | Seamless data exchange between Julia, JavaScript, Python, Dart, and MicroPython | +| Cross-platform interoperability | Seamless data exchange between Julia, JavaScript, Python, Dart, Rust, and MicroPython | | Intelligent transport selection | Direct transport (<0.5MB) vs Link transport (≥0.5MB) based on payload size | | Unified API | Consistent `smartsend()` and `smartreceive()` functions across all platforms | | Multi-payload support | List of (dataname, data, type) tuples with appropriate handling | @@ -88,6 +89,11 @@ NATSBridge is a cross-platform, bi-directional data bridge that enables seamless | Dart | nats | Latest stable | | Dart | http | Latest stable | | Dart | uuid | Latest stable | +| Rust | nats | Latest stable | +| Rust | serde | Latest stable | +| Rust | serde_json | Latest stable | +| Rust | tokio | Latest stable | +| Rust | uuid | Latest stable | ### 2.4 Platform Compatibility @@ -98,6 +104,7 @@ NATSBridge is a cross-platform, bi-directional data bridge that enables seamless | Python | 3.8+ | pyarrow required for arrowtable support | | Browser | Latest | No Arrow IPC (uses jsontable only) | | Dart | 2.17+ | Supports Desktop (Dart SDK), Flutter (Dart SDK), and Web (Dart SDK) | +| Rust | 1.70+ | Full support with async/await, Arrow IPC on desktop | | MicroPython | 1.19+ | Limited to direct transport | --- @@ -118,8 +125,8 @@ NATSBridge is a cross-platform, bi-directional data bridge that enables seamless | **FR-010** | Exponential backoff retry | System shall implement exponential backoff with configurable retries (default: 5, base_delay: 100ms, max_delay: 5000ms) for file server download failures | | **FR-011** | Correlation ID propagation | System shall propagate correlation IDs through all message processing steps | | **FR-012** | Message serialization | System shall serialize data types using Base64, JSON, or Arrow IPC encoding | -| **FR-013** | NATS publishing | System shall publish messages to NATS subjects | -| **FR-014** | NATS subscription | System shall receive and process NATS messages | +| **FR-013** | NATS publishing | System shall return JSON string representation for caller to publish to NATS subjects (caller is responsible for actual NATS publish) | +| **FR-014** | NATS subscription | System shall receive and process NATS messages by accepting JSON string from NATS payload | --- @@ -189,14 +196,14 @@ NATSBridge is a cross-platform, bi-directional data bridge that enables seamless | Type | Julia | JavaScript | Python | Dart | MicroPython | Description | |------|-------|------------|--------|------|-------------|-------------| -| `text` | `String` | `string` | `str` | `String` | `str` | Plain text strings | -| `dictionary` | `Dict`, `NamedTuple` | `Object`, `Array` | `dict`, `list` | `Map` | `dict` | JSON-serializable data | -| `arrowtable` | `DataFrame`, `Arrow.Table` | ❌ (Browser), ✅ (Node.js) | `pandas.DataFrame` | `List` (Desktop), `List` (Flutter) | ❌ | Tabular data (Arrow IPC) | -| `jsontable` | `Vector{NamedTuple}` | `Array` | `list[dict]` | `List` | ⚠️ | Tabular data (JSON) - **Only table type in Browser** | -| `image` | `Vector{UInt8}` | `Uint8Array`, `Buffer` | `bytes` | `Uint8List` | `bytearray` | Image binary data | -| `audio` | `Vector{UInt8}` | `Uint8Array`, `Buffer` | `bytes` | `Uint8List` | `bytearray` | Audio binary data | -| `video` | `Vector{UInt8}` | `Uint8Array`, `Buffer` | `bytes` | `Uint8List` | `bytearray` | Video binary data | -| `binary` | `Vector{UInt8}`, `IOBuffer` | `Uint8Array`, `Buffer` | `bytes`, `bytearray` | `Uint8List` | `bytearray` | Generic binary data | +| `text` | `String` | `string` | `str` | `String` | `String` | `str` | Plain text strings | +| `dictionary` | `Dict`, `NamedTuple` | `Object`, `Array` | `dict`, `list` | `Map`, `serde_json::Value` | `String` | `dict` | JSON-serializable data | +| `arrowtable` | `DataFrame`, `Arrow.Table` | ❌ (Browser), ✅ (Node.js) | `pandas.DataFrame` | `List` (Desktop), `List` (Flutter) | `arrow2::Table` | ❌ | Tabular data (Arrow IPC) | +| `jsontable` | `Vector{NamedTuple}` | `Array` | `list[dict]` | `Vec` | ⚠️ | Tabular data (JSON) - **Only table type in Browser** | +| `image` | `Vector{UInt8}` | `Uint8Array`, `Buffer` | `bytes` | `Uint8List` | `Vec` | `bytearray` | Image binary data | +| `audio` | `Vector{UInt8}` | `Uint8Array`, `Buffer` | `bytes` | `Uint8List` | `Vec` | `bytearray` | Audio binary data | +| `video` | `Vector{UInt8}` | `Uint8Array`, `Buffer` | `bytes` | `Uint8List` | `Vec` | `bytearray` | Video binary data | +| `binary` | `Vector{UInt8}`, `IOBuffer` | `Uint8Array`, `Buffer` | `bytes`, `bytearray` | `Uint8List` | `Vec` | `bytearray` | Generic binary data | ### 6.2 Encoding Requirements @@ -220,6 +227,7 @@ NATSBridge is a cross-platform, bi-directional data bridge that enables seamless | Dart Desktop | 0.5MB | Default size threshold | | Dart Flutter | 0.5MB | Default size threshold | | Dart Web | 0.5MB | Default size threshold | +| Rust | 0.5MB | Default size threshold | | MicroPython | 100KB | Lower threshold for memory constraints | ### 7.2 Maximum Payload Size @@ -230,6 +238,7 @@ NATSBridge is a cross-platform, bi-directional data bridge that enables seamless | Dart Desktop | Unlimited | Limited by NATS server configuration | | Dart Flutter | Unlimited | Limited by NATS server configuration | | Dart Web | Unlimited | Limited by NATS server configuration | +| Rust | Unlimited | Limited by NATS server configuration | | MicroPython | 50KB | Hard limit due to 256KB-1MB memory | --- @@ -324,11 +333,11 @@ NATSBridge is a cross-platform, bi-directional data bridge that enables seamless ```julia function smartsend( subject::String, - data::AbstractArray{Tuple{String, Any, String}}; - broker_url::String = "nats://localhost:4222", - fileserver_url::String = "http://localhost:8080", + data::AbstractArray{Tuple{String, T1, String}, 1}; + broker_url::String = DEFAULT_BROKER_URL, + fileserver_url::String = DEFAULT_FILESERVER_URL, fileserver_upload_handler::Function = plik_oneshot_upload, - size_threshold::Int = 1_000_000, + size_threshold::Int = DEFAULT_SIZE_THRESHOLD, correlation_id::String = string(uuid4()), msg_purpose::String = "chat", sender_name::String = "NATSBridge", @@ -336,18 +345,18 @@ function smartsend( receiver_id::String = "", reply_to::String = "", reply_to_msg_id::String = "", - is_publish::Bool = true, - NATS_connection::Union{NATS.Connection, Nothing} = nothing, msg_id::String = string(uuid4()), sender_id::String = string(uuid4()) -)::Tuple{msg_envelope_v1, String} +)::Tuple{msg_envelope_v1, String} where {T1<:Any} ``` +**Note**: NATS publishing is the caller's responsibility. `smartsend` returns `(env::msg_envelope_v1, env_json_str::String)`. + ### 11.2 smartreceive Signature ```julia function smartreceive( - msg::NATS.Msg; + msg_json_str::String; fileserver_download_handler::Function = _fetch_with_backoff, max_retries::Int = 5, base_delay::Int = 100, @@ -355,6 +364,8 @@ function smartreceive( )::JSON.Object{String, Any} ``` +**Note**: Pass `String(nats_msg.payload)` from NATS subscription to `smartreceive`. + --- ## 12. Deployment Requirements @@ -374,7 +385,7 @@ function smartreceive( |----------|---------|-------------| | `NATS_URL` | `nats://localhost:4222` | NATS server URL | | `FILESERVER_URL` | `http://localhost:8080` | HTTP file server URL | -| `SIZE_THRESHOLD` | `1000000` | Size threshold in bytes | +| `SIZE_THRESHOLD` | `500000` | Size threshold in bytes (0.5MB) | --- @@ -390,7 +401,7 @@ function smartreceive( | Version | Supported Platforms | |---------|---------------------| -| v1.0.x | Julia 1.7+, Node.js 16+, Python 3.8+, Dart 2.17+, Browser (latest), MicroPython 1.19+ | +| v1.0.x | Julia 1.7+, Node.js 16+, Python 3.8+, Dart 2.17+, Rust 1.70+, Browser (latest), MicroPython 1.19+ | --- @@ -398,6 +409,13 @@ function smartreceive( | Date | Version | Changes | |------|---------|---------| +| 2026-05-13 | 1.2.0 | Aligned with ground truth implementation (src/NATSBridge.jl) | +| - | - | Fixed smartsend signature: removed is_publish, NATS_connection; added sender_name | +| - | - | Fixed smartreceive signature: takes msg_json_str::String instead of msg::NATS.Msg | +| - | - | Fixed size_threshold default from 1,000,000 to 500,000 | +| - | - | Updated FR-013/FR-014 to reflect caller responsibility for NATS publishing | +| - | - | Updated FR-008/FR-009 to include file path upload overload | +| - | - | Updated SIZE_THRESHOLD env var default to 500000 | | 2026-03-23 | 1.0.0 | Updated to ASG Framework requirements structure | --- @@ -410,6 +428,7 @@ function smartreceive( - [`src/natsbridge.py`](../src/natsbridge.py) - Python implementation - [`src/natsbridge.dart`](../src/natsbridge.dart) - Dart implementation - [`src/natsbridge_mpy.py`](../src/natsbridge_mpy.py) - MicroPython implementation +- [`src/natsbridge.rs`](../src/natsbridge.rs) - Rust implementation - [`README.md`](../README.md) - Project overview - [`docs/specification.md`](./specification.md) - Technical specification - [`docs/ui-specification.md`](./ui-specification.md) - UI specification diff --git a/docs/specification.md b/docs/specification.md index e97bf91..4453119 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -1,7 +1,7 @@ # Specification: NATSBridge -**Version**: 1.1.0 -**Date**: 2026-03-23 +**Version**: 1.2.0 +**Date**: 2026-05-13 **Status**: Active **Ground Truth**: [`src/NATSBridge.jl`](../src/NATSBridge.jl) **Specification Format**: JSON Schema + AsyncAPI @@ -10,7 +10,7 @@ ## 1. Technical Contract Overview -This document defines the **technical contract** for NATSBridge - the cross-platform bi-directional data bridge that enables seamless communication between **Julia**, **JavaScript**, **Python**, **Dart**, and **MicroPython** applications using NATS as the message bus. +This document defines the **technical contract** for NATSBridge - the cross-platform bi-directional data bridge that enables seamless communication between **Julia**, **JavaScript**, **Python**, **Dart**, **Rust**, and **MicroPython** applications using NATS as the message bus. This specification serves as the single source of truth for: - **Inputs**: What data structures are accepted by `smartsend()` @@ -418,11 +418,11 @@ When `transport = "link"`, the `data` field contains a URL pointing to the uploa ```julia function smartsend( subject::String, - data::AbstractArray{Tuple{String, Any, String}}; - broker_url::String = "nats://localhost:4222", - fileserver_url::String = "http://localhost:8080", + data::AbstractArray{Tuple{String, T1, String}, 1}; + broker_url::String = DEFAULT_BROKER_URL, + fileserver_url::String = DEFAULT_FILESERVER_URL, fileserver_upload_handler::Function = plik_oneshot_upload, - size_threshold::Int = 500_000, + size_threshold::Int = DEFAULT_SIZE_THRESHOLD, correlation_id::String = string(uuid4()), msg_purpose::String = "chat", sender_name::String = "NATSBridge", @@ -430,13 +430,13 @@ function smartsend( receiver_id::String = "", reply_to::String = "", reply_to_msg_id::String = "", - is_publish::Bool = true, - NATS_connection::Union{NATS.Connection, Nothing} = nothing, msg_id::String = string(uuid4()), sender_id::String = string(uuid4()) -)::Tuple{msg_envelope_v1, String} +)::Tuple{msg_envelope_v1, String} where {T1<:Any} ``` +**Note**: NATS publishing is the caller's responsibility. Returns `(env::msg_envelope_v1, env_json_str::String)`. + #### Python ```python @@ -454,13 +454,13 @@ async def smartsend( receiver_id: str = "", reply_to: str = "", reply_to_msg_id: str = "", - is_publish: bool = True, - nats_connection: Any = None, msg_id: str = None, sender_id: str = None ) -> Tuple[Dict, str]: ``` +**Note**: NATS publishing is the caller's responsibility. + #### JavaScript (Node.js) ```typescript @@ -479,14 +479,14 @@ async function smartsend( receiver_id?: string; reply_to?: string; reply_to_msg_id?: string; - is_publish?: boolean; - nats_connection?: NATS.Connection; msg_id?: string; sender_id?: string; } ): Promise<[Object, string]>; ``` +**Note**: NATS publishing is the caller's responsibility. + #### JavaScript (Browser) ```typescript @@ -505,51 +505,27 @@ async function smartsend( receiver_id?: string; reply_to?: string; reply_to_msg_id?: string; - is_publish?: boolean; - nats_connection?: NATSClient | NATS.Connection; msg_id?: string; sender_id?: string; } ): Promise<[Object, string]>; - -// NATSClient class for connection management -class NATSClient { - constructor(url: string, keepAlive?: boolean); - connect(): Promise; - publish(subject: string, message: string, correlationId: string): Promise; - close(): Promise; - getConnection(): NATS.Connection | null; - isConnected(): boolean; -} - -// NATSConnectionPool for managing multiple connections -class NATSConnectionPool { - constructor(url: string, maxSize?: number); - acquire(): Promise; - release(client: NATSClient): void; - closeAll(): Promise; -} - -// publishMessage function for manual publishing -async function publishMessage( - brokerUrlOrClient: string | NATSClient | NATS.Connection, - subject: string, - message: string, - correlationId: string, - closeConnection?: boolean -): Promise; ``` +**Note**: NATS publishing is the caller's responsibility. + #### MicroPython ```python def smartsend( subject: str, data: List[Tuple[str, Any, str]], + size_threshold: int = 100_000, # Lower threshold for memory constraints **kwargs ) -> Tuple[Dict, str]: ``` +**Note**: NATS publishing is the caller's responsibility. + #### Dart (Desktop/Flutter) ```dart @@ -567,12 +543,11 @@ Future<[Map, String]> smartsend( String receiverId = '', String replyTo = '', String replyToMsgId = '', - bool isPublish = true, - dynamic natsConnection, String? msgId, String? senderId, }) async { // Returns [envelope, jsonString] + // NATS publishing is caller's responsibility } ``` @@ -593,22 +568,82 @@ Future<[Map, String]> smartsend( String receiverId = '', String replyTo = '', String replyToMsgId = '', - bool isPublish = true, - dynamic natsConnection, String? msgId, String? senderId, }) async { // Returns [envelope, jsonString] + // NATS publishing is caller's responsibility } ``` +#### Rust + +```rust +pub async fn smartsend( + subject: &str, + data: &[(String, Payload, String)], + options: &SmartsendOptions, +) -> Result<(MsgEnvelopeV1, String), NatSBridgeError> + +// SmartsendOptions struct +pub struct SmartsendOptions { + pub broker_url: String, + pub fileserver_url: String, + pub fileserver_upload_handler: Option, + pub size_threshold: usize, + pub correlation_id: String, + pub msg_purpose: String, + pub sender_name: String, + pub receiver_name: String, + pub receiver_id: String, + pub reply_to: String, + pub reply_to_msg_id: String, + pub msg_id: String, + pub sender_id: String, +} + +// Payload enum for type-safe data handling +#[derive(Serialize, Deserialize, Clone)] +pub enum Payload { + Text(String), + Dictionary(serde_json::Value), + ArrowTable(Vec), + JsonTable(serde_json::Value), + Image(Vec), + Audio(Vec), + Video(Vec), + Binary(Vec), +} + +// MsgEnvelopeV1 struct (serde-serializable) +#[derive(Serialize, Deserialize, Clone)] +pub struct MsgEnvelopeV1 { + pub correlation_id: String, + pub msg_id: String, + pub timestamp: String, + pub send_to: String, + pub msg_purpose: String, + pub sender_name: String, + pub sender_id: String, + pub receiver_name: String, + pub receiver_id: String, + pub reply_to: String, + pub reply_to_msg_id: String, + pub broker_url: String, + pub metadata: serde_json::Value, + pub payloads: Vec, +} +``` + +**Note**: NATS publishing is the caller's responsibility. Returns `Result<(MsgEnvelopeV1, String), NatSBridgeError>`. Uses `serde` for JSON serialization. + ### `smartreceive` Function Signature #### Julia ```julia function smartreceive( - msg::NATS.Msg; + msg_json_str::String; # Pass String(nats_msg.payload) from NATS subscription fileserver_download_handler::Function = _fetch_with_backoff, max_retries::Int = 5, base_delay::Int = 100, @@ -616,11 +651,13 @@ function smartreceive( )::JSON.Object{String, Any} ``` +**Note**: Input is JSON string from NATS message payload, not NATS.Msg directly. + #### Python ```python async def smartreceive( - msg: Any, + msg_json_str: str, # JSON string from NATS message payload fileserver_download_handler: Callable = fetch_with_backoff, max_retries: int = 5, base_delay: int = 100, @@ -628,11 +665,13 @@ async def smartreceive( ) -> Dict[str, Any]: ``` +**Note**: Input is JSON string from NATS message payload. + #### JavaScript (Node.js) ```typescript async function smartreceive( - msg: Object, + msg_json_str: string, // JSON string from NATS message payload options?: { fileserver_download_handler?: Function; max_retries?: number; @@ -646,7 +685,7 @@ async function smartreceive( ```typescript async function smartreceive( - msg: Object, + msg_json_str: string, // JSON string from NATS message payload options?: { fileserver_download_handler?: Function; max_retries?: number; @@ -656,17 +695,22 @@ async function smartreceive( ): Promise; ``` +**Note**: Input is JSON string from NATS message payload. + #### MicroPython ```python -def smartreceive(msg: Any, **kwargs) -> Dict[str, Any]: +def smartreceive(msg_json_str: str, **kwargs) -> Dict[str, Any]: ``` +**Note**: Input is JSON string from NATS message payload. + #### Dart (Desktop/Flutter) ```dart Future> smartreceive( - Map msg, { + Map msg_json_str, // JSON object from NATS message payload + { Function? fileserverDownloadHandler, int maxRetries = 5, int baseDelay = 100, @@ -680,7 +724,8 @@ Future> smartreceive( ```dart Future> smartreceive( - Map msg, { + Map msg_json_str, // JSON object from NATS message payload + { Function? fileserverDownloadHandler, int maxRetries = 5, int baseDelay = 100, @@ -690,6 +735,25 @@ Future> smartreceive( } ``` +#### Rust + +```rust +pub async fn smartreceive( + msg_json_str: &str, // JSON string from NATS message payload + options: &SmartreceiveOptions, +) -> Result + +// SmartreceiveOptions struct +pub struct SmartreceiveOptions { + pub fileserver_download_handler: Option, + pub max_retries: u32, + pub base_delay: u64, + pub max_delay: u64, +} +``` + +**Note**: Input is JSON string from NATS message payload. Returns `Result`. + --- ## File Server Interface @@ -703,6 +767,12 @@ function fileserver_upload_handler( dataname::String, data::Vector{UInt8} )::Dict{String, Any} + +# Overload: Upload file from disk +function fileserver_upload_handler( + file_server_url::String, + filepath::String +)::Dict{String, Any} ``` **Return Format**: @@ -796,6 +866,18 @@ function fileserver_download_handler( | File server download | ✅ Supported | HTTP/HTTPS | | Size threshold | 500KB | Configurable | +### Rust + +| Feature | Status | Notes | +|---------|--------|-------| +| Arrow IPC | ✅ Supported | Requires `arrow2` crate | +| JSON table | ✅ Supported | Uses `serde_json` | +| File server upload | ✅ Supported | HTTP/HTTPS via `reqwest` | +| File server download | ✅ Supported | HTTP/HTTPS via `reqwest` with retry | +| Size threshold | 500KB | Configurable | +| Async runtime | ✅ Supported | Uses `tokio` for async I/O | +| Type safety | ✅ Supported | Compile-time type checking via Rust enums | + ### MicroPython | Feature | Status | Notes | @@ -818,6 +900,7 @@ function fileserver_download_handler( | [`src/natsbridge_csr.js`](../src/natsbridge_csr.js) | Browser | JSON table only, WebSocket NATS | Client-side rendering | | [`src/natsbridge.py`](../src/natsbridge.py) | Python | Arrow IPC, async/await | Desktop Python | | [`src/natsbridge.dart`](../src/natsbridge.dart) | Dart | Full feature set, Arrow IPC, async/await | Desktop/Flutter/Web | +| [`src/natsbridge.rs`](../src/natsbridge.rs) | Rust | Full feature set, Arrow IPC, async/await, type-safe | Uses tokio + serde + arrow2 | | [`src/natsbridge_mpy.py`](../src/natsbridge_mpy.py) | MicroPython | Limited to direct transport | Memory-constrained | ### Browser Implementation Notes @@ -832,16 +915,16 @@ The browser implementation ([`src/natsbridge_csr.js`](../src/natsbridge_csr.js)) ### Payload Type Availability by Platform -| Payload Type | Julia | Node.js | Browser | Python | Dart | MicroPython | -|--------------|-------|---------|---------|--------|------|-------------| -| `text` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | -| `dictionary` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | -| `arrowtable` | ✅ | ✅ | ❌ | ✅ | ✅ | ❌ | -| `jsontable` | ✅ | ✅ | ✅ | ✅ | ✅ | ⚠️ | -| `image` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | -| `audio` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | -| `video` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | -| `binary` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| Payload Type | Julia | Node.js | Browser | Python | Dart | Rust | MicroPython | +|--------------|-------|---------|---------|--------|------|------|-------------| +| `text` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| `dictionary` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| `arrowtable` | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ❌ | +| `jsontable` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⚠️ | +| `image` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| `audio` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| `video` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| `binary` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | --- @@ -979,6 +1062,13 @@ flowchart TD | Dart | http | Latest | HTTP file server | | Dart | uuid | Latest | UUID generation | | Dart | dart-arrow | Latest | Arrow IPC support (Desktop/Flutter) | +| Rust | nats | Latest | NATS client | +| Rust | serde | Latest | JSON serialization | +| Rust | serde_json | Latest | JSON handling | +| Rust | tokio | Latest | Async runtime | +| Rust | reqwest | Latest | HTTP file server | +| Rust | uuid | Latest | UUID generation | +| Rust | arrow2 | Latest | Arrow IPC support | | MicroPython | builtin | N/A | Limited implementation | ### Optional Dependencies @@ -1031,6 +1121,8 @@ flowchart TD | [`src/natsbridge_ssr.js`](../src/natsbridge_ssr.js) | Node.js | Arrow IPC, async/await | FR-001 through FR-014, NFR-101 through NFR-405 | | [`src/natsbridge_csr.js`](../src/natsbridge_csr.js) | Browser | JSON table only, WebSocket NATS | FR-001 through FR-014, NFR-101 through NFR-405 | | [`src/natsbridge.py`](../src/natsbridge.py) | Python | Arrow IPC, async/await | FR-001 through FR-014, NFR-101 through NFR-405 | +| [`src/natsbridge.dart`](../src/natsbridge.dart) | Dart | Full feature set, Arrow IPC, async/await | FR-001 through FR-014, NFR-101 through NFR-405 | +| [`src/natsbridge.rs`](../src/natsbridge.rs) | Rust | Full feature set, Arrow IPC, async/await, type-safe | FR-001 through FR-014, NFR-101 through NFR-405 | | [`src/natsbridge_mpy.py`](../src/natsbridge_mpy.py) | MicroPython | Limited to direct transport | FR-005, FR-006, FR-012 | ### 20.3 External Dependencies @@ -1049,6 +1141,17 @@ flowchart TD | Python | nats-py | Latest | NATS client | FR-013, FR-014 | | Python | aiohttp | Latest | HTTP file server | FR-008, FR-009 | | Python | pyarrow | Latest | Arrow IPC support | FR-002, FR-012 | +| Dart | nats | Latest | NATS client | FR-013, FR-014 | +| Dart | http | Latest | HTTP file server | FR-008, FR-009 | +| Dart | uuid | Latest | UUID generation | FR-011, NFR-401 | +| Dart | dart-arrow | Latest | Arrow IPC support | FR-002, FR-012 | +| Rust | nats | Latest | NATS client | FR-013, FR-014 | +| Rust | serde | Latest | JSON serialization | FR-012, NFR-101, NFR-102 | +| Rust | serde_json | Latest | JSON handling | FR-012, NFR-101, NFR-102 | +| Rust | tokio | Latest | Async runtime | FR-013, FR-014 | +| Rust | reqwest | Latest | HTTP file server | FR-008, FR-009 | +| Rust | uuid | Latest | UUID generation | FR-011, NFR-401 | +| Rust | arrow2 | Latest | Arrow IPC support | FR-002, FR-012 | | MicroPython | builtin | N/A | Limited implementation | FR-005, FR-006 | --- @@ -1057,6 +1160,12 @@ flowchart TD | Date | Version | Changes | Requirement ID(s) | |------|---------|---------|-------------------| +| 2026-05-13 | 1.2.0 | Aligned with ground truth implementation (src/NATSBridge.jl) | All | +| - | - | Updated smartsend signatures: removed is_publish, nats_connection; added sender_name | FR-001 through FR-014 | +| - | - | Updated smartreceive signatures: takes msg_json_str::String instead of msg | FR-001 through FR-014 | +| - | - | Removed publishMessage function and NATSClient/NATSConnectionPool classes from browser section | FR-013, FR-014 | +| - | - | Added plik_oneshot_upload(filepath) overload to file server interface | FR-008, FR-009 | +| - | - | Fixed SIZE_THRESHOLD default to 500,000 bytes | FR-003, FR-004 | | 2026-03-23 | 1.1.0 | Updated to ASG Framework specification guidelines | All | | 2026-03-15 | 1.1.0 | Browser connection management | FR-001 through FR-014 | | 2026-03-13 | 1.0.0 | Initial specification | FR-001 through FR-014, NFR-101 through NFR-405 | diff --git a/docs/walkthrough.md b/docs/walkthrough.md index 4f5c554..349aebb 100644 --- a/docs/walkthrough.md +++ b/docs/walkthrough.md @@ -1,7 +1,7 @@ # Walkthrough: NATSBridge -**Version**: 1.0.0 -**Date**: 2026-03-23 +**Version**: 1.2.0 +**Date**: 2026-05-13 **Status**: Active **Ground Truth**: [`src/NATSBridge.jl`](../src/NATSBridge.jl) @@ -9,7 +9,7 @@ ## 1. Executive Summary -This document provides the **end-to-end trace** for NATSBridge - the cross-platform bi-directional data bridge that enables seamless communication between **Julia**, **JavaScript**, **Python**, **Dart**, and **MicroPython** applications using NATS as the message bus. +This document provides the **end-to-end trace** for NATSBridge - the cross-platform bi-directional data bridge that enables seamless communication between **Julia**, **JavaScript**, **Python**, **Dart**, **Rust**, and **MicroPython** applications using NATS as the message bus. This walkthrough serves as the primary onboarding guide for new developers and explains: - **User scenarios** - Real-world use cases from developer perspective @@ -213,23 +213,25 @@ NATSBridge builds the message envelope: - **reply_to**: Tells backend where to send response - **payloads array**: Contains all data with metadata for proper handling -#### Step 5: Publish to NATS +#### Step 5: Publish to NATS (Caller's Responsibility) ```javascript -await NATSBridge.NATSClient.connect("ws://localhost:4222"); -await NATSBridge.NATSClient.publish("/agent/wine/api/v1/prompt", msgJson); +// NATS publishing is the caller's responsibility +const conn = await NATS.connect({ servers: "ws://localhost:4222" }); +await conn.publish("/agent/wine/api/v1/prompt", msgJson); ``` **Rationale**: - NATS provides low-latency message delivery - JSON format ensures cross-platform compatibility +- `smartsend()` returns `(env, msgJson)` - caller handles publishing #### Step 6: Julia Backend Receives Message ```julia # Julia backend -msg = NATS.subscription.next() # Get message from NATS -env = smartreceive(msg) +nats_msg = NATS.subscription.next() # Get message from NATS +env = smartreceive(String(nats_msg.payload)) # env["payloads"] is now: # [ @@ -355,8 +357,8 @@ const response = await plikOneshotUpload( ```julia # Julia backend -msg = NATS.subscription.next() -env = smartreceive(msg) +nats_msg = NATS.subscription.next() +env = smartreceive(String(nats_msg.payload)) # NATSBridge automatically: # 1. Extracts URL from payload @@ -428,8 +430,8 @@ arrow_bytes = buf.getvalue() ```julia # Julia backend -msg = NATS.subscription.next() -env = smartreceive(msg) +nats_msg = NATS.subscription.next() +env = smartreceive(String(nats_msg.payload)) # env["payloads"][1] is now: # ("data", DataFrame with id, name, score columns, "arrowtable") @@ -461,7 +463,155 @@ env, msg_json = smartsend( --- -## User Scenario 4: MicroPython Device +## User Scenario 4: Rust Service with Type-Safe API + +### Scenario Description + +A Rust service needs to process messages from a Julia analytics pipeline and send typed results back. The Rust implementation leverages compile-time type safety via Rust enums and serde for serialization. + +### Step-by-Step Flow + +#### Step 1: Rust Service Receives Message + +```rust +// Rust service - using tokio async runtime +use natsbridge::{smartreceive, MsgEnvelopeV1}; + +#[tokio::main] +async fn main() { + let conn = nats::connect("nats://localhost:4222").unwrap(); + + // Subscribe and receive messages + let mut sub = conn.subscribe("/agent/wine/api/v1/analyze").unwrap(); + + for msg in sub.messages() { + let envelope: MsgEnvelopeV1 = smartreceive( + &String::from_utf8_lossy(&msg.payload), + &Default::default(), + ).await.unwrap(); + + // Type-safe payload access + for payload in &envelope.payloads { + match &payload.data { + Payload::ArrowTable(arrow_bytes) => { + // Process Arrow IPC data using arrow2 + let table = arrow2::io::ipc::read::Reader::new( + std::io::Cursor::new(arrow_bytes.clone()), + ); + println!("Received {} rows", table.len()); + }, + Payload::Text(text) => { + println!("Message: {}", text); + }, + _ => println!("Received {} bytes of {} data", + match &payload.data { + Payload::Binary(b) => b.len(), + _ => 0, + }, + payload.payload_type), + } + } + } +} +``` + +**Rationale**: +- **Type-safe payloads**: Rust enum discriminates between payload types at compile time +- **serde serialization**: Automatic JSON deserialization to `MsgEnvelopeV1` +- **tokio runtime**: Efficient async I/O for NATS and HTTP operations +- **arrow2 integration**: Direct Arrow IPC deserialization without intermediate format + +#### Step 2: Rust Service Sends Processed Results + +```rust +// Rust service sends results back with mixed payload types +use natsbridge::{smartsend, Payload, SmartsendOptions}; + +let results_df = /* processed Arrow table */; +let result_bytes = /* serialize to Arrow IPC */; + +let (envelope, json_str) = smartsend( + "/agent/wine/api/v1/results", + &[ + ( + "results".to_string(), + Payload::ArrowTable(result_bytes), + "arrowtable".to_string(), + ), + ( + "summary".to_string(), + Payload::Text("Analysis complete: 1500 rows processed".to_string()), + "text".to_string(), + ), + ], + &SmartsendOptions { + broker_url: "nats://localhost:4222".to_string(), + reply_to: "/python/worker/v1/results".to_string(), + msg_purpose: "chat".to_string(), + ..Default::default() + }, +).await?; + +// Caller publishes to NATS +conn.publish("/agent/wine/api/v1/results", &json_str)?; +``` + +**Rationale**: +- **Builder pattern**: `SmartsendOptions` provides clean configuration +- **Enum-based payloads**: Type safety prevents sending incorrect data types +- **Default options**: sensible defaults reduce boilerplate +- **Result**: idiomatic Rust error handling + +#### Step 3: Python/Julia Receives Rust Response + +```python +# Python backend receives Rust response +env = await smartreceive(str(nats_msg.payload)) + +# env["payloads"][0] is now: +# ("results", arrow_table_data, "arrowtable") +# env["payloads"][1] is now: +# ("summary", "Analysis complete: 1500 rows processed", "text") +``` + +**Rationale**: +- **Cross-platform parity**: Rust envelope matches other platform envelopes exactly +- **Same JSON wire format**: No protocol translation needed +- **Type preservation**: Arrow IPC and text types preserved across all platforms + +#### Step 4: Large File Transfer from Rust + +```rust +// Rust service sends large binary file via link transport +let large_file_data: Vec = std::fs::read("/data/large_dataset.parquet")?; + +let (envelope, json_str) = smartsend( + "/agent/wine/api/v1/upload", + &[ + ( + "dataset".to_string(), + Payload::Binary(large_file_data), + "binary".to_string(), + ), + ], + &SmartsendOptions { + broker_url: "nats://localhost:4222".to_string(), + fileserver_url: "http://localhost:8080".to_string(), + size_threshold: 500_000, // 0.5MB triggers link transport + ..Default::default() + }, +).await?; +``` + +**Rationale**: +- **Automatic transport selection**: Same 0.5MB threshold as other desktop platforms +- **reqwest integration**: Efficient HTTP client for file server upload/download +- **Exponential backoff**: Built-in retry with configurable parameters +- **Zero-copy where possible**: `Vec` passed directly without intermediate copies + +--- + +## User Scenario 5: MicroPython Device ### Scenario Description @@ -512,8 +662,8 @@ payload_b64 = base64.b64encode(json_bytes).decode('ascii') ```python # Python backend -msg = await nats_consumer.next() -env = await smartreceive(msg) +nats_msg = await nats_consumer.next() +env = await smartreceive(str(nats_msg.payload)) # env["payloads"][0] is now: # ("data", {"temperature": 25.5, "humidity": 60.0, ...}, "dictionary") @@ -526,7 +676,7 @@ env = await smartreceive(msg) --- -## User Scenario 5: Cross-Platform Chat with Mixed Payloads +## User Scenario 6: Cross-Platform Chat with Mixed Payloads ### Scenario Description @@ -561,8 +711,8 @@ const [env, msgJson] = await NATSBridge.smartsend( ```python # Python (Backend) -msg = await nats_consumer.next() -env = await smartreceive(msg) +nats_msg = await nats_consumer.next() +env = await smartreceive(str(nats_msg.payload)) # env["payloads"] is now: # [ @@ -580,8 +730,8 @@ env = await smartreceive(msg) ```julia # Julia (Backend) -msg = NATS.subscription.next() -env = smartreceive(msg) +nats_msg = NATS.subscription.next() +env = smartreceive(String(nats_msg.payload)) # env["payloads"] is now: # [ @@ -726,7 +876,7 @@ log_trace(correlation_id, "Published to NATS") |----------|---------|-------------| | `NATS_URL` | `nats://localhost:4222` | NATS server URL | | `FILESERVER_URL` | `http://localhost:8080` | HTTP file server URL | -| `SIZE_THRESHOLD` | `1000000` | Size threshold in bytes | +| `SIZE_THRESHOLD` | `500000` | Size threshold in bytes (0.5MB) | --- @@ -761,6 +911,7 @@ log_trace(correlation_id, "Published to NATS") | [`src/natsbridge_csr.js`](../src/natsbridge_csr.js) | Browser | JSON table only, WebSocket NATS | specification.md:2-19 (all sections) | | [`src/natsbridge.py`](../src/natsbridge.py) | Python | Arrow IPC, async/await | specification.md:2-19 (all sections) | | [`src/natsbridge.dart`](../src/natsbridge.dart) | Dart | Full feature set, Arrow IPC, async/await | specification.md:2-19 (all sections) | +| [`src/natsbridge.rs`](../src/natsbridge.rs) | Rust | Full feature set, Arrow IPC, async/await, type-safe | specification.md:2-19 (all sections) | | [`src/natsbridge_mpy.py`](../src/natsbridge_mpy.py) | MicroPython | Limited to direct transport | specification.md:2-19 (all sections) | --- @@ -769,6 +920,13 @@ log_trace(correlation_id, "Published to NATS") | Date | Version | Changes | Specification Reference | |------|---------|---------|------------------------| +| 2026-05-13 | 1.3.0 | Added Rust support with tokio, serde, and arrow2 | All sections | +| - | - | Added Rust user scenario (User Scenario 4) | specification.md:11 (Rust API) | +| - | - | Updated scenario numbering (MicroPython → Scenario 5, Cross-Platform → Scenario 6) | All sections | +| 2026-05-13 | 1.2.0 | Aligned with ground truth implementation (src/NATSBridge.jl) | All sections | +| - | - | Updated smartreceive calls to use String(nats_msg.payload) pattern | All sections | +| - | - | Removed NATSClient.publish() calls (caller responsible for NATS publishing) | All sections | +| - | - | Removed is_publish and nats_connection parameter references | All sections | | 2026-03-23 | 1.0.0 | Updated to ASG Framework walkthrough guidelines | All sections | | 2026-03-13 | 1.0.0 | Initial walkthrough documentation | specification.md:2-19 (all sections) | diff --git a/examples/smartreceive_example.rs b/examples/smartreceive_example.rs new file mode 100644 index 0000000..0cf631c --- /dev/null +++ b/examples/smartreceive_example.rs @@ -0,0 +1,96 @@ +use natsbridge::{smartreceive, SmartreceiveOptions}; + +#[tokio::main] +async fn main() { + // Simulated NATS message JSON (received from NATS subscription) + let msg_json_str = r#"{ + "correlation_id": "abc123-def456-ghi789", + "msg_id": "msg-uuid-001", + "timestamp": "2026-05-13T12:00:00.000Z", + "send_to": "/agent/wine/api/v1/prompt", + "msg_purpose": "chat", + "sender_name": "js-webapp", + "sender_id": "sender-uuid-001", + "receiver_name": "rust-backend", + "receiver_id": "", + "reply_to": "/agent/wine/api/v1/response", + "reply_to_msg_id": "", + "broker_url": "nats://localhost:4222", + "metadata": {}, + "payloads": [ + { + "id": "payload-uuid-001", + "dataname": "message", + "payload_type": "text", + "transport": "direct", + "encoding": "base64", + "size": 29, + "data": "SGVsbG8gZnJvbSBKYXZhU2NyaXB0ISE=", + "metadata": {"payload_bytes": 29} + }, + { + "id": "payload-uuid-002", + "dataname": "user_data", + "payload_type": "dictionary", + "transport": "direct", + "encoding": "json", + "size": 58, + "data": "eyJ0eXBlIjoiY2hhdCIsInNlbmRlciI6InNlcnZpY2VBIiwicmVjZWl2ZXIiOiJzZXJ2aWNlQiJ9", + "metadata": {"payload_bytes": 58} + } + ] + }"#; + + let options = SmartreceiveOptions::default(); + + match smartreceive(msg_json_str, &options).await { + Ok(envelope) => { + println!("=== Envelope Received ==="); + println!("Correlation ID: {}", envelope.correlation_id); + println!("Message ID: {}", envelope.msg_id); + println!("Subject: {}", envelope.send_to); + println!("Purpose: {}", envelope.msg_purpose); + println!("Sender: {}", envelope.sender_name); + println!("Receiver: {}", envelope.receiver_name); + println!("Payloads: {}", envelope.payloads.len()); + println!(); + + for payload in &envelope.payloads { + println!("--- Payload: {} ---", payload.dataname); + println!(" Type: {}", payload.payload_type); + println!(" Transport: {}", payload.transport); + println!(" Encoding: {}", payload.encoding); + println!(" Size: {} bytes", payload.size); + + // In a real scenario, you would deserialize payload.data here + // based on payload_type to get the actual data + match payload.payload_type.as_str() { + "text" => { + // For demonstration, decode the base64 + use base64::{Engine as _, engine::general_purpose::STANDARD as BASE64}; + if payload.transport == "direct" { + let decoded = BASE64.decode(&payload.data).unwrap(); + println!(" Data: {}", String::from_utf8_lossy(&decoded)); + } else { + println!(" URL: {}", payload.data); + } + } + "dictionary" => { + use base64::{Engine as _, engine::general_purpose::STANDARD as BASE64}; + if payload.transport == "direct" { + let decoded = BASE64.decode(&payload.data).unwrap(); + let json: serde_json::Value = serde_json::from_slice(&decoded).unwrap(); + println!(" Data: {}", serde_json::to_string_pretty(&json).unwrap()); + } + } + other => { + println!(" Data type: {}", other); + } + } + } + } + Err(e) => { + eprintln!("Error: {}", e); + } + } +} diff --git a/examples/smartsend_example.rs b/examples/smartsend_example.rs new file mode 100644 index 0000000..c8b9343 --- /dev/null +++ b/examples/smartsend_example.rs @@ -0,0 +1,70 @@ +use natsbridge::{smartsend, Payload, SmartsendOptions}; + +#[tokio::main] +async fn main() { + // Create mixed payload data + let payloads = vec![ + ( + "message".to_string(), + Payload::Text("Hello from Rust!".to_string()), + "text".to_string(), + ), + ( + "user_data".to_string(), + Payload::Dictionary(serde_json::json!({ + "name": "Alice", + "role": "admin", + "scores": [95, 88, 92] + })), + "dictionary".to_string(), + ), + ( + "avatar".to_string(), + Payload::Binary(vec![0x89, 0x50, 0x4E, 0x47]), // PNG header + "image".to_string(), + ), + ]; + + let options = SmartsendOptions { + broker_url: "nats://localhost:4222".to_string(), + fileserver_url: "http://localhost:8080".to_string(), + msg_purpose: "chat".to_string(), + sender_name: "rust-example".to_string(), + ..Default::default() + }; + + match smartsend("/agent/wine/api/v1/prompt", &payloads, &options).await { + Ok((envelope, json_str)) => { + println!("=== Envelope Created ==="); + println!("Correlation ID: {}", envelope.correlation_id); + println!("Message ID: {}", envelope.msg_id); + println!("Timestamp: {}", envelope.timestamp); + println!("Subject: {}", envelope.send_to); + println!("Purpose: {}", envelope.msg_purpose); + println!("Sender: {}", envelope.sender_name); + println!("Payloads: {}", envelope.payloads.len()); + println!(); + + for payload in &envelope.payloads { + println!("Payload: {} (type: {}, transport: {}, encoding: {})", + payload.dataname, + payload.payload_type, + payload.transport, + payload.encoding); + println!(" Size: {} bytes", payload.size); + println!(" Data: {}", if payload.transport == "direct" { + &payload.data[..payload.data.len().min(40)] + } else { + &payload.data[..payload.data.len().min(60)] + }); + } + + println!(); + println!("=== JSON String for NATS Publishing ==="); + println!("{}", json_str); + } + Err(e) => { + eprintln!("Error: {}", e); + } + } +} diff --git a/src/NATSBridge.jl b/src/NATSBridge.jl index fd152f5..88bf6db 100644 --- a/src/NATSBridge.jl +++ b/src/NATSBridge.jl @@ -43,7 +43,7 @@ module NATSBridge -using NATS, JSON, Arrow, HTTP, UUIDs, Dates, Base64, PrettyPrinting, DataFrames +using JSON, Arrow, HTTP, UUIDs, Dates, Base64, PrettyPrinting, DataFrames # ---------------------------------------------- 100 --------------------------------------------- # # Constants @@ -340,25 +340,29 @@ end """ smartsend - Send data either directly via NATS or via a fileserver URL, depending on payload size This function intelligently routes data delivery based on payload size relative to a threshold. -If the serialized payload is smaller than `size_threshold`, it encodes the data as Base64 and publishes directly over NATS. -Otherwise, it uploads the data to a fileserver (by default using `plik_oneshot_upload`) and publishes only the download URL over NATS. +If the serialized payload is smaller than `size_threshold`, it encodes the data as Base64 and constructs a "direct" msg_payload_v1. +Otherwise, it uploads the data to a fileserver (by default using `plik_oneshot_upload`) and constructs a "link" msg_payload_v1 with the download URL. The function accepts a list of (dataname, data, type) tuples as input and processes each payload individually. Each payload can have a different type, enabling mixed-content messages (e.g., chat with text, images, audio). +This function creates and returns the msg_envelope_v1 and its JSON string representation only. +NATS publishing must be performed by the caller. + # Function Workflow: 1. Iterates through the list of (dataname, data, type) tuples 2. For each payload: extracts the type from the tuple and serializes accordingly 3. Compares the serialized size against `size_threshold` 4. For small payloads: encodes as Base64, constructs a "direct" msg_payload_v1 5. For large payloads: uploads to the fileserver, constructs a "link" msg_payload_v1 with the URL -6. Converts envelope to JSON string and optionally publishes to NATS +6. Constructs msg_envelope_v1 with all payloads and metadata +7. Converts envelope to JSON string and returns (NATS publishing is handled by the caller) # Arguments: - `subject::String` - NATS subject to publish the message to - - `data::AbstractArray{Tuple{String, Any, String}}` - List of (dataname, data, type) tuples to send + - `data::AbstractArray{Tuple{String, T1, String}, 1}` - List of (dataname, data, type) tuples to send - `dataname::String` - Name of the payload - - `data::Any` - The actual data to send + - `data::T1` - The actual data to send (any type supported by `_serialize_data`) - `payload_type::String` - Payload type: "text", "dictionary", "arrowtable", "jsontable", "image", "audio", "video", "binary" - No standalone `type` parameter - type is specified per payload @@ -367,17 +371,15 @@ Each payload can have a different type, enabling mixed-content messages (e.g., c - `fileserver_url = DEFAULT_FILESERVER_URL` - URL of the HTTP file server for large payloads - `fileserver_upload_handler::Function = plik_oneshot_upload` - Function to handle fileserver uploads (must return Dict with "status", "uploadid", "fileid", "url" keys) - `size_threshold::Int = DEFAULT_SIZE_THRESHOLD` - Threshold in bytes separating direct vs link transport - - `correlation_id::String = string(uuid4())` - Correlation ID for tracing (auto-generated UUID) - - `msg_purpose::String = "chat"` - Purpose of the message: "ACK", "NACK", "updateStatus", "shutdown", "chat", etc. - - `sender_name::String = "NATSBridge"` - Name of the sender - - `receiver_name::String = ""` - Name of the receiver (empty string means broadcast) + - `correlation_id::String = string(uuid4())` - Correlation ID for tracing (auto-generated UUID) + - `msg_purpose::String = "chat"` - Purpose of the message: "ACK", "NACK", "updateStatus", "shutdown", "chat", etc. + - `sender_name::String = "NATSBridge"` - Name of the sender + - `receiver_name::String = ""` - Name of the receiver (empty string means broadcast) - `receiver_id::String = ""` - UUID of the receiver (empty string means broadcast) - - `reply_to::String = ""` - Topic to reply to (empty string if no reply expected) - - `reply_to_msg_id::String = ""` - Message ID this message is replying to - - `is_publish::Bool = true` - Whether to automatically publish the message to NATS - - `NATS_connection::Union{NATS.Connection, Nothing} = nothing` - Pre-existing NATS connection (if provided, uses this connection instead of creating a new one; saves connection establishment overhead) - - `msg_id::String = string(uuid4())` - Message ID (auto-generated UUID if not provided) - - `sender_id::String = string(uuid4())` - Sender ID (auto-generated UUID if not provided) + - `reply_to::String = ""` - Topic to reply to (empty string if no reply expected) + - `reply_to_msg_id::String = ""` - Message ID this message is replying to + - `msg_id::String = string(uuid4())` - Message ID (auto-generated UUID if not provided) + - `sender_id::String = string(uuid4())` - Sender ID (auto-generated UUID if not provided) # Return: - `::Tuple{msg_envelope_v1, String}` - A tuple containing: @@ -412,8 +414,9 @@ env, msg_json = smartsend("chat.subject", [ ("audio_clip", audio_data, "audio") ]) -# Publish the JSON string directly using NATS request-reply pattern -# reply = NATS.request(broker_url, subject, env_json_str; reply_to=reply_to_topic) +# Publish the JSON string directly using NATS (manual publish) +# conn = NATS.connect(broker_url) +# NATS.publish(conn, subject, env_json_str) ``` """ function smartsend( @@ -438,8 +441,6 @@ function smartsend( receiver_id::String = "", reply_to::String = "", reply_to_msg_id::String = "", - is_publish::Bool = true, # some time the user want to get env and env_json_str from this function without publishing the msg - NATS_connection::Union{NATS.Connection, Nothing} = nothing, # a provided connection saves establishing connection overhead. msg_id::String = string(uuid4()), # Message ID sender_id::String = string(uuid4()) # Sender ID )::Tuple{msg_envelope_v1, String} where {T1<:Any} @@ -539,13 +540,15 @@ function smartsend( ) env_json_str = envelope_to_json(env) # Convert envelope to JSON - if is_publish == false - # skip publish a message - elseif is_publish == true && NATS_connection === nothing - publish_message(broker_url, subject, env_json_str, correlation_id) # Publish message to NATS - elseif is_publish == true && NATS_connection !== nothing - publish_message(NATS_connection, subject, env_json_str, correlation_id) # Publish message to NATS - end + # if is_publish == false + # # skip publish a message + # elseif is_publish == true && NATS_connection === nothing + # # Publish message to NATS using new connection + # publish_message(broker_url, subject, env_json_str, correlation_id) + # elseif is_publish == true && NATS_connection !== nothing + # # Publish message to NATS using existing connection + # publish_message(NATS_connection, subject, env_json_str, correlation_id) + # end return (env, env_json_str) end @@ -700,73 +703,73 @@ function _serialize_data(data::Any, payload_type::String) end -""" publish_message - Publish message to NATS -This function publishes a message to a NATS subject with proper -connection management and logging. +# """ publish_message - Publish message to NATS +# This function publishes a message to a NATS subject with proper +# connection management and logging. -# Arguments: - - `broker_url::String` - NATS server URL (e.g., "nats://localhost:4222") - - `subject::String` - NATS subject to publish to (e.g., "/agent/wine/api/v1/prompt") - - `message::String` - JSON message to publish - - `correlation_id::String` - Correlation ID for tracing and logging +# # Arguments: +# - `broker_url::String` - NATS server URL (e.g., "nats://localhost:4222") +# - `subject::String` - NATS subject to publish to (e.g., "/agent/wine/api/v1/prompt") +# - `message::String` - JSON message to publish +# - `correlation_id::String` - Correlation ID for tracing and logging -# Return: - - `nothing` - This function performs publishing but returns nothing +# # Return: +# - `nothing` - This function performs publishing but returns nothing -# Example -```jldoctest -using NATS +# # Example +# ```jldoctest +# using NATS -# Prepare JSON message -message = "{\"correlation_id\":\"abc123\",\"payload\":\"test\"}" +# # Prepare JSON message +# message = "{\"correlation_id\":\"abc123\",\"payload\":\"test\"}" -# Publish to NATS -publish_message("nats://localhost:4222", "my.subject", message, "abc123") -``` -""" -function publish_message(broker_url::String, subject::String, message::String, correlation_id::String) - conn = NATS.connect(broker_url) # Create NATS connection - publish_message(conn, subject, message, correlation_id) -end +# # Publish to NATS +# publish_message("nats://localhost:4222", "my.subject", message, "abc123") +# ``` +# """ +# function publish_message(broker_url::String, subject::String, message::String, correlation_id::String) +# conn = NATS.connect(broker_url) # Create NATS connection +# publish_message(conn, subject, message, correlation_id) +# end -""" publish_message - Publish message to NATS using pre-existing connection -This function publishes a message to a NATS subject using a pre-existing NATS connection, -avoiding the overhead of connection establishment. +# """ publish_message - Publish message to NATS using pre-existing connection +# This function publishes a message to a NATS subject using a pre-existing NATS connection, +# avoiding the overhead of connection establishment. -# Arguments: - - `conn::NATS.Connection` - Pre-existing NATS connection - - `subject::String` - NATS subject to publish to (e.g., "/agent/wine/api/v1/prompt") - - `message::String` - JSON message to publish - - `correlation_id::String` - Correlation ID for tracing and logging +# # Arguments: +# - `conn::NATS.Connection` - Pre-existing NATS connection +# - `subject::String` - NATS subject to publish to (e.g., "/agent/wine/api/v1/prompt") +# - `message::String` - JSON message to publish +# - `correlation_id::String` - Correlation ID for tracing and logging -# Return: - - `nothing` - This function performs publishing but returns nothing +# # Return: +# - `nothing` - This function performs publishing but returns nothing -# Example -```jldoctest -using NATS +# # Example +# ```jldoctest +# using NATS -# Prepare JSON message -message = "{\"correlation_id\":\"abc123\",\"payload\":\"test\"}" +# # Prepare JSON message +# message = "{\"correlation_id\":\"abc123\",\"payload\":\"test\"}" -# Create connection once and reuse for multiple publishes -conn = NATS.connect("nats://localhost:4222") -publish_message(conn, "my.subject", message, "abc123") -# Connection is automatically drained after publish -``` +# # Create connection once and reuse for multiple publishes +# conn = NATS.connect("nats://localhost:4222") +# publish_message(conn, "my.subject", message, "abc123") +# # Connection is automatically drained after publish +# ``` -# Use Case: -Use this version when you already have an established NATS connection and want to publish -multiple messages without the overhead of creating a new connection for each publish. -""" -function publish_message(conn::NATS.Connection, subject::String, message::String, correlation_id::String) - try - NATS.publish(conn, subject, message) # Publish message to NATS - log_trace(correlation_id, "Message published to $subject") # Log successful publish - finally - NATS.drain(conn) # Ensure connection is closed properly - end -end +# # Use Case: +# Use this version when you already have an established NATS connection and want to publish +# multiple messages without the overhead of creating a new connection for each publish. +# """ +# function publish_message(conn::NATS.Connection, subject::String, message::String, correlation_id::String) +# try +# NATS.publish(conn, subject, message) # Publish message to NATS +# log_trace(correlation_id, "Message published to $subject") # Log successful publish +# finally +# NATS.drain(conn) # Ensure connection is closed properly +# end +# end """ smartreceive - Receive and process messages from NATS @@ -783,7 +786,7 @@ A HTTP file server is required along with its download function. 5. For link transport: fetches data from URL with exponential backoff, then deserializes # Arguments: - - `msg::NATS.Msg` - NATS message to process + - `msg_json_str::String` - JSON string from NATS message payload (e.g., `String(nats_msg.payload)`) # Keyword Arguments: - `fileserver_download_handler::Function = _fetch_with_backoff` - Function to handle downloading data from file server URLs @@ -798,19 +801,21 @@ A HTTP file server is required along with its download function. ```jldoctest # Receive and process message msg = nats_message # NATS message -env = smartreceive(msg; fileserver_download_handler=_fetch_with_backoff, max_retries=5, base_delay=100, max_delay=5000) +msg_json_str = String(msg.payload) +env = smartreceive(msg_json_str; fileserver_download_handler=_fetch_with_backoff, max_retries=5, base_delay=100, max_delay=5000) # env["payloads"] = [("dataname1", data1, "type1"), ("dataname2", data2, "type2"), ...] ``` """ function smartreceive( - msg::NATS.Msg; + msg_json_str::String; # get it from String(nats_msg.payload) fileserver_download_handler::Function = _fetch_with_backoff, max_retries::Int = 5, base_delay::Int = 100, max_delay::Int = 5000 )::JSON.Object{String, Any} + # Parse the JSON envelope - env_json_obj = JSON.parse(String(msg.payload)) + env_json_obj = JSON.parse(msg_json_str) log_trace(env_json_obj["correlation_id"], "Processing received message") # Log message processing start # Process all payloads in the envelope diff --git a/src/natsbridge.rs b/src/natsbridge.rs new file mode 100644 index 0000000..dfc194b --- /dev/null +++ b/src/natsbridge.rs @@ -0,0 +1,1230 @@ +// NATSBridge Rust Module +// Cross-platform bi-directional data bridge for NATS communication +// Implements smartsend and smartreceive for NATS communication +// with support for both direct payload transport and URL-based transport +// for larger payloads using the Claim-Check pattern. +// +// File Server Handler Architecture: +// The system uses handler functions to abstract file server operations, +// allowing support for different file server implementations +// (e.g., Plik, AWS S3, custom HTTP server). +// +// Multi-Payload Support (Standard API): +// The system uses a standardized tuple format for all payload operations. +// Each payload is (dataname, data, type) and can have a different type, +// enabling mixed-content messages (e.g., chat with text, images, audio). +// +// Supported types: "text", "dictionary", "arrowtable", "jsontable", +// "image", "audio", "video", "binary" + +use async_trait::async_trait; +use base64::{Engine as _, engine::general_purpose::STANDARD as BASE64}; +use chrono::Utc; +use reqwest::Client; +use serde::{Deserialize, Serialize}; +use serde_json::Value as JsonValue; +use std::collections::HashMap; +use std::fmt; +use std::path::Path; +use std::sync::Arc; +use std::time::Duration; +use tokio::time::sleep; +use uuid::Uuid; + +// ============================================================================ +// Constants +// ============================================================================ + +/// Default size threshold (0.5MB) for switching from direct to link transport +pub const DEFAULT_SIZE_THRESHOLD: usize = 500_000; + +/// Default NATS server URL +pub const DEFAULT_BROKER_URL: &str = "nats://localhost:4222"; + +/// Default HTTP file server URL for link transport +pub const DEFAULT_FILESERVER_URL: &str = "http://localhost:8080"; + +/// Default max retries for download with exponential backoff +pub const DEFAULT_MAX_RETRIES: u32 = 5; + +/// Default base delay for exponential backoff (milliseconds) +pub const DEFAULT_BASE_DELAY: u64 = 100; + +/// Default max delay for exponential backoff (milliseconds) +pub const DEFAULT_MAX_DELAY: u64 = 5_000; + +// ============================================================================ +// Error Types +// ============================================================================ + +/// Errors that can occur during NATSBridge operations +#[derive(Debug)] +pub enum NatSBridgeError { + /// Unsupported or unknown payload type + UnknownPayloadType(String), + /// File server upload failed + UploadFailed(String), + /// File server download failed after retries + DownloadFailed { url: String, retries: u32 }, + /// Unknown transport type + UnknownTransport(String), + /// NATS connection failed + NatConnectionFailed(String), + /// Payload deserialization error + DeserializationError(String), + /// HTTP request error + HttpError { status: u16, message: String }, + /// IO error + IoError(String), + /// JSON serialization/deserialization error + JsonError(String), + /// Base64 decode error + Base64Error(String), + /// Payload size exceeded maximum + SizeExceeded { size: usize, max: usize }, + /// Invalid envelope (missing required fields) + InvalidEnvelope(String), +} + +impl fmt::Display for NatSBridgeError { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match self { + NatSBridgeError::UnknownPayloadType(p) => write!(f, "Unknown payload_type: {}", p), + NatSBridgeError::UploadFailed(msg) => write!(f, "Failed to upload: {}", msg), + NatSBridgeError::DownloadFailed { url, retries } => { + write!(f, "Failed to fetch {} after {} attempts", url, retries) + } + NatSBridgeError::UnknownTransport(t) => write!(f, "Unknown transport type: {}", t), + NatSBridgeError::NatConnectionFailed(msg) => write!(f, "NATS connection failed: {}", msg), + NatSBridgeError::DeserializationError(msg) => { + write!(f, "Deserialization error: {}", msg) + } + NatSBridgeError::HttpError { status, message } => { + write!(f, "HTTP error {}: {}", status, message) + } + NatSBridgeError::IoError(msg) => write!(f, "IO error: {}", msg), + NatSBridgeError::JsonError(msg) => write!(f, "JSON error: {}", msg), + NatSBridgeError::Base64Error(msg) => write!(f, "Base64 error: {}", msg), + NatSBridgeError::SizeExceeded { size, max } => { + write!(f, "Payload size {} exceeds max {}", size, max) + } + NatSBridgeError::InvalidEnvelope(msg) => write!(f, "Invalid envelope: {}", msg), + } + } +} + +impl std::error::Error for NatSBridgeError {} + +// ============================================================================ +// Payload Enum - Type-safe payload data +// ============================================================================ + +/// Type-safe payload data for sending. Each variant represents a supported +/// payload type with its corresponding data representation. +#[derive(Serialize, Deserialize, Clone, Debug)] +pub enum Payload { + Text(String), + Dictionary(JsonValue), + ArrowTable(Vec), + JsonTable(JsonValue), + Image(Vec), + Audio(Vec), + Video(Vec), + Binary(Vec), +} + +impl Payload { + /// Get the payload type string for this variant + pub fn payload_type(&self) -> &'static str { + match self { + Payload::Text(_) => "text", + Payload::Dictionary(_) => "dictionary", + Payload::ArrowTable(_) => "arrowtable", + Payload::JsonTable(_) => "jsontable", + Payload::Image(_) => "image", + Payload::Audio(_) => "audio", + Payload::Video(_) => "video", + Payload::Binary(_) => "binary", + } + } + + /// Get the serialized bytes for this payload + pub fn serialized_bytes(&self) -> Vec { + match self { + Payload::Text(s) => s.as_bytes().to_vec(), + Payload::Dictionary(v) => serde_json::to_vec(v).unwrap_or_default(), + Payload::ArrowTable(b) => b.clone(), + Payload::JsonTable(v) => serde_json::to_vec(v).unwrap_or_default(), + Payload::Image(b) => b.clone(), + Payload::Audio(b) => b.clone(), + Payload::Video(b) => b.clone(), + Payload::Binary(b) => b.clone(), + } + } + + /// Get the size of the serialized bytes + pub fn size(&self) -> usize { + self.serialized_bytes().len() + } +} + +// ============================================================================ +// Message Payload Structure (wire format) +// ============================================================================ + +/// Represents a single payload within a NATS message envelope. +/// Supports both direct transport (base64-encoded data) and link transport (URL-based). +#[derive(Serialize, Deserialize, Clone, Debug, Default)] +pub struct MsgPayloadV1 { + /// Unique identifier for this payload (UUID v4) + pub id: String, + /// Name of the payload (e.g., "login_image", "msg") + pub dataname: String, + /// Payload type: "text", "dictionary", "arrowtable", "jsontable", + /// "image", "audio", "video", "binary" + pub payload_type: String, + /// Transport method: "direct" or "link" + pub transport: String, + /// Encoding method: "none", "json", "base64", "arrow-ipc" + pub encoding: String, + /// Size of the payload in bytes + pub size: usize, + /// Payload data (base64 string for direct transport, URL for link transport) + pub data: String, + /// Optional payload-level metadata + #[serde(skip_serializing_if = "Option::is_none")] + pub metadata: Option>, +} + +impl MsgPayloadV1 { + /// Create a new direct transport payload + pub fn new_direct( + dataname: String, + payload_type: String, + data: String, + size: usize, + ) -> Self { + let encoding = match payload_type.as_str() { + "jsontable" => "json".to_string(), + "arrowtable" => "arrow-ipc".to_string(), + _ => "base64".to_string(), + }; + MsgPayloadV1 { + id: Uuid::new_v4().to_string(), + dataname, + payload_type, + transport: "direct".to_string(), + encoding, + size, + data, + metadata: Some({ + let mut m = HashMap::new(); + m.insert( + "payload_bytes".to_string(), + JsonValue::Number(size.into()), + ); + m + }), + } + } + + /// Create a new link transport payload + pub fn new_link( + dataname: String, + payload_type: String, + url: String, + size: usize, + ) -> Self { + let encoding = match payload_type.as_str() { + "jsontable" => "json".to_string(), + "arrowtable" => "arrow-ipc".to_string(), + _ => "none".to_string(), + }; + MsgPayloadV1 { + id: Uuid::new_v4().to_string(), + dataname, + payload_type, + transport: "link".to_string(), + encoding, + size, + data: url, + metadata: None, + } + } +} + +// ============================================================================ +// Message Envelope Structure (wire format) +// ============================================================================ + +/// Represents a complete NATS message envelope containing multiple payloads +/// with metadata for routing, tracing, and message context. +#[derive(Serialize, Deserialize, Clone, Debug, Default)] +pub struct MsgEnvelopeV1 { + /// Unique identifier to track messages across systems (UUID v4) + pub correlation_id: String, + /// Unique message identifier (UUID v4) + pub msg_id: String, + /// Message publication timestamp (ISO 8601 UTC) + pub timestamp: String, + + /// NATS subject/topic to publish the message to + pub send_to: String, + /// Purpose of the message: "ACK", "NACK", "updateStatus", "shutdown", + /// "chat", "command", "event" + pub msg_purpose: String, + /// Sender application name + pub sender_name: String, + /// Sender UUID (UUID v4) + pub sender_id: String, + /// Receiver application name (empty string = broadcast) + pub receiver_name: String, + /// Receiver UUID (empty string = broadcast) + pub receiver_id: String, + + /// Topic where receiver should reply + pub reply_to: String, + /// Message ID this message is replying to + pub reply_to_msg_id: String, + /// NATS broker URL + pub broker_url: String, + + /// Optional message-level metadata + #[serde(skip_serializing_if = "Option::is_none")] + pub metadata: Option>, + /// List of payloads + pub payloads: Vec, +} + +impl MsgEnvelopeV1 { + /// Create a new message envelope + pub fn new(send_to: String, payloads: Vec) -> Self { + MsgEnvelopeV1 { + correlation_id: Uuid::new_v4().to_string(), + msg_id: Uuid::new_v4().to_string(), + timestamp: Utc::now().to_rfc3339(), + send_to, + msg_purpose: "chat".to_string(), + sender_name: "NATSBridge".to_string(), + sender_id: Uuid::new_v4().to_string(), + receiver_name: String::new(), + receiver_id: String::new(), + reply_to: String::new(), + reply_to_msg_id: String::new(), + broker_url: DEFAULT_BROKER_URL.to_string(), + metadata: Some(HashMap::new()), + payloads, + } + } + + /// Convert the envelope to a JSON string for NATS publishing + pub fn to_json(&self) -> Result { + serde_json::to_string(self).map_err(|e| NatSBridgeError::JsonError(e.to_string())) + } +} + +// ============================================================================ +// Options Structures +// ============================================================================ + +/// Options for the `smartsend` function +pub struct SmartsendOptions { + /// NATS server URL + pub broker_url: String, + /// HTTP file server URL for large payloads + pub fileserver_url: String, + /// Custom file server upload handler (optional, uses Plik by default) + pub fileserver_upload_handler: Option>, + /// Size threshold in bytes for switching from direct to link transport + pub size_threshold: usize, + /// Correlation ID for distributed tracing (auto-generated if empty) + pub correlation_id: String, + /// Purpose of the message + pub msg_purpose: String, + /// Sender application name + pub sender_name: String, + /// Receiver application name (empty = broadcast) + pub receiver_name: String, + /// Receiver UUID (empty = broadcast) + pub receiver_id: String, + /// Topic to reply to + pub reply_to: String, + /// Message ID being replied to + pub reply_to_msg_id: String, + /// Message ID (auto-generated if empty) + pub msg_id: String, + /// Sender UUID (auto-generated if empty) + pub sender_id: String, +} + +impl Default for SmartsendOptions { + fn default() -> Self { + SmartsendOptions { + broker_url: DEFAULT_BROKER_URL.to_string(), + fileserver_url: DEFAULT_FILESERVER_URL.to_string(), + fileserver_upload_handler: None, + size_threshold: DEFAULT_SIZE_THRESHOLD, + correlation_id: String::new(), + msg_purpose: "chat".to_string(), + sender_name: "NATSBridge".to_string(), + receiver_name: String::new(), + receiver_id: String::new(), + reply_to: String::new(), + reply_to_msg_id: String::new(), + msg_id: String::new(), + sender_id: String::new(), + } + } +} + +/// Options for the `smartreceive` function +pub struct SmartreceiveOptions { + /// Custom file server download handler (optional, uses exponential backoff by default) + pub fileserver_download_handler: Option>, + /// Maximum retry attempts for fetching a URL + pub max_retries: u32, + /// Initial delay for exponential backoff in milliseconds + pub base_delay: u64, + /// Maximum delay for exponential backoff in milliseconds + pub max_delay: u64, +} + +impl Default for SmartreceiveOptions { + fn default() -> Self { + SmartreceiveOptions { + fileserver_download_handler: None, + max_retries: DEFAULT_MAX_RETRIES, + base_delay: DEFAULT_BASE_DELAY, + max_delay: DEFAULT_MAX_DELAY, + } + } +} + +// ============================================================================ +// File Server Handler Traits +// ============================================================================ + +/// Trait for uploading data to a file server +#[async_trait] +pub trait FileUploadHandler: Send + Sync { + /// Upload data to the file server + /// Returns upload ID, file ID, and download URL + async fn upload( + &self, + file_server_url: &str, + dataname: &str, + data: &[u8], + ) -> Result; +} + +/// Result of a file server upload +#[derive(Debug, Clone)] +pub struct UploadResult { + /// HTTP response status code + pub status: u16, + /// Upload session identifier + pub uploadid: String, + /// File identifier within the session + pub fileid: String, + /// Full download URL + pub url: String, +} + +/// Trait for downloading data from a file server +#[async_trait] +pub trait FileDownloadHandler: Send + Sync { + /// Download data from a URL with retry logic + async fn download( + &self, + url: &str, + max_retries: u32, + base_delay: u64, + max_delay: u64, + correlation_id: &str, + ) -> Result, NatSBridgeError>; +} + +// ============================================================================ +// Plik One-Shot Upload Handler Implementation +// ============================================================================ + +/// Default file server upload handler using Plik one-shot mode. +/// +/// Workflow: +/// 1. Creates a one-shot upload session (POST /upload with `{"OneShot": true}`) +/// 2. Retrieves upload ID and token from response +/// 3. Uploads binary data as multipart form data with the token +/// 4. Returns identifiers and download URL +pub struct PlikOneshotUploadHandler; + +#[async_trait] +impl FileUploadHandler for PlikOneshotUploadHandler { + async fn upload( + &self, + file_server_url: &str, + dataname: &str, + data: &[u8], + ) -> Result { + let client = Client::new(); + + // Step 1: Create one-shot upload session + let session_body = serde_json::json!({"OneShot": true}); + let session_resp = client + .post(format!("{}/upload", file_server_url)) + .header("Content-Type", "application/json") + .json(&session_body) + .send() + .await + .map_err(|e| NatSBridgeError::UploadFailed(format!("Failed to create upload session: {}", e)))?; + + if !session_resp.status().is_success() { + return Err(NatSBridgeError::UploadFailed(format!( + "Session creation failed with status: {}", + session_resp.status() + ))); + } + + let session_json: JsonValue = session_resp + .json() + .await + .map_err(|e| NatSBridgeError::UploadFailed(format!("Failed to parse session response: {}", e)))?; + + let uploadid = session_json["id"] + .as_str() + .unwrap_or("") + .to_string(); + let uploadtoken = session_json["uploadToken"] + .as_str() + .unwrap_or("") + .to_string(); + + if uploadid.is_empty() || uploadtoken.is_empty() { + return Err(NatSBridgeError::UploadFailed( + "Missing uploadid or uploadToken in session response".to_string(), + )); + } + + // Step 2: Upload the file as multipart/form-data + let upload_url = format!("{}/file/{}", file_server_url, uploadid); + let form = reqwest::multipart::Form::new() + .part( + "file", + reqwest::multipart::Part::bytes(data.to_vec()) + .file_name(dataname.to_string()) + .mime_str("application/octet-stream") + .map_err(|e| NatSBridgeError::UploadFailed(format!("Invalid MIME type: {}", e)))?, + ); + let resp = client + .post(&upload_url) + .header("X-UploadToken", &uploadtoken) + .multipart(form) + .send() + .await + .map_err(|e| NatSBridgeError::UploadFailed(format!("Upload request failed: {}", e)))?; + + if !resp.status().is_success() { + return Err(NatSBridgeError::UploadFailed(format!( + "Upload failed with status: {}", + resp.status() + ))); + } + + let status_code = resp.status().as_u16(); + let upload_json: JsonValue = resp + .json() + .await + .map_err(|e| NatSBridgeError::UploadFailed(format!("Failed to parse upload response: {}", e)))?; + + let fileid = upload_json["id"].as_str().unwrap_or("").to_string(); + + let url = format!( + "{}/file/{}/{}/{}", + file_server_url, uploadid, fileid, dataname + ); + + Ok(UploadResult { + status: status_code, + uploadid, + fileid, + url, + }) + } +} + +// ============================================================================ +// Exponential Backoff Download Handler Implementation +// ============================================================================ + +/// Default download handler using exponential backoff retry logic. +/// +/// Workflow: +/// 1. Attempts to fetch data from URL +/// 2. On failure, retries with exponentially increasing delay +/// 3. Capped at max_delay between retries +/// 4. Throws error after max_retries are exhausted +pub struct BackoffDownloadHandler; + +#[async_trait] +impl FileDownloadHandler for BackoffDownloadHandler { + async fn download( + &self, + url: &str, + max_retries: u32, + base_delay: u64, + max_delay: u64, + correlation_id: &str, + ) -> Result, NatSBridgeError> { + let client = Client::new(); + let mut delay = base_delay; + + for attempt in 1..=max_retries { + match client.get(url).send().await { + Ok(response) if response.status().is_success() => { + log_trace(correlation_id, &format!( + "Successfully fetched {} on attempt {}", + url, attempt + )); + let bytes = response.bytes().await + .map(|b| b.to_vec()) + .map_err(|_e| NatSBridgeError::DownloadFailed { + url: url.to_string(), + retries: max_retries, + })?; + return Ok(bytes); + } + Ok(response) => { + log_trace(correlation_id, &format!( + "Attempt {} failed with status {}: {}", + attempt, + response.status(), + url + )); + } + Err(e) => { + log_trace(correlation_id, &format!( + "Attempt {} failed: {}: {}", + attempt, + e, + url + )); + } + } + + if attempt < max_retries { + sleep(Duration::from_millis(delay)).await; + delay = (delay * 2).min(max_delay); + } + } + + Err(NatSBridgeError::DownloadFailed { + url: url.to_string(), + retries: max_retries, + }) + } +} + +// ============================================================================ +// Serialization +// ============================================================================ + +/// Serialize payload data according to the specified payload type. +/// Returns the raw bytes for the serialized data. +fn serialize_data(payload: &Payload) -> Result, NatSBridgeError> { + match payload { + Payload::Text(s) => Ok(s.as_bytes().to_vec()), + Payload::Dictionary(v) => serde_json::to_vec(v) + .map_err(|e| NatSBridgeError::DeserializationError(format!("Dictionary serialization failed: {}", e))), + Payload::ArrowTable(b) => Ok(b.clone()), + Payload::JsonTable(v) => serde_json::to_vec(v) + .map_err(|e| NatSBridgeError::DeserializationError(format!("JsonTable serialization failed: {}", e))), + Payload::Image(b) => Ok(b.clone()), + Payload::Audio(b) => Ok(b.clone()), + Payload::Video(b) => Ok(b.clone()), + Payload::Binary(b) => Ok(b.clone()), + } +} + +// ============================================================================ +// Deserialization +// ============================================================================ + +/// Deserialize bytes back to a Payload based on the payload type. +/// Handles direct transport (base64 decoded) and link transport (fetched bytes). +fn deserialize_data( + payload_bytes: &[u8], + payload_type: &str, + _correlation_id: &str, +) -> Result { + match payload_type { + "text" => { + let text = String::from_utf8(payload_bytes.to_vec()) + .map_err(|e| NatSBridgeError::DeserializationError(format!("Invalid UTF-8 for text: {}", e)))?; + Ok(Payload::Text(text)) + } + "dictionary" => { + let json_str = String::from_utf8(payload_bytes.to_vec()) + .map_err(|e| NatSBridgeError::DeserializationError(format!("Invalid UTF-8 for dictionary: {}", e)))?; + let value: JsonValue = serde_json::from_str(&json_str) + .map_err(|e| NatSBridgeError::DeserializationError(format!("Invalid JSON for dictionary: {}", e)))?; + Ok(Payload::Dictionary(value)) + } + "arrowtable" => { + Ok(Payload::ArrowTable(payload_bytes.to_vec())) + } + "jsontable" => { + let json_str = String::from_utf8(payload_bytes.to_vec()) + .map_err(|e| NatSBridgeError::DeserializationError(format!("Invalid UTF-8 for jsontable: {}", e)))?; + let value: JsonValue = serde_json::from_str(&json_str) + .map_err(|e| NatSBridgeError::DeserializationError(format!("Invalid JSON for jsontable: {}", e)))?; + Ok(Payload::JsonTable(value)) + } + "image" => Ok(Payload::Image(payload_bytes.to_vec())), + "audio" => Ok(Payload::Audio(payload_bytes.to_vec())), + "video" => Ok(Payload::Video(payload_bytes.to_vec())), + "binary" => Ok(Payload::Binary(payload_bytes.to_vec())), + _ => Err(NatSBridgeError::UnknownPayloadType(payload_type.to_string())), + } +} + +// ============================================================================ +// Logging +// ============================================================================ + +/// Log a trace message with correlation ID and timestamp. +/// Uses tokio::task::spawn_blocking to avoid blocking the async runtime. +pub fn log_trace(correlation_id: &str, message: &str) { + let ts = Utc::now().format("%Y-%m-%dT%H:%M:%S%.3fZ"); + eprintln!("[{}] [Correlation: {}] {}", ts, correlation_id, message); +} + +// ============================================================================ +// Public API: smartsend +// ============================================================================ + +/// Send data via NATS with automatic transport selection. +/// +/// This function intelligently routes data delivery based on payload size. +/// If the serialized payload is smaller than `size_threshold`, it encodes the +/// data as Base64 and constructs a "direct" MsgPayloadV1. Otherwise, it uploads +/// the data to a file server and constructs a "link" MsgPayloadV1 with the URL. +/// +/// Each payload in the list can have a different type, enabling mixed-content +/// messages (e.g., chat with text, images, audio). +/// +/// NATS publishing is the caller's responsibility. This function returns the +/// envelope and its JSON string representation. +/// +/// # Arguments +/// - `subject`: NATS subject to publish the message to +/// - `data`: Slice of (dataname, payload, payload_type) tuples +/// - `options`: Configuration options +/// +/// # Returns +/// - `Result<(MsgEnvelopeV1, String), NatSBridgeError>` containing the envelope and JSON string +/// +/// # Example +/// ```no_run +/// use natsbridge::{smartsend, Payload, SmartsendOptions}; +/// +/// # async fn example() -> Result<(), Box> { +/// let (envelope, json_str) = smartsend( +/// "/agent/wine/api/v1/prompt", +/// &[ +/// ("msg".to_string(), Payload::Text("Hello!".to_string()), "text".to_string()), +/// ("data".to_string(), Payload::Binary(vec![1, 2, 3]), "binary".to_string()), +/// ], +/// &SmartsendOptions::default(), +/// ).await?; +/// +/// // Caller publishes to NATS +/// // conn.publish("/agent/wine/api/v1/prompt", &json_str)?; +/// # Ok(()) +/// # } +/// ``` +pub async fn smartsend( + subject: &str, + data: &[(String, Payload, String)], + options: &SmartsendOptions, +) -> Result<(MsgEnvelopeV1, String), NatSBridgeError> { + let correlation_id = if options.correlation_id.is_empty() { + Uuid::new_v4().to_string() + } else { + options.correlation_id.clone() + }; + + let msg_id = if options.msg_id.is_empty() { + Uuid::new_v4().to_string() + } else { + options.msg_id.clone() + }; + + let sender_id = if options.sender_id.is_empty() { + Uuid::new_v4().to_string() + } else { + options.sender_id.clone() + }; + + log_trace(&correlation_id, &format!( + "Starting smartsend for subject: {}", subject + )); + + let mut payloads: Vec = Vec::new(); + + // Determine the upload handler to use (custom or default Plik) + let upload_handler: Arc = options.fileserver_upload_handler.clone() + .unwrap_or_else(|| Arc::new(PlikOneshotUploadHandler)); + + for (dataname, payload, payload_type) in data { + // Use the explicitly provided payload_type from the tuple, + // or derive from the Payload enum + let ptype = if payload_type.is_empty() { + payload.payload_type().to_string() + } else { + payload_type.clone() + }; + + // Serialize the payload data + let payload_bytes = serialize_data(payload)?; + let payload_size = payload_bytes.len(); + + log_trace(&correlation_id, &format!( + "Serialized payload '{}' (type: {}) size: {} bytes", + dataname, ptype, payload_size + )); + + if payload_size < options.size_threshold { + // Direct transport: Base64 encode and include in NATS message + let payload_b64 = BASE64.encode(&payload_bytes); + log_trace(&correlation_id, &format!( + "Using direct transport for {} bytes", payload_size + )); + + let msg_payload = MsgPayloadV1::new_direct( + dataname.clone(), + ptype, + payload_b64, + payload_size, + ); + payloads.push(msg_payload); + } else { + // Link transport: Upload to file server, include URL in NATS message + log_trace(&correlation_id, "Using link transport, uploading to fileserver"); + + let upload_result = upload_handler + .upload(&options.fileserver_url, dataname, &payload_bytes) + .await?; + + log_trace(&correlation_id, &format!( + "Uploaded to URL: {}", upload_result.url + )); + + let msg_payload = MsgPayloadV1::new_link( + dataname.clone(), + ptype, + upload_result.url, + payload_size, + ); + payloads.push(msg_payload); + } + } + + // Build the message envelope + let env = MsgEnvelopeV1 { + correlation_id: correlation_id.clone(), + msg_id, + timestamp: Utc::now().to_rfc3339(), + send_to: subject.to_string(), + msg_purpose: options.msg_purpose.clone(), + sender_name: options.sender_name.clone(), + sender_id, + receiver_name: options.receiver_name.clone(), + receiver_id: options.receiver_id.clone(), + reply_to: options.reply_to.clone(), + reply_to_msg_id: options.reply_to_msg_id.clone(), + broker_url: options.broker_url.clone(), + metadata: Some(HashMap::new()), + payloads, + }; + + let env_json_str = env.to_json()?; + + log_trace(&correlation_id, "Envelope created successfully"); + + Ok((env, env_json_str)) +} + +// ============================================================================ +// Helper: store deserialized data back into MsgPayloadV1 +// ============================================================================ + +/// Store deserialized Payload data back into a MsgPayloadV1's data field. +/// After smartreceive(), payload.data contains the deserialized content as a string +/// (decoded text, JSON string, or base64 for binary types). +fn store_deserialized_data(payload: &MsgPayloadV1, deserialized: &Payload) -> MsgPayloadV1 { + let mut p = payload.clone(); + match deserialized { + Payload::Text(s) => p.data = s.clone(), + Payload::Dictionary(v) => p.data = serde_json::to_string(v).unwrap_or_default(), + Payload::JsonTable(v) => p.data = serde_json::to_string(v).unwrap_or_default(), + Payload::ArrowTable(b) => p.data = BASE64.encode(b), + Payload::Image(b) | Payload::Audio(b) | Payload::Video(b) | Payload::Binary(b) => { + p.data = BASE64.encode(b); + } + } + p +} + +// ============================================================================ +// Public API: smartreceive +// ============================================================================ + +/// Receive and process messages from NATS. +/// +/// This function processes incoming NATS messages, handling both direct transport +/// (base64 decoded payloads) and link transport (URL-based payloads). +/// It deserializes the data based on the payload type and returns the envelope +/// with deserialized payloads. +/// +/// # Arguments +/// - `msg_json_str`: JSON string from NATS message payload +/// - `options`: Configuration options +/// +/// # Returns +/// - `Result` with deserialized payloads +/// +/// # Example +/// ```no_run +/// use natsbridge::{smartreceive, SmartreceiveOptions}; +/// use base64::{Engine as _, engine::general_purpose::STANDARD as BASE64}; +/// +/// # async fn example() -> Result<(), Box> { +/// let msg_json_str = r#"{"correlation_id":"abc123","msg_id":"msg-uuid", +/// "timestamp":"2026-01-01T00:00:00Z","send_to":"/test", +/// "msg_purpose":"chat","sender_name":"test","sender_id":"sender-uuid", +/// "receiver_name":"","receiver_id":"","reply_to":"","reply_to_msg_id":"", +/// "broker_url":"nats://localhost:4222","payloads":[{ +/// "id":"payload-uuid","dataname":"msg","payload_type":"text", +/// "transport":"direct","encoding":"base64","size":5, +/// "data":"SGVsbG8=","metadata":{"payload_bytes":5} +/// }]}"#; +/// +/// let envelope = smartreceive(msg_json_str, &SmartreceiveOptions::default()).await?; +/// +/// for payload in &envelope.payloads { +/// if payload.transport == "direct" { +/// let decoded = BASE64.decode(&payload.data)?; +/// println!("{}: {}", payload.dataname, String::from_utf8_lossy(&decoded)); +/// } else { +/// println!("{}: URL={}", payload.dataname, payload.data); +/// } +/// } +/// # Ok(()) +/// # } +/// ``` +pub async fn smartreceive( + msg_json_str: &str, + options: &SmartreceiveOptions, +) -> Result { + // Parse the JSON envelope + let mut env: MsgEnvelopeV1 = serde_json::from_str(msg_json_str) + .map_err(|e| NatSBridgeError::InvalidEnvelope(format!( + "Failed to parse envelope JSON: {}", e + )))?; + + let correlation_id = env.correlation_id.clone(); + log_trace(&correlation_id, "Processing received message"); + + // Determine the download handler to use (custom or default backoff) + let download_handler: Arc = options.fileserver_download_handler.clone() + .unwrap_or_else(|| Arc::new(BackoffDownloadHandler)); + + // Process each payload + let mut updated_payloads: Vec = Vec::new(); + + for payload in &env.payloads { + let transport = payload.transport.as_str(); + let dataname = payload.dataname.clone(); + let payload_type = payload.payload_type.clone(); + + match transport { + "direct" => { + log_trace(&correlation_id, &format!( + "Direct transport - decoding payload '{}'", dataname + )); + + // Decode Base64 payload + let payload_bytes = BASE64.decode(&payload.data) + .map_err(|e| NatSBridgeError::Base64Error(format!( + "Base64 decode failed for '{}': {}", dataname, e + )))?; + + // Deserialize based on type and store result back into payload + let deserialized = deserialize_data( + &payload_bytes, + &payload_type, + &correlation_id, + )?; + let updated = store_deserialized_data(payload, &deserialized); + + updated_payloads.push(updated); + } + "link" => { + let url = payload.data.clone(); + log_trace(&correlation_id, &format!( + "Link transport - fetching '{}' from URL: {}", dataname, url + )); + + // Fetch with exponential backoff + let downloaded_data = download_handler + .download( + &url, + options.max_retries, + options.base_delay, + options.max_delay, + &correlation_id, + ) + .await?; + + // Deserialize based on type and store result back into payload + let deserialized = deserialize_data( + &downloaded_data, + &payload_type, + &correlation_id, + )?; + let updated = store_deserialized_data(payload, &deserialized); + + updated_payloads.push(updated); + } + unknown => { + return Err(NatSBridgeError::UnknownTransport(format!( + "Unknown transport type '{}' for payload '{}'", + unknown, dataname + ))); + } + } + } + + env.payloads = updated_payloads; + Ok(env) +} + +// ============================================================================ +// Convenience Functions +// ============================================================================ + +/// Send a single text payload +pub async fn send_text( + subject: &str, + text: &str, + options: &SmartsendOptions, +) -> Result<(MsgEnvelopeV1, String), NatSBridgeError> { + smartsend( + subject, + &[( + "text".to_string(), + Payload::Text(text.to_string()), + "text".to_string(), + )], + options, + ) + .await +} + +/// Send a single dictionary payload +pub async fn send_dictionary( + subject: &str, + data: &JsonValue, + options: &SmartsendOptions, +) -> Result<(MsgEnvelopeV1, String), NatSBridgeError> { + smartsend( + subject, + &[( + "dictionary".to_string(), + Payload::Dictionary(data.clone()), + "dictionary".to_string(), + )], + options, + ) + .await +} + +/// Send a single binary payload +pub async fn send_binary( + subject: &str, + data: &[u8], + options: &SmartsendOptions, +) -> Result<(MsgEnvelopeV1, String), NatSBridgeError> { + smartsend( + subject, + &[( + "binary".to_string(), + Payload::Binary(data.to_vec()), + "binary".to_string(), + )], + options, + ) + .await +} + +// ============================================================================ +// Plik File Upload from Disk +// ============================================================================ + +/// Upload a file from disk to a Plik server in one-shot mode. +/// +/// Reads the file at `filepath`, extracts its filename, and uploads it +/// using the Plik one-shot upload protocol (multipart/form-data). +/// +/// # Arguments +/// - `file_server_url`: Base URL of the Plik server (e.g., `"http://localhost:8080"`) +/// - `filepath`: Full path to the local file to upload +/// +/// # Returns +/// - `Result` with uploadid, fileid, and download URL +/// +/// # Example +/// ```no_run +/// use natsbridge::plik_upload_file; +/// +/// # async fn example() -> Result<(), Box> { +/// let result = plik_upload_file("http://localhost:8080", "./large_file.zip").await?; +/// println!("Uploaded to: {}", result.url); +/// # Ok(()) +/// # } +/// ``` +pub async fn plik_upload_file( + file_server_url: &str, + filepath: &str, +) -> Result { + // Read the file from disk + let data = tokio::fs::read(filepath).await + .map_err(|e| NatSBridgeError::IoError(format!( + "Failed to read file '{}': {}", filepath, e + )))?; + + // Extract filename from path + let dataname = Path::new(filepath) + .file_name() + .map(|n| n.to_string_lossy().to_string()) + .unwrap_or_default(); + + // Upload using the Plik one-shot handler + PlikOneshotUploadHandler.upload(file_server_url, &dataname, &data).await +} + +// ============================================================================ +// Module Exports +// ============================================================================ + +// All public types are already exported via `pub` on their definitions. +// Key types: +// - `smartsend`, `smartreceive` - main API functions +// - `Payload` - type-safe payload enum +// - `MsgEnvelopeV1`, `MsgPayloadV1` - wire format structs +// - `SmartsendOptions`, `SmartreceiveOptions` - configuration +// - `FileUploadHandler`, `FileDownloadHandler` - trait abstractions +// - `PlikOneshotUploadHandler`, `BackoffDownloadHandler` - default implementations +// - `NatSBridgeError` - error type + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn test_payload_serialization() { + let text = Payload::Text("Hello".to_string()); + assert_eq!(text.payload_type(), "text"); + assert_eq!(text.size(), 5); + + let dict = Payload::Dictionary(serde_json::json!({"key": "value"})); + assert_eq!(dict.payload_type(), "dictionary"); + + let binary = Payload::Binary(vec![1, 2, 3]); + assert_eq!(binary.payload_type(), "binary"); + assert_eq!(binary.size(), 3); + } + + #[test] + fn test_serialize_deserialize_text() { + let payload = Payload::Text("Hello, World!".to_string()); + let bytes = serialize_data(&payload).unwrap(); + let deserialized = deserialize_data(&bytes, "text", "test-corr").unwrap(); + match deserialized { + Payload::Text(s) => assert_eq!(s, "Hello, World!"), + _ => panic!("Expected Text payload"), + } + } + + #[test] + fn test_serialize_deserialize_dictionary() { + let dict = serde_json::json!({"name": "Alice", "age": 30}); + let payload = Payload::Dictionary(dict.clone()); + let bytes = serialize_data(&payload).unwrap(); + let deserialized = deserialize_data(&bytes, "dictionary", "test-corr").unwrap(); + match deserialized { + Payload::Dictionary(v) => assert_eq!(v, dict), + _ => panic!("Expected Dictionary payload"), + } + } + + #[test] + fn test_serialize_deserialize_binary() { + let data = vec![0u8, 1, 2, 255, 128]; + let payload = Payload::Binary(data.clone()); + let bytes = serialize_data(&payload).unwrap(); + let deserialized = deserialize_data(&bytes, "binary", "test-corr").unwrap(); + match deserialized { + Payload::Binary(b) => assert_eq!(b, data), + _ => panic!("Expected Binary payload"), + } + } + + #[test] + fn test_envelope_json_roundtrip() { + let payload = MsgPayloadV1::new_direct( + "msg".to_string(), + "text".to_string(), + "SGVsbG8=".to_string(), // "Hello" in base64 + 5, + ); + let env = MsgEnvelopeV1::new("/test/subject".to_string(), vec![payload]); + let json = env.to_json().unwrap(); + let parsed: MsgEnvelopeV1 = serde_json::from_str(&json).unwrap(); + assert_eq!(parsed.send_to, "/test/subject"); + assert_eq!(parsed.payloads.len(), 1); + assert_eq!(parsed.payloads[0].dataname, "msg"); + } + + #[test] + fn test_base64_encoding() { + let data = b"Hello, NATSBridge!"; + let encoded = BASE64.encode(data); + let decoded = BASE64.decode(&encoded).unwrap(); + assert_eq!(decoded, data.to_vec()); + } + + #[test] + fn test_error_display() { + let err = NatSBridgeError::UnknownPayloadType("custom_type".to_string()); + assert!(format!("{}", err).contains("custom_type")); + + let err = NatSBridgeError::DownloadFailed { + url: "http://example.com/file".to_string(), + retries: 5, + }; + assert!(format!("{}", err).contains("example.com")); + } + + #[test] + fn test_default_options() { + let opts = SmartsendOptions::default(); + assert_eq!(opts.size_threshold, DEFAULT_SIZE_THRESHOLD); + assert_eq!(opts.broker_url, DEFAULT_BROKER_URL); + assert_eq!(opts.fileserver_url, DEFAULT_FILESERVER_URL); + + let opts = SmartreceiveOptions::default(); + assert_eq!(opts.max_retries, DEFAULT_MAX_RETRIES); + assert_eq!(opts.base_delay, DEFAULT_BASE_DELAY); + assert_eq!(opts.max_delay, DEFAULT_MAX_DELAY); + } +}