feat: "hidden" attribute to exclude exporting method in export_candid…

…!() (#451)

* feat: no_export attribute to exclude exporting method in did file

* changelog

* test: example & macro compile

* rename to hidden

* typo

---------

Co-authored-by: Linwei Shang <[email protected]>

examples/counter/.gitignore

@@ -1,3 +1,5 @@
 .dfx/
 canisters/
 target/
+
+src/counter_rs/counter.did

examples/counter/dfx.json

@@ -5,7 +5,10 @@
       "type": "custom",
       "candid": "src/counter_rs/counter.did",
       "wasm": "target/wasm32-unknown-unknown/release/counter_rs-opt.wasm",
-      "build": "sh ../build.sh counter counter_rs"
+      "build": [
+        "sh ../build.sh counter counter_rs",
+        "cp /tmp/a.did src/counter_rs/counter.did"
+      ]
     },
     "counter_mo": {
       "type": "motoko",

examples/counter/src/counter_rs/lib.rs

@@ -28,4 +28,10 @@ fn write(input: candid::Nat) {
     COUNTER.with(|counter| *counter.borrow_mut() = input);
 }
 
+#[update(hidden = true)]
+fn update_hidden() {}
+
+#[query(hidden = true)]
+fn query_hidden() {}
+
 ic_cdk::export_candid!();

examples/counter/tests/basic.bats

@@ -56,3 +56,9 @@ teardown() {
   run dfx canister call counter_rs read
   [ "$output" == '(6 : nat)' ]
 }
+
+@test "counter_rs generated Candid excludes hidden methods" {
+  dfx build --check counter_rs
+  ! grep -q update_hidden src/counter_rs/counter.did
+  ! grep -q query_hidden src/counter_rs/counter.did
+}

src/ic-cdk-macros/CHANGELOG.md

@@ -6,6 +6,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [unreleased]
 
+## [0.8.2] - 2023-12-13
+
+### Added
+
+- `#[query(hidden = true)]`/`#[update(hidden = true)]` attribute to exclude exporting certain endpoints in Candid generated by `export_candid!()`. (#451)
+
 ## [0.8.2] - 2023-11-23
 
 ### Changed

src/ic-cdk-macros/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ic-cdk-macros"
-version = "0.8.2" # no need to sync with ic-cdk
+version = "0.8.3" # no need to sync with ic-cdk
 authors.workspace = true
 edition.workspace = true
 license.workspace = true

src/ic-cdk-macros/src/export.rs

@@ -14,6 +14,8 @@ struct ExportAttributes {
     pub manual_reply: bool,
     #[serde(default)]
     pub composite: bool,
+    #[serde(default)]
+    pub hidden: bool,
 }
 
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
@@ -198,18 +200,23 @@ fn dfn_macro(
         quote! {}
     };
 
-    let candid_method_attr = match method {
-        MethodType::Query if attrs.composite => {
-            quote! { #[::candid::candid_method(composite_query, rename = #function_name)] }
-        }
-        MethodType::Query => quote! { #[::candid::candid_method(query, rename = #function_name)] },
-        MethodType::Update => {
-            quote! { #[::candid::candid_method(update, rename = #function_name)] }
+    let candid_method_attr = if attrs.hidden {
+        quote! {}
+    } else {
+        match method {
+            MethodType::Query if attrs.composite => {
+                quote! { #[::candid::candid_method(composite_query, rename = #function_name)] }
+            }
+            MethodType::Query => {
+                quote! { #[::candid::candid_method(query, rename = #function_name)] }
+            }
+            MethodType::Update => {
+                quote! { #[::candid::candid_method(update, rename = #function_name)] }
+            }
+            MethodType::Init => quote! { #[::candid::candid_method(init)] },
+            _ => quote! {},
         }
-        MethodType::Init => quote! { #[::candid::candid_method(init)] },
-        _ => quote! {},
     };
-
     let item = quote! {
         #candid_method_attr
         #item

src/ic-cdk-macros/src/lib.rs

@@ -110,6 +110,18 @@ pub fn export_candid(input: TokenStream) -> TokenStream {
 /// }
 /// ```
 ///
+/// If you want to hide this method in the Candid generated by [export_candid],
+/// you will need to set `hidden` to `true`. The entry point still exists in the canister.
+///
+/// ```rust
+/// # use ic_cdk::query;
+/// #[query(hidden = true)]
+/// fn query_function() {
+///     // ...
+/// # unimplemented!()
+/// }
+/// ```
+///
 /// You can specify a guard function to be executed before the query function.
 /// When the guard function returns an error, the query function will not proceed.
 ///
@@ -186,6 +198,18 @@ pub fn query(attr: TokenStream, item: TokenStream) -> TokenStream {
 /// }
 /// ```
 ///
+/// If you want to hide this method in the Candid generated by [export_candid],
+/// you will need to set `hidden` to `true`. The entry point still exists in the canister.
+///
+/// ```rust
+/// # use ic_cdk::update;
+/// #[update(hidden = true)]
+/// fn update_function() {
+///     // ...
+/// # unimplemented!()
+/// }
+/// ```
+///
 /// You can specify a guard function to be executed before the update function.
 /// When the guard function returns an error, the update function will not proceed.
 ///

src/ic-cdk/Cargo.toml

@@ -22,7 +22,7 @@ include = ["src", "Cargo.toml", "LICENSE", "README.md"]
 [dependencies]
 candid.workspace = true
 ic0.workspace = true
-ic-cdk-macros = { path = "../ic-cdk-macros", version = "0.8.2" }
+ic-cdk-macros = { path = "../ic-cdk-macros", version = "0.8.3" }
 serde.workspace = true
 serde_bytes.workspace = true
 slotmap = { workspace = true, optional = true }

src/ic-cdk/tests/pass/blank_methods.rs

@@ -12,9 +12,15 @@ fn post_upgrade() {}
 #[update]
 fn update() {}
 
+#[update(hidden = true)]
+fn update_hidden() {}
+
 #[query]
 fn query() {}
 
+#[query(hidden = true)]
+fn query_hidden() {}
+
 #[query(composite = true)]
 fn composite_query() {}