Skip to content

Commit

Permalink
refactor: add Canister methods with no trailing underscore (#467)
Browse files Browse the repository at this point in the history
  • Loading branch information
@ericswanson-dfinity
ericswanson-dfinity committed Sep 12, 2023
1 parent f8ceed9 commit 5637972
Show file tree
Hide file tree
Showing 7 changed files with 87 additions and 56 deletions.
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## Unreleased

* The `Unknown` lookup of a request_status path in a certificate results in an `AgentError` (the IC returns `Absent` for non-existing paths).
* For `Canister` type, added methods with no trailing underscore: update(), query(), canister_id(), clone_with()

## [0.27.0] - 2023-08-30

Expand Down
38 changes: 35 additions & 3 deletions ic-utils/src/canister.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -87,10 +87,16 @@ pub struct Canister<'agent> {

impl<'agent> Canister<'agent> {
/// Get the canister ID of this canister.
/// Prefer using [`canister_id`](Canister::canister_id) instead.
pub fn canister_id_<'canister: 'agent>(&'canister self) -> &Principal {
&self.canister_id
}

/// Get the canister ID of this canister.
pub fn canister_id<'canister: 'agent>(&'canister self) -> &Principal {
&self.canister_id
}

/// Create an AsyncCallBuilder to do an update call.
pub fn update_<'canister: 'agent>(
&'canister self,
Expand All @@ -99,14 +105,32 @@ impl<'agent> Canister<'agent> {
AsyncCallBuilder::new(self, method_name)
}

/// Create an AsyncCallBuilder to do an update call.
/// Prefer using [`update`](Canister::update) instead.
pub fn update<'canister: 'agent>(
&'canister self,
method_name: &str,
) -> AsyncCallBuilder<'agent, 'canister> {
AsyncCallBuilder::new(self, method_name)
}

/// Create a SyncCallBuilder to do a query call.
/// Prefer using [`query`](Canister::query) instead.
pub fn query_<'canister: 'agent>(
&'canister self,
method_name: &str,
) -> SyncCallBuilder<'agent, 'canister> {
SyncCallBuilder::new(self, method_name)
}

/// Create a SyncCallBuilder to do a query call.
pub fn query<'canister: 'agent>(
&'canister self,
method_name: &str,
) -> SyncCallBuilder<'agent, 'canister> {
SyncCallBuilder::new(self, method_name)
}

/// Call request_status on the RequestId in a loop and return the response as a byte vector.
pub async fn wait<'canister: 'agent>(
&'canister self,
Expand All @@ -116,12 +140,20 @@ impl<'agent> Canister<'agent> {
}

/// Creates a copy of this canister, changing the canister ID to the provided principal.
/// Prefer using [`clone_with`](Canister::clone_with) instead.
pub fn clone_with_(&self, id: Principal) -> Self {
Self {
agent: self.agent,
canister_id: id,
}
}
/// Creates a copy of this canister, changing the canister ID to the provided principal.
pub fn clone_with(&self, id: Principal) -> Self {
Self {
agent: self.agent,
canister_id: id,
}
}

/// Create a CanisterBuilder instance to build a canister abstraction.
pub fn builder() -> CanisterBuilder<'agent> {
Expand Down Expand Up @@ -216,7 +248,7 @@ impl<'agent, 'canister: 'agent> SyncCallBuilder<'agent, 'canister> {
Self {
canister,
method_name: method_name.into(),
effective_canister_id: canister.canister_id_().to_owned(),
effective_canister_id: canister.canister_id().to_owned(),
arg: Default::default(),
}
}
Expand Down Expand Up @@ -301,7 +333,7 @@ impl<'agent, 'canister: 'agent> AsyncCallBuilder<'agent, 'canister> {
Self {
canister,
method_name: method_name.to_string(),
effective_canister_id: canister.canister_id_().to_owned(),
effective_canister_id: canister.canister_id().to_owned(),
arg: Default::default(),
}
}
Expand Down Expand Up @@ -431,7 +463,7 @@ mod tests {
.unwrap();

assert!(canister
.update_("hello")
.update("hello")
.build::<()>()
.call_and_wait()
.await
Expand Down
8 changes: 4 additions & 4 deletions ic-utils/src/interfaces/http_request.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -434,7 +434,7 @@ impl<'agent> HttpRequestCanister<'agent> {
T: 'agent + Send + Sync + CandidType + for<'de> Deserialize<'de>,
C: 'agent + Send + Sync + CandidType + for<'de> Deserialize<'de>,
{
self.query_("http_request")
self.query("http_request")
.with_arg(HttpRequest {
method,
url,
Expand Down Expand Up @@ -472,7 +472,7 @@ impl<'agent> HttpRequestCanister<'agent> {
T: 'agent + Send + Sync + CandidType + for<'de> Deserialize<'de>,
C: 'agent + Send + Sync + CandidType + for<'de> Deserialize<'de>,
{
self.update_("http_request_update")
self.update("http_request_update")
.with_arg(HttpUpdateRequest {
method,
url,
Expand All @@ -488,7 +488,7 @@ impl<'agent> HttpRequestCanister<'agent> {
method: impl AsRef<str>,
token: Token,
) -> impl 'agent + SyncCall<(StreamingCallbackHttpResponse,)> {
self.query_(method.as_ref()).with_value_arg(token.0).build()
self.query(method.as_ref()).with_value_arg(token.0).build()
}

/// Retrieves the next chunk of a stream from a streaming callback, using the method from [`CallbackStrategy`].
Expand All @@ -501,7 +501,7 @@ impl<'agent> HttpRequestCanister<'agent> {
where
T: 'agent + Send + Sync + CandidType + for<'de> Deserialize<'de>,
{
self.query_(method.as_ref()).with_arg(token).build()
self.query(method.as_ref()).with_arg(token).build()
}
}

Expand Down
16 changes: 8 additions & 8 deletions ic-utils/src/interfaces/management_canister.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -140,7 +140,7 @@ impl<'agent> ManagementCanister<'agent> {
canister_id: Principal,
}

self.update_(MgmtMethod::CanisterStatus.as_ref())
self.update(MgmtMethod::CanisterStatus.as_ref())
.with_arg(In {
canister_id: *canister_id,
})
Expand All @@ -167,7 +167,7 @@ impl<'agent> ManagementCanister<'agent> {
canister_id: Principal,
}

self.update_(MgmtMethod::DepositCycles.as_ref())
self.update(MgmtMethod::DepositCycles.as_ref())
.with_arg(Argument {
canister_id: *canister_id,
})
Expand All @@ -185,7 +185,7 @@ impl<'agent> ManagementCanister<'agent> {
canister_id: Principal,
}

self.update_(MgmtMethod::DeleteCanister.as_ref())
self.update(MgmtMethod::DeleteCanister.as_ref())
.with_arg(Argument {
canister_id: *canister_id,
})
Expand All @@ -208,7 +208,7 @@ impl<'agent> ManagementCanister<'agent> {
amount: u64,
}

self.update_(MgmtMethod::ProvisionalTopUpCanister.as_ref())
self.update(MgmtMethod::ProvisionalTopUpCanister.as_ref())
.with_arg(Argument {
canister_id: *canister_id,
amount,
Expand All @@ -221,7 +221,7 @@ impl<'agent> ManagementCanister<'agent> {
/// The return value is unknown to any part of the IC at time of the submission of this call.
/// A new return value is generated for each call to this method.
pub fn raw_rand<'canister: 'agent>(&'canister self) -> impl 'agent + AsyncCall<(Vec<u8>,)> {
self.update_(MgmtMethod::RawRand.as_ref())
self.update(MgmtMethod::RawRand.as_ref())
.build()
.map(|result: (Vec<u8>,)| (result.0,))
}
Expand All @@ -236,7 +236,7 @@ impl<'agent> ManagementCanister<'agent> {
canister_id: Principal,
}

self.update_(MgmtMethod::StartCanister.as_ref())
self.update(MgmtMethod::StartCanister.as_ref())
.with_arg(Argument {
canister_id: *canister_id,
})
Expand All @@ -254,7 +254,7 @@ impl<'agent> ManagementCanister<'agent> {
canister_id: Principal,
}

self.update_(MgmtMethod::StopCanister.as_ref())
self.update(MgmtMethod::StopCanister.as_ref())
.with_arg(Argument {
canister_id: *canister_id,
})
Expand All @@ -278,7 +278,7 @@ impl<'agent> ManagementCanister<'agent> {
canister_id: Principal,
}

self.update_(MgmtMethod::UninstallCode.as_ref())
self.update(MgmtMethod::UninstallCode.as_ref())
.with_arg(Argument {
canister_id: *canister_id,
})
Expand Down
8 changes: 4 additions & 4 deletions ic-utils/src/interfaces/management_canister/builders.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -271,12 +271,12 @@ impl<'agent, 'canister: 'agent> CreateCanisterBuilder<'agent, 'canister> {
specified_id: self.specified_id,
};
self.canister
.update_(MgmtMethod::ProvisionalCreateCanisterWithCycles.as_ref())
.update(MgmtMethod::ProvisionalCreateCanisterWithCycles.as_ref())
.with_arg(in_arg)
.with_effective_canister_id(self.effective_canister_id)
} else {
self.canister
.update_(MgmtMethod::CreateCanister.as_ref())
.update(MgmtMethod::CreateCanister.as_ref())
.with_arg(CanisterSettings {
controllers,
compute_allocation,
Expand Down Expand Up @@ -423,7 +423,7 @@ impl<'agent, 'canister: 'agent> InstallCodeBuilder<'agent, 'canister> {
pub fn build(self) -> Result<impl 'agent + AsyncCall<()>, AgentError> {
Ok(self
.canister
.update_(MgmtMethod::InstallCode.as_ref())
.update(MgmtMethod::InstallCode.as_ref())
.with_arg(CanisterInstall {
mode: self.mode.unwrap_or(InstallMode::Install),
canister_id: self.canister_id,
Expand Down Expand Up @@ -627,7 +627,7 @@ impl<'agent, 'canister: 'agent> UpdateCanisterBuilder<'agent, 'canister> {

Ok(self
.canister
.update_(MgmtMethod::UpdateSettings.as_ref())
.update(MgmtMethod::UpdateSettings.as_ref())
.with_arg(In {
canister_id: self.canister_id,
settings: CanisterSettings {
Expand Down
Loading

0 comments on commit 5637972

Please sign in to comment.