hoodie connection status API

[gr2m]

Due to its offline-first nature, the Hoodie client should provide APIs to tell if connected to its back-end or not.

Current APIs

hoodie.checkConnection()
hoodie.isConnected()
hoodie.on('connected', handler)
hoodie.on('disconnected', handler)

I never liked the fact that the logic is not contained in a namespace like hoodie.store & hoodie.account, and thet .isConnected() is a function.

💡 New API

I've an idea for a new API but am not yet happy with it. What we need:

• tell if connection is ok based on last request
• persist status in localStorage
• trigger disconnected event if request to check connection failed, pass meaningful error
• trigger reconnected event if request to check connection succeeded when it failed before
• I'd really like to add a namespace, like hoodie.connection

Here's what my current idea looks like

// - undefined if no status yet,
// - true last request responded ok
// - false if last request failed
hoodie.connection.ok 

// returns promise, rejects with meaningful error
hoodie.connection.check({
  // optional: start checking with interval. Not true interval, ignore time of pending requests.
  //           there can only be one interval at a time. Starting a new one clears existing.
  //           different intervals can be set with { connected: 30000, disconnected: 1000 }
  interval: 1000,  
  // optional: timeout when to abort
  timeout: 1000
})

// events
hoodie.connection.on('disconnected', handler)
hoodie.connection.on('reconnected', handler)

Open questions (updated Oct 24):

1. Shall we allow to set defaults for check request interval / timeout? How?
   We tend to yes, via config like {connection: { check: { interval: 10000, timeout: 1000 }}}
2. Shall we add an API to let the user know when connection was last checked?
   API could look like hoodie.connection.lastCheckedAt
3. Shall we add a timeout for the cache?
   Use case: I used my app months ago without internet connection. If we read out the last state my app would tell me that I'm offline and would trigger a "reconnected" event, which might be confusing. To avoid that, we can set a cache timeout after which the cache will be ignored

[gr2m]

I've created a repo with a README here and will keep it updated based on our discussion here

https://github.com/hoodiehq/hoodie-client-connection

[zoepage]

Really nice thoughts here. Thank you for writing this down.
After giving it some thought, I think the new API is more conclusive and feels easier to use.

Would it be possible to add a method to try to reconnect manually or is this made by connection.check?
My use case here:
App checks connection just every 5-10 minutes to save battery and requests. But after editing the data locally, the user might want to upload the data asap. Does it make sense?

re: questions:

1. I love the idea to allow to set defaults for intervals / timeouts, because it looks like it's a feature people are asking for again and again. Saving in the app config could be an idea?
2. I'd love that. Gives more insight and freedom. Always up for that.
3. -1 on that, but maybe just not seeing the use case here.

[gr2m]

App checks connection just every 5-10 minutes to save battery and requests. But after editing the data locally, the user might want to upload the data asap. Does it make sense?

hoodie.connection is independent from the store sync. If you change something locally, it gets pushed immediately by default. hoodie.connection.check({interval: 10 * 60 * 1000}) would only check if you are still connected every 10 minutes.

If a request fails from hoodie.store, I'd immediately run hoodie.connection.check() to see if it's an issue with CouchDB, or if the entire server cannot be reached.

Does that make sense?

[zoepage]

So basically hoodie.connection.check() is for debugging? :)

[gr2m]

In a way, yeah. it's to manually check the connection

[zoepage]

Okay, cool :)

[gr2m]

Instead of hoodie.connection, we could call it hoodie.connectionStatus.

I can imagine that reading hoodie.connection in code without context looks like it would be an open socket to the back-end, with the ability to emit and receive events in both directions.

The full API on hoodie client being

hoodie.connectionStatus.ok // undefined, true, false
hoodie.connectionStatus.check(options)
hoodie.connectionStatus.on(event, handler) // disconnected, reconnected

Another alternative would be to call it hoodie.status, with the full API on hoodie client being

hoodie.status.connected // undefined, true, false
hoodie.status.check(options)
hoodie.status.on(event, handler) // disconnected, reconnected

For sake of clarity, I tend towards hoodie.connectionStatus. Any thoughts?

[HipsterBrown]

I like the clarity of hoodie.connectionStatus as well.

• What does hoodie.connectionStatus.check(options) return?
• Does undefined from hoodie.connectionStatus.ok mean a connection has never been made?

[gr2m]

check() returns a promise, rejects with error, resolves with nothing, see docs on hoodie-client-connection

[gr2m]

And yes undefined means connection has not yet been checked

[gr2m]

I settled on ConnectionStatus, it's implemented at https://github.com/hoodiehq/hoodie-client-connection-status. I'll leave the issue open, maybe we can farther streamline the API, it's easy to change before the release of 1.0

[gr2m]

We settled on an API now, we split up .check with interval into .startChecking / .stopChecking as suggested here: hoodiehq/hoodie-connection-status#13