Acknowledgment handling in the NMOS-CPP library

[gururajsb13]

Hello,

I have a question regarding acknowledgment handling in the NMOS-CPP library.

I'm curious if the PATCH action is supposed to wait for acknowledgment from the application to confirm whether the changes have been successfully updated?

In the connection_api.cpp file, it seems that the validate_merged() callback function does not wait for acknowledgment. Should it be waiting, or is there a different method to handle acknowledgments in the library?

I would greatly appreciate it if someone could provide insights into the acknowledgment handling mechanism in the NMOS library.

[garethsb]

Are you talking about the handling of IS-05 Connection API PATCH requests on the /staged endpoints?

If so, the important point is that these requests can take four forms:

1. Requests that only update the staged parameters but don't apply the new values to the active state of the application's underlying Sender or Receiver
2. Requests that also, or only, schedule a future "activation", when the current staged parameters will be applied to the active state of the application's underlying Sender or Receiver
3. Requests that ask for an immediate activation
4. Requests that cancel a pending scheduled activation

According to the spec, only (3), an immediate activation, requires that the application's underlying state change is complete before the HTTP response is sent. This is intentional design, and means a scheduled activation is asynchronous.

Hopefully this explains why and when each of the application callbacks is made.

validate_merged is called during the handling of all PATCH requests, whereas connection_activated is called during activation. In the case of (3), immediate activation, it is the call of connection_activated that ensures the underlying state change is completed before the PATCH response is sent.

The update of the IS-04 resources in the Node API, and notification of those changes to the Registration API, also happens after activation, but the latter is asynchronous with respect to the PATCH response.

[gururajsb13]

Thankyou for your quick response and clarifications @gareth Sylvester-Bradley.

For instance, when we try to change the Destination Port number, via the Riedel Controller, it sends a PATCH command to the NMOS library with immediate activation.

Below is a Wireshark capture of the HTTP PATCH command with file data:
{"activation":{"mode":"activate_immediate"},"transport_params":[{"destination_port":50025},{"destination_port":50021}]}

In the application code's case #3(an immediate activation), we wait for a response from the underlying process (product-specific) to respond with "Patch Success" before returning. However, what happens if the underlying patch returns an error? How will the application indicate this failure? validate_merged() (doesn't return any value)

[garethsb]

nmos-cpp/Development/nmos/connection_api.h

Lines 31 to 34 in 0a29731

	// a connection_resource_patch_validator can be used to perform any final validation of the specified merged /staged value for the specified (IS-04/IS-05) resource/connection_resource
	// that cannot be expressed by the schemas or /constraints endpoint
	// it may throw web::json::json_exception, which will be mapped to a 400 Bad Request status code with NMOS error "debug" information including the exception message
	typedef std::function<void(const nmos::resource& resource, const nmos::resource& connection_resource, const web::json::value& endpoint_staged, slog::base_gate& gate)> connection_resource_patch_validator;

[garethsb]

Let me reemphasise, the application must not apply the patch to the underlying process in the validate_merged callback. It indicates most limitations via the constraints, then checks during validate_merged for any additional limitations that cannot be represented via constraints. It must only apply the changes when it gets connection_activated callback:

nmos-cpp/Development/nmos/connection_activation.h

Lines 32 to 34 in 0a29731

	// a connection_activation_handler is a notification that the active parameters for the specified (IS-04/IS-05) sender/connection_sender or receiver/connection_receiver have changed
	// this callback should not throw exceptions, as the active transport parameters will already have been changed and those changes will not be rolled back
	typedef std::function<void(const nmos::resource& resource, const nmos::resource& connection_resource)> connection_activation_handler;

[garethsb]

If the actual underlying activation fails, an exception from the connection_activated callback will cause a 500 Internal Error status code to be returned from an immediate activation, but the changes to /active endpoint will not be undone.