Skip to content

Commit

Permalink
further
Browse files Browse the repository at this point in the history
  • Loading branch information
@lawrence-forooghian
lawrence-forooghian committed Mar 13, 2024
1 parent cc13e53 commit 1fc6d22
Showing 1 changed file with 30 additions and 182 deletions.
212 changes: 30 additions & 182 deletions docs/migration-guides/v2/lib.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,22 +9,32 @@ Here’s how to migrate:

## Stop using functionality deprecated in ably-js v1

First update to ably-js 1.2.50 or later
TODO First update to ably-js 1.2.50 or later

### Deprecation warnings from v1

In ably-js 1.2.50 or later, use of the following APIs will trigger a deprecation warning when used (TODO what log level, also you might miss them for non client options)

- The ability to pass the encryption key as the first argument of `Crypto.getDefaultParams()` has been removed. Update your code so that it instead passes an object whose `key` property contains the key. That is, replace `Crypto.getDefaultParams(key)` with `Crypto.getDefaultParams({ key })`.
- The `headers` client option has been removed. Remove your use of this client option.
- The `fallbackHostsUseDefault` client option has been removed.
- If you’re using this client option to force the library to make use of fallback hosts even though you’ve set the `environment` client option, then this is no longer necessary: remove your usage of the `fallbackHostsUseDefault` client option and the library will then automatically choose the correct fallback hosts to use for the specified environment.
- If you’re using this client option to force the library to make use of fallback hosts even though you’re not using the primary Ably environment, then stop using `fallbackHostsUseDefault`, and update your code to either pass the `environment` client option (in which case the library will automatically choose the correct fallback hosts to use for the specified environment), or to pass the `fallbackHosts` client option to specify a custom list of fallback hosts to use (for example, if you’re using a custom CNAME, in which case Ably will have provided you with an explicit list of fallback hosts).
- The ability to use a boolean value for the `recover` client option has been removed. If you wish for the connection to always be recovered, replace `{ recover: true }` with a function that always passes `true` to its callback: `{ recover: function(lastConnectionDetails, cb) { cb(true); } }`.
- The `log` client option has been removed. Equivalent functionality is provided by the `logLevel` and `logHandler` client options. Update your client options code of the form `{ log: { level: logLevel, handler: logHandler } }` to instead be `{ logLevel, logHandler }`.
- The ability to pass an array of channel mode flags as the first argument of `RealtimeChannel.attach()` has been removed. To set channel mode flags, populate the `modes` property of the channel options object that you pass to `Channels.get()` or `RealtimeChannel.setOptions()`.
- The `force` auth option has been removed. If you’re using this option to force `authorize()` to fetch a new token even if the current token has not expired, this is no longer necessary, as `authorize()` now always fetches a new token. Update your code to no longer pass the `force` auth option. Note that, in general, passing an auth options argument to `authorize()` will overwrite the library’s stored auth options, which may not be what you want. The library currently contains a special case behavior where passing an auth options object which only contains `{ force: true }` will _not_ overwrite the stored options. This special case behavior will be removed alongside support for the `force` option, so if you’re currently passing `authorize()` an auth options object which only contains `{ force: true }`, you should stop passing it an auth options object entirely.
- The `host` client option has been renamed to `restHost`. Update your code to use `restHost`.
- The `wsHost` client option has been renamed to `realtimeHost`. Update your code to use `realtimeHost`.
- The `queueEvents` client option has been renamed to `queueMessages`. Update your code to use `queueMessages`.
- `RealtimePresence`’s `on` method has been renamed to `subscribe`. Update your code to use `subscribe`.
- `RealtimePresence`’s `off` method has been renamed to `unsubscribe`. Update your code to use `unsubscribe`.
- `Auth`’s `authorise` method has been renamed to `authorize`. Update your code to use `authorize`.
- The `"xhr"` transport has been renamed to `"xhr_streaming"`. Update your client options code to use `transports: ["xhr_streaming"]`.

## Update to ably-js v2 and address any non-deprecation breaking changes in v2

## Take advantage of new features that v2 introduces

### Using the modular variant of the library

- [Distribute an ECMAScript module variant of the library](https://github.com/ably/ably-js/commit/21fcf137f585591dfcbc1937caacf1ad76af57ee) (and the modular variant in general, with less logging, tree-shakability etc)

TODO again, not clear to me, thinking about it now, why we decided to ship the modular variant in v2; presumably we could do this in v1. Is it a business decision? I guess it also wouldn’t be clear what to do about crypto; CryptoJS isn’t tree-shakable so we’d either have to take the size hit in modular variant, or exclude crypto from modular variant. Furthermore, we wouldn’t necessarily be able to make use of the `exports` key in `package.json`.

#### `Crypto.generateRandomKey()` now works with promises
### `Crypto.generateRandomKey()` now only works with promises, and it didn’t work with promises in v1

- [Change Crypto.generateRandomKey API to use Promises](https://github.com/ably/ably-js/commit/a0105eb80ef6a9c133b4fc861cd2fc0aea71afc5)  — it’s actually that it now _supports_ promises. Not sure why I put this into v2, though; the support could have gone in v1. TODO I think this would be good to put in v1

Expand All @@ -34,14 +44,21 @@ TODO again, not clear to me, thinking about it now, why we decided to ship the m
- JSONP support removed ("for browsers that do not support cross-origin XHR")

- A bunch of platform compatibility stuff:
- [Update `engines` in `package.json` to `node >=16`](https://github.com/ably/ably-js/commit/cc963f8425e254bca10db8b14b2fb0d36e273236)
- [Update platform compatibility statements in READMEs](https://github.com/ably/ably-js/commit/581a6fd705318d2a46ebff171bc61f8041f71f25)
- [Change build/bundle ES target to ES2017](https://github.com/ably/ably-js/commit/54d4c3908cda2c2fb7b3e9f357b875a7882f1bb2)
- [Update `engines` in `package.json` to `node >=16`](https://github.com/ably/ably-js/commit/cc963f8425e254bca10db8b14b2fb0d36e273236)
- [Update platform compatibility statements in READMEs](https://github.com/ably/ably-js/commit/581a6fd705318d2a46ebff171bc61f8041f71f25)
- [Change build/bundle ES target to ES2017](https://github.com/ably/ably-js/commit/54d4c3908cda2c2fb7b3e9f357b875a7882f1bb2)

### Being aware of crypto restrictions

- [Use Web Crypto for encrypting and decrypting on web](https://github.com/ably/ably-js/commit/fcdb9f35ebeaf47883493be04d2ff3d0f985a4fc) (means that encryption is only available in a secure context)

## Take advantage of new features that v2 introduces

### Using the modular variant of the library

- [Distribute an ECMAScript module variant of the library](https://github.com/ably/ably-js/commit/21fcf137f585591dfcbc1937caacf1ad76af57ee) (and the modular variant in general, with less logging, tree-shakability etc)

TODO again, not clear to me, thinking about it now, why we decided to ship the modular variant in v2; presumably we could do this in v1. Is it a business decision? I guess it also wouldn’t be clear what to do about crypto; CryptoJS isn’t tree-shakable so we’d either have to take the size hit in modular variant, or exclude crypto from modular variant. Furthermore, we wouldn’t necessarily be able to make use of the `exports` key in `package.json`.

### Migrating existing code to handle breaking changes

Expand Down Expand Up @@ -143,172 +160,3 @@ TODO could we implement this in v1 and add a deprecation? I guess we _could_, do
### Migrating existing code to handle stuff now deprecated in v2

- [Typings: update v2 typings to use createRecoveryKey() instead of reco…](https://github.com/ably/ably-js/commit/717b060122ace7c7495e6dbade4be25ff260b598)

### Stuff from note "Deprecation messages in v1 and how to write migration guide for them"

Looking at https://github.com/ably/ably-js/compare/64caf8e52152a1ed7b0c1ca32689e2e45369dca8...2462e9bfa412284a3c3975ad83a8ea4da9d9e7f4 (the same commit range used for commit `dd8db94` of changelog)

#### Removal of client options

It would be good for these things to be clear when it's just a rename and when there's something more to it. "use x instead" can mean a lot of things.

##### Already deprecated

- [Remove DeprecatedClientOptions.host](https://github.com/ably/ably-js/commit/5330f75feb3c01aff64faa7c66dbfca10c03c924)

Logger.deprecated('host', 'restHost');

```
Ably: Deprecation warning - The `host` client option has been renamed to `restHost`. Update your code to use `restHost`. `host` will be removed in a future version.
```

this is just a rename
switched log statement

- [Remove DeprecatedClientOptions.wsHost](https://github.com/ably/ably-js/commit/616d2f24ec4281f87379d16702cff5119082850b)

Logger.deprecated('wsHost', 'realtimeHost');

this is a rename
switched log statement

- [Remove DeprecatedClientOptions.queueEvents](https://github.com/ably/ably-js/commit/757ecb5b81476ed63c0e0e5b232dedb82312f753)

Logger.deprecated('queueEvents', 'queueMessages');

this is a rename
switched log statement

- [Remove DeprecatedClientOptions.headers](https://github.com/ably/ably-js/commit/d7aaf347d26991b6139bce8260e32c3735c9165c)

This option is no longer supported (i.e. no replacement)

- [Remove deprecated ClientOptions.fallbackHostsUseDefault](https://github.com/ably/ably-js/commit/adfe5992891e7b140696317bf254edc615e05024)

TODO

this one refers to a replacement piece of functionality that isn't even in the typings

it's described as a development environment feature

- [`(TO3k7)`](https://sdk.ably.com/builds/ably/specification/main/features/#TO3k7) `fallbackHostsUseDefault` boolean (deprecated) – optionally allows the default fallback hosts `[a-e].ably-realtime.com` to be used when `environment` is not production or a custom realtime or REST host endpoint is being used. It is never valid to configure `fallbackHost` and set `fallbackHostsUseDefault` to `true`. The `fallbackHostsUseDefault`option is deprecated and future library releases will ignore any supplied value

[`(RSC15b)`](https://sdk.ably.com/builds/ably/specification/main/features/#RSC15b) The fallback behavior described by this section, [RSC15](https://sdk.ably.com/builds/ably/specification/main/features/#RSC15), only applies when either:

- - [`(RSC15b3)`](https://sdk.ably.com/builds/ably/specification/main/features/#RSC15b3) the deprecated `ClientOptions#fallbackHostsUseDefault` option is set to `true`

[`(RSC15g)`](https://sdk.ably.com/builds/ably/specification/main/features/#RSC15g) When the use of fallbacks applies, the set of fallback hosts is chosen as follows:

- - [`(RSC15g4)`](https://sdk.ably.com/builds/ably/specification/main/features/#RSC15g4) For backwards-compatibility only, if `ClientOptions#fallbackHostsUseDefault` is set to `true` and `ClientOptions#fallbackHosts` is not set, do not consider the value of the `ClientOptions#environment` option and use the default fallback hosts (see [RSC15h](https://sdk.ably.com/builds/ably/specification/main/features/#RSC15h))

OK, what we want to do here is: if `fallbackHostsUseDefault` is specified and the library would use the default fallback hosts anyway given the configuration, then explain why. If it wouldn’t, then explain what the user needs to do.

**But** what was the previous motivation for using this option? has something changed that makes it no longer necessary? Yeah, I think it's because in the past it wouldn't use fallback hosts when the endpoint had been overridden; see spec commit `7ffe000`

I’ve expanded the log messages to address the

- [Remove deprecated ability to pass ClientOptions.recover as a boolean](https://github.com/ably/ably-js/commit/399c896445b1505adcdf462f5ff7798dc04b7439)

clarified log statement a bit

- [Remove deprecated ability to pass "xhr" in ClientOptions.transports](https://github.com/ably/ably-js/commit/b8ad229524d433c401c1a3a4cd19b452913068ed)

Logger.deprecated('transports: ["xhr"]', 'transports: ["xhr_streaming"]');

this is a rename
updated log statement

- [Remove deprecated RealtimePresence.on/off methods](https://github.com/ably/ably-js/commit/742a981dcac464e417f6e80c9c6674e4c66ec181)

Logger.deprecated('presence.on', 'presence.subscribe');
Logger.deprecated('presence.off', 'presence.unsubscribe');

this is a rename
updated log statement

- [Remove deprecated ability to pass AuthOptions.force property](https://github.com/ably/ably-js/commit/2402dc249d683a5b8d3dd39f89b6be15957cefd4)

I think we should stick to the existing pattern of saying that some ability is going to be removed

what was the use case for this option? I think to get it to fetch (e.g. to activate new capabilities) even if token not expired: here's what was in the spec

```
-+* @(RSA10)@ @Auth#authorize@ function:
-+** @(RSA10a)@ Instructs the library to create a token immediately and ensures Token Auth is used for all future requests. See "RTC8":#RTC8 for re-au
thentication behavior when called for a realtime client
-+** @(RSA10j)@ Method signature is @authorize(TokenParams, AuthOptions)@. @TokenParams@ and @AuthOptions@ are optional. When the arguments are presen
t, even if empty, the @TokenParams@ and @AuthOptions@ supersede any previously client library configured @TokenParams@ and @AuthOptions@. For example,
if a client is initialized with @TokenParams#ttl@ configured with a custom value, and a @TokenParams@ object is passed in as an argument to @#authori
ze@ with a @null@ or missing value for @ttl@, then the @ttl@ used for every subsequent authorization will be @null@
- ** @(RSA10b)@ Supports all @AuthOptions@ and @TokenParams@ in the function arguments
--** @(RSA10c)@ Will not create a new token unless no previous token exists or current token has expired. Please note that a buffer of 15s for token e
xpiry is recommended to avoid race conditions where the token is valid at the time of the request, but invalid when it reaches the server. Therefore,
we recommend that a token is considered expired 15s before the time field `expires`
--** @(RSA10d)@ If the @AuthOption@ argument's @force@ attribute is true, it will force @Auth#authorise@ to issue a new token even if an existing token exists. A special case convenience exists for @AuthOption@ stating that if all its attributes are @null@ apart from @force@, then when passed to @authorise@ as an argument, the previously configured authentication options will remain intact. This behaviour takes precedence over "@RSA10j@":#RSA10j
```

I’ve improved the deprecation comment.

- [Remove deprecated ability to pass flags to RealtimeChannel.attach](https://github.com/ably/ably-js/commit/2b56a434c6d0a81846a29f2d31677dbac0f794b0)

TODO

Logger.deprecated('channel.attach() with flags', 'channel.setOptions() with channelOptions.params');

What's going on here?

how are params and flags the same? Why was it called flags and not modes?

```
this._requestedFlags = _flags as API.Types.ChannelMode[];
```

The `modes` property can be used to set channel mode flags. Channel mode flags enable a client to specify a subset of the [capabilities](https://ably.com/docs/auth/capabilities) granted by their token or API key. Channel mode flags offer the ability for clients to use different capabilities for different channels, however, as they are flags and not permissions they cannot be enforced by an authentication server.

A common use case for channel mode flags is to provide clients the ability to be present on a channel, without subscribing to [presence](https://ably.com/docs/presence-occupancy/presence) events.

```
textile/features.textile:** @(RTL4l)@ If the user has specified a @modes@ array in the @ChannelOptions@ ("@TB2d@":#TB2d), it must be encoded as a bitfield per "@TR3@":#TR3 and set as the @flags@ field of the @ATTACH@ @ProtocolMessage@. (For the avoidance of doubt, when multiple different spec items require flags to be set in the @ATTACH@, the final @flags@ field should be the bitwise OR of them all)
-+** @(RTL4l)@ If the user has specified a @modes@ array in the @ChannelOptions@ ("@TB2d@":#TB2d), it must be encoded as a bitfield per "@TR3@":#TR3 and set as the @flags@ field of the @ATTACH@ @ProtocolMessage@. (For the avoidance of doubt, when multiple different spec items require flags to be set in the @ATTACH@, the final @flags@ field should be the bitwise OR of them all)
```

It's not clear to me where the ability to pass flags to `attach` was in the spec, if it was? Well, it seems like now you’re either meant to set the flags in `get()` or `setOptions()`

channeloptions.params

the message is wrong too, it's meant to be modes not params

Well, updated the log message

##### Not previously deprecated

- [Conform to spec for logging configuration](https://github.com/ably/ably-js/commit/eaee6f6ff20f5d38ae2305edf2a7061b799249e3) (`ClientOptions.log` replaced with `logHandler` and `logLevel` )

This one now _is_ previously deprecated —

Logger.deprecated('the `log` client option', 'the `logLevel` and `logHandler` client options');

#### Removal of other stuff

##### Already deprecated

- [Remove deprecated Auth.authorise method](https://github.com/ably/ably-js/commit/5d3a18ac0f5b3927ed61250532a8a1c334ec6a16)

just a rename
switched log statement

- [Remove deprecated forms of calling Crypto.getDefaultParams](https://github.com/ably/ably-js/commit/0f2074ec5d366991238f93a4000f62a360887437)

it's just a case of having to wrap in an object nowo

i've updated message

## Migration guide for React Hooks

- A bunch of React hooks changes, the end result of which I think is that there’s a new `ChannelProvider` API which I _think_ is the only way to get access to a channel and hence a breaking change (but need to understand better). **Also, there seem to be no documentation changes to explain any of this.**
- [WIP!: `ChannelProvider` implementation draft](https://github.com/ably/ably-js/commit/c6ff4264d00d320e69a250130ac8a8d7bb607401)
- [chore: rename `channelToOptions` to show it's internal](https://github.com/ably/ably-js/commit/ab365de3123344c37977089bacf3393006aa3021)
- [chore: make `ChannelProvider` mandatory](https://github.com/ably/ably-js/commit/5b7a34034a3ace318df71a029cb91a7028843a53)
- [refactor: use React context to store channel instance](https://github.com/ably/ably-js/commit/baf68c809adac1de5e32abb9fa7277eebb7795d2)
- [chore: update example App, wording for channel without provider excep…](https://github.com/ably/ably-js/commit/5324354c8f9b3faf071055973c7f255ce7d7ac62)

0 comments on commit 1fc6d22

Please sign in to comment.