feat: implement RFS client with authentication and file management APIs

examples/rfsclient/README.md

@@ -0,0 +1,47 @@
+# RFS Client Rhai Examples
+
+This folder contains Rhai examples that use the SAL RFS client wrappers registered by `sal::rhai::register(&mut engine)` and executed by the `herodo` binary.
+
+## Prerequisites
+
+- Build with the client feature enabled (any of these):
+  - `--features rfsclient`
+  - `--features clients`
+  - `--features all`
+- Environment variables:
+  - `RFS_BASE_URL` (e.g., `https://rfs.example.com`)
+  - `RFS_USER` and `RFS_PASS`
+
+## Quick start
+
+Run the auth + upload + download example:
+
+```bash
+RFS_BASE_URL=https://rfs.example.com \
+RFS_USER=your_user \
+RFS_PASS=your_pass \
+cargo run -p herodo --features clients -- examples/rfsclient/auth_and_upload.rhai
+```
+
+## What the example does
+
+- Creates the RFS client: `rfs_create_client(BASE_URL, USER, PASS, TIMEOUT)`
+- Health check: `rfs_health_check()`
+- Authenticates: `rfs_authenticate()`
+- Uploads a file: `rfs_upload_file(local_path)` -> file hash
+- Downloads it back: `rfs_download_file(file_id_or_hash, dest_path)`
+
+See `examples/rfsclient/auth_and_upload.rhai` for details.
+
+## Using the Rust client directly (optional)
+
+If you want to use the Rust API (without Rhai), depend on `sal-rfs-client` and see:
+
+- `packages/clients/rfsclient/src/client.rs` (`RfsClient`)
+- `packages/clients/rfsclient/src/types.rs` (config and option types)
+
+## Troubleshooting
+
+- Missing functions in Rhai: ensure features include `rfsclient` (or `clients`/`all`).
+- Auth failures: verify `RFS_USER`/`RFS_PASS` and that the server requires/authenticates credentials.
+- Connection errors: verify `RFS_BASE_URL` is reachable from your machine.

examples/rfsclient/auth_and_upload.rhai

@@ -0,0 +1,40 @@
+// RFS Client: Auth + Upload + Download example
+// Prereqs:
+// - RFS server reachable at RFS_BASE_URL
+// - Valid credentials in env: RFS_USER, RFS_PASS
+// - Run with herodo so the SAL Rhai modules are registered
+
+let BASE_URL = env_get("RFS_BASE_URL");
+let USER = env_get("RFS_USER");
+let PASS = env_get("RFS_PASS");
+let TIMEOUT = 30; // seconds
+
+if BASE_URL == null || BASE_URL == "" { throw "Set RFS_BASE_URL in your environment"; }
+if USER == null || PASS == null { throw "Set RFS_USER and RFS_PASS in your environment"; }
+
+// Create client
+let ok = rfs_create_client(BASE_URL, USER, PASS, TIMEOUT);
+if !ok { throw "Failed to create RFS client"; }
+
+// Optional health check
+let health = rfs_health_check();
+print(`RFS health: ${health}`);
+
+// Authenticate (required for some operations)
+let auth_ok = rfs_authenticate();
+if !auth_ok { throw "Authentication failed"; }
+
+// Upload a local file
+let local_file = "/tmp/rfs_example.txt";
+os_write_file(local_file, "hello rfs");
+let hash = rfs_upload_file(local_file);
+print(`Uploaded file hash: ${hash}`);
+
+// Download it back
+let out_path = "/tmp/rfs_example_out.txt";
+let dl_ok = rfs_download_file(hash, out_path);
+if !dl_ok { throw "Download failed"; }
+
+print(`Downloaded to: ${out_path}`);
+
+true