Are you ready yet? Adding defined (or at least bounded) timeouts to the FDC3 Desktop Agent API

[kriswest]

Enhancement Request

During the implementation of the FDC3 conformance testing framework it became clear there is some variation between desktop agents on the implementation of fdc3.open & fdc3.raiseIntent/fdc3.raiseIntentForContext and the errors that they return. Specifically, the OpenError.AppTimeout and ResolveError.IntentDeliveryFailed errors, which (as documented in FDC3 2.0) are returned if an app fails to add the necessary context listener or intent listener (via fdc3.addContextListener and fdc3.addIntentListener) within a timeout.

As there is no way in FDC3 for an app to indicate that it is 'ready' other than to add the relevant listeners, the listeners are a key point of synchronization and waiting on them with a timeout is the only way for a Desktop Agent to detect an issue and to return an error. The ability to do so is important as many FDC3 interactions will involve up to 3 firms/development team (AppA, Desktop Agent, AppB) and the error indicates where any issue (currently being debugged) is likely to lie.

The errors returned by all Desktop Agent functions are very poorly documented in FDC3 1.2 (individual errors are not described or documented) and some tests based on them have been removed from the corresponding version of the conformance testing framework. FDC3 2.0 is more specific in the documentation of the errors - although the reference documentation for the relevant functions could and should be more specific as well to aid both app and platform developers using them as reference.

However, there is a further issue for conformance testing in that the specific timeouts used are not defined or bounded by the standard. Hence, the conformance tests (currently) adopt a relatively large value (75 seconds) - but also include the caveat that this can be extended if a Desktop Agent implementation uses a longer timeout.

We propose that:

• a required maximum timeout is specified, while DA implementation MAY use a shorter timeout if they wish.
• a short description of which errors are returned when is added to the function reference for any Desktop Agent or Channel function that can return them OR a similar reference created in the Errors page and referred to.

Use Case:

Apps in financial services can sometimes take a while to bootstrap themselves (leading to the relatively long timeouts used in some DA implementations). However, there are often ways that this can be handled (such as adding the listeners early and retaining/queuing up messages received to be processed when the app is ready. Were FDC3 to define suitable timeouts (or at least bounds on them) then:

• developers would be encouraged to use such handling
• behaviour from desktop agents would be more consistent
• conformance tests would not require long (and extensible) timeouts and would run quicker.

[rikoe]

I would like to propose that this is a conformance issue and doesn't and shouldn't be addressed by the standard. It is complex and messy for the standard to try and dictate this.

I think the conformance standard should simply make a call on expected timeouts - they can be relatively short, and anyone who doesn't fall into that conformance settings cannot get certified.

I do not agree that these timeout settings should be pushed from the conformance layer into the standard though.

[kriswest]

@rikoe the meetings about conformance framework were a chance for the DA vendors to discuss a vague part of the specification and how they approached them / whether that was as intended when it was written - and the issue in the framework was intended just to highlight a class of issue (that its hard to know how long an app should be allowed, how long a desktop agent should allow etc.), not to serve as the justification for the change.

Essentially, an FDC3 Desktop Agent has to have some form of timeout, that creates an expectation on an app, however, that expectation will vary when that app is run under different agents. By putting some form of bound (particularly a lower bound - unlike the description in this issue currently) in the standard we help both the app developers and desktop agent developers know where the edges are/the range of those expectations.

I think the conformance standard should simply make a call on expected timeouts - they can be relatively short, and anyone who doesn't fall into that conformance settings cannot get certified.

There's an FDC3 Standard and a conformance framework/project testing compliance with it - rather than a 'conformance standard'. Hence, I do think its the Standard that should take a view on behaviour, with the conformance framework then uses is in its implementation.

[kriswest]

The PR has been adjusted to only require a minimum timeout and to provide no upper bound. See the comment on the PR for more details:
#987 (comment)