Enhancements to messages defined in BrowserTypes

[Roaders]

Enhancement Request

Use Case:

I am a developer implementing a Desktop Agent Proxy that will use the proposed messaging protocol to communicate with a Desktop Agent. The types defined in BrowserTypes are very helpful but there are things that can be done to make things easier.

• Have a union type of all messages called FDC3Message (name is just an example. I am not good at naming things! feel free to suggest a different name)
• The FDC3Message union type should be composed of 2 other union types RequestMessage and ResponseMessage
• Have a RequestMessageBase and a ResponseMessageBase. All response messages should have a source: AppIdentifier and request / response uuid in the meta object for example (I am not sure how practical this is but some commanality between messages would be great)
• Have a type predicate defined for each message type:

export function isAddContextListenerRequest(value: any): value is AddContextListenerRequest{
    return (value as AddContextListenerRequest).type === "addContextListenerRequest"; 
}

This isn't necessarily the desired implementation - we could probably use some of the logic from the Convert class to do a better check that it is in fact a valid message. The important bit is the type predicate return type.

We have already implemeted a lot of type predicates and union types but I am not sure how useful it would be to contribute these as I understand that the BrowserTypes are generated by magic so that magic should probably also generate the predicates and union types.

[kriswest]

@Roaders There exist AppRequestMessage, AgentResponseMessage and AgentEvent message schemas and types. See:

• FDC3/src/api/BrowserTypes.ts

  Lines 86 to 101 in d941719

  	export interface AppRequestMessage {
  	/**
  	* Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent.
  	*/
  	meta: AppRequestMessageMeta;
  	/**
  	* The message payload typically contains the arguments to FDC3 API functions.
  	*/
  	payload: { [key: string]: any };
  	/**
  	* Identifies the type of the message and it is typically set to the FDC3 function name that
  	* the message relates to, e.g. 'findIntent', with 'Request' appended.
  	*/
  	type: RequestMessageType;
  	}

• FDC3/src/api/BrowserTypes.ts

  Lines 172 to 188 in d941719

  	export interface AgentResponseMessage {
  	/**
  	* Metadata for messages sent by a Desktop Agent to an App in response to an API call
  	*/
  	meta: AgentResponseMessageMeta;
  	/**
  	* A payload for a response to an API call that will contain any return values or an `error`
  	* property containing a standardized error message indicating that the request was
  	* unsuccessful.
  	*/
  	payload: AgentResponseMessageResponsePayload;
  	/**
  	* Identifies the type of the message and it is typically set to the FDC3 function name that
  	* the message relates to, e.g. 'findIntent', with 'Response' appended.
  	*/
  	type: ResponseMessageType;
  	}

• FDC3/src/api/BrowserTypes.ts

  Lines 233 to 247 in d941719

  	export interface AgentEventMessage {
  	/**
  	* Metadata for messages sent by a Desktop Agent to an App notifying it of an event.
  	*/
  	meta: AgentEventMessageMeta;
  	/**
  	* The message payload contains details of the event that the app is being notified about.
  	*/
  	payload: { [key: string]: any };
  	/**
  	* Identifies the type of the message and it is typically set to the FDC3 function name that
  	* the message relates to, e.g. 'findIntent', with 'Response' appended.
  	*/
  	type: EventMessageType;
  	}

The types are structurally compatible with all messages derived from them so you can use them to write generalized TypeScript code in your implementation. However, as we generate the TypeScript code from the schemas, the type definitions of specific message types don't formally extend these types - but as TypeScript uses structural compatibility rather than than more traditional declarative typing that should not matter (other than it feeling a little odd to those of us that grew up with OO languages).

Given the number of messages, we should try to avoid creating a manual maintenance situation wherever possible (lest we incur the wrath of future generations of FDC3 maintainers). However, I believe it could/should be possible to come up with a way to generate some of your above suggestions by post processing the BrowserTypes file.

Type detection does seem like something the Convert class could be doing...

[kriswest]

Closed as completed - merged into fdc3-for-web-impl branch