diff --git a/requirements/specifications/openrpc-extensions/app-passthrough-apis.md b/requirements/specifications/openrpc-extensions/app-passthrough-apis.md index 768eeaa6a..666612dac 100644 --- a/requirements/specifications/openrpc-extensions/app-passthrough-apis.md +++ b/requirements/specifications/openrpc-extensions/app-passthrough-apis.md @@ -64,6 +64,8 @@ If the *app provided method's* `capabilities` tag has the `x-multiple-providers` > If more than one app is possible, then the candidate apps **MUST** be pruned by reevaluating the `x-lifecycle` array with the last value removed; This is repeated until there is only one app or only one lifecycle state remaining. > > If more than one app is still possible, then the app that was most recently in the `foreground` state **MUST** be selected; In the case of a tie, the platform **MUST** choose only one app using its own discretion. +> +> If there is no provider most recently in the `foreground` state then the app that was most recently in the inactive state **MUST** be selected. If the app provided method does not have an `event` tag and no matching app provides the required capability then the calling app **MUST** receive an error that the capability is unavailable and not a result. diff --git a/requirements/specifications/openrpc-extensions/lifecycle-api-gating.md b/requirements/specifications/openrpc-extensions/lifecycle-api-gating.md new file mode 100644 index 000000000..d32554dad --- /dev/null +++ b/requirements/specifications/openrpc-extensions/lifecycle-api-gating.md @@ -0,0 +1,65 @@ +# App Pass-through APIs + +Document Status: Working Draft + +See [Firebolt Requirements Governance](../../governance.md) for more info. + +| Contributor | Organization | +|-----------------|----------------| +| Jeremy LaCivita | Comcast | +| Kevin Pearson | Comcast | + +## 1. Overview +This document describes the the `x-lifecycle` Firebolt OpenRPC extension. + +Some APIs require that they are only called when an app is in a certain Lifecycle state. + +To facilitate these APIs, Firebolt denotes an OpenRPC extension to limit the states than ap app is allowed to be in when a method request is made. + +This document is written using the [IETF Best Common Practice 14](https://www.rfc-editor.org/rfc/rfc2119.txt) and should include the following summary in the Overview section: + +The key words "**MUST**", "**MUST NOT**", "**REQUIRED**", "**SHALL**", "**SHALL NOT**", "**SHOULD**", "**SHOULD NOT**", "**RECOMMENDED**", "**NOT RECOMMENDED**", "**MAY**", and "**OPTIONAL**" in this document are to be interpreted as described in [BCP 14](https://www.rfc-editor.org/rfc/rfc2119.txt) [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. + +## 2. Table of Contents +- [1. Overview](#1-overview) +- [2. Table of Contents](#2-table-of-contents) +- [3. Lifecycle Extension on the Capabilities tag](#3-lifecycle-extension-on-the-capabilities-tag) + - [Events](#events) + +## 3. Lifecycle Extension on the Capabilities tag +Firebolt OpenRPC **MUST** support an extension named `x-lifecycle` that denotes a method should not be requested when an app is in a particular state. + +The `x-lifecycle` extension **MUST** only be used on a method's `capabilities` tag. + +The `x-lifecycle` value **MUST** be an array with one or more of the following values: + + - initializing + - foreground + - background + - inactive + +If the `x-lifecycle` value is not provided, then it **MUST** default to: + +```json +[ + "initializing" + "foreground" + "background" + "inactive" +] +``` + +If a method has an `x-lifecycle` extension on the `capabilities` tag then that method **MUST NOT** return a success/result unless the app is in one of the listed lifecycle states during the time of the method request. + +If the app is not in one of the listed lifecycle states during the time of the request then the method **MUST** return an unavailable error. + +**TODO**: define the error? + +### Events +If a method with an `event` tag has the `x-lifecycle` extension set to a valid value then event notifications **MUST NOT** be sent to the app when it is not in one of the listed states during the time of the notification. + +The default behavior is that events not sent to an app due to `x-lifecycle` configuration **MUST NOT** be stored and sent to the app at a later point. + +An overriding requirement **MUST** exist in a specific feature document in order for a specific event to deviate from the default behavior. + +Registering for event notifications is possible in any lifecycle state and **MUST NOT** be prevented by a method's `x-lifecycle` value.