Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix the language about the NMOS Controller makeing IS-05 connections (active/inactive Sender, keep/change configuration of Sender, use real/fictious Receivers) #109

Closed
wants to merge 4 commits into from
+7 −2
Closed

Fix the language about the NMOS Controller makeing IS-05 connections (active/inactive Sender, keep/change configuration of Sender, use real/fictious Receivers) #109

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
1deb954
Update Behaviour - Client Side.md
alabou Nov 7, 2022
37f0485
Update Behaviour - Client Side.md
alabou Nov 7, 2022
de7b83a
Update Behaviour - Client Side.md
alabou Nov 8, 2022
d264381
Update Behaviour - Client Side.md
alabou Nov 8, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 7 additions & 2 deletions docs/Behaviour - Client Side.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,13 @@

## Active Constraints of Sender

Before making an [IS-05][IS-05] connection, NMOS Controller chooses a Sender and a number of Receivers. Then NMOS Controller MUST `GET /constraints/supported` from the Sender, MUST collect Receiver Capabilities from the Receivers and make such processing of them that they can be utilized for building Active Constraints satisfying all (by default) or some (depending on user preferences) of the Receivers and using Parameter Constraint URNs supported by the Sender. If the Sender supports fewer Parameter Constraint URNs than used in the Receiver Capabilities, the NMOS Controller SHOULD inform the user about it. If the processing of the Receiver Capabilities results in an empty `constraint_sets` of Active Constraints, NMOS Controller SHOULD inform the user about it. After that NMOS Controller MUST `PUT /constraints/active` to the Sender and SHOULD make the IS-05 connections if the Constraints have been applied succesfully to the Sender. After breaking these connections via IS-05, NMOS Controller is RECOMMENDED to `DELETE /constraints/active` of the Sender.
Before making an [IS-05][IS-05] connection, an NMOS Controller chooses a Sender and a number of Receivers. The NMOS Controller MAY use effective Receivers (real devices) or target Receivers (fictitious devices). The NMOS Controller MAY choose to connect the Receivers to an active Sender or an inactive Sender. If the Sender is active, the NMOS Controller MAY keep the actual configuration of the Sender or deactivate the Sender and change its configuration. If the Sender is inactive, the NMOS Controller MAY keep the actual configuration of the Sender or change its configuration.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Before making an [IS-05][IS-05] connection, an NMOS Controller chooses a Sender and a number of Receivers. The NMOS Controller MAY use effective Receivers (real devices) or target Receivers (fictitious devices). The NMOS Controller MAY choose to connect the Receivers to an active Sender or an inactive Sender. If the Sender is active, the NMOS Controller MAY keep the actual configuration of the Sender or deactivate the Sender and change its configuration. If the Sender is inactive, the NMOS Controller MAY keep the actual configuration of the Sender or change its configuration.
Before making an [IS-05][IS-05] connection, an NMOS Controller chooses a Sender and a number of Receivers. The NMOS Controller MAY choose to connect the Receivers to an active Sender or an inactive Sender. If the Sender is active, the NMOS Controller MAY keep the actual configuration of the Sender or deactivate the Sender and change its configuration. If the Sender is inactive, the NMOS Controller MAY keep the actual configuration of the Sender or change its configuration.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The spec doesn't prohibit changing the configuration of an active Sender, so we can remove this distinction or emphasize that deactivating such Sender MAY be required and depends on the Sender itself.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree with Nikita. Also I prefer "current configuration" to "actual configuration".


If changing the configuration of the Sender, the NMOS Controller MUST `GET /constraints/supported` from the Sender, MUST collect Receiver Capabilities from the Receivers and make such processing of them that they can be utilized for building Active Constraints satisfying all (by default) or some (depending on user preferences) of the Receivers and using Parameter Constraint URNs supported by the Sender. If the Sender supports fewer Parameter Constraint URNs than used in the Receiver Capabilities, the NMOS Controller SHOULD inform the user about it. If the processing of the Receiver Capabilities results in an empty `constraint_sets` of Active Constraints, the NMOS Controller SHOULD inform the user about it. After that the NMOS Controller MUST `PUT /constraints/active` to the Sender and SHOULD make the IS-05 connections of the Receivers if the Constraints have been applied succesfully to the Sender.
Copy link
Contributor

@garethsb garethsb Feb 27, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If the processing of the Receiver Capabilities results in an empty constraint_sets of Active Constraints, the NMOS Controller SHOULD inform the user about it.

Does empty constraint_sets mean no Constraint Sets at all, i.e. it was impossible to come up with any Constraint Set that would satisfy all of the Receivers? If so, is SHOULD enough? How would the Controller be expected to proceed if it cannot make the connection to all of the Receivers that the User requested? I think the answer is that something like this:

If the processing of the Receiver Capabilities results in an empty constraint_sets, the NMOS Controller SHOULD inform the User that not all of the specified Receivers can be satisfied at the same time.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this read better?

If the processing of the Receiver Capabilities results in an empty constraint_sets, the NMOS Controller SHOULD inform the User that all of the specified Receivers cannot be satisfied at the same time.

I think we should keep the SHOULD to allow the controller to decide in some scenarios ...

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"User" is a defined NMOS term now - https://specs.amwa.tv/nmos/branches/main/docs/Glossary.html#user - so we could capitalize it like other terms if we like?


If keeping the configuration of the Sender, the NMOS Controller MUST `GET /constraints/supported` and `GET /constraints/active` from the Sender, MUST collect Receiver Capabilities from the Receivers and make such processing of them that they can be utilized for building Active Constraints satisfying all (by default) or some (depending on user preferences) of the Receivers and using Parameter Constraint URNs supported by the Sender. If the Sender supports fewer Parameter Constraint URNs than used in the Receiver Capabilities, the NMOS Controller SHOULD inform the user about it. If the processing of the Receiver Capabilities results in an empty `constraint_sets` of Active Constraints, the NMOS Controller SHOULD inform the user about it. If the resulting `constraint_sets` is not a subset of the active constraints of the sender the NMOS Controller SHOULD inform the user about it. After that the NMOS Controller SHOULD make the IS-05 connection of the Receivers.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is not a subset

Maybe requires a definition of subset. Here is one that Gareth and me formulated for the nmos-cpp PR:

Constraint Set B is a subset of Constraint Set A if all Parameter Constraints of Constraint Set A are present in Constraint Set B, and for each Parameter Constraint that is present in both, the Parameter Constraint of Constraint Set B is a subconstraint of the Parameter Constraint of Constraint Set A.

Constraint B is a subconstraint of Constraint A if:

  1. Constraint B has enum keyword when Constraint A has it and enumerated values of Constraint B are a subset of enumerated values of Constraint A
  2. Constraint B has enum or minimum keyword when Constraint A has minimum keyword and allowed values of Constraint B are greater than minimum value of Constraint A
  3. Constraint B has enum or maximum keyword when Constraint A has maximum keyword and allowed values of Constraint B are less than maximum value of Constraint A

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I made a mistake in the sentence .. It shall be the reverse "If the active constraints are not a subset of the resulting constraint_sets" ... that is: the new constraint_sets must not be more constrained than the actual ones because it would mean that a stream/flow produces by the active sender would not be compliant with the new receiver(s).

My definition of a subset is different ... Constraint Sets A is a subset of Constraint Sets B if a stream/flow compliant with CS-A is also compliant with CS-B. I don't think we should define the complete algorithm that ensure that CS-A is a subset with CS-B but dictate what such subset represent.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm, yeah, use of subset at this point is interesting, given we've been over the spec language before...

The current statement above that a Controller "make such processing of them that they can be utilized for building Active Constraints satisfying all (by default) or some (depending on user preferences) of the Receivers and using Parameter Constraint URNs supported by the Sender" is quite vague but could be implemented as intersection of the Receivers' constraint_sets. Effectively, Nikita and I had to come up with the above subset/intersection definition when implementing this.

When we have access to the Sender's own capabilities... which we didn't quite finish off specifying (#63).... the Controller would sensibly consider including those in the processing/subset to ensure it will get a 200 not a 422!

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm, actually, isn't this whole paragraph a bit confused... The fact that the "processing of the Receiver Capabilities" results in a subset or not doesn't mean that the Sender's current configuration will match all those Receivers, since the current stream might be within the Sender's current active constraints but not in the subset supported by the new Receivers?
Unless the Controller applies these new active constraints with a PUT request, it cannot guarantee either way?

Unless I've misunderstood, in order to guarantee to satisfy the new Receivers, the Controller MUST apply the new active constraints unless the current ones are a subset of the new ones?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Aha, yes, I see @alabou made same comment... I agree with your idea!

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If the resulting constraint_sets is not a subset of the active constraints of the sender the NMOS Controller SHOULD inform the user about it.

So, putting this the right way round, avoiding "subset", clarifying the rationale for informing the user, and expanding, something like:

If there can be streams compliant with the current active constraints of the Sender that would not be compliant with the resulting constraint_sets, the NMOS Controller SHOULD inform the User that the Receivers cannot be accommodated without replacing the active constraints.

Long winded, so maybe needs breaking into several sentences...

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK with that wording.


After breaking these connections via IS-05, NMOS Controller is RECOMMENDED to `DELETE /constraints/active` of the Sender after making it inactive.
Copy link
Collaborator

@SoloAs SoloAs Feb 19, 2023 •
edited by garethsb
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
After breaking these connections via IS-05, NMOS Controller is RECOMMENDED to `DELETE /constraints/active` of the Sender after making it inactive.
After breaking these connections via IS-05, NMOS Controller is RECOMMENDED to `DELETE /constraints/active` of the Sender after making it inactive.
In order to change the configuration of the Sender without establishing an IS-05 connection, NMOS Controller MUST use `PUT /constraints/active` endpoint. If the Sender is active, NMOS Controller SHOULD deactivate it first.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like that way of introducing the alternate approach "In order to change the configuration of the Sender without establishing an IS-05 connection".

With this phrasing and the "MAY choose to connect the Receivers to an active Sender or an inactive Sender" along with the accompanying text seems to cover all the possibilities.

It would be nice to look at the final text as a single piece to make sure everything is there.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is that recommendation to deactivate before changing the active constraints covered anywhere else in the spec so far?


Constraint Sets of Active Constraints SHOULD represent a consensus among Receivers. For example, there are Receiver A, Receiver B, Receiver C with equal Receiver Capabilities consisting of Constraint Sets 1, 2, 3, 4, 5 and Receiver D with Constraint Sets 2, 3, 4, 5 and 6 which is incompatible with the previous ones. In this case the consensus is Constraint Sets 2, 3, 4, 5 which are common for all the four Receivers. The user may control how the consensus is obtained, providing preferences to the NMOS Controller among the Receivers and the Constraint Sets of each Receiver and criteria about the size of the consensus.

Expand All @@ -12,7 +18,6 @@ Constraint Sets of Active Constraints SHOULD represent a consensus among Receive

Constraint Sets of Receiver Capabilities with `urn:x-nmos:cap:meta:enabled` set to false MUST be ignored completely while making the processing.


## Dynamic format changes on Sender

### Changes which break Active Constraints
Expand Down