From 48558135245ced53fcbc27d25f6f17c65c9aef8c Mon Sep 17 00:00:00 2001 From: Jost Schulte Date: Tue, 12 Nov 2024 19:38:20 -0600 Subject: [PATCH] chore(release): v0.19.0-dev.2 --- CHANGELOG.md | 5 +- ...bandoncountersigningsessionstaterequest.md | 15 ++ ...andoncountersigningsessionstateresponse.md | 12 ++ ...pwebsocket.abandoncountersigningsession.md | 71 +++++++++ docs/client.appwebsocket.callzome.md | 4 +- docs/client.appwebsocket.createclonecell.md | 4 +- docs/client.appwebsocket.disableclonecell.md | 4 +- docs/client.appwebsocket.enableclonecell.md | 4 +- ...websocket.getcountersigningsessionstate.md | 51 ++++++ docs/client.appwebsocket.md | 82 ++++++++++ ...pwebsocket.publishcountersigningsession.md | 71 +++++++++ docs/client.countersigningsessionstate.md | 84 ++++++++++ docs/client.countersigningsessionstatetype.md | 74 +++++++++ ...nt.getcountersigningsessionstaterequest.md | 15 ++ ...t.getcountersigningsessionstateresponse.md | 14 ++ docs/client.md | 149 ++++++++++++++++++ ...ublishcountersigningsessionstaterequest.md | 15 ++ ...blishcountersigningsessionstateresponse.md | 12 ++ docs/client.resolutionrequiredreason.md | 65 ++++++++ docs/client.sessioncompletiondecision.md | 16 ++ docs/client.sessioncompletiondecisiontype.md | 97 ++++++++++++ docs/client.sessionresolutionoutcome.agent.md | 13 ++ ...ient.sessionresolutionoutcome.decisions.md | 13 ++ docs/client.sessionresolutionoutcome.md | 78 +++++++++ ...lient.sessionresolutionsummary.attempts.md | 17 ++ ...essionresolutionsummary.last_attempt_at.md | 13 ++ docs/client.sessionresolutionsummary.md | 118 ++++++++++++++ ...lient.sessionresolutionsummary.outcomes.md | 13 ++ ...essionresolutionsummary.required_reason.md | 13 ++ docs/client.signedaction.data.md | 11 ++ docs/client.signedaction.md | 71 +++++++++ docs/client.signedaction.signature.md | 11 ++ package-lock.json | 4 +- package.json | 2 +- src/api/app/types.ts | 17 ++ test/e2e/app-websocket.ts | 2 +- 36 files changed, 1247 insertions(+), 13 deletions(-) create mode 100644 docs/client.abandoncountersigningsessionstaterequest.md create mode 100644 docs/client.abandoncountersigningsessionstateresponse.md create mode 100644 docs/client.appwebsocket.abandoncountersigningsession.md create mode 100644 docs/client.appwebsocket.getcountersigningsessionstate.md create mode 100644 docs/client.appwebsocket.publishcountersigningsession.md create mode 100644 docs/client.countersigningsessionstate.md create mode 100644 docs/client.countersigningsessionstatetype.md create mode 100644 docs/client.getcountersigningsessionstaterequest.md create mode 100644 docs/client.getcountersigningsessionstateresponse.md create mode 100644 docs/client.publishcountersigningsessionstaterequest.md create mode 100644 docs/client.publishcountersigningsessionstateresponse.md create mode 100644 docs/client.resolutionrequiredreason.md create mode 100644 docs/client.sessioncompletiondecision.md create mode 100644 docs/client.sessioncompletiondecisiontype.md create mode 100644 docs/client.sessionresolutionoutcome.agent.md create mode 100644 docs/client.sessionresolutionoutcome.decisions.md create mode 100644 docs/client.sessionresolutionoutcome.md create mode 100644 docs/client.sessionresolutionsummary.attempts.md create mode 100644 docs/client.sessionresolutionsummary.last_attempt_at.md create mode 100644 docs/client.sessionresolutionsummary.md create mode 100644 docs/client.sessionresolutionsummary.outcomes.md create mode 100644 docs/client.sessionresolutionsummary.required_reason.md create mode 100644 docs/client.signedaction.data.md create mode 100644 docs/client.signedaction.md create mode 100644 docs/client.signedaction.signature.md diff --git a/CHANGELOG.md b/CHANGELOG.md index e8701ebc..a097dbd0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,11 +5,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ## \[Unreleased\] ### Added -- AppWebsocket calls to interact with countersigning sessions, i.e. `GetCountersigningSessionState` as well as `AbandonCountersigningSession` and `PublishCountersigningSession` when a session could not be resolved automatically. Countersigning is an unstable feature which must explicitly be enabled in Holochain. ### Fixed ### Changed ### Removed +## 2024-11-12: v0.19.0-dev.2 +### Added +- AppWebsocket calls to interact with countersigning sessions, i.e. `GetCountersigningSessionState` as well as `AbandonCountersigningSession` and `PublishCountersigningSession` when a session could not be resolved automatically. Countersigning is an unstable feature which must explicitly be enabled in Holochain. + ## 2024-10-28: v0.19.0-dev.1 ### Added - Bring back a websocket reconnection automation for Admin and App websockets. When either of them is closed and a new request made, it will attempt to reconnect using the same app authentication token that was used to initially authenticate the websocket. A specific `InvalidTokenError` is returned if that fails. diff --git a/docs/client.abandoncountersigningsessionstaterequest.md b/docs/client.abandoncountersigningsessionstaterequest.md new file mode 100644 index 00000000..8857ff0b --- /dev/null +++ b/docs/client.abandoncountersigningsessionstaterequest.md @@ -0,0 +1,15 @@ + + +[Home](./index.md) > [@holochain/client](./client.md) > [AbandonCountersigningSessionStateRequest](./client.abandoncountersigningsessionstaterequest.md) + +## AbandonCountersigningSessionStateRequest type + +Cell id for which the countersigning session should be abandoned. + +**Signature:** + +```typescript +export type AbandonCountersigningSessionStateRequest = CellId; +``` +**References:** [CellId](./client.cellid.md) + diff --git a/docs/client.abandoncountersigningsessionstateresponse.md b/docs/client.abandoncountersigningsessionstateresponse.md new file mode 100644 index 00000000..e700f25d --- /dev/null +++ b/docs/client.abandoncountersigningsessionstateresponse.md @@ -0,0 +1,12 @@ + + +[Home](./index.md) > [@holochain/client](./client.md) > [AbandonCountersigningSessionStateResponse](./client.abandoncountersigningsessionstateresponse.md) + +## AbandonCountersigningSessionStateResponse type + + +**Signature:** + +```typescript +export type AbandonCountersigningSessionStateResponse = null; +``` diff --git a/docs/client.appwebsocket.abandoncountersigningsession.md b/docs/client.appwebsocket.abandoncountersigningsession.md new file mode 100644 index 00000000..473f2e02 --- /dev/null +++ b/docs/client.appwebsocket.abandoncountersigningsession.md @@ -0,0 +1,71 @@ + + +[Home](./index.md) > [@holochain/client](./client.md) > [AppWebsocket](./client.appwebsocket.md) > [abandonCountersigningSession](./client.appwebsocket.abandoncountersigningsession.md) + +## AppWebsocket.abandonCountersigningSession() method + +Abandon an unresolved countersigning session. + +If the current session has not been resolved automatically, it can be forcefully abandoned. A condition for this call to succeed is that at least one attempt has been made to resolve it automatically. + +\# Returns + +\[`AppResponse::CountersigningSessionAbandoned`\] + +The session is marked for abandoning and the countersigning workflow was triggered. The session has not been abandoned yet. + +Upon successful abandoning the system signal \[`SystemSignal::AbandonedCountersigning`\] will be emitted and the session removed from state, so that \[`AppRequest::GetCountersigningSessionState`\] would return `None`. + +In the countersigning workflow it will first be attempted to resolve the session with incoming signatures of the countersigned entries, before force-abandoning the session. In a very rare event it could happen that in just the moment where the \[`AppRequest::AbandonCountersigningSession`\] is made, signatures for this session come in. If they are valid, the session will be resolved and published as usual. Should they be invalid, however, the flag to abandon the session is erased. In such cases this request can be retried until the session has been abandoned successfully. + +\# Errors + +\[`CountersigningError::WorkspaceDoesNotExist`\] likely indicates that an invalid cell id was passed in to the call. + +\[`CountersigningError::SessionNotFound`\] when no ongoing session could be found for the provided cell id. + +\[`CountersigningError::SessionNotUnresolved`\] when an attempt to resolve the session automatically has not been made. + +**Signature:** + +```typescript +abandonCountersigningSession(args: AbandonCountersigningSessionStateRequest): Promise; +``` + +## Parameters + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +args + + + + +[AbandonCountersigningSessionStateRequest](./client.abandoncountersigningsessionstaterequest.md) + + + + + +
+**Returns:** + +Promise<null> + diff --git a/docs/client.appwebsocket.callzome.md b/docs/client.appwebsocket.callzome.md index 58c82a94..72ebf95d 100644 --- a/docs/client.appwebsocket.callzome.md +++ b/docs/client.appwebsocket.callzome.md @@ -9,7 +9,7 @@ Call a zome. **Signature:** ```typescript -callZome(request: AppCallZomeRequest, timeout?: number): Promise; +callZome(request: AppCallZomeRequest, timeout?: number): Promise; ``` ## Parameters @@ -65,7 +65,7 @@ _(Optional)_ A timeout to override the default. **Returns:** -Promise<[CallZomeResponse](./client.callzomeresponse.md)> +Promise<ReturnType> The zome call's response. diff --git a/docs/client.appwebsocket.createclonecell.md b/docs/client.appwebsocket.createclonecell.md index 3eaf8010..aaca715c 100644 --- a/docs/client.appwebsocket.createclonecell.md +++ b/docs/client.appwebsocket.createclonecell.md @@ -9,7 +9,7 @@ Clone an existing provisioned cell. **Signature:** ```typescript -createCloneCell(args: AppCreateCloneCellRequest): Promise; +createCloneCell(args: AppCreateCloneCellRequest): Promise; ``` ## Parameters @@ -49,7 +49,7 @@ Specify the cell to clone. **Returns:** -Promise<[CreateCloneCellResponse](./client.createclonecellresponse.md)> +Promise<import("../admin/types.js").[ClonedCell](./client.clonedcell.md)> The created clone cell. diff --git a/docs/client.appwebsocket.disableclonecell.md b/docs/client.appwebsocket.disableclonecell.md index 0ec7b5ba..7ac6ca46 100644 --- a/docs/client.appwebsocket.disableclonecell.md +++ b/docs/client.appwebsocket.disableclonecell.md @@ -9,7 +9,7 @@ Disable an enabled clone cell. **Signature:** ```typescript -disableCloneCell(args: AppDisableCloneCellRequest): Promise; +disableCloneCell(args: AppDisableCloneCellRequest): Promise; ``` ## Parameters @@ -49,5 +49,5 @@ Specify the clone cell to disable. **Returns:** -Promise<[DisableCloneCellResponse](./client.disableclonecellresponse.md)> +Promise<void> diff --git a/docs/client.appwebsocket.enableclonecell.md b/docs/client.appwebsocket.enableclonecell.md index 6329d0ab..1875899a 100644 --- a/docs/client.appwebsocket.enableclonecell.md +++ b/docs/client.appwebsocket.enableclonecell.md @@ -9,7 +9,7 @@ Enable a disabled clone cell. **Signature:** ```typescript -enableCloneCell(args: AppEnableCloneCellRequest): Promise; +enableCloneCell(args: AppEnableCloneCellRequest): Promise; ``` ## Parameters @@ -49,7 +49,7 @@ Specify the clone cell to enable. **Returns:** -Promise<[EnableCloneCellResponse](./client.enableclonecellresponse.md)> +Promise<import("../admin/types.js").[ClonedCell](./client.clonedcell.md)> The enabled clone cell. diff --git a/docs/client.appwebsocket.getcountersigningsessionstate.md b/docs/client.appwebsocket.getcountersigningsessionstate.md new file mode 100644 index 00000000..57d44e28 --- /dev/null +++ b/docs/client.appwebsocket.getcountersigningsessionstate.md @@ -0,0 +1,51 @@ + + +[Home](./index.md) > [@holochain/client](./client.md) > [AppWebsocket](./client.appwebsocket.md) > [getCountersigningSessionState](./client.appwebsocket.getcountersigningsessionstate.md) + +## AppWebsocket.getCountersigningSessionState() method + +Get the state of a countersigning session. + +**Signature:** + +```typescript +getCountersigningSessionState(args: GetCountersigningSessionStateRequest): Promise; +``` + +## Parameters + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +args + + + + +[GetCountersigningSessionStateRequest](./client.getcountersigningsessionstaterequest.md) + + + + + +
+**Returns:** + +Promise<[GetCountersigningSessionStateResponse](./client.getcountersigningsessionstateresponse.md)> + diff --git a/docs/client.appwebsocket.md b/docs/client.appwebsocket.md index 1b188f8f..acfb3b51 100644 --- a/docs/client.appwebsocket.md +++ b/docs/client.appwebsocket.md @@ -134,6 +134,40 @@ Description +[abandonCountersigningSession(args)](./client.appwebsocket.abandoncountersigningsession.md) + + + + + + + +Abandon an unresolved countersigning session. + +If the current session has not been resolved automatically, it can be forcefully abandoned. A condition for this call to succeed is that at least one attempt has been made to resolve it automatically. + +\# Returns + +\[`AppResponse::CountersigningSessionAbandoned`\] + +The session is marked for abandoning and the countersigning workflow was triggered. The session has not been abandoned yet. + +Upon successful abandoning the system signal \[`SystemSignal::AbandonedCountersigning`\] will be emitted and the session removed from state, so that \[`AppRequest::GetCountersigningSessionState`\] would return `None`. + +In the countersigning workflow it will first be attempted to resolve the session with incoming signatures of the countersigned entries, before force-abandoning the session. In a very rare event it could happen that in just the moment where the \[`AppRequest::AbandonCountersigningSession`\] is made, signatures for this session come in. If they are valid, the session will be resolved and published as usual. Should they be invalid, however, the flag to abandon the session is erased. In such cases this request can be retried until the session has been abandoned successfully. + +\# Errors + +\[`CountersigningError::WorkspaceDoesNotExist`\] likely indicates that an invalid cell id was passed in to the call. + +\[`CountersigningError::SessionNotFound`\] when no ongoing session could be found for the provided cell id. + +\[`CountersigningError::SessionNotUnresolved`\] when an attempt to resolve the session automatically has not been made. + + + + + [appInfo(timeout)](./client.appwebsocket.appinfo.md) @@ -245,6 +279,20 @@ Enable a disabled clone cell. Get a cell id by its role name or clone id. + + + +[getCountersigningSessionState(args)](./client.appwebsocket.getcountersigningsessionstate.md) + + + + + + + +Get the state of a countersigning session. + + @@ -287,5 +335,39 @@ Register an event listener for signals. Provide membrane proofs for the app. + + + +[publishCountersigningSession(args)](./client.appwebsocket.publishcountersigningsession.md) + + + + + + + +Publish an unresolved countersigning session. + +If the current session has not been resolved automatically, it can be forcefully published. A condition for this call to succeed is that at least one attempt has been made to resolve it automatically. + +\# Returns + +\[`AppResponse::PublishCountersigningSessionTriggered`\] + +The session is marked for publishing and the countersigning workflow was triggered. The session has not been published yet. + +Upon successful publishing the system signal \[`SystemSignal::SuccessfulCountersigning`\] will be emitted and the session removed from state, so that \[`AppRequest::GetCountersigningSessionState`\] would return `None`. + +In the countersigning workflow it will first be attempted to resolve the session with incoming signatures of the countersigned entries, before force-publishing the session. In a very rare event it could happen that in just the moment where the \[`AppRequest::PublishCountersigningSession`\] is made, signatures for this session come in. If they are valid, the session will be resolved and published as usual. Should they be invalid, however, the flag to publish the session is erased. In such cases this request can be retried until the session has been published successfully. + +\# Errors + +\[`CountersigningError::WorkspaceDoesNotExist`\] likely indicates that an invalid cell id was passed in to the call. + +\[`CountersigningError::SessionNotFound`\] when no ongoing session could be found for the provided cell id. + +\[`CountersigningError::SessionNotUnresolved`\] when an attempt to resolve the session automatically has not been made. + + diff --git a/docs/client.appwebsocket.publishcountersigningsession.md b/docs/client.appwebsocket.publishcountersigningsession.md new file mode 100644 index 00000000..c926c494 --- /dev/null +++ b/docs/client.appwebsocket.publishcountersigningsession.md @@ -0,0 +1,71 @@ + + +[Home](./index.md) > [@holochain/client](./client.md) > [AppWebsocket](./client.appwebsocket.md) > [publishCountersigningSession](./client.appwebsocket.publishcountersigningsession.md) + +## AppWebsocket.publishCountersigningSession() method + +Publish an unresolved countersigning session. + +If the current session has not been resolved automatically, it can be forcefully published. A condition for this call to succeed is that at least one attempt has been made to resolve it automatically. + +\# Returns + +\[`AppResponse::PublishCountersigningSessionTriggered`\] + +The session is marked for publishing and the countersigning workflow was triggered. The session has not been published yet. + +Upon successful publishing the system signal \[`SystemSignal::SuccessfulCountersigning`\] will be emitted and the session removed from state, so that \[`AppRequest::GetCountersigningSessionState`\] would return `None`. + +In the countersigning workflow it will first be attempted to resolve the session with incoming signatures of the countersigned entries, before force-publishing the session. In a very rare event it could happen that in just the moment where the \[`AppRequest::PublishCountersigningSession`\] is made, signatures for this session come in. If they are valid, the session will be resolved and published as usual. Should they be invalid, however, the flag to publish the session is erased. In such cases this request can be retried until the session has been published successfully. + +\# Errors + +\[`CountersigningError::WorkspaceDoesNotExist`\] likely indicates that an invalid cell id was passed in to the call. + +\[`CountersigningError::SessionNotFound`\] when no ongoing session could be found for the provided cell id. + +\[`CountersigningError::SessionNotUnresolved`\] when an attempt to resolve the session automatically has not been made. + +**Signature:** + +```typescript +publishCountersigningSession(args: PublishCountersigningSessionStateRequest): Promise; +``` + +## Parameters + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +args + + + + +[PublishCountersigningSessionStateRequest](./client.publishcountersigningsessionstaterequest.md) + + + + + +
+**Returns:** + +Promise<null> + diff --git a/docs/client.countersigningsessionstate.md b/docs/client.countersigningsessionstate.md new file mode 100644 index 00000000..c2664e85 --- /dev/null +++ b/docs/client.countersigningsessionstate.md @@ -0,0 +1,84 @@ + + +[Home](./index.md) > [@holochain/client](./client.md) > [CountersigningSessionState](./client.countersigningsessionstate.md) + +## CountersigningSessionState type + + +**Signature:** + +```typescript +export type CountersigningSessionState = +/** + * This is the entry state. Accepting a countersigning session through the HDK will immediately + * register the countersigning session in this state, for management by the countersigning workflow. + * + * The session will stay in this state even when the agent commits their countersigning entry and only + * move to the next state when the first signature bundle is received. + */ +{ + [CountersigningSessionStateType.Accepted]: PreflightRequest; +} +/** + * This is the state where we have collected one or more signatures for a countersigning session. + * + * This state can be entered from the [CountersigningSessionState::Accepted] state, which happens + * when a witness returns a signature bundle to us. While the session has not timed out, we will + * stay in this state and wait until one of the signatures bundles we have received is valid for + * the session to be completed. + * + * If we entered this state from the [CountersigningSessionState::Accepted] state, we will either + * complete the session successfully or the session will time out. On a timeout we will move + * to the [CountersigningSessionState::Unknown] for a limited number of attempts to recover the session. + * + * This state can also be entered from the [CountersigningSessionState::Unknown] state, which happens when we + * have been able to recover the session from the source chain and have requested signed actions + * from agent authorities to build a signature bundle. + * + * If we entered this state from the [CountersigningSessionState::Unknown] state, we will either + * complete the session successfully, or if the signatures are invalid, we will return to the + * [CountersigningSessionState::Unknown] state. + */ + | { + [CountersigningSessionStateType.SignaturesCollected]: { + preflight_request: PreflightRequest; + signature_bundles: SignedAction[][]; + resolution?: SessionResolutionSummary; + }; +} +/** + * The session is in an unknown state and needs to be resolved. + * + * This state is used when we have lost track of the countersigning session. This happens if + * we have got far enough to create the countersigning entry but have crashed or restarted + * before we could complete the session. In this case we need to try to discover what the other + * agent or agents involved in the session have done. + * + * This state is also entered temporarily when we have published a signature and then the + * session has timed out. To avoid deadlocking with two parties both waiting for each other to + * proceed, we cannot stay in this state indefinitely. We will make a limited number of attempts + * to recover and if we cannot, we will abandon the session. + * + * The only exception to the attempt limiting is if we are unable to reach agent activity authorities + * to progress resolving the session. In this case, the attempts are not counted towards the + * configured limit. This does not protect us against a network partition where we can only see + * a subset of the network, but it does protect us against Holochain forcing a decision while + * it is unable to reach any peers. + * + * Note that because the [PreflightRequest] is stored here, we only ever enter the unknown state + * if we managed to keep the preflight request in memory, or if we have been able to recover it + * from the source chain as part of the committed [CounterSigningSessionData]. Otherwise, we + * are unable to discover what session we were participating in, and we must abandon the session + * without going through this recovery state. + */ + | { + [CountersigningSessionStateType.Unknown]: { + preflight_request: PreflightRequest; + resolution: SessionResolutionSummary; + force_abandon: boolean; + force_publish: boolean; + }; +}; +``` +**References:** [CountersigningSessionStateType.Accepted](./client.countersigningsessionstatetype.md), [PreflightRequest](./client.preflightrequest.md), [CountersigningSessionStateType.SignaturesCollected](./client.countersigningsessionstatetype.md), [SignedAction](./client.signedaction.md), [SessionResolutionSummary](./client.sessionresolutionsummary.md), [CountersigningSessionStateType.Unknown](./client.countersigningsessionstatetype.md) + diff --git a/docs/client.countersigningsessionstatetype.md b/docs/client.countersigningsessionstatetype.md new file mode 100644 index 00000000..8918a34d --- /dev/null +++ b/docs/client.countersigningsessionstatetype.md @@ -0,0 +1,74 @@ + + +[Home](./index.md) > [@holochain/client](./client.md) > [CountersigningSessionStateType](./client.countersigningsessionstatetype.md) + +## CountersigningSessionStateType enum + + +**Signature:** + +```typescript +export declare enum CountersigningSessionStateType +``` + +## Enumeration Members + + + + + +
+ +Member + + + + +Value + + + + +Description + + +
+ +Accepted + + + + +`"Accepted"` + + + + + +
+ +SignaturesCollected + + + + +`"SignaturesCollected"` + + + + + +
+ +Unknown + + + + +`"Unknown"` + + + + + +
diff --git a/docs/client.getcountersigningsessionstaterequest.md b/docs/client.getcountersigningsessionstaterequest.md new file mode 100644 index 00000000..2927afde --- /dev/null +++ b/docs/client.getcountersigningsessionstaterequest.md @@ -0,0 +1,15 @@ + + +[Home](./index.md) > [@holochain/client](./client.md) > [GetCountersigningSessionStateRequest](./client.getcountersigningsessionstaterequest.md) + +## GetCountersigningSessionStateRequest type + +Cell id for which the countersigning session state is requested. + +**Signature:** + +```typescript +export type GetCountersigningSessionStateRequest = CellId; +``` +**References:** [CellId](./client.cellid.md) + diff --git a/docs/client.getcountersigningsessionstateresponse.md b/docs/client.getcountersigningsessionstateresponse.md new file mode 100644 index 00000000..0b66c6fc --- /dev/null +++ b/docs/client.getcountersigningsessionstateresponse.md @@ -0,0 +1,14 @@ + + +[Home](./index.md) > [@holochain/client](./client.md) > [GetCountersigningSessionStateResponse](./client.getcountersigningsessionstateresponse.md) + +## GetCountersigningSessionStateResponse type + + +**Signature:** + +```typescript +export type GetCountersigningSessionStateResponse = null | CountersigningSessionState; +``` +**References:** [CountersigningSessionState](./client.countersigningsessionstate.md) + diff --git a/docs/client.md b/docs/client.md index 0153f394..90b7e3ce 100644 --- a/docs/client.md +++ b/docs/client.md @@ -140,6 +140,16 @@ Description + + + +[CountersigningSessionStateType](./client.countersigningsessionstatetype.md) + + + + + + @@ -160,6 +170,28 @@ Description + + + +[ResolutionRequiredReason](./client.resolutionrequiredreason.md) + + + + +The reason why a countersigning session can not be resolved automatically and requires manual resolution. + + + + + +[SessionCompletionDecisionType](./client.sessioncompletiondecisiontype.md) + + + + +Decision about an incomplete countersigning session. + + @@ -979,6 +1011,40 @@ Description + + + +[SessionResolutionOutcome](./client.sessionresolutionoutcome.md) + + + + +The outcome for a single agent who participated in a countersigning session. + +\[NUM\_AUTHORITIES\_TO\_QUERY\] authorities are made to agent activity authorities for each agent, and the decisions are collected into \[SessionResolutionOutcome::decisions\]. + + + + + +[SessionResolutionSummary](./client.sessionresolutionsummary.md) + + + + +Summary of the workflow's attempts to resolve the outcome a failed countersigning session. This tracks the numbers of attempts and the outcome of the most recent attempt. + + + + + +[SignedAction](./client.signedaction.md) + + + + + + @@ -1166,6 +1232,27 @@ Description +[AbandonCountersigningSessionStateRequest](./client.abandoncountersigningsessionstaterequest.md) + + + + +Cell id for which the countersigning session should be abandoned. + + + + + +[AbandonCountersigningSessionStateResponse](./client.abandoncountersigningsessionstateresponse.md) + + + + + + + + + [Action](./client.action.md) @@ -1645,6 +1732,16 @@ This type is meant to be opaque + + + +[CountersigningSessionState](./client.countersigningsessionstate.md) + + + + + + @@ -2065,6 +2162,27 @@ This type is meant to be opaque + + + +[GetCountersigningSessionStateRequest](./client.getcountersigningsessionstaterequest.md) + + + + +Cell id for which the countersigning session state is requested. + + + + + +[GetCountersigningSessionStateResponse](./client.getcountersigningsessionstateresponse.md) + + + + + + @@ -2456,6 +2574,27 @@ An internal link type index within the DNA, from 0 to 255. + + + +[PublishCountersigningSessionStateRequest](./client.publishcountersigningsessionstaterequest.md) + + + + +Cell id for which the countersigning session should be published. + + + + + +[PublishCountersigningSessionStateResponse](./client.publishcountersigningsessionstateresponse.md) + + + + + + @@ -2619,6 +2758,16 @@ If the key could not be deleted from all cells, the call [RevokeAgentKeyRequest] + + + +[SessionCompletionDecision](./client.sessioncompletiondecision.md) + + + + + + diff --git a/docs/client.publishcountersigningsessionstaterequest.md b/docs/client.publishcountersigningsessionstaterequest.md new file mode 100644 index 00000000..8af3ad81 --- /dev/null +++ b/docs/client.publishcountersigningsessionstaterequest.md @@ -0,0 +1,15 @@ + + +[Home](./index.md) > [@holochain/client](./client.md) > [PublishCountersigningSessionStateRequest](./client.publishcountersigningsessionstaterequest.md) + +## PublishCountersigningSessionStateRequest type + +Cell id for which the countersigning session should be published. + +**Signature:** + +```typescript +export type PublishCountersigningSessionStateRequest = CellId; +``` +**References:** [CellId](./client.cellid.md) + diff --git a/docs/client.publishcountersigningsessionstateresponse.md b/docs/client.publishcountersigningsessionstateresponse.md new file mode 100644 index 00000000..66dbb264 --- /dev/null +++ b/docs/client.publishcountersigningsessionstateresponse.md @@ -0,0 +1,12 @@ + + +[Home](./index.md) > [@holochain/client](./client.md) > [PublishCountersigningSessionStateResponse](./client.publishcountersigningsessionstateresponse.md) + +## PublishCountersigningSessionStateResponse type + + +**Signature:** + +```typescript +export type PublishCountersigningSessionStateResponse = null; +``` diff --git a/docs/client.resolutionrequiredreason.md b/docs/client.resolutionrequiredreason.md new file mode 100644 index 00000000..fa6f4754 --- /dev/null +++ b/docs/client.resolutionrequiredreason.md @@ -0,0 +1,65 @@ + + +[Home](./index.md) > [@holochain/client](./client.md) > [ResolutionRequiredReason](./client.resolutionrequiredreason.md) + +## ResolutionRequiredReason enum + +The reason why a countersigning session can not be resolved automatically and requires manual resolution. + +**Signature:** + +```typescript +export declare enum ResolutionRequiredReason +``` + +## Enumeration Members + + + + +
+ +Member + + + + +Value + + + + +Description + + +
+ +Timeout + + + + +`"Timeout"` + + + + +The session has timed out, so we should try to resolve its state before abandoning. + + +
+ +Unknown + + + + +`"Unknown"` + + + + +Something happened, like a conductor restart, and we lost track of the session. + + +
diff --git a/docs/client.sessioncompletiondecision.md b/docs/client.sessioncompletiondecision.md new file mode 100644 index 00000000..98ab43b0 --- /dev/null +++ b/docs/client.sessioncompletiondecision.md @@ -0,0 +1,16 @@ + + +[Home](./index.md) > [@holochain/client](./client.md) > [SessionCompletionDecision](./client.sessioncompletiondecision.md) + +## SessionCompletionDecision type + + +**Signature:** + +```typescript +export type SessionCompletionDecision = { + [SessionCompletionDecisionType.Complete]: SignedActionHashed; +} | SessionCompletionDecisionType.Abandoned | SessionCompletionDecisionType.Indeterminate | SessionCompletionDecisionType.Failed; +``` +**References:** [SessionCompletionDecisionType.Complete](./client.sessioncompletiondecisiontype.md), [SignedActionHashed](./client.signedactionhashed.md), [SessionCompletionDecisionType.Abandoned](./client.sessioncompletiondecisiontype.md), [SessionCompletionDecisionType.Indeterminate](./client.sessioncompletiondecisiontype.md), [SessionCompletionDecisionType.Failed](./client.sessioncompletiondecisiontype.md) + diff --git a/docs/client.sessioncompletiondecisiontype.md b/docs/client.sessioncompletiondecisiontype.md new file mode 100644 index 00000000..b91f9a38 --- /dev/null +++ b/docs/client.sessioncompletiondecisiontype.md @@ -0,0 +1,97 @@ + + +[Home](./index.md) > [@holochain/client](./client.md) > [SessionCompletionDecisionType](./client.sessioncompletiondecisiontype.md) + +## SessionCompletionDecisionType enum + +Decision about an incomplete countersigning session. + +**Signature:** + +```typescript +export declare enum SessionCompletionDecisionType +``` + +## Enumeration Members + + + + + + +
+ +Member + + + + +Value + + + + +Description + + +
+ +Abandoned + + + + +`"Abandoned"` + + + + +Evidence found on the network that this session was abandoned and other agents have added to their chain without completing the session. + + +
+ +Complete + + + + +`"Complete"` + + + + +Evidence found on the network that this session completed successfully. + + +
+ +Failed + + + + +`"Failed"` + + + + +There were errors encountered while trying to resolve the session. Errors such as network errors are treated differently to inconclusive evidence. We don't want to force a decision when we're offline, for example. In this case, the resolution must be retried later and this attempt should not be counted. + + +
+ +Indeterminate + + + + +`"Indeterminate"` + + + + +No evidence, or inconclusive evidence, was found on the network. Holochain will not make an automatic decision until the evidence is conclusive. + + +
diff --git a/docs/client.sessionresolutionoutcome.agent.md b/docs/client.sessionresolutionoutcome.agent.md new file mode 100644 index 00000000..78f4edf9 --- /dev/null +++ b/docs/client.sessionresolutionoutcome.agent.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [@holochain/client](./client.md) > [SessionResolutionOutcome](./client.sessionresolutionoutcome.md) > [agent](./client.sessionresolutionoutcome.agent.md) + +## SessionResolutionOutcome.agent property + +The agent who participated in the countersigning session and is the subject of this resolution outcome. + +**Signature:** + +```typescript +agent: AgentPubKey; +``` diff --git a/docs/client.sessionresolutionoutcome.decisions.md b/docs/client.sessionresolutionoutcome.decisions.md new file mode 100644 index 00000000..c5a8cd9a --- /dev/null +++ b/docs/client.sessionresolutionoutcome.decisions.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [@holochain/client](./client.md) > [SessionResolutionOutcome](./client.sessionresolutionoutcome.md) > [decisions](./client.sessionresolutionoutcome.decisions.md) + +## SessionResolutionOutcome.decisions property + +The resolved decision for each authority for the subject agent. + +**Signature:** + +```typescript +decisions: SessionCompletionDecision[]; +``` diff --git a/docs/client.sessionresolutionoutcome.md b/docs/client.sessionresolutionoutcome.md new file mode 100644 index 00000000..e0d82393 --- /dev/null +++ b/docs/client.sessionresolutionoutcome.md @@ -0,0 +1,78 @@ + + +[Home](./index.md) > [@holochain/client](./client.md) > [SessionResolutionOutcome](./client.sessionresolutionoutcome.md) + +## SessionResolutionOutcome interface + +The outcome for a single agent who participated in a countersigning session. + +\[NUM\_AUTHORITIES\_TO\_QUERY\] authorities are made to agent activity authorities for each agent, and the decisions are collected into \[SessionResolutionOutcome::decisions\]. + +**Signature:** + +```typescript +export interface SessionResolutionOutcome +``` + +## Properties + + + + +
+ +Property + + + + +Modifiers + + + + +Type + + + + +Description + + +
+ +[agent](./client.sessionresolutionoutcome.agent.md) + + + + + + + +[AgentPubKey](./client.agentpubkey.md) + + + + +The agent who participated in the countersigning session and is the subject of this resolution outcome. + + +
+ +[decisions](./client.sessionresolutionoutcome.decisions.md) + + + + + + + +[SessionCompletionDecision](./client.sessioncompletiondecision.md)\[\] + + + + +The resolved decision for each authority for the subject agent. + + +
diff --git a/docs/client.sessionresolutionsummary.attempts.md b/docs/client.sessionresolutionsummary.attempts.md new file mode 100644 index 00000000..fb640a1e --- /dev/null +++ b/docs/client.sessionresolutionsummary.attempts.md @@ -0,0 +1,17 @@ + + +[Home](./index.md) > [@holochain/client](./client.md) > [SessionResolutionSummary](./client.sessionresolutionsummary.md) > [attempts](./client.sessionresolutionsummary.attempts.md) + +## SessionResolutionSummary.attempts property + +How many attempts have been made to resolve the session. + +Attempts are made according to the frequency specified by \[RETRY\_UNKNOWN\_SESSION\_STATE\_DELAY\]. + +This count is only correct for the current run of the Holochain conductor. If the conductor is restarted then this counter is also reset. + +**Signature:** + +```typescript +attempts: number; +``` diff --git a/docs/client.sessionresolutionsummary.last_attempt_at.md b/docs/client.sessionresolutionsummary.last_attempt_at.md new file mode 100644 index 00000000..ba3a8a38 --- /dev/null +++ b/docs/client.sessionresolutionsummary.last_attempt_at.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [@holochain/client](./client.md) > [SessionResolutionSummary](./client.sessionresolutionsummary.md) > [last\_attempt\_at](./client.sessionresolutionsummary.last_attempt_at.md) + +## SessionResolutionSummary.last\_attempt\_at property + +The time of the last attempt to resolve the session. + +**Signature:** + +```typescript +last_attempt_at?: Timestamp; +``` diff --git a/docs/client.sessionresolutionsummary.md b/docs/client.sessionresolutionsummary.md new file mode 100644 index 00000000..46f1e98d --- /dev/null +++ b/docs/client.sessionresolutionsummary.md @@ -0,0 +1,118 @@ + + +[Home](./index.md) > [@holochain/client](./client.md) > [SessionResolutionSummary](./client.sessionresolutionsummary.md) + +## SessionResolutionSummary interface + +Summary of the workflow's attempts to resolve the outcome a failed countersigning session. This tracks the numbers of attempts and the outcome of the most recent attempt. + +**Signature:** + +```typescript +export interface SessionResolutionSummary +``` + +## Properties + + + + + + +
+ +Property + + + + +Modifiers + + + + +Type + + + + +Description + + +
+ +[attempts](./client.sessionresolutionsummary.attempts.md) + + + + + + + +number + + + + +How many attempts have been made to resolve the session. + +Attempts are made according to the frequency specified by \[RETRY\_UNKNOWN\_SESSION\_STATE\_DELAY\]. + +This count is only correct for the current run of the Holochain conductor. If the conductor is restarted then this counter is also reset. + + +
+ +[last\_attempt\_at?](./client.sessionresolutionsummary.last_attempt_at.md) + + + + + + + +[Timestamp](./client.timestamp.md) + + + + +_(Optional)_ The time of the last attempt to resolve the session. + + +
+ +[outcomes](./client.sessionresolutionsummary.outcomes.md) + + + + + + + +[SessionResolutionOutcome](./client.sessionresolutionoutcome.md)\[\] + + + + +The outcome of the most recent attempt to resolve the session. + + +
+ +[required\_reason](./client.sessionresolutionsummary.required_reason.md) + + + + + + + +[ResolutionRequiredReason](./client.resolutionrequiredreason.md) + + + + +The reason why session resolution is required. + + +
diff --git a/docs/client.sessionresolutionsummary.outcomes.md b/docs/client.sessionresolutionsummary.outcomes.md new file mode 100644 index 00000000..e1f504c3 --- /dev/null +++ b/docs/client.sessionresolutionsummary.outcomes.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [@holochain/client](./client.md) > [SessionResolutionSummary](./client.sessionresolutionsummary.md) > [outcomes](./client.sessionresolutionsummary.outcomes.md) + +## SessionResolutionSummary.outcomes property + +The outcome of the most recent attempt to resolve the session. + +**Signature:** + +```typescript +outcomes: SessionResolutionOutcome[]; +``` diff --git a/docs/client.sessionresolutionsummary.required_reason.md b/docs/client.sessionresolutionsummary.required_reason.md new file mode 100644 index 00000000..23f51a1b --- /dev/null +++ b/docs/client.sessionresolutionsummary.required_reason.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [@holochain/client](./client.md) > [SessionResolutionSummary](./client.sessionresolutionsummary.md) > [required\_reason](./client.sessionresolutionsummary.required_reason.md) + +## SessionResolutionSummary.required\_reason property + +The reason why session resolution is required. + +**Signature:** + +```typescript +required_reason: ResolutionRequiredReason; +``` diff --git a/docs/client.signedaction.data.md b/docs/client.signedaction.data.md new file mode 100644 index 00000000..713154a6 --- /dev/null +++ b/docs/client.signedaction.data.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [@holochain/client](./client.md) > [SignedAction](./client.signedaction.md) > [data](./client.signedaction.data.md) + +## SignedAction.data property + +**Signature:** + +```typescript +data: Action; +``` diff --git a/docs/client.signedaction.md b/docs/client.signedaction.md new file mode 100644 index 00000000..419c367e --- /dev/null +++ b/docs/client.signedaction.md @@ -0,0 +1,71 @@ + + +[Home](./index.md) > [@holochain/client](./client.md) > [SignedAction](./client.signedaction.md) + +## SignedAction interface + + +**Signature:** + +```typescript +export interface SignedAction +``` + +## Properties + + + + +
+ +Property + + + + +Modifiers + + + + +Type + + + + +Description + + +
+ +[data](./client.signedaction.data.md) + + + + + + + +[Action](./client.action.md) + + + + + +
+ +[signature](./client.signedaction.signature.md) + + + + + + + +[Signature](./client.signature.md) + + + + + +
diff --git a/docs/client.signedaction.signature.md b/docs/client.signedaction.signature.md new file mode 100644 index 00000000..b0eaf456 --- /dev/null +++ b/docs/client.signedaction.signature.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [@holochain/client](./client.md) > [SignedAction](./client.signedaction.md) > [signature](./client.signedaction.signature.md) + +## SignedAction.signature property + +**Signature:** + +```typescript +signature: Signature; +``` diff --git a/package-lock.json b/package-lock.json index bdc4e1c6..64f06998 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@holochain/client", - "version": "0.19.0-dev.1", + "version": "0.19.0-dev.2", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@holochain/client", - "version": "0.19.0-dev.1", + "version": "0.19.0-dev.2", "license": "CAL-1.0", "dependencies": { "@bitgo/blake2b": "^3.2.4", diff --git a/package.json b/package.json index 38333c20..a928192e 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@holochain/client", - "version": "0.19.0-dev.1", + "version": "0.19.0-dev.2", "description": "A JavaScript client for the Holochain Conductor API", "author": "Holochain Foundation (https://holochain.org)", "license": "CAL-1.0", diff --git a/src/api/app/types.ts b/src/api/app/types.ts index c0446c8e..9ca96705 100644 --- a/src/api/app/types.ts +++ b/src/api/app/types.ts @@ -276,12 +276,18 @@ export type PublishCountersigningSessionStateRequest = CellId; */ export type PublishCountersigningSessionStateResponse = null; +/** + * @public + */ export enum CountersigningSessionStateType { Accepted = "Accepted", SignaturesCollected = "SignaturesCollected", Unknown = "Unknown", } +/** + * @public + */ export type CountersigningSessionState = /** * This is the entry state. Accepting a countersigning session through the HDK will immediately @@ -366,6 +372,8 @@ export type CountersigningSessionState = /** * Summary of the workflow's attempts to resolve the outcome a failed countersigning session. * This tracks the numbers of attempts and the outcome of the most recent attempt. + * + * @public */ export interface SessionResolutionSummary { /** The reason why session resolution is required. */ @@ -387,6 +395,8 @@ export interface SessionResolutionSummary { /** * The reason why a countersigning session can not be resolved automatically and requires manual resolution. + * + * @public */ export enum ResolutionRequiredReason { /** The session has timed out, so we should try to resolve its state before abandoning. */ @@ -400,6 +410,8 @@ export enum ResolutionRequiredReason { * * [NUM_AUTHORITIES_TO_QUERY] authorities are made to agent activity authorities for each agent, * and the decisions are collected into [SessionResolutionOutcome::decisions]. + * + * @public */ export interface SessionResolutionOutcome { /** @@ -413,6 +425,8 @@ export interface SessionResolutionOutcome { /** * Decision about an incomplete countersigning session. + * + * @public */ export enum SessionCompletionDecisionType { /** Evidence found on the network that this session completed successfully. */ @@ -435,6 +449,9 @@ export enum SessionCompletionDecisionType { Failed = "Failed", } +/** + * @public + */ export type SessionCompletionDecision = | { [SessionCompletionDecisionType.Complete]: SignedActionHashed } | SessionCompletionDecisionType.Abandoned diff --git a/test/e2e/app-websocket.ts b/test/e2e/app-websocket.ts index 2ba44f19..794e6faa 100644 --- a/test/e2e/app-websocket.ts +++ b/test/e2e/app-websocket.ts @@ -324,7 +324,7 @@ if (process.env.TEST_UNSTABLE === "true") { ADMIN_PORT ); - let response = await appWs.getCountersigningSessionState(cell_id); + const response = await appWs.getCountersigningSessionState(cell_id); console.log("response", response); t.equals(response, null, "countersigning session state should be null");