feat: Allow to enforce Stack link on request chain #1575

Ldoppea · 2024-12-17T16:04:01Z

In previous commits we implemented supports for offline mode through CozyPouchLink and FlagshipLink

Since this feature, the StackLink is able to check for internet reachability by using the isOnline() method. When no internet is detected, then the request is forwarded to the next link (i.e. the CozyPouchLink)

In some scenario we may want to prevent that behavior. This is the case when we are working on a feature that cannot work without internet access, or when the query's result is expected to contain data that is injected by the cozy-stack (and so that is not available in the local Pouch database)

To make this possible we introduce the forceStack parameter that can be set in the query options

When set to true then the StackLink will not attempt to forward the request when offline, instead it will still attempt to do the request and throw

We chose to attempt the request instead of directly throwing an error in order to prevent hypothetical scenario where isOnline() method returns false even if internet is reachable

BREAKING CHANGE: CozyLink's request methods now takes an additional options argument that can be used to enforce usage of Stack link. Although .request() is meant to be an internal API, if your code calls it, you'll want to introduce a new argument for options. This is also the case if you instanciate a new CozyLink with a handler argument for request

Before:

// Initialization
new CozyLink((operation, result = '', forward) => {
  return forward(operation, result + 'foo')
})

// Call
link.request(operation)

// Call with result and forward
link.request(operation, null, () => { /* do stuff */ })

After:

// Initialization
new CozyLink((operation, options, result = '', forward) => {
  return forward(operation, options, result + 'foo')
})

// Call
link.request(operation, options)

// Call with result and forward
link.request(operation, options, null, () => { /* do stuff */ })

Related PR: cozy/cozy-flagship-app#1269

paultranvan · 2024-12-19T11:34:32Z

packages/cozy-client/src/StackLink.js

-    if (this.isOnline && !(await this.isOnline())) {
-      return forward(operation)
+  async request(operation, options, result, forward) {
+    if (this.isOnline && !(await this.isOnline()) && !options?.forceStack) {


It might be worth it to reverse the conditions here, by evaluation forceStack first: if the options?.forceStack is true, there is no need to call the this.isOnline(), and thus we save a network call

paultranvan · 2024-12-19T11:35:47Z

packages/cozy-client/src/StackLink.js

-  async request(operation, result, forward) {
-    if (this.isOnline && !(await this.isOnline())) {
-      return forward(operation)
+  async request(operation, options, result, forward) {


No jsdoc for the options ?

paultranvan · 2024-12-19T11:37:04Z

packages/cozy-pouch-link/src/CozyPouchLink.js

@@ -410,7 +410,7 @@ class PouchLink extends CozyLink {
    return !!this.getPouch(impactedDoctype)
  }

-  async request(operation, result = null, forward = doNothing) {
+  async request(operation, options, result = null, forward = doNothing) {


If the forceStack: true option is given here, we should forward the request

When doing a backup, we don't want instable network to make the CozyClient use local PouchLink for some queries that need to read files paths In cozy/cozy-client#1575 we implemented the `forceStack` option that allows to enforce the usage of StackLink instead of other links that may retrieve local incomplete data This commit enforce the stack on backup related queries Related PR: cozy/cozy-client#1575

In previous commits we implemented supports for offline mode through CozyPouchLink and FlagshipLink Since this feature, the StackLink is able to check for internet reachability by using the `isOnline()` method. When no internet is detected, then the request is forwarded to the next link (i.e. the CozyPouchLink) In some scenario we may want to prevent that behavior. This is the case when we are working on a feature that cannot work without internet access, or when the query's result is expected to contain data that is injected by the cozy-stack (and so that is not available in the local Pouch database) To make this possible we introduce the `forceStack` parameter that can be set in the query options When set to `true` then the StackLink will not attempt to forward the request when offline, instead it will still attempt to do the request and throw We chose to attempt the request instead of directly throwing an error in order to prevent hypothetical scenario where `isOnline()` method returns false even if internet is reachable BREAKING CHANGE: CozyLink's request methods now takes an additional `options` argument that can be used to enforce usage of Stack link. Although `.request()` is meant to be an internal API, if your code calls it, you'll want to introduce a new argument for `options`. This is also the case if you instanciate a new CozyLink with a handler argument for `request` Before: ``` // Initialization new CozyLink((operation, result = '', forward) => { return forward(operation, result + 'foo') }) // Call link.request(operation) // Call with result and forward link.request(operation, null, () => { /* do stuff */ }) ``` After: ``` // Initialization new CozyLink((operation, options, result = '', forward) => { return forward(operation, options, result + 'foo') }) // Call link.request(operation, options) // Call with result and forward link.request(operation, options, null, () => { /* do stuff */ }) ```