is-04
is-04 copied to clipboard
AMWA-TV
Reconsider automatic Query API key stripping functionality
@andrewbonney said that https://github.com/AMWA-TV/nmos-event-tally/issues/38 adds "further weight to a feeling I've had that we ought to be removing the automatic Query API key stripping functionality and depending upon the query downgrade mechanism for multi-version support instead, but that's very much an IS-04 discussion point."
@garethsb-sony "So v1.3 resources would never appear in a response to a v1.2 API?"
@andrewbonney "Yes, that's the thinking. You could as a result only cause mixed version responses by using /v1.3/resources/?query.downgrade=v1.2 etc, ensuring that only clients which are explicitly written to support multiple versions are exposed to it."
@garethsb-sony "That makes sense but loses us some of the flexibility discussed in IS-04 Upgrade Path - Performing Upgrades."
Just to add a few more notes for consideration. We first encountered an issue like this with the ability to set a Sender 'flow_id' to 'null' introduced in v1.1. This meant that when viewing this record via a Query API set to v1.0, a v1.0 client may encounter these values which technically breach the v1.0 schema. A similar requirement is now appearing in https://github.com/AMWA-TV/nmos-discovery-registration/pull/97 which will cause the same problem for v1.0-v1.2 clients when working against a registry which can also handle v1.3.
The cases above are bad because they are potentially unforeseeable changes from a client's perspective. There is also a further class of additions which could cause issues for legacy clients. This includes the addition of support for new transport types. Whilst clients should be checking the 'transport' key, as v1.0 to v1.2 have primarily been used for RTP some assumptions may have been made.
The aim of the key stripping functionality was to ensure that legacy clients could continue to function in upgraded systems. The danger is that whilst they may continue to function for a while, as more new Nodes are introduced to the system there is a greater chance that they may suddenly fail. The trade-off is of course that by changing this mechanism, the legacy clients would only be able to communicate with Nodes which continue to operate at the lower version(s).
The upgrade path does already suggest upgrading clients to the new version before upgrading Nodes (which protects against this issue), but there is no guarantee that this guidance will be followed in practice.
A (potentially contentious) complement to this would be to enable query downgrades by default from v1.3 onwards (or whichever version this changed in). This would encourage client implementers to support a wider range of versions. The query downgrade parameter could then be used as a limiter so that a client could explicitly state that it doesn't support resources below a particular version. This may be completely unnecessary, but I thought it might be worth noting.
Noting another reason in favour of removing the key stripping functionality. If we are generally aiming to avoid future version bumps and define new IS-04 keys externally, registry implementations will not be aware of the new keys which have been added and may inadvertently leak them into lower versioned endpoints.
The updates added in #112 around client handling of attributes hopefully reduce this issue. The key remaining concern is around attributes which gain a new type (such as the possibility to be set to 'null' when they couldn't be previously). These should be kept to a minimum anyway.