Question: getAgent documentation clarification

[Roaders]

Question Area

• App Directory
• API
• Context Data
• Intents
• Use Cases
• Other

Question

On a discussion with @kriswest and @robmoffat it became clear to me that the implementation of getAgent will return a cached promise for any subsequent calls that are made to it. This should probably be documented along with the potentially unexpected behavior where any parameters passed to the function are ignored after the first call.

@kriswest also said that the case where getAgent fails and is then called again that the promise should be cleared and another attempt made.

[kriswest]

I'll look into documenting this - the latter point (clearing the cached promise on error) has already been implemented and appears to work well. On the former point, given that only a single agent can be in scope for a window for either the Desktop Agent Preload or Desktop Agent Proxy interfaces (as they are currently defined) we only really have three options:

1. Allow multiple calls, taking the arguments from the first call only and responding to all calls with the same promise
2. Allow only a single call and define an error to return on subsequent cals
3. (Hybrid of previous approaches) Allow multiple calls, but check that the arguments match the first call made, return the same promise for each call if they do, return an error if they do not.

At present the implementation uses the first approach. This could easily be augmented with a log message on subsequent calls to make it clear whats happening.

@Roaders are you happy for us to proceed with 1. (+ a log message)?

[Roaders]

I don't like 2 or 3. I think it would be normal to have many places in an app that will call getAgent() - that's certainly how we intend to use it.

The way I have implemented it is I log a warning if params have been passed but we're ignoring them. The expected use is that the first call will configure it - with a fallback for example - and subsequent calls will get the same promise as was returned when the initial params were passed.

I would consider a log every subsequent time getAgent() is called as noise that's not really necessary (but am not arguing against if you want to add one) but a log when parameters are ignored is useful.

I hope that makes sense,