From 0a1f3f62e3f11faab56f7f7e59a4712af254624e Mon Sep 17 00:00:00 2001 From: Quintin Willison Date: Thu, 29 Sep 2022 18:17:04 +0100 Subject: [PATCH 1/3] Add feature node for 'Error Information' under 'Debugging'. I considered 'Supportability' as a new root feature node, but then realised that 'Debugging' was already fulfilling that same categorisation. --- sdk-manifests/ably-java.yaml | 1 + sdk-manifests/ably-php.yaml | 1 + sdk-manifests/ably-ruby.yaml | 1 + sdk.yaml | 5 +++++ 4 files changed, 8 insertions(+) diff --git a/sdk-manifests/ably-java.yaml b/sdk-manifests/ably-java.yaml index 599e86e..c50daf3 100644 --- a/sdk-manifests/ably-java.yaml +++ b/sdk-manifests/ably-java.yaml @@ -16,6 +16,7 @@ compliance: URL: Query Time: Debugging: + Error Information: Logs: Protocol: JSON: diff --git a/sdk-manifests/ably-php.yaml b/sdk-manifests/ably-php.yaml index ce66b4c..418a972 100644 --- a/sdk-manifests/ably-php.yaml +++ b/sdk-manifests/ably-php.yaml @@ -12,6 +12,7 @@ compliance: URL: Query Time: Debugging: + Error Information: Logs: Protocol: JSON: diff --git a/sdk-manifests/ably-ruby.yaml b/sdk-manifests/ably-ruby.yaml index 52aa00c..4e465e6 100644 --- a/sdk-manifests/ably-ruby.yaml +++ b/sdk-manifests/ably-ruby.yaml @@ -13,6 +13,7 @@ compliance: URL: Query Time: Debugging: + Error Information: Logs: Protocol: JSON: diff --git a/sdk.yaml b/sdk.yaml index feb80f7..bf35e20 100644 --- a/sdk.yaml +++ b/sdk.yaml @@ -70,6 +70,11 @@ Debugging: .synopsis: | Behaviours that are not necessarily suitable for production environments, however may need to be enabled - even when running against production environments and executing on end-customer/consumer devices - to debug issues. + Error Information: + .specification: [TI1, TI2] + .synopsis: | + Receive details of Ably service errors in Ably's conformed `ErrorInfo` structure. + Includes `code`, `message` and `statusCode`. Logs: .specification: [TO3b, TO3c] .synopsis: | From ddb4ad6569e3cc3190478f1311b395aa7c5f630c Mon Sep 17 00:00:00 2001 From: Quintin Willison Date: Thu, 29 Sep 2022 18:18:28 +0100 Subject: [PATCH 2/3] Add optional `requires` property to canonical feature nodes. Allows them to indicate another node which must be implemented in order to support them. --- build.js | 15 +++++++++++---- sdk-node-properties.js | 5 +++++ sdk.yaml | 1 + 3 files changed, 17 insertions(+), 4 deletions(-) diff --git a/build.js b/build.js index c6d223b..eeedb71 100644 --- a/build.js +++ b/build.js @@ -148,6 +148,7 @@ function generateTableRows(writer, maximumLevel, parentKeys, node) { const { specificationPoints, documentationUrls, + requires, synopsis, } = new Properties(value); @@ -192,13 +193,19 @@ function generateTableRows(writer, maximumLevel, parentKeys, node) { rowWriter.class(`px-1 ${commonCellStyle}`); rowWriter.cell((cellContentWriter) => { let empty = true; + + const markdownRequires = requires ? `Requires: **${requires.join(': ')}**` : null; + const markdown = synopsis + ? `${synopsis}${markdownRequires ? `\n${markdownRequires}` : ''}` + : markdownRequires; + if (documentationUrls) { - const needComplexLayout = !!synopsis; + const needComplexLayout = !!markdown; if (needComplexLayout) { // With Synopsis and Documentation URLs we need a more complex layout cellContentWriter.write('
'); // this div is closed below, after writing documentation URLs - cellContentWriter.write(`
${marked.parse(synopsis)}
`); + cellContentWriter.write(`
${marked.parse(markdown)}
`); cellContentWriter.write('
'); // this div is closed below, after writing documentation URLs } @@ -211,9 +218,9 @@ function generateTableRows(writer, maximumLevel, parentKeys, node) { } empty = false; - } else if (synopsis) { + } else if (markdown) { // No Documentation URLs, so simply render the Synopsis. - cellContentWriter.write(marked.parse(synopsis)); + cellContentWriter.write(marked.parse(markdown)); empty = false; } if (empty) { diff --git a/sdk-node-properties.js b/sdk-node-properties.js index 8916d01..8bca9e1 100644 --- a/sdk-node-properties.js +++ b/sdk-node-properties.js @@ -44,6 +44,11 @@ class Properties { this.documentationUrls = transformStrings(value, (stringValue) => new URL(stringValue)); break; + case 'requires': + // used in the canonical features list + this.requires = transformStrings(value, IDENTITY_TRANSFORM); + break; + case 'specification': // used in the canonical features list this.specificationPoints = transformStrings(value, (stringValue) => new SpecificationPoint(stringValue)); diff --git a/sdk.yaml b/sdk.yaml index bf35e20..4e7e992 100644 --- a/sdk.yaml +++ b/sdk.yaml @@ -450,6 +450,7 @@ REST: Provides a function to issue HTTP REST requests to the Ably endpoints with all the built in functionality of the library such as authentication, pagination, fallback hosts, MessagePack and JSON support etc.. Convenience for customers who wish to use REST API functionality that is either not documented or is not included in the API for our client libraries. Request Identifiers: + .requires: [Debugging, Error Information] .specification: [RSC7c, TO3p] .synopsis: | Add a query string parameter, based on a source of randomness, to all REST requests. From 6a4e6105c84c5a758353b91f0668adfe9a924725 Mon Sep 17 00:00:00 2001 From: Quintin Willison Date: Thu, 29 Sep 2022 18:19:01 +0100 Subject: [PATCH 3/3] Add feature node for the `href` member of `ErrorInfo` instances. --- sdk-manifests/ably-java.yaml | 1 + sdk.yaml | 5 +++++ 2 files changed, 6 insertions(+) diff --git a/sdk-manifests/ably-java.yaml b/sdk-manifests/ably-java.yaml index c50daf3..88a8d23 100644 --- a/sdk-manifests/ably-java.yaml +++ b/sdk-manifests/ably-java.yaml @@ -82,6 +82,7 @@ compliance: Get Time: Statistics: Query: + Support Hyperlink on Request Failure: Service: Environment: Fallback Hosts: diff --git a/sdk.yaml b/sdk.yaml index 4e7e992..688e13b 100644 --- a/sdk.yaml +++ b/sdk.yaml @@ -490,6 +490,11 @@ REST: Uses the `/stats` REST endpoint. Paginated. Results are provided aggregated across all channels in use in the application in the specified period and may be used to track usage against account quotas. + Support Hyperlink on Request Failure: + .requires: [Debugging, Error Information] + .specification: TI4 + .synopsis: | + Receive `ErrorInfo` instances that include an `href` member, populated if provided by the service response, containing an Internet hyperlink for more information on the failure. Service: .synopsis: | Relating to how REST and Realtime client instances communicate with the Ably service,