fix: Handle 503 Blocked response when calling rootCozyUrl

When calling `rootCozyUrl` we want the method to throw a specific
exception if the Cozy is in a "blocked" state

If a `503 Blocked` is returned we conclude that there is a Cozy behind
the URL but we cannot check if the URL points to the Cozy's root or to
a specific slug. So it is safer to throw an exception that should then
be handled by the caller

BREAKING CHANGE: rootCozyUrl() can now throw a BlockedCozyError
exception if the target Cozy is blocked

docs/api/cozy-client/README.md

@@ -10,6 +10,7 @@ cozy-client
 ## Classes
 
 *   [Association](classes/Association.md)
+*   [BlockedCozyError](classes/BlockedCozyError.md)
 *   [BulkEditError](classes/BulkEditError.md)
 *   [CozyClient](classes/CozyClient.md)
 *   [CozyLink](classes/CozyLink.md)
@@ -615,7 +616,7 @@ The root Cozy URL
 
 *Defined in*
 
-[packages/cozy-client/src/helpers/urlHelper.js:249](https://github.com/cozy/cozy-client/blob/master/packages/cozy-client/src/helpers/urlHelper.js#L249)
+[packages/cozy-client/src/helpers/urlHelper.js:269](https://github.com/cozy/cozy-client/blob/master/packages/cozy-client/src/helpers/urlHelper.js#L269)
 
 ***
 

docs/api/cozy-client/classes/BlockedCozyError.md

@@ -0,0 +1,39 @@
+[cozy-client](../README.md) / BlockedCozyError
+
+# Class: BlockedCozyError
+
+## Hierarchy
+
+*   `Error`
+
+    ↳ **`BlockedCozyError`**
+
+## Constructors
+
+### constructor
+
+• **new BlockedCozyError**(`url`)
+
+*Parameters*
+
+| Name | Type |
+| :------ | :------ |
+| `url` | `any` |
+
+*Overrides*
+
+Error.constructor
+
+*Defined in*
+
+[packages/cozy-client/src/helpers/urlHelper.js:138](https://github.com/cozy/cozy-client/blob/master/packages/cozy-client/src/helpers/urlHelper.js#L138)
+
+## Properties
+
+### url
+
+• **url**: `any`
+
+*Defined in*
+
+[packages/cozy-client/src/helpers/urlHelper.js:141](https://github.com/cozy/cozy-client/blob/master/packages/cozy-client/src/helpers/urlHelper.js#L141)

docs/api/cozy-client/classes/InvalidCozyUrlError.md

@@ -26,7 +26,7 @@ Error.constructor
 
 *Defined in*
 
-[packages/cozy-client/src/helpers/urlHelper.js:138](https://github.com/cozy/cozy-client/blob/master/packages/cozy-client/src/helpers/urlHelper.js#L138)
+[packages/cozy-client/src/helpers/urlHelper.js:146](https://github.com/cozy/cozy-client/blob/master/packages/cozy-client/src/helpers/urlHelper.js#L146)
 
 ## Properties
 
@@ -36,4 +36,4 @@ Error.constructor
 
 *Defined in*
 
-[packages/cozy-client/src/helpers/urlHelper.js:141](https://github.com/cozy/cozy-client/blob/master/packages/cozy-client/src/helpers/urlHelper.js#L141)
+[packages/cozy-client/src/helpers/urlHelper.js:149](https://github.com/cozy/cozy-client/blob/master/packages/cozy-client/src/helpers/urlHelper.js#L149)

packages/cozy-client/src/helpers/index.js

@@ -6,7 +6,8 @@ export {
   rootCozyUrl,
   InvalidRedirectLinkError,
   InvalidCozyUrlError,
-  InvalidProtocolError
+  InvalidProtocolError,
+  BlockedCozyError
 } from './urlHelper'
 
 export { dehydrate } from './dehydrateHelper'

packages/cozy-client/src/helpers/urlHelper.js

@@ -134,6 +134,14 @@ export class InvalidProtocolError extends Error {
   }
 }
 
+export class BlockedCozyError extends Error {
+  constructor(url) {
+    super(`Blocked cozy ${url.toString()}`)
+
+    this.url = url
+  }
+}
+
 export class InvalidCozyUrlError extends Error {
   constructor(url) {
     super(`URL ${url.toString()} does not seem to be a valid Cozy URL`)
@@ -187,6 +195,10 @@ const wellKnownUrl = url => uri(url) + '/.well-known/change-password'
  * - a 401 response status means the pointed page requires authentication so the
  *   origin is probably pointing to a cozy-app. In that case we should consider this
  *   URL to be invalid
+ * - a 503 response status with a "Blocked" reason means the pointed page is a Cozy
+ *   but it is blocked. In that case we consider that the url is a valid Cozy origin
+ *   but we want the method to throw as we cannot verify if the URL points to the
+ *   Cozy's root or to a specifc slug. The caller is responsible to handle that exception
  * - another status means there aren't any Cozy behind to the given origin
  *
  * @param {object} url          Object of URL elements
@@ -196,13 +208,20 @@ const wellKnownUrl = url => uri(url) + '/.well-known/change-password'
  *
  * @returns {Promise<boolean>} True if we believe there's a Cozy behind the given origin
  * @throws {InvalidCozyUrlError} Thrown when we know for sure there aren't any Cozy behind the given origin
+ * @throws {BlockedCozyError} Thrown when we know for sure there is Cozy behind the given origin but it is in a "Blocked" state
  */
 const isValidOrigin = async url => {
-  const { status } = await fetch(wellKnownUrl(url))
+  const response = await fetch(wellKnownUrl(url))
+  const { status } = response
 
   if (status === 404) {
     throw new InvalidCozyUrlError(url)
   }
+
+  if (await isResponseAboutBlockedCozy(response)) {
+    throw new BlockedCozyError(url)
+  }
+
   return status === 200
 }
 
@@ -286,3 +305,23 @@ export const rootCozyUrl = async url => {
   // without success. So bail out and let the user provide a valid one.
   throw new InvalidCozyUrlError(url)
 }
+
+/**
+ * Check if the given response is about a Cozy being blocked
+ *
+ * @param {Response} response - Fetch API response
+ * @returns {Promise<boolean>} true if the response is about a Cozy being blocked, false otherwize
+ */
+const isResponseAboutBlockedCozy = async response => {
+  if (response.status !== 503) return false
+
+  const contentType = response.headers.get('content-type')
+  const isJson = contentType && contentType.indexOf('json') >= 0
+  const data = await (isJson ? response.json() : response.text())
+
+  if (data?.some?.(reason => reason.title === 'Blocked')) {
+    return true
+  }
+
+  return false
+}

packages/cozy-client/src/helpers/urlHelper.spec.js

@@ -7,7 +7,8 @@ import {
   rootCozyUrl,
   InvalidRedirectLinkError,
   InvalidCozyUrlError,
-  InvalidProtocolError
+  InvalidProtocolError,
+  BlockedCozyError
 } from './urlHelper'
 
 describe('generateWebLink', () => {
@@ -420,4 +421,60 @@ describe('rootCozyUrl', () => {
       rootCozyUrl(new URL('https://missing.mycozy.cloud'))
     ).rejects.toBeInstanceOf(InvalidCozyUrlError)
   })
+
+  it('should reject if Blocked cozy', async () => {
+    fetch.mockResponse(() => {
+      return Promise.resolve({
+        headers: {
+          'content-type': 'application/json; charset=UTF-8'
+        },
+        body: JSON.stringify([
+          {
+            status: '503',
+            title: 'Blocked',
+            code: 'UNKNOWN',
+            detail: 'The Cozy is blocked for an unknown reason',
+            source: {}
+          }
+        ]),
+        ok: false,
+        status: 503,
+        statusText: '',
+        type: 'default',
+        url: 'https://camillenimbus.com/.well-known/change-password'
+      })
+    })
+
+    await expect(
+      rootCozyUrl(new URL('https://camillenimbus.com'))
+    ).rejects.toBeInstanceOf(BlockedCozyError)
+  })
+
+  it('should reject on 503 error (if not Blocked)', async () => {
+    fetch.mockResponse(() => {
+      return Promise.resolve({
+        headers: {
+          'content-type': 'application/json; charset=UTF-8'
+        },
+        body: JSON.stringify([
+          {
+            status: '503',
+            title: 'Some error',
+            code: 'UNKNOWN',
+            detail: 'Some error description',
+            source: {}
+          }
+        ]),
+        ok: false,
+        status: 503,
+        statusText: '',
+        type: 'default',
+        url: 'https://camillenimbus.com/.well-known/change-password'
+      })
+    })
+
+    await expect(
+      rootCozyUrl(new URL('https://camillenimbus.com'))
+    ).rejects.toBeInstanceOf(InvalidCozyUrlError)
+  })
 })

packages/cozy-client/src/index.js

@@ -32,7 +32,8 @@ export {
   rootCozyUrl,
   InvalidRedirectLinkError,
   InvalidCozyUrlError,
-  InvalidProtocolError
+  InvalidProtocolError,
+  BlockedCozyError
 } from './helpers'
 export { cancelable, isQueryLoading, hasQueryBeenLoaded } from './utils'
 export { getQueryFromState } from './store'

packages/cozy-client/src/index.node.js

@@ -25,7 +25,8 @@ export {
   ensureFirstSlash,
   rootCozyUrl,
   InvalidCozyUrlError,
-  InvalidProtocolError
+  InvalidProtocolError,
+  BlockedCozyError
 } from './helpers'
 export { cancelable } from './utils'
 export { getQueryFromState } from './store'

packages/cozy-client/types/helpers/index.d.ts

@@ -1,2 +1,2 @@
 export { dehydrate } from "./dehydrateHelper";
-export { deconstructCozyWebLinkWithSlug, deconstructRedirectLink, generateWebLink, ensureFirstSlash, rootCozyUrl, InvalidRedirectLinkError, InvalidCozyUrlError, InvalidProtocolError } from "./urlHelper";
+export { deconstructCozyWebLinkWithSlug, deconstructRedirectLink, generateWebLink, ensureFirstSlash, rootCozyUrl, InvalidRedirectLinkError, InvalidCozyUrlError, InvalidProtocolError, BlockedCozyError } from "./urlHelper";

packages/cozy-client/types/helpers/urlHelper.d.ts

@@ -17,6 +17,10 @@ export class InvalidProtocolError extends Error {
     constructor(url: any);
     url: any;
 }
+export class BlockedCozyError extends Error {
+    constructor(url: any);
+    url: any;
+}
 export class InvalidCozyUrlError extends Error {
     constructor(url: any);
     url: any;

packages/cozy-client/types/index.d.ts

@@ -19,6 +19,6 @@ export { manifest, models };
 export { QueryDefinition, Q, Mutations, MutationTypes, getDoctypeFromOperation } from "./queries/dsl";
 export { Association, HasMany, HasOne, HasOneInPlace, HasManyInPlace, HasManyTriggers } from "./associations";
 export { isReferencedBy, isReferencedById, getReferencedBy, getReferencedById } from "./associations/helpers";
-export { deconstructCozyWebLinkWithSlug, deconstructRedirectLink, dehydrate, generateWebLink, ensureFirstSlash, rootCozyUrl, InvalidRedirectLinkError, InvalidCozyUrlError, InvalidProtocolError } from "./helpers";
+export { deconstructCozyWebLinkWithSlug, deconstructRedirectLink, dehydrate, generateWebLink, ensureFirstSlash, rootCozyUrl, InvalidRedirectLinkError, InvalidCozyUrlError, InvalidProtocolError, BlockedCozyError } from "./helpers";
 export { cancelable, isQueryLoading, hasQueryBeenLoaded } from "./utils";
 export { queryConnect, queryConnectFlat, withClient } from "./hoc";

packages/cozy-client/types/index.node.d.ts

@@ -14,4 +14,4 @@ import * as models from "./models";
 export { manifest, models };
 export { QueryDefinition, Mutations, MutationTypes, getDoctypeFromOperation, Q } from "./queries/dsl";
 export { Association, HasMany, HasOne, HasOneInPlace, HasManyInPlace, HasManyTriggers } from "./associations";
-export { deconstructCozyWebLinkWithSlug, deconstructRedirectLink, dehydrate, generateWebLink, ensureFirstSlash, rootCozyUrl, InvalidCozyUrlError, InvalidProtocolError } from "./helpers";
+export { deconstructCozyWebLinkWithSlug, deconstructRedirectLink, dehydrate, generateWebLink, ensureFirstSlash, rootCozyUrl, InvalidCozyUrlError, InvalidProtocolError, BlockedCozyError } from "./helpers";