clarify units

docs/dfx-json-schema.json

@@ -82,6 +82,20 @@
         "trace"
       ]
     },
+    "Byte": {
+      "title": "Byte Count",
+      "description": "A quantity of bytes. Representable either as an integer, or as an SI unit string",
+      "examples": [
+        72,
+        "2KB",
+        "4 MiB"
+      ],
+      "type": [
+        "integer",
+        "string"
+      ],
+      "pattern": "^[0-9]+( *([KkMmGgTtPpEeZzYy]i?)?B)?$"
+    },
     "CanisterDeclarationsConfig": {
       "title": "Declarations Configuration",
       "description": "Configurations about which canister interface declarations to generate, and where to generate them.",
@@ -924,14 +938,16 @@
         },
         "memory_allocation": {
           "title": "Memory Allocation",
-          "description": "Maximum memory (in bytes) this canister is allowed to occupy.",
+          "description": "Maximum memory (in bytes) this canister is allowed to occupy. Can be specified as an integer, or as an SI unit string (e.g. \"4KB\", \"2 MiB\")",
           "default": null,
-          "type": [
-            "integer",
-            "null"
-          ],
-          "format": "uint64",
-          "minimum": 0.0
+          "anyOf": [
+            {
+              "$ref": "#/definitions/Byte"
+            },
+            {
+              "type": "null"
+            }
+          ]
         },
         "reserved_cycles_limit": {
           "title": "Reserved Cycles Limit",
@@ -946,14 +962,16 @@
         },
         "wasm_memory_limit": {
           "title": "WASM Memory Limit",
-          "description": "Specifies a soft limit (in bytes) on the Wasm memory usage of the canister.\n\nUpdate calls, timers, heartbeats, installs, and post-upgrades fail if the WASM memory usage exceeds this limit. The main purpose of this setting is to protect against the case when the canister reaches the hard 4GiB limit.\n\nMust be a number between 0 and 2^48 (i.e. 256 TiB), inclusive.",
+          "description": "Specifies a soft limit (in bytes) on the Wasm memory usage of the canister.\n\nUpdate calls, timers, heartbeats, installs, and post-upgrades fail if the WASM memory usage exceeds this limit. The main purpose of this setting is to protect against the case when the canister reaches the hard 4GiB limit.\n\nMust be a number of bytes between 0 and 2^48 (i.e. 256 TiB), inclusive. Can be specified as an integer, or as an SI unit string (e.g. \"4KB\", \"2 MiB\")",
           "default": null,
-          "type": [
-            "integer",
-            "null"
-          ],
-          "format": "uint64",
-          "minimum": 0.0
+          "anyOf": [
+            {
+              "$ref": "#/definitions/Byte"
+            },
+            {
+              "type": "null"
+            }
+          ]
         }
       }
     },

src/dfx-core/src/config/model/dfinity.rs

@@ -41,6 +41,7 @@ use crate::extension::manager::ExtensionManager;
 use crate::fs::create_dir_all;
 use crate::json::save_json_file;
 use crate::json::structure::{PossiblyStr, SerdeVec};
+use crate::util::ByteSchema;
 use byte_unit::Byte;
 use candid::Principal;
 use schemars::JsonSchema;
@@ -408,7 +409,8 @@ pub struct InitializationValues {
 
     /// # Memory Allocation
     /// Maximum memory (in bytes) this canister is allowed to occupy.
-    #[schemars(with = "Option<u64>")]
+    /// Can be specified as an integer, or as an SI unit string (e.g. "4KB", "2 MiB")
+    #[schemars(with = "Option<ByteSchema>")]
     pub memory_allocation: Option<Byte>,
 
     /// # Freezing Threshold
@@ -439,8 +441,9 @@ pub struct InitializationValues {
     /// to protect against the case when the canister reaches the hard 4GiB
     /// limit.
     ///
-    /// Must be a number between 0 and 2^48 (i.e. 256 TiB), inclusive.
-    #[schemars(with = "Option<u64>")]
+    /// Must be a number of bytes between 0 and 2^48 (i.e. 256 TiB), inclusive.
+    /// Can be specified as an integer, or as an SI unit string (e.g. "4KB", "2 MiB")
+    #[schemars(with = "Option<ByteSchema>")]
     pub wasm_memory_limit: Option<Byte>,
 }
 

src/dfx-core/src/util/mod.rs

@@ -1,4 +1,10 @@
-use std::time::Duration;
+use std::{borrow::Cow, time::Duration};
+
+use schemars::{
+    gen::SchemaGenerator,
+    schema::{InstanceType, Metadata, Schema, SchemaObject, StringValidation},
+    JsonSchema,
+};
 
 pub fn network_to_pathcompat(network_name: &str) -> String {
     network_name.replace(|c: char| !c.is_ascii_alphanumeric(), "_")
@@ -9,3 +15,31 @@ pub fn expiry_duration() -> Duration {
     // 4 minutes accounts for possible replica drift
     Duration::from_secs(60 * 4)
 }
+
+pub struct ByteSchema;
+
+impl JsonSchema for ByteSchema {
+    fn schema_name() -> String {
+        "Byte".to_string()
+    }
+    fn schema_id() -> Cow<'static, str> {
+        Cow::Borrowed("byte_unit::Byte")
+    }
+    fn json_schema(_: &mut SchemaGenerator) -> Schema {
+        Schema::Object(SchemaObject {
+            instance_type: Some(vec![InstanceType::Integer, InstanceType::String].into()),
+            number: None,
+            string: Some(Box::new(StringValidation {
+                pattern: Some("^[0-9]+( *([KkMmGgTtPpEeZzYy]i?)?B)?$".to_string()),
+                ..Default::default()
+            })),
+            metadata: Some(Box::new(Metadata {
+                title: Some("Byte Count".to_string()),
+                description: Some("A quantity of bytes. Representable either as an integer, or as an SI unit string".to_string()),
+                examples: vec![72.into(), "2KB".into(), "4 MiB".into()],
+                ..Default::default()
+            })),
+            ..Default::default()
+        })
+    }
+}

src/dfx/src/commands/canister/create.rs

@@ -56,7 +56,7 @@ pub struct CanisterCreateOpts {
     compute_allocation: Option<u64>,
 
     /// Specifies how much memory the canister is allowed to use in total.
-    /// This should be a value in the range [0..12 GiB].
+    /// This should be a value in the range [0..12 GiB]. Can include units, e.g. "4KiB".
     /// A setting of 0 means the canister will have access to memory on a “best-effort” basis:
     /// It will only be charged for the memory it uses, but at any point in time may stop running
     /// if it tries to allocate more memory when there isn’t space available on the subnet.
@@ -85,7 +85,7 @@ pub struct CanisterCreateOpts {
     /// to protect against the case when the canister reaches the hard 4GiB
     /// limit.
     ///
-    /// Must be a number between 0 B and 256 TiB, inclusive.
+    /// Must be a number between 0 B and 256 TiB, inclusive. Can include units, e.g. "4KiB".
     #[arg(long, value_parser = wasm_memory_limit_parser, hide = true)]
     wasm_memory_limit: Option<Byte>,
 

src/dfx/src/commands/canister/update_settings.rs

@@ -50,7 +50,7 @@ pub struct UpdateSettingsOpts {
     compute_allocation: Option<u64>,
 
     /// Specifies how much memory the canister is allowed to use in total.
-    /// This should be a value in the range [0..12 GiB].
+    /// This should be a value in the range [0..12 GiB]. Can include units, e.g. "4KiB".
     /// A setting of 0 means the canister will have access to memory on a “best-effort” basis:
     /// It will only be charged for the memory it uses, but at any point in time may stop running
     /// if it tries to allocate more memory when there isn’t space available on the subnet.
@@ -83,7 +83,7 @@ pub struct UpdateSettingsOpts {
     /// to protect against the case when the canister reaches the hard 4GiB
     /// limit.
     ///
-    /// Must be a number between 0 B and 256 TiB, inclusive.
+    /// Must be a number between 0 B and 256 TiB, inclusive. Can include units, e.g. "4KiB".
     #[arg(long, value_parser = wasm_memory_limit_parser)]
     wasm_memory_limit: Option<Byte>,