From fb81b238bbf8d503c8a8eb55751e5281ed3ae3f6 Mon Sep 17 00:00:00 2001 From: Kris West Date: Wed, 6 Dec 2023 17:40:52 +0000 Subject: [PATCH] Correcting IntentResult error in FDC3 2.0 and adding a very minor clarification to 2.1/next --- docs/api/spec.md | 2 +- website/versioned_docs/version-2.0/api/ref/DesktopAgent.md | 2 +- website/versioned_docs/version-2.0/api/ref/Errors.md | 4 ++-- website/versioned_docs/version-2.0/api/ref/Metadata.md | 6 +++--- website/versioned_docs/version-2.0/api/ref/Types.md | 6 +++++- website/versioned_docs/version-2.0/api/spec.md | 2 +- website/versioned_docs/version-2.1/api/spec.md | 2 +- 7 files changed, 14 insertions(+), 10 deletions(-) diff --git a/docs/api/spec.md b/docs/api/spec.md index bafbad461..4b163fa92 100644 --- a/docs/api/spec.md +++ b/docs/api/spec.md @@ -226,7 +226,7 @@ As an alternative to raising a specific intent, you may also raise an unspecifie ### Intent Results -An optional [`IntentResult`](ref/Types#intentresult) may also be returned as output by an application handling an intent. Results maybe either a single `Context` object, or a `Channel` that may be used to send a stream of responses. The [`PrivateChannel`](ref/PrivateChannel) type is provided to support synchronization of data transmitted over returned channels, by allowing both parties to listen for events denoting subscription and unsubscription from the returned channel. `PrivateChannels` are only retrievable via [raising an intent](ref/DesktopAgent#raiseintent). +An optional [`IntentResult`](ref/Types#intentresult) may also be returned as output by an application handling an intent. Results may be a single `Context` object, a `Channel` that may be used to send a stream of responses, or `void` (no result). The [`PrivateChannel`](ref/PrivateChannel) type is provided to support synchronization of data transmitted over returned channels, by allowing both parties to listen for events denoting subscription and unsubscription from the returned channel. `PrivateChannels` are only retrievable via [raising an intent](ref/DesktopAgent#raiseintent). For example, an application handling a `CreateOrder` intent might return a context representing the order and including an ID, allowing the application that raised the intent to make further calls using that ID. diff --git a/website/versioned_docs/version-2.0/api/ref/DesktopAgent.md b/website/versioned_docs/version-2.0/api/ref/DesktopAgent.md index 8a1bb56f8..f114885f1 100644 --- a/website/versioned_docs/version-2.0/api/ref/DesktopAgent.md +++ b/website/versioned_docs/version-2.0/api/ref/DesktopAgent.md @@ -642,7 +642,7 @@ If you wish to raise an intent without a context, use the `fdc3.nothing` context Returns an [`IntentResolution`](Metadata#intentresolution) object with details of the app instance that was selected (or started) to respond to the intent. -Issuing apps may optionally wait on the promise that is returned by the `getResult()` member of the IntentResolution. This promise will resolve when the _receiving app's_ intent handler function returns and resolves a promise. The Desktop Agent resolves the issuing app's promise with the Context object or Channel that is provided as resolution by the receiving app. The Desktop Agent MUST reject the issuing app's promise, with a string from the [`ResultError`](Errors#resulterror) enumeration, if: (1) the intent handling function's returned promise rejects, (2) the intent handling function doesn't return a promise, or (3) the returned promise resolves to an invalid type. +Issuing apps may optionally wait on the promise that is returned by the `getResult()` member of the `IntentResolution`. This promise will resolve when the _receiving app's_ intent handler function returns and resolves a promise. The Desktop Agent resolves the issuing app's promise with the Context object, Channel object or void that is provided as resolution within the receiving app. The Desktop Agent MUST reject the issuing app's promise, with a string from the [`ResultError`](Errors#resulterror) enumeration, if: (1) the intent handling function's returned promise rejects, (2) the intent handling function doesn't return a valid response (a promise or void), or (3) the returned promise resolves to an invalid type. #### Example diff --git a/website/versioned_docs/version-2.0/api/ref/Errors.md b/website/versioned_docs/version-2.0/api/ref/Errors.md index fecdc124a..6953021a7 100644 --- a/website/versioned_docs/version-2.0/api/ref/Errors.md +++ b/website/versioned_docs/version-2.0/api/ref/Errors.md @@ -122,8 +122,8 @@ Contains constants representing the errors that can be encountered when calling ```typescript enum ResultError { - /** Returned if the `IntentHandler` exited without returning a Promise or that - * Promise was not resolved with a Context or Channel object. + /** Returned if the intent handler exited without returning a valid result + * (a promise resolving to a Context, Channel object or void). */ NoResultReturned = 'NoResultReturned', diff --git a/website/versioned_docs/version-2.0/api/ref/Metadata.md b/website/versioned_docs/version-2.0/api/ref/Metadata.md index fee7560e8..25a9e43ef 100644 --- a/website/versioned_docs/version-2.0/api/ref/Metadata.md +++ b/website/versioned_docs/version-2.0/api/ref/Metadata.md @@ -345,9 +345,9 @@ interface IntentResolution { * receive a stream of data. * * If an error occurs (i.e. an error is thrown by the handler function, - * the promise it returns is rejected, or a promise is not returned by the - * handler function) then the Desktop Agent MUST reject the promise returned - * by the `getResult()` function of the `IntentResolution` with a string from + * the promise it returns is rejected, or the promise resolved to an invalid + * type) then the Desktop Agent MUST reject the promise returned by the + * `getResult()` function of the `IntentResolution` with a string from * the `ResultError` enumeration. */ getResult(): Promise; diff --git a/website/versioned_docs/version-2.0/api/ref/Types.md b/website/versioned_docs/version-2.0/api/ref/Types.md index 76ac1ebf3..99e2793d3 100644 --- a/website/versioned_docs/version-2.0/api/ref/Types.md +++ b/website/versioned_docs/version-2.0/api/ref/Types.md @@ -104,13 +104,17 @@ Optional metadata about the intent & context message, including the app that ori ## `IntentResult` ```typescript -type IntentResult = Context | Channel; +type IntentResult = Context | Channel | void; ``` Describes results that an Intent handler may optionally return that should be communicated back to the app that raised the intent, via the [`IntentResolution`](Metadata#intentresolution). Represented as a union type in TypeScript, however, this type may be rendered as an interface in other languages that both the `Context` and `Channel` types implement, allowing either to be returned by an `IntentHandler`. +:::warning +The original release of FDC3 2.0 contained an error in the `IntentResult` type, which omitted `void` as a valid return type. It was intended that an `IntentHandler` be able to return either `void` or a Promise that resolves to `void` and, as these are valid results, no error should be thrown by `IntentResolution.getResult()`. This was corrected in FDC3 2.1 and retrospectively corrected in FDC3 2.0. +::: + #### See also * [`Context`](#context) diff --git a/website/versioned_docs/version-2.0/api/spec.md b/website/versioned_docs/version-2.0/api/spec.md index b687bc9a2..41f89f357 100644 --- a/website/versioned_docs/version-2.0/api/spec.md +++ b/website/versioned_docs/version-2.0/api/spec.md @@ -222,7 +222,7 @@ As an alternative to raising a specific intent, you may also raise an unspecifie ### Intent Results -An optional [`IntentResult`](ref/Types#intentresult) may also be returned as output by an application handling an intent. Results maybe either a single `Context` object, or a `Channel` that may be used to send a stream of responses. The [`PrivateChannel`](ref/PrivateChannel) type is provided to support synchronization of data transmitted over returned channels, by allowing both parties to listen for events denoting subscription and unsubscription from the returned channel. `PrivateChannels` are only retrievable via [raising an intent](ref/DesktopAgent#raiseintent). +An optional [`IntentResult`](ref/Types#intentresult) may also be returned as output by an application handling an intent. Results may be a single `Context` object, a `Channel` that may be used to send a stream of responses, or `void` (no result). The [`PrivateChannel`](ref/PrivateChannel) type is provided to support synchronization of data transmitted over returned channels, by allowing both parties to listen for events denoting subscription and unsubscription from the returned channel. `PrivateChannels` are only retrievable via [raising an intent](ref/DesktopAgent#raiseintent). For example, an application handling a `CreateOrder` intent might return a context representing the order and including an ID, allowing the application that raised the intent to make further calls using that ID. diff --git a/website/versioned_docs/version-2.1/api/spec.md b/website/versioned_docs/version-2.1/api/spec.md index 0fd5f5cfa..12bf2bdce 100644 --- a/website/versioned_docs/version-2.1/api/spec.md +++ b/website/versioned_docs/version-2.1/api/spec.md @@ -226,7 +226,7 @@ As an alternative to raising a specific intent, you may also raise an unspecifie ### Intent Results -An optional [`IntentResult`](ref/Types#intentresult) may also be returned as output by an application handling an intent. Results maybe either a single `Context` object, or a `Channel` that may be used to send a stream of responses. The [`PrivateChannel`](ref/PrivateChannel) type is provided to support synchronization of data transmitted over returned channels, by allowing both parties to listen for events denoting subscription and unsubscription from the returned channel. `PrivateChannels` are only retrievable via [raising an intent](ref/DesktopAgent#raiseintent). +An optional [`IntentResult`](ref/Types#intentresult) may also be returned as output by an application handling an intent. Results may be a single `Context` object, a `Channel` that may be used to send a stream of responses, or `void` (no result). The [`PrivateChannel`](ref/PrivateChannel) type is provided to support synchronization of data transmitted over returned channels, by allowing both parties to listen for events denoting subscription and unsubscription from the returned channel. `PrivateChannels` are only retrievable via [raising an intent](ref/DesktopAgent#raiseintent). For example, an application handling a `CreateOrder` intent might return a context representing the order and including an ID, allowing the application that raised the intent to make further calls using that ID.