@react-native-gpui/fs 0.0.1-alpha.0 → 0.0.1-alpha.1

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 All notable changes to `@react-native-gpui/fs` are listed here. Each version's section becomes the notes of its GitHub release.
 
+## 0.0.1-alpha.1 - 2026-11-12
+
+- Add `upload(url, path, options)`, which streams a file, or a range of one, as an HTTP request body in small blocks, reports progress, honours an `AbortSignal` and resolves with the response status, headers and the start of its body.
+- Add `download(url, path, options)`, which streams an HTTP response to a file through `<path>.part`, reports progress, honours an `AbortSignal` and rejects on a non-2xx status.
+
 ## 0.0.1-alpha.0 - 2026-11-01
 
 - First release.

package/README.md

@@ -1,6 +1,6 @@
 # @react-native-gpui/fs
 
-A file system API for desktop apps, shaped like Node's `node:fs`, with file dialogs and the operating system's well-known folders.
+Our own module: a file system API for desktop apps, shaped like Node's `node:fs`, with file dialogs and the operating system's well-known folders.
 
 Part of [react-native-gpui](https://github.com/streetwriters/react-native-gpui), React Native for macOS, Windows and Linux.
 
@@ -30,7 +30,7 @@ The default export has the synchronous, callback and promise forms of the common
 
 ## Documentation
 
-[File system](https://streetwriters.github.io/react-native-gpui/docs/desktop-file-system)
+[File system](docs/file-system.md)
 
 ## License
 

package/desktop/Cargo.toml

@@ -20,6 +20,10 @@ tempfile = "3"
 libc = "0.2"
 # `realpath` without the `\\?\` prefix on Windows.
 dunce = "1"
+# Streams a download; rustls with the system certificate store, as the upload module does.
+ureq = { version = "3", default-features = false, features = ["rustls", "platform-verifier"] }
+# Hands a download's result back to the async method.
+futures = "0.3"
 
 [build-dependencies]
 rn-gpui-module-build = { version = "0.1" }

package/desktop/src/download.rs

@@ -0,0 +1,329 @@
+//! `download`: an HTTP body streamed to a file.
+//!
+//! A transfer is two threads. The network thread makes the request and reads the
+//! body in chunks; the coordinator receives them, writes `<path>.part` and renames
+//! it onto `path` when the body is complete. Splitting them is what makes a cancel
+//! prompt: the coordinator polls the cancel flag between messages, so it does not
+//! wait on a socket that has gone quiet, and the network thread simply stops the
+//! next time it tries to hand over a chunk.
+//!
+//! The module's own thread is only waited on through a channel, so a slow download
+//! never blocks other file calls.
+
+use std::collections::HashMap;
+use std::fs::File;
+use std::io::{Read, Write};
+use std::path::PathBuf;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::mpsc::{self, RecvTimeoutError, SyncSender};
+use std::sync::{Arc, Mutex, OnceLock};
+use std::time::{Duration, Instant};
+
+use rn_gpui_module::ModuleError;
+use ureq::config::Config;
+use ureq::tls::{RootCerts, TlsConfig};
+use ureq::Agent;
+
+use crate::{
+    errors, DownloadHeader, DownloadOptions, DownloadProgress, DownloadResult, RNFsModule,
+};
+
+const CHUNK: usize = 64 * 1024;
+const PROGRESS_INTERVAL: Duration = Duration::from_millis(100);
+const POLL: Duration = Duration::from_millis(25);
+/// How much of a failed response's body is kept for the error.
+const ERROR_BODY_LIMIT: u64 = 2048;
+
+pub type Downloads = Mutex<HashMap<u32, Arc<AtomicBool>>>;
+
+enum Message {
+    Head {
+        status: u16,
+        headers: Vec<DownloadHeader>,
+        total: Option<u64>,
+    },
+    Rejected {
+        status: u16,
+        headers: Vec<DownloadHeader>,
+        body: String,
+    },
+    Chunk(Vec<u8>),
+    End,
+    Failed(String),
+}
+
+fn agent() -> &'static Agent {
+    static AGENT: OnceLock<Agent> = OnceLock::new();
+    AGENT.get_or_init(|| {
+        let config = Config::builder()
+            .http_status_as_error(false)
+            .timeout_connect(Some(Duration::from_secs(30)))
+            .tls_config(
+                TlsConfig::builder()
+                    .root_certs(RootCerts::PlatformVerifier)
+                    .build(),
+            )
+            .build();
+        Agent::new_with_config(config)
+    })
+}
+
+fn aborted() -> ModuleError {
+    ModuleError::with_code("ABORT_ERR", "The download was aborted")
+}
+
+fn failed(message: impl Into<String>) -> ModuleError {
+    ModuleError::with_code("ERR_DOWNLOAD", message.into())
+}
+
+fn id_of(value: f64) -> u32 {
+    value as u32
+}
+
+pub fn cancel(module: &RNFsModule, id: f64) -> bool {
+    match module.downloads.lock().expect("downloads").get(&id_of(id)) {
+        Some(stop) => {
+            stop.store(true, Ordering::SeqCst);
+            true
+        }
+        None => false,
+    }
+}
+
+fn fetch(
+    url: &str,
+    method: &str,
+    headers: &[DownloadHeader],
+    sender: &SyncSender<Message>,
+    stop: &AtomicBool,
+) {
+    let result = (|| -> Result<(), String> {
+        let mut builder = ureq::http::Request::builder().method(method).uri(url);
+        for header in headers {
+            builder = builder.header(header.name.as_str(), header.value.as_str());
+        }
+        let request = builder.body(()).map_err(|e| e.to_string())?;
+        let mut response = agent().run(request).map_err(|e| e.to_string())?;
+        let status = response.status().as_u16();
+        let mut listed: Vec<DownloadHeader> = Vec::new();
+        for (name, value) in response.headers() {
+            let value = String::from_utf8_lossy(value.as_bytes()).into_owned();
+            match listed.iter_mut().find(|h| h.name == name.as_str()) {
+                Some(existing) => {
+                    existing.value.push_str(", ");
+                    existing.value.push_str(&value);
+                }
+                None => listed.push(DownloadHeader {
+                    name: name.as_str().to_string(),
+                    value,
+                }),
+            }
+        }
+        let total = response
+            .headers()
+            .get("content-length")
+            .and_then(|v| v.to_str().ok())
+            .and_then(|v| v.parse::<u64>().ok());
+        let mut reader = response.body_mut().as_reader();
+        if !(200..300).contains(&status) {
+            let mut body = Vec::new();
+            let _ = reader
+                .by_ref()
+                .take(ERROR_BODY_LIMIT)
+                .read_to_end(&mut body);
+            let _ = sender.send(Message::Rejected {
+                status,
+                headers: listed,
+                body: String::from_utf8_lossy(&body).into_owned(),
+            });
+            return Ok(());
+        }
+        if sender
+            .send(Message::Head {
+                status,
+                headers: listed,
+                total,
+            })
+            .is_err()
+        {
+            return Ok(());
+        }
+        loop {
+            if stop.load(Ordering::SeqCst) {
+                return Ok(());
+            }
+            let mut chunk = vec![0u8; CHUNK];
+            let read = reader.read(&mut chunk).map_err(|e| e.to_string())?;
+            if read == 0 {
+                let _ = sender.send(Message::End);
+                return Ok(());
+            }
+            chunk.truncate(read);
+            if sender.send(Message::Chunk(chunk)).is_err() {
+                return Ok(());
+            }
+        }
+    })();
+    if let Err(message) = result {
+        let _ = sender.send(Message::Failed(message));
+    }
+}
+
+fn transfer(
+    module_events: &crate::NativeFsEvents,
+    id: u32,
+    url: String,
+    dest: PathBuf,
+    method: String,
+    headers: Vec<DownloadHeader>,
+    stop: Arc<AtomicBool>,
+) -> Result<DownloadResult, ModuleError> {
+    let mut partial = dest.clone().into_os_string();
+    partial.push(".part");
+    let partial = PathBuf::from(partial);
+    let shown = dest.display().to_string();
+
+    let (sender, receiver) = mpsc::sync_channel::<Message>(8);
+    {
+        let stop = stop.clone();
+        std::thread::spawn(move || fetch(&url, &method, &headers, &sender, &stop));
+    }
+
+    let mut file: Option<File> = None;
+    let mut head: Option<(u16, Vec<DownloadHeader>, Option<u64>)> = None;
+    let mut received: u64 = 0;
+    let mut last_progress = Instant::now() - PROGRESS_INTERVAL;
+    let emit = |received: u64, total: Option<u64>| {
+        module_events.on_download_progress(DownloadProgress {
+            id: f64::from(id),
+            received: received as f64,
+            total: total.map_or(-1.0, |t| t as f64),
+        });
+    };
+
+    let outcome: Result<DownloadResult, ModuleError> = loop {
+        if stop.load(Ordering::SeqCst) {
+            break Err(aborted());
+        }
+        let message = match receiver.recv_timeout(POLL) {
+            Ok(message) => message,
+            Err(RecvTimeoutError::Timeout) => continue,
+            Err(RecvTimeoutError::Disconnected) => break Err(failed("the connection closed")),
+        };
+        match message {
+            Message::Rejected {
+                status,
+                headers,
+                body,
+            } => {
+                break Ok(DownloadResult {
+                    status: f64::from(status),
+                    headers,
+                    bytes: 0.0,
+                    body: Some(body),
+                });
+            }
+            Message::Head {
+                status,
+                headers,
+                total,
+            } => {
+                match File::create(&partial) {
+                    Ok(created) => file = Some(created),
+                    Err(e) => break Err(errors::from_io(e, &shown)),
+                }
+                head = Some((status, headers, total));
+                emit(0, total);
+            }
+            Message::Chunk(bytes) => {
+                let Some(target) = file.as_mut() else {
+                    break Err(failed("data arrived before the response"));
+                };
+                if let Err(e) = target.write_all(&bytes) {
+                    break Err(errors::from_io(e, &shown));
+                }
+                received += bytes.len() as u64;
+                if last_progress.elapsed() >= PROGRESS_INTERVAL {
+                    last_progress = Instant::now();
+                    emit(received, head.as_ref().and_then(|h| h.2));
+                }
+            }
+            Message::End => {
+                let Some((status, headers, total)) = head.take() else {
+                    break Err(failed("the response had no head"));
+                };
+                if let Some(expected) = total {
+                    if received != expected {
+                        break Err(failed(format!(
+                            "the connection closed after {received} of {expected} bytes"
+                        )));
+                    }
+                }
+                if let Some(mut target) = file.take() {
+                    if let Err(e) = target.flush() {
+                        break Err(errors::from_io(e, &shown));
+                    }
+                }
+                if let Err(e) = std::fs::rename(&partial, &dest) {
+                    break Err(errors::from_io(e, &shown));
+                }
+                emit(received, total);
+                break Ok(DownloadResult {
+                    status: f64::from(status),
+                    headers,
+                    bytes: received as f64,
+                    body: None,
+                });
+            }
+            Message::Failed(message) => break Err(failed(message)),
+        }
+    };
+
+    drop(receiver);
+    drop(file);
+    let kept = matches!(&outcome, Ok(result) if result.body.is_none());
+    if !kept {
+        let _ = std::fs::remove_file(&partial);
+    }
+    outcome
+}
+
+pub async fn download(
+    module: &RNFsModule,
+    url: String,
+    path: String,
+    options: DownloadOptions,
+) -> Result<DownloadResult, ModuleError> {
+    let id = id_of(options.id);
+    let stop = Arc::new(AtomicBool::new(false));
+    {
+        let mut running = module.downloads.lock().expect("downloads");
+        if running.contains_key(&id) {
+            return Err(failed(format!("download {id} is already running")));
+        }
+        running.insert(id, stop.clone());
+    }
+    let (sender, receiver) = futures::channel::oneshot::channel();
+    let events = module.events.clone();
+    let method = if options.method.is_empty() {
+        "GET".to_string()
+    } else {
+        options.method
+    };
+    let flag = stop.clone();
+    std::thread::spawn(move || {
+        let result = transfer(
+            &events,
+            id,
+            url,
+            PathBuf::from(path),
+            method,
+            options.headers,
+            flag,
+        );
+        let _ = sender.send(result);
+    });
+    let result = receiver.await;
+    module.downloads.lock().expect("downloads").remove(&id);
+    result.unwrap_or_else(|_| Err(failed("the download stopped unexpectedly")))
+}

package/desktop/src/lib.rs

@@ -23,12 +23,14 @@ rn_gpui_module::include_specs!();
 
 mod dialogs;
 mod dirs;
+mod download;
 mod errors;
 mod files;
 mod handles;
 mod links;
 mod module;
 mod paths;
+mod upload;
 mod watching;
 
 pub use module::RNFsModule;
@@ -183,6 +185,32 @@ impl NativeFsSpec for RNFsModule {
         watching::watch(self, path, recursive)
     }
 
+    async fn download(
+        &self,
+        url: String,
+        path: String,
+        options: DownloadOptions,
+    ) -> Result<DownloadResult, ModuleError> {
+        download::download(self, url, path, options).await
+    }
+
+    async fn upload(
+        &self,
+        url: String,
+        path: String,
+        options: UploadOptions,
+    ) -> Result<UploadResult, ModuleError> {
+        upload::upload(self, url, path, options).await
+    }
+
+    fn cancel_upload(&self, id: f64) -> Result<bool, ModuleError> {
+        Ok(upload::cancel(self, id))
+    }
+
+    fn cancel_download(&self, id: f64) -> Result<bool, ModuleError> {
+        Ok(download::cancel(self, id))
+    }
+
     fn unwatch(&self, id: f64) {
         watching::unwatch(self, id);
     }

package/desktop/src/module.rs

@@ -62,6 +62,9 @@ pub struct RNFsModule {
     /// Live watchers, keyed the same way.
     pub watchers: Mutex<std::collections::HashMap<u32, crate::watching::Watcher>>,
     pub next_watcher: AtomicU32,
+    /// Running downloads, keyed by the id JS chose, with the flag that stops each.
+    pub downloads: crate::download::Downloads,
+    pub uploads: crate::upload::Uploads,
 }
 
 impl RNFsModule {
@@ -72,6 +75,8 @@ impl RNFsModule {
             next_fd: AtomicU32::new(1),
             watchers: Mutex::new(std::collections::HashMap::new()),
             next_watcher: AtomicU32::new(1),
+            downloads: Default::default(),
+            uploads: Default::default(),
         }
     }
 

package/desktop/src/upload.rs

@@ -0,0 +1,237 @@
+//! `upload`: a file, or a range of one, streamed as an HTTP request body.
+//!
+//! The file is read in small blocks as the connection takes them, so the body is
+//! never held in memory. The request runs on its own thread; the cancel flag is
+//! checked on every block, which is what makes a cancel prompt while the
+//! connection is busy.
+
+use std::collections::HashMap;
+use std::fs::File;
+use std::io::{self, Read, Seek, SeekFrom};
+use std::path::PathBuf;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Mutex, OnceLock};
+use std::time::{Duration, Instant};
+
+use rn_gpui_module::ModuleError;
+use ureq::config::Config;
+use ureq::tls::{RootCerts, TlsConfig};
+use ureq::{Agent, SendBody};
+
+use crate::{
+    errors, DownloadHeader, NativeFsEvents, RNFsModule, UploadOptions, UploadProgress,
+    UploadResult,
+};
+
+const BLOCK: usize = 64 * 1024;
+const PROGRESS_INTERVAL: Duration = Duration::from_millis(100);
+const RESPONSE_BODY_LIMIT: u64 = 2048;
+
+pub type Uploads = Mutex<HashMap<u32, Arc<AtomicBool>>>;
+
+fn agent() -> &'static Agent {
+    static AGENT: OnceLock<Agent> = OnceLock::new();
+    AGENT.get_or_init(|| {
+        let config = Config::builder()
+            .http_status_as_error(false)
+            .timeout_connect(Some(Duration::from_secs(30)))
+            .tls_config(
+                TlsConfig::builder()
+                    .root_certs(RootCerts::PlatformVerifier)
+                    .build(),
+            )
+            .build();
+        Agent::new_with_config(config)
+    })
+}
+
+fn aborted() -> ModuleError {
+    ModuleError::with_code("ABORT_ERR", "The upload was aborted")
+}
+
+fn failed(message: impl Into<String>) -> ModuleError {
+    ModuleError::with_code("ERR_UPLOAD", message.into())
+}
+
+fn id_of(value: f64) -> u32 {
+    value as u32
+}
+
+pub fn cancel(module: &RNFsModule, id: f64) -> bool {
+    match module.uploads.lock().expect("uploads").get(&id_of(id)) {
+        Some(stop) => {
+            stop.store(true, Ordering::SeqCst);
+            true
+        }
+        None => false,
+    }
+}
+
+struct Body {
+    file: File,
+    remaining: u64,
+    sent: u64,
+    total: u64,
+    id: u32,
+    events: NativeFsEvents,
+    stop: Arc<AtomicBool>,
+    last_progress: Instant,
+}
+
+impl Body {
+    fn emit(&self) {
+        self.events.on_upload_progress(UploadProgress {
+            id: f64::from(self.id),
+            sent: self.sent as f64,
+            total: self.total as f64,
+        });
+    }
+}
+
+impl Read for Body {
+    fn read(&mut self, buffer: &mut [u8]) -> io::Result<usize> {
+        if self.stop.load(Ordering::SeqCst) {
+            return Err(io::Error::new(io::ErrorKind::Other, "aborted"));
+        }
+        if self.remaining == 0 {
+            return Ok(0);
+        }
+        let wanted = buffer.len().min(BLOCK).min(self.remaining as usize);
+        let read = self.file.read(&mut buffer[..wanted])?;
+        if read == 0 {
+            return Err(io::Error::new(
+                io::ErrorKind::UnexpectedEof,
+                "the file is shorter than the requested range",
+            ));
+        }
+        self.remaining -= read as u64;
+        self.sent += read as u64;
+        if self.last_progress.elapsed() >= PROGRESS_INTERVAL || self.remaining == 0 {
+            self.last_progress = Instant::now();
+            self.emit();
+        }
+        Ok(read)
+    }
+}
+
+fn run(
+    events: NativeFsEvents,
+    id: u32,
+    url: String,
+    path: PathBuf,
+    options: UploadOptions,
+    stop: Arc<AtomicBool>,
+) -> Result<UploadResult, ModuleError> {
+    let shown = path.display().to_string();
+    let mut file = File::open(&path).map_err(|e| errors::from_io(e, &shown))?;
+    let size = file
+        .metadata()
+        .map_err(|e| errors::from_io(e, &shown))?
+        .len();
+    let offset = if options.offset > 0.0 {
+        options.offset as u64
+    } else {
+        0
+    };
+    if offset > size {
+        return Err(failed("the offset is past the end of the file"));
+    }
+    let length = if options.length < 0.0 {
+        size - offset
+    } else {
+        options.length as u64
+    };
+    if offset + length > size {
+        return Err(failed("the range is past the end of the file"));
+    }
+    file.seek(SeekFrom::Start(offset))
+        .map_err(|e| errors::from_io(e, &shown))?;
+
+    let method = if options.method.is_empty() {
+        "PUT".to_string()
+    } else {
+        options.method.clone()
+    };
+    let mut builder = ureq::http::Request::builder().method(method.as_str()).uri(&url);
+    let mut has_length = false;
+    for header in &options.headers {
+        if header.name.eq_ignore_ascii_case("content-length") {
+            has_length = true;
+        }
+        builder = builder.header(header.name.as_str(), header.value.as_str());
+    }
+    if !has_length {
+        builder = builder.header("content-length", length.to_string());
+    }
+
+    let mut body = Body {
+        file,
+        remaining: length,
+        sent: 0,
+        total: length,
+        id,
+        events,
+        stop: stop.clone(),
+        last_progress: Instant::now() - PROGRESS_INTERVAL,
+    };
+    body.emit();
+    let request = builder
+        .body(SendBody::from_reader(&mut body))
+        .map_err(|e| failed(e.to_string()))?;
+    let outcome = agent().run(request);
+    if stop.load(Ordering::SeqCst) {
+        return Err(aborted());
+    }
+    let mut response = outcome.map_err(|e| failed(e.to_string()))?;
+    let status = response.status().as_u16();
+    let mut headers: Vec<DownloadHeader> = Vec::new();
+    for (name, value) in response.headers() {
+        let value = String::from_utf8_lossy(value.as_bytes()).into_owned();
+        match headers.iter_mut().find(|h| h.name == name.as_str()) {
+            Some(existing) => {
+                existing.value.push_str(", ");
+                existing.value.push_str(&value);
+            }
+            None => headers.push(DownloadHeader {
+                name: name.as_str().to_string(),
+                value,
+            }),
+        }
+    }
+    let mut text = Vec::new();
+    let _ = response
+        .body_mut()
+        .as_reader()
+        .take(RESPONSE_BODY_LIMIT)
+        .read_to_end(&mut text);
+    Ok(UploadResult {
+        status: f64::from(status),
+        headers,
+        body: String::from_utf8_lossy(&text).into_owned(),
+    })
+}
+
+pub async fn upload(
+    module: &RNFsModule,
+    url: String,
+    path: String,
+    options: UploadOptions,
+) -> Result<UploadResult, ModuleError> {
+    let id = id_of(options.id);
+    let stop = Arc::new(AtomicBool::new(false));
+    {
+        let mut running = module.uploads.lock().expect("uploads");
+        if running.contains_key(&id) {
+            return Err(failed(format!("upload {id} is already running")));
+        }
+        running.insert(id, stop.clone());
+    }
+    let (sender, receiver) = futures::channel::oneshot::channel();
+    let events = module.events.clone();
+    std::thread::spawn(move || {
+        let _ = sender.send(run(events, id, url, PathBuf::from(path), options, stop));
+    });
+    let result = receiver.await;
+    module.uploads.lock().expect("uploads").remove(&id);
+    result.unwrap_or_else(|_| Err(failed("the upload stopped unexpectedly")))
+}

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@react-native-gpui/fs",
-  "version": "0.0.1-alpha.0",
+  "version": "0.0.1-alpha.1",
   "description": "File system access for React Native GPUI apps",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/streetwriters/react-native-gpui.git",
+    "url": "git+https://github.com/streetwriters/react-native-gpui-modules.git",
     "directory": "modules/fs"
   },
-  "homepage": "https://streetwriters.github.io/react-native-gpui/",
+  "homepage": "https://github.com/streetwriters/react-native-gpui-modules/tree/main/modules/fs#readme",
   "bugs": {
-    "url": "https://github.com/streetwriters/react-native-gpui/issues"
+    "url": "https://github.com/streetwriters/react-native-gpui-modules/issues"
   },
   "main": "src/index.ts",
   "files": [
@@ -18,6 +18,7 @@
     "desktop",
     "react-native.config.js",
     "README.md",
+    "LICENSE",
     "CHANGELOG.md",
     "!**/*.test.js",
     "!**/*.test.mjs",