This project is archived, which means that it's in read-only state; you can download and use this code, but please be aware that it may be buggy and may also contain security vulnerabilities. If you're interested to restore development activities on this project, please email [email protected]

A continuation of the FDC3 Desktop Agent can be found at FDC3 Sail.

FDC3 desktop-agent

The FDC3 Desktop Agent is an open source implementation of FDC3 as a Chrome Extension. Its purpose is to provide a quick and easy way for app developers to get started with the FDC3 APIs. The extension makes FDC3 directly available in Chrome and provides a default App Directory with a number of demo apps available.

Please note: This project is not intended to be an entire financial desktop solution, it does not address windowing, native integration, or integration with other desktop agents. There are great products such as OpenFin which handle these problems.

features

This project aims to create a full featured FDC3 implementation. These features include:

API

The extension makes the FDC3 API available to all pages loaded in Chrome (except incongnito pages - where the extension does not run). This API will be kept up to date with the developing FDC3 standards.

app directory

The extension uses an app directory hosted at https://appd.kolbito.com by default. This can be overridden in the options panel for the extension. The extension also works without a directory.

The default directory is not currently open source, but it is public for reads. If you want to get something added, please file an issue to this project.

Intent Resolution

When an intent is raised that has multiple possible providers, the extension will bring up a dialog in the Chrome tab raising the intent and present the apps available. This list may include apps from the app directory as well as apps running that have registered intents with the extension (they don't need to be in the app directory).

Channel linking

The extension adds a button into the Chrome toolbar that gives you access to channel linking and other features. You can add any tab in Chrome into a color channel. The color channels control the routing of all FDC3 broadcasts.

Search

The FDC3 extension button also give you access to search functionality. Currently, the search will go against the app directory and return apps that can be lauched as new tabs in Chrome.

examples

Here are some examples of the extension in actions

FDC3 browser action button

color linking

clicking on the link icon opens the color picker
grey indicates the default/no channel
the selected channel is indicated as a badge on the browser action button

search

intent resolution dialogue

options

The extension exposes some options to let you customize the behavior of the desktop agent. Right click on the FDC3 browser action button in the Chrome toolbar to access the options page.

Current options are:

App Directory URL Let's you customize the app directory the extension points to. Defaults to the public directory at https://appd.kolbito.com
Open new tabs in 'global' channel Sets the channel behavior, so that tabs will be put on the 'global' channel by default, allowing tabs to broadcast on recieve context out of the box, without being explicitly put on a channel.

getting the extension

The extension is not published with Chrome. To use it, you will need to get the project and install it locally.

clone and build the project locally

git clone this repo
npm i
npm run build

install the extension

In Chrome, got to chrome://extensions
Click the Load unpacked button in the top left of the screen (if this option is not available, select 'Developer mode' using the toggle switch in the top right)
Select the desktop-agent/dist directory from your local desktop-agent setup

To try out changes, just rebuild with npm and refresh the extension from the extensions page.

using the extension with apps

The extension will automatically inject the FDC3 API into every Chrome tab. The API is documented # https://fdc3.finos.org.

waiting for the api

The readiness of the api is non-determistic and depending on your app, the api may not be injected before your first script runs. To prevent issues, the extension will try to call a global function named onFDC3 when it first loads. It is recommended that if you are setting up fdc3 context and intent handlers on load of your app, that you use this function.

For example:

const onFDC3 = () => {
    fdc3.addContextListener(myListener);
};

working with the extension code

The project consists of these layers:

background - contains most of the business logic for the desktop agent and the connection to the appD backend
content - this establishes the connection to the background script and the individual app windows, handles UI footprint like resolver dialogues, and injects the actual fdc3 api into each window
api - this provides the fdc3 api. It is injected into the given chrome tab by the content script.
popup - ui for color linking and directory search

Going between layers

All API calls typically have to traverse from the api layer to through the content script to the background (where they are actually processed) and back.

return messages

Most calls will have some return value. These messages use the original message name prefixed with return. The actual message structures will differ depending on what layer they are traversing.

api and content layers

Calls between the api and content layers are synthetic document events using document.dispatchEvent and document.addEventListener. All of these events use a prefix of FDC3: in their event name. These events add custom data to the detail property of the event object. For example:

document.dispatchEvent(new CustomEvent('FDC3:broadcast', {
    detail:{
        context:context
    } 
    
}));

content layer to background layer

Communication between the content and background scripts happens via postMessage on a connection created when a page first loads. For example:

port.postMessage({topic:"broadcast", "data": data}); 

port.postMessage({topic:"_environmentData",  "data": data});

Message Payload Structure:

All messages have a topic property. This is the identifier for the message. Naming scheme works as follows:
- if the message is remoting an fdc3 api call - it will be exactly the name of the api
- internal events between content and background scripts will be prefixed with an underscore
- return events carry a unique topic that is generated in the api layer and carried on the original document event as the propoperty event.detail.eventId and as the eventId property on the message for the original event.
All messages have a data property - this is the actual payload for the message.

Contributing

Like FDC3, this is an Apache 2.0 licensed open source project that welcomes contributions!

See Contributing for more details.

Promise API - Errors returned in resolve instead of reject

I believe there is a discrepancy between FDC3 DesktopAgent TypeScript typings and the @finos/fdc3-desktop-agent implementation with regards to Promise typing and associated error handling.

I hope the resolution of this issue will make the two consistent as well as clarify the responsibility for FDC3 DesktopAgent implementations in general. I apologize if the answer is already documented somewhere that I missed.

The core question is: Should FDC3 Promise-based API implementations respond with associated errors (ChannelError, OpenError, ResolveError) using resolve or reject?

Current Typings

Current DesktopAgent typings in @finos/fdc3-desktop-agent and @finos/fdc3 include references to Error typings as tsdoc comments rather than being included in the parameterized Promise types, Promise<T>.

Example:

    /**
     * ...
     * If opening errors, it returns an `Error` with a string from the `OpenError` enumeration.
     * ...
     */
    open(name: string, context?: Context): Promise<void>;

To clarify, the type parameter (T) in Promise<T> refers only to the resolve method's parameter type. The type for reject is and should remain any by design (exception typing).

These typings suggest that errors would not be passed to resolve, but instead be passed to reject, where the any type can be refined using appropriate type guards.

Current fdc3-desktop-agent

From my use of the fdc3-desktop-agent Chrome plugin, it appears that errors are only passed to resolve and that reject may not currently be called at all.

Option: Adapt Typings

To build our initial prototype with the plugin, I created my own types for DesktopAgent that incorporates error types into the Promise type parameter T as applies to resolve method function parameters, as shown by the following excerpt:

import {OpenError, ...} from '@finos/fdc3';

export interface DesktopAgent {
  open(name: string, context?: Context): Promise<undefined | Error<OpenError>>;
  ...
}

export interface Error<T> {
  error: T;
}

If the intended use for errors is to use resolve, should the published typings be updated?

I would also suggest that the Error object typing should be included as part of the public FDC3 interface. The Error<T> interface above is just one way this can be accomplished. I could imagine this interface evolving over time - for instance, if multiple errors could apply to a single reject response or if additional metadata should be included.

Option: Adjust fdc3-desktop-agent

If the intended use for errors is to use reject as suggested by current typings, should the fdc3-desktop-agent be adjusted/fixed?

Thank you in advance.
Ryan

finos / fdc3-desktop-agent Goto Github PK