feat: Implement Volumes API

tomasol · tomasol · commit 79b74ecbe639 · 2025-09-13T12:43:46.000+02:00
diff --git a/README.md b/README.md
@@ -47,6 +47,28 @@ obelisk client execution submit -f activity-flyio:fly-http/machines@1.0.0-beta.l
 \"$FLY_APP_NAME\"
 ```
 
+List volumes:
+```sh
+obelisk client execution submit -f activity-flyio:fly-http/volumes@1.0.0-beta.list -- \
+\"$FLY_APP_NAME\"
+```
+
+Create a volume:
+```sh
+VOLUME_ID=$(obelisk client execution submit -f --json activity-flyio:fly-http/volumes@1.0.0-beta.create -- \
+\"$FLY_APP_NAME\" '{
+      "name": "my_app_vol",
+      "region": "ams",
+      "size-gb": 1
+    }' | jq -r '.[-1].ok.ok.id')
+```
+
+Destroy the volume:
+```sh
+obelisk client execution submit -f activity-flyio:fly-http/volumes@1.0.0-beta.delete -- \
+\"$FLY_APP_NAME\" \"$VOLUME_ID\"
+```
+
 Launch a VM:
 ```sh
 MACHINE_ID=$(obelisk client execution submit -f --json activity-flyio:fly-http/machines@1.0.0-beta.create -- \
diff --git a/fly-http/src/lib.rs b/fly-http/src/lib.rs
@@ -1,6 +1,7 @@
 mod app;
 mod machine;
 mod secret;
+mod volume;
 
 use anyhow::Context;
 use wit_bindgen::generate;
diff --git a/fly-http/src/snapshots/fly_http__volume__tests__volume_deserialization.snap b/fly-http/src/snapshots/fly_http__volume__tests__volume_deserialization.snap
@@ -0,0 +1,21 @@
+---
+source: fly-http/src/volume.rs
+expression: volume
+---
+VolumeSer {
+    id: "vol_vjeylkgg6gll7j94",
+    name: "my_app_vol",
+    state: "created",
+    region: MachineRegion::Ams,
+    size_gb: 1,
+    encrypted: true,
+    attached_machine_id: None,
+    host_status: "ok",
+    created_at: "2025-09-13T09:27:18.803Z",
+    blocks: 0,
+    block_size: 0,
+    blocks_free: 0,
+    blocks_avail: 0,
+    bytes_used: 0,
+    bytes_total: 0,
+}
diff --git a/fly-http/src/volume.rs b/fly-http/src/volume.rs
@@ -0,0 +1,261 @@
+use crate::exports::activity_flyio::fly_http::volumes::{Volume, VolumeCreateRequest};
+use crate::machine::ser::ToLowerWrapper;
+use crate::{API_BASE_URL, Component, request_with_api_token};
+use anyhow::{Context, anyhow, bail};
+use ser::{VolumeCreateRequestSer, VolumeSer};
+use wstd::http::request::JsonRequest;
+use wstd::http::{Client, Method};
+use wstd::runtime::block_on;
+
+// These structs are internal implementation details. They are designed to serialize
+// into the exact JSON format expected by the Fly.io Volumes API.
+pub(crate) mod ser {
+    use crate::exports::activity_flyio::fly_http::{machines::MachineRegion, volumes::Volume};
+    use crate::machine::ser::ToLowerWrapper;
+    use serde::{Deserialize, Serialize};
+
+    #[derive(Serialize, Debug)]
+    pub(crate) struct VolumeCreateRequestSer {
+        pub(crate) name: String,
+        pub(crate) size_gb: u32,
+        pub(crate) region: ToLowerWrapper<MachineRegion>,
+        #[serde(rename = "require_unique_zone")]
+        pub(crate) require_unique_zone: Option<bool>,
+    }
+
+    #[derive(Deserialize, Debug)]
+    pub(crate) struct VolumeSer {
+        pub(crate) id: String,
+        pub(crate) name: String,
+        pub(crate) state: String,
+        pub(crate) region: ToLowerWrapper<MachineRegion>,
+        pub(crate) size_gb: u32,
+        pub(crate) encrypted: bool,
+        pub(crate) attached_machine_id: Option<String>,
+        pub(crate) host_status: String,
+        pub(crate) created_at: String,
+        pub(crate) blocks: u32,
+        pub(crate) block_size: u32,
+        pub(crate) blocks_free: u32,
+        pub(crate) blocks_avail: u32,
+        pub(crate) bytes_used: u32,
+        pub(crate) bytes_total: u32,
+    }
+
+    impl From<VolumeSer> for Volume {
+        fn from(value: VolumeSer) -> Volume {
+            Volume {
+                id: value.id,
+                name: value.name,
+                state: value.state,
+                region: value.region.0,
+                size_gb: value.size_gb,
+                encrypted: value.encrypted,
+                attached_machine_id: value.attached_machine_id,
+                host_status: value.host_status,
+                created_at: value.created_at,
+                blocks: value.blocks,
+                block_size: value.block_size,
+                blocks_free: value.blocks_free,
+                blocks_avail: value.blocks_avail,
+                bytes_used: value.bytes_used,
+                bytes_total: value.bytes_total,
+            }
+        }
+    }
+}
+
+async fn list(app_name: String) -> Result<Vec<Volume>, anyhow::Error> {
+    let url = format!("{API_BASE_URL}/apps/{app_name}/volumes");
+    let request = request_with_api_token()?
+        .method(Method::GET)
+        .uri(url)
+        .body(wstd::io::empty())?;
+    let response = Client::new().send(request).await?;
+
+    if response.status().is_success() {
+        let response_body = response.into_body().bytes().await?;
+        let response_ser: Vec<VolumeSer> =
+            serde_json::from_slice(&response_body).inspect_err(|_| {
+                eprintln!(
+                    "cannot deserialize: {}",
+                    String::from_utf8_lossy(&response_body)
+                )
+            })?;
+        Ok(response_ser.into_iter().map(Volume::from).collect())
+    } else {
+        let error_status = response.status();
+        let error_body = response.into_body().bytes().await?;
+        Err(anyhow!(
+            "failed with status {error_status}: {}",
+            String::from_utf8_lossy(&error_body)
+        ))
+    }
+}
+
+async fn create(app_name: String, request: VolumeCreateRequest) -> Result<Volume, anyhow::Error> {
+    let fly_request = VolumeCreateRequestSer {
+        name: request.name,
+        size_gb: request.size_gb,
+        region: ToLowerWrapper(request.region),
+        require_unique_zone: request.require_unique_zone,
+    };
+    let url = format!("{API_BASE_URL}/apps/{app_name}/volumes");
+    let http_request = request_with_api_token()?
+        .method(Method::POST)
+        .uri(url)
+        .json(&fly_request)?;
+
+    let response = Client::new().send(http_request).await?;
+
+    if response.status().is_success() {
+        let response_body = response.into_body().bytes().await?;
+        let volume_ser: VolumeSer = serde_json::from_slice(&response_body).with_context(|| {
+            format!(
+                "Deserialization of response failed: `{}`",
+                String::from_utf8_lossy(&response_body)
+            )
+        })?;
+        Ok(Volume::from(volume_ser))
+    } else {
+        let error_status = response.status();
+        let error_body = response.into_body().bytes().await?;
+        bail!("{error_status} - {}", String::from_utf8_lossy(&error_body))
+    }
+}
+
+async fn get(app_name: String, volume_id: String) -> Result<Volume, anyhow::Error> {
+    let url = format!("{API_BASE_URL}/apps/{app_name}/volumes/{volume_id}");
+    let request = request_with_api_token()?
+        .method(Method::GET)
+        .uri(url)
+        .body(wstd::io::empty())?;
+    let response = Client::new().send(request).await?;
+
+    if response.status().is_success() {
+        let response_body = response.into_body().bytes().await?;
+        let volume_ser: VolumeSer = serde_json::from_slice(&response_body).inspect_err(|_| {
+            eprintln!(
+                "cannot deserialize: {}",
+                String::from_utf8_lossy(&response_body)
+            )
+        })?;
+        Ok(Volume::from(volume_ser))
+    } else {
+        let error_status = response.status();
+        let error_body = response.into_body().bytes().await?;
+        Err(anyhow!(
+            "failed with status {error_status}: {}",
+            String::from_utf8_lossy(&error_body)
+        ))
+    }
+}
+
+async fn delete(app_name: String, volume_id: String) -> Result<(), anyhow::Error> {
+    let url = format!("{API_BASE_URL}/apps/{app_name}/volumes/{volume_id}");
+    let request = request_with_api_token()?
+        .method(Method::DELETE)
+        .uri(url)
+        .body(wstd::io::empty())?;
+
+    let response = Client::new().send(request).await?;
+
+    if response.status().is_success() {
+        Ok(())
+    } else {
+        let error_status = response.status();
+        let error_body = response.into_body().bytes().await?;
+        Err(anyhow!(
+            "failed with status {error_status}: {}",
+            String::from_utf8_lossy(&error_body)
+        ))
+    }
+}
+
+async fn extend(
+    app_name: String,
+    volume_id: String,
+    new_size_gb: u32,
+) -> Result<(), anyhow::Error> {
+    let url = format!("{API_BASE_URL}/apps/{app_name}/volumes/{volume_id}/extend");
+    let body = serde_json::json!({
+        "size_gb": new_size_gb,
+    });
+    let request = request_with_api_token()?
+        .method(Method::PUT)
+        .uri(url)
+        .json(&body)?;
+
+    let response = Client::new().send(request).await?;
+
+    if response.status().is_success() {
+        Ok(())
+    } else {
+        let error_status = response.status();
+        let error_body = response.into_body().bytes().await?;
+        Err(anyhow!(
+            "failed with status {error_status}: {}",
+            String::from_utf8_lossy(&error_body)
+        ))
+    }
+}
+
+// Implementation of the volumes interface for the component.
+impl crate::exports::activity_flyio::fly_http::volumes::Guest for Component {
+    fn list(app_name: String) -> Result<Vec<Volume>, String> {
+        block_on(list(app_name)).map_err(|err| err.to_string())
+    }
+
+    fn create(app_name: String, request: VolumeCreateRequest) -> Result<Volume, String> {
+        block_on(create(app_name, request)).map_err(|err| err.to_string())
+    }
+
+    fn get(app_name: String, volume_id: String) -> Result<Volume, String> {
+        block_on(get(app_name, volume_id)).map_err(|err| err.to_string())
+    }
+
+    fn delete(app_name: String, volume_id: String) -> Result<(), String> {
+        block_on(delete(app_name, volume_id)).map_err(|err| err.to_string())
+    }
+
+    fn extend(app_name: String, volume_id: String, new_size_gb: u32) -> Result<(), String> {
+        block_on(extend(app_name, volume_id, new_size_gb)).map_err(|err| err.to_string())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::ser::VolumeSer;
+    use insta::assert_debug_snapshot;
+
+    #[test]
+    fn volume_deserialization() {
+        let json = r#"
+        {
+            "id": "vol_vjeylkgg6gll7j94",
+            "name": "my_app_vol",
+            "state": "created",
+            "size_gb": 1,
+            "region": "ams",
+            "zone": "119a",
+            "encrypted": true,
+            "attached_machine_id": null,
+            "attached_alloc_id": null,
+            "created_at": "2025-09-13T09:27:18.803Z",
+            "blocks": 0,
+            "block_size": 0,
+            "blocks_free": 0,
+            "blocks_avail": 0,
+            "bytes_used": 0,
+            "bytes_total": 0,
+            "fstype": "ext4",
+            "snapshot_retention": 5,
+            "auto_backup_enabled": true,
+            "host_status": "ok",
+            "host_dedication_key": ""
+        }
+        "#;
+        let volume: VolumeSer = serde_json::from_str(json).unwrap();
+        assert_debug_snapshot!(volume)
+    }
+}
diff --git a/fly-http/wit/activity-flyio_fly-http@1.0.0-beta/fly.wit b/fly-http/wit/activity-flyio_fly-http@1.0.0-beta/fly.wit
@@ -215,8 +215,55 @@ interface secrets {
 
 }
 
+/// [Volumes API](https://docs.machines.dev/#tag/volumes)
+interface volumes {
+    use machines.{machine-region};
+
+    record volume {
+        id: string,
+        name: string,
+        state: string,
+        region: machine-region,
+        size-gb: u32,
+        encrypted: bool,
+        attached-machine-id: option<string>,
+        host-status: string,
+        created-at: string,
+        blocks: u32,
+        block-size: u32,
+        blocks-free: u32,
+        blocks-avail: u32,
+        bytes-used: u32,
+        bytes-total: u32,
+    }
+
+    record volume-create-request {
+        name: string,
+        size-gb: u32,
+        region: machine-region,
+        require-unique-zone: option<bool>,
+    }
+
+    /// List all the volumes in an app.
+    %list: func(app-name: string) -> result<list<volume>, string>;
+
+    /// Create a volume.
+    create: func(app-name: string, request: volume-create-request) -> result<volume, string>;
+
+    /// Get a specific volume.
+    get: func(app-name: string, volume-id: string) -> result<volume, string>;
+
+    /// Extend a volume.
+    extend: func(app-name: string, volume-id: string, new-size-gb: u32) -> result<_, string>;
+
+    /// Delete a volume permanently.
+    delete: func(app-name: string, volume-id: string) -> result<_, string>;
+
+}
+
 world exports {
     export apps;
     export machines;
     export secrets;
+    export volumes;
 }
