GithubHelp home page GithubHelp logo

finos / fdc3-sail Goto Github PK

View Code? Open in Web Editor NEW
30.0 7.0 18.0 4.14 MB

Open implementation of the FDC3 standard using Electron and an integrated App Directory.

License: Apache License 2.0

JavaScript 4.31% TypeScript 94.08% HTML 0.97% CSS 0.63%
electron fdc3

fdc3-sail's Introduction

FDC3 Sail Icon

FDC3 Sail

Develop easier.   Build faster.   Integrate quicker.


What is FDC3 Sail?

This project provides a fully open source implementation of the FDC3 interoperability standard. Including:

  • A fully featured and secure electron desktop agent featuring:
    • intent resolution
    • channel linking
    • directory search
  • A local file-based app directory implementation

FDC3 Standard Primer

If you are an Electron and/or Web Dev new to FDC3, it may be helpful to check out this primer.

Sail at OSFF!

Nick Kolba (Connectifi) and Seb M'Barek (Norman and Sons) presented FDC3-Sail at the Open Source In Finance Forum (OSFF) in New York in December 2022. They showed how you could git-clone FDC3-Sail, run it and play with all the apps in the FINOS App Directory. They also showed how to build apps and share context data.

If you haven't already, check out their demo here: https://youtu.be/5VJzftderO0

About This Implementation

  • FDC3-Sail is an Electron application built from the Vite Electron Builder Boilerplate
  • The UI for the desktop agent is built using React MUI.
  • All remotely hosted content is run in BrowserView following electron security best practices.

The following libraries are used:

Structure

  • directory/ - for local app directories
  • packages/main - the main Electron application, has access to Node
  • packages/preload - preload scripts for web renderers. Bridges the frontend ui to the main process through events and apis
  • packages/renderer - the parts of the desktop agent UI built with React, isolated from main app, and shown in a window on the desktop
    • channelPicker - UI for the channel picker
    • homeView - UI for the default home view
    • intentResolver - UI for the intent resolver window
    • searchResults - UI for the searchResults window
    • sessionView - UI for the sessionView window
    • topNavigation - UI for the Top Navigation that includes the Tabs, channel picker button, and Dev Tools Menu.

Getting Started

npm install
npm start

This will use the FINOS app directory at https://directory.fdc3.finos.org/v2/apps

Getting Started With Your Own App Directory

  1. Install dependencies:
npm install
  1. Create your own local App directory manifest .e.g. local.v2.json in the /directory folder

  2. Set the environment variable to use this directory:

export SAIL_DIRECTORY_URL=directory/local.v2.json
  1. Start the FDC3 application:
npm start

Other useful commands:

  1. npm start / npm run watch - Start the Electron app in dev mode.
  2. npm run compile - Build the app for local debugging only.
  3. npm run lint - Lint the code.
  4. npm run typecheck - Run a TypeScript check.
  5. npm run test - Run tests for all parts of the application, including end-to-end tests.

Mailing List

To join the Electron FDC3 Desktop Agent & App Directory mailing list please email [email protected].

Roadmap

BMO Hackathon Milestone

Contributing

  1. Fork it (https://github.com/finos/fdc3-sail/fork)
  2. Create your feature branch (git checkout -b feature/fooBar)
  3. Read our contribution guidelines and Community Code of Conduct
  4. Commit your changes (git commit -am 'Add some fooBar')
  5. Push to the branch (git push origin feature/fooBar)
  6. Create a new Pull Request

NOTE: Commits and pull requests to FINOS repositories will only be accepted from those contributors with an active, executed Individual Contributor License Agreement (ICLA) with FINOS OR who are covered under an existing and active Corporate Contribution License Agreement (CCLA) executed with FINOS. Commits from individuals not covered under an ICLA or CCLA will be flagged and blocked by the FINOS Clabot tool (or EasyCLA). Please note that some CCLAs require individuals/employees to be explicitly named on the CCLA.

Need an ICLA? Unsure if you are covered under an existing CCLA? Email [email protected]

License

Copyright 2022 FINOS

Distributed under the Apache License, Version 2.0.

SPDX-License-Identifier: Apache-2.0

fdc3-sail's People

Contributors

andreifloricel avatar colineberhardt avatar kriswest avatar nkolba avatar robmoffat avatar sebbenmbarek avatar symphony-jean-michael avatar thejuanandonly99 avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar

fdc3-sail's Issues

Support tear-out and drop in of tabs

A user should be able to drag a tab out of window and drop it on the desktop to create a new window with the tab.

A user should be able to drag a tab from one window and drop it into the tab set of another window. When dropping into the tab set, the user should be able to drop it at a specific point in the tab set.

Developer Introductory Video

  • Introduce FDC3 Sail
  • Show how to create a new app, add to the overall directory
  • Show how you can add intents/context listeners.

(option) Take the FDC3 Sail demo from OSFF 2022 and shorten it?

Add default message to local directory

Navigating to the '/' route on the directory just returns an error

image

Instead, a JSON payload should be returned with metadata describing the directory. e.g.

    {
          "description":"FDC3 App Directory",
          "version" : 1.2
      }

Update intent methods to use AppIdentifier type

  • raiseIntent - signature
  • raiseIntentForContext - signature
  • route to instance if an instance identifier is provided
  • deprecate old signatures

Ensure proper error is thrown if target instance is specified but not found:

If a specific target app parameter was set, but either the app or app instance is not available then the ResolveError.TargetAppUnavailable or ResolveError.TargetInstanceUnavailable errors MUST be returned.

Testing FDC3 Apps

Feature Request

Description of Problem:

Could we build an FDC3 app compliance tool using FDC3 Electron? Writing an app in FDC3 requires the desktop agent to test with, perhaps in a CI environment.

Potential Solutions:

From Nick's Email:

Could the Electron Agent provide testing hooks for apps? ie. the app could expose a set of FDC3 integration tests that the agent could then orchestrate, run, and generate some output for.

Perhaps we can "script" FDC3 Electron and via command line? (Just an idea)

AppD - remove 'icon' field

An additional 'icon' field was added in the appD implementation. This is intended as a convenience for the front end - the field isn't added in the data itself, only in the API response - and is just the first icon url in the 'icons' list.

However, as a reference implementation, the response from appD should conform to the standard and this field should be removed.

Any UI code relying on the 'icon' field should also be updated to use the icons array rather than icon.

Namespace FDC3 Handlers according to version

Use Case
Support different apps on different versions of FDC3 running simultaneously and interoperating against different API version

  • Add version name spacing to all FDC3 topics. e.g. FDC3_TOPICS.BROADCAST becomes FDC3_1_2_TOPICS.BROADCAST and FDC3_2_0_TOPICS.BROADCAST with values of FDC3_1.2:broadcast and FDC3_2.0:broadcast
  • Change topics used in api Preloads
  • Change assignments in respective handler index files (see note below)

Note
For clarity, we should maintain complete separation of topics (i.e. there should only be versioned topics), but for many FDC3 topics, the handler logic may not be changed between functions. In this case, the assignment of the handler to the topic in the index file could be to the same handler. i.e. if handling logic hasn't changed, 2.0 Topics could be assigned to 1.2 handlers.

News API is broken

Bug Report

I get this when I try to start News API:

Application error: a client-side exception has occurred (see the browser console for more information).

Can you investigate?

Side-Loading

If you are building a new app, it should be possible to "side-load" this into the app-directory without having to modify / create a directory of your own.

This would allow people who are building apps from scratch to test them out without having to worry about creating a directory.

This would work particularly well with the FDC3 Workbench, which would allow them to test receiving/sending contexts and intents via channels in the app.

This is something that I used extensively when developing apps in Symphony (see https://symphonyoss.github.io/Integrations-Docs/quickstart/):

Run your application again as indicated above, to get the new bundle.js information packaged.
Launch the Symphony client on your browser, adding your bundle.js as path of the query parameters in the URL. For instance, using the Foundation Dev Pod with the above ngrok sample URL: https://foundation-dev.symphony.com?bundle=https://d74a790c.ngrok.io/apps/zapier/bundle.json.

getCurrentChannel fails if there is no current channel

Bug Report

Steps to Reproduce:

Run conformance test getCurrentChannel (FDC31.2)

Expected Result:

Promise of null

Actual Result:

Exception thrown;

Additional Context:

 getCurrentChannel: async () => {
      const result: ChannelData = await sendMessage(
        FDC3_1_2_TOPICS.GET_CURRENT_CHANNEL,
        {},
      );

      return createChannelObject(
        result.id,
        result.type,
        result.displayMetadata || { name: result.id },
      );
    },

in the above code from api.ts, result is null but nevertheless it tries to create a channel object.

color picker positioning off

Color picker should appear horizontally centered with the color picker button and just below. It is currently being offset to the right .

image

Also, if the window is maximized, the offsetting forces the color picker off the screen.

1.2 Conformance Tests

We need to pass the 1.2 conformance test suite (which is now ready) and get our passing badge from FINOS

Refactoring / Multiple Sub-Projects

@sebbenmbarek and I were chatting today about how to factor-out Electron FDC3. We're thinking along the lines of:

FDC3 Bus

  • Implements the DesktopAgent API, handles Context Data / Intents etc.
  • Plugable (Servlet-style) middleware layer so that we can interact with the other layers.

Skeleton App

  • Super basic app that I can build / run within the desktop and see how things work.
  • Easy place to hack on top of.

UI / Window Management

Electron

  • Handles all the concerns of doing the Electron Framework, including memory management stuff I guess
  • Alternatively we could base a UI on something else like deno or Tauri?

SaaS?

  • Would be nice to run the whole thing in a browser and not use Electron at all.

App Directory

  • Could be run on localhost via a command, or using the FINOS AppDirectory

Ideally, all of these should be sub-modules in the repo.

Developer Experience

  1. Play With FDC3.
    • Download, run, build locally with some example apps.
  2. Developer tools built-in
    • FDC3 workbench goes in this direction
    • A middleware logger layer that shows you exactly how things are being processed / work
  3. Wrap an existing app
    • Say GMaiil (?). Point to url, run in the container
    • Point to an existing url and run it in a container
    • Create an FDC3 AppD record from a URL
    • I want to add some stuff to the app directory to try out some arrangement of apps.
    • "I already have this running on X, but I want to try this in Electron FDC3"
  4. Build a new app4.
    • We need some examples to hack on. e.g. Nicks existing apps
  5. Use one layer in your own app
    • E.g. symphony (for example ) using this OSS FDC3 bus implementation)

Demo

What do we want to achieve in NYC? We've seen lots of demos where we have interop between two or more different apps. What's the "next level"?

The story could be the Dev UX?

  • Visualisation of the bus
  • How to put this together from a developer standpoint
  • Can we show the developer learning curve being really easy?

OpenSSF Badge

Can someone fill this in and add the badge to the Electron project?

https://bestpractices.coreinfrastructure.org/en

It's about a 30 minute job filling out questions about how well the project is run - even if you don't get a "passing" badge, we can have the "working towards" level which is good enough.

Raise issues for anything we don't pass, I guess.

Stub out 2.0 API

  • support switching API from 1.2 to 2.0
  • internalize interfaces for 1.2 (to support npm update of @finos/fdc3)
  • update @finos/fdc3 package
  • get all type errors resolved (don't worry about functionality just yet ;))

UI / UX Mock-Ups

Feature Request

Description of Problem:

  • We need to know what we are "aiming for" for the December OSFF in terms of how the UI will hang together.
  • Run Electron FDC3 Locally, snapshot pieces of the look-and-feel, try to come up with how it should look

Potential Solutions:

  • Recommended libraries / components

  • Choice of CSS Framework / skin

  • Pieces of chrome - how they should look:

    • Intents Chooser
    • Overall screen layout
    • Options page?
    • Directory page?
    • Startup Page
  • Address tabbing / workspace layout.

Other Considerations

  • Search bar?
  • Nav Bar?

Nick's Existing Apps

  • Can we refresh these so they look good, and consistent?

What's the Workflow we want to show?

(Stock info)

  • Twitter embedded? User selects stock price, then creates context data from that.
  • Research app running in another window, which adjusts to show research relating to it
  • Chart App updates with a stock price window
  • Symphony app? Some interaction with that...

(User Details)

  • User is in a symphony chat, and they are talking to someone
  • Their linkedIn window adjusts to show them the details of that person

Workspaces & Layouts

Placeholder for a discussion with @nkolba and @sebbenmbarek about how we handle layouts (Golden Layout?) and workspaces.

  • We need to consider how Sail will handle multiple tabs, and how it will divide a tab into multiple apps.
  • How does the user configure this? How is it persisted between sessions?
  • What happens when an app opens a new window? How will this be handled?
  • Display of directory "drawer" as in @sebbenmbarek's Miro designs.

Sail failing on new conformance test

Bug Report

Steps to Reproduce:

We're running this test: https://github.com/finos/FDC3/blob/conformance2.0-rm/toolbox/fdc3-conformance/User-Channel-Tests.md UCFilteredUsage3 and UCFilteredUsage4 using the https://github.com/finos/FDC3-conformance-framework/tree/2.0-release-candidate-2 branch of conformance tests

Expected Result:

When an app broadcasts on a user channel, then another app subscribes, the second app should receive the context from the first app, even if it subscribes after the broadcast has finished.

Actual Result:

Doesn't seem to happen

Environment:

HEAD of Sail

Color Picker content not centered

There is an uneven amount of whitespace around the color channel squares - resulting in the picker looking a bit off. Spacing should be even all around. Looks like the amount of spacing on the top and left is correct.

image

Support Opening Apps in new window

As per comments from @kriswest

'I couldn't figure out how to open an app in a new window (rather than browserview/tab) other than by raising an intent...'

This isn't a feature currently supported. Not sure how we would make it an option without extending the open API (and maybe it needs extending). Either that, or this would need to be binary - either fdc3.open always targets a new window or always targets a new tab.

Note: there are also an open issue (#13 ) for supporting tear out and drop-in of tabs - which also address this use case to some extent.

Proposed Architecture Improvements

The following is a high level proposal and some improvements to make to the underlying architecture to achieve the following goals. This is coming out of a series of discussions with @sebbenmbarek and @robmoffat .

  • make the project easier for others to contribute to and use as a starting point for their own extensions
  • make the code more robust and testable
  • make it easier to plug-in new/different APIs and handlers (with FDC3 2.0 being the first use case)

object model

current model looks like:

  • runtime
    • workspace(s)
      • window : BrowserWindow
      • id : string
      • resultsWindow : BrowserWindow
      • channelWindow : BrowserWindow
      • resultsId : string (?)
      • channel : string
      • selectedTab : string
      • views : Array
        • id : string
        • parent : Workspace
        • directoryData : App Data
        • content : BrowserView
        • pendingContexts : Array
        • pendingIntents : Array

Some problems with this currently are:

  • The handlers (currently listeners) are essentially hard-coded into the project as a monolith. These need to be modular.
  • The distinction/separation/and naming for FDC3 and non-fdc3 related handlers should be much clearer and easier to navigate.
  • The object model is a bit rigid and over-opinionated - for example, calling what are really windows 'workspaces' conflates a number of concepts, is a bit confusing, and isn't set up well for a number of different configurations of windows.
  • The data structure for storage of state and movement of messages needs to be cleaner, more consistent, and more maintainable.
  • FDC3 state data is mixed into the object model for the views: directoryData, pendingContexts, etc this should all be managed within the handlers layer with the window/view object model only responsible for rendering.

Proposed changes to the object model

  • change 'workspace' to 'FDC3Window'
  • create an fdc3Window interface so that other implementations can be supported
  • change 'view' to 'FDC3View' and create an interface as above
  • remove directoryData, pendingContexts, and pendingIntents from FDC3View

handlers

  • split out handlers (replaces listeners...)
    • fdc3 handlers
    • runtime handlers
  • each handler type gets its own directory
  • each handler grouping gets it's own file (i.e. context listeners, broadcast, channels, etc) and test file
  • handlers can/will be pluggable

Directory Structure for handlers will look like this:

- /handlers
   - /runtime
      - window.ts
      - window.spec.ts
      - tabs.ts
      - tabs.spec.ts
   - /fdc3
      - contextListeners.ts
      - contextListeners.spec.ts
      - broadcast.ts
      - broadcast.spec.ts

Proposed standardizing data structures

Data for representing state and messages should be stanardized across the board.

  • standardize event messages - for both FDC3 and Runtime events

  • create interface for each data structure needed for interop

    • appinstance
    • context
    • channels
    • contextlistener
    • intentlistener
    • pending
  • create a standardized access layer for these to support moving to storage

Success Criteria

Key goals that we wish to achieve with the architecture changes:

  • have 80% + code coverage on all handler logic
  • can switch between FDC3 2.0 and 1.2 apis (at build time)
  • can visualize the state data of interop in real time

2.0 Compatibility

Feature Request

Implement FDC3 2.0 API.

Suggested Test Cases

We can use the FDC3 Conformance Project to test this, once it is 2.0 compatible.

Dev Tools Menu should open in a dedicated window

As per issue #43... Currently, if the main window size is too small, the '...' menu for dev tools wraps so that the menu items become obscured. This happens because the toolbar is being rendered in a window that is truncated by the browser view for rendering the tab content. The current menu for devtools is rendered in the DOM of the toolbar window - so if there isn't enough space - it just gets cutoff.

The solution is to use the same method for rendering this menu as is used for the color picker menu, search results, etc, which is to render as a dedicated window that can overlay the content of the main window and is not bound by it's DOM.

Hyperlinks Load in Chrome

Bug Report

Links load into Chrome - shouldn't they stay in sail. e.g. when I click the 1.2 link below it loads into Chrome and so obviously FDC3 fails to work there.

Screenshot 2023-09-18 at 15 55 29

App height gets truncated on Windows OS

Bug Report

Steps to Reproduce:

  1. Use a Windows OS
  2. Launch Sail via npm start
  3. Open any app that uses the entire screen. e.g.:
    • Symphony
    • TradingView

Expected Result:

The entire app is visible

Actual Result:

The bottom bit of the app is truncated and cannot be seen or scrolled to or interacted with. The missing portion looks to be about the height of the menu bar above.

Environment:

  1. Windows 11 natively
  2. Windows 11 + WSL + X410
  3. Windows 11 + WSL + WSLg

Additional Context:

macOS does not appear to suffer from this bug

The intent result is not returned when the intent UI resolver has been opened

Bug Report

Steps to Reproduce:

  1. Register 2 applications (B, C) that listen to the same Intent FDC3
  2. Send the intent from application A
  3. The Intent UI resolver will opened, and ask to the user to select the application to open B, or C
  4. Select an application B, or C
  5. Then in the selected application, the intent is processed and returns a result
    ==> But the intent result is never received in application A

Expected Result:

The intent result is received in application A (Application that triggers the FDC3 intent)

Actual Result:

The intent result is never received in application A (Application that triggers the FDC3 intent).
This bug only occurs when the intent UI resolver is displayed. It does not occur when there is only one application registered for the intent and therefore no intent UI resolver is used.

The problem seems to come from:

Where the main logic to get and returns the result is only executed when there is only 1 app listening the intent.
So, we should also executes it once the user has selected an application in the UI Resolver (the UI Resolver should return a Promise)

Environment:

  • FDC3 v2.0
  • Mac OS 12.6.3
  • Sail hash commit: 48566d8

Put tools buttons in a menu

The Frame, and View tool buttons take up too much space and are visually distracting. They should be combined into a tools menu or a vertical dot menu (like in Chrome).

image

directory/local.v2.json doesn't match appD spec on `interop.intents.raises`

Bug Report

Originally raised on the FDC3 repository as: finos/FDC3#1085

directory/local.v2.json contains records that don't match the appD spec on interop.intents.raises . They are incorrectly using the schema for interop.intents.listensFor. See:

"raises": {
"CreateInteraction": {
"contexts": [
"fdc3.interaction"
],
"displayName": "Create Interaction"
},
"ViewContact": {
"contexts": [
"fdc3.contact"
],
"displayName": "View Contact"
},
"ViewInstrument": {
"contexts": [
"fdc3.instrument"
],
"displayName": "View Instrument"
}
}

This is also wrong the FINOS App Directory, see: finos/FDC3#1085

and compare to the spec: https://fdc3.finos.org/schemas/2.1/app-directory.html#tag/Application/paths/~1v2~1apps~1%7BappId%7D/get
image

That value is unlikely to be read by Sail for anything so its likely just the data files that need correcting

CVE-2023-2251 (High) detected in yaml-1.10.2.tgz - autoclosed

CVE-2023-2251 - High Severity Vulnerability

Vulnerable Library - yaml-1.10.2.tgz

JavaScript parser and stringifier for YAML

Library home page: https://registry.npmjs.org/yaml/-/yaml-1.10.2.tgz

Path to dependency file: /package.json

Path to vulnerable library: /node_modules/yaml/package.json

Dependency Hierarchy:

  • react-11.10.6.tgz (Root Library)
    • babel-plugin-11.10.6.tgz
      • babel-plugin-macros-3.1.0.tgz
        • cosmiconfig-7.1.0.tgz
          • yaml-1.10.2.tgz (Vulnerable Library)

Found in base branch: main

Vulnerability Details

Uncaught Exception in GitHub repository eemeli/yaml prior to 2.2.2.

Publish Date: 2023-04-24

URL: CVE-2023-2251

CVSS 3 Score Details (7.5)

Base Score Metrics:

  • Exploitability Metrics:
    • Attack Vector: Network
    • Attack Complexity: Low
    • Privileges Required: None
    • User Interaction: None
    • Scope: Unchanged
  • Impact Metrics:
    • Confidentiality Impact: None
    • Integrity Impact: None
    • Availability Impact: High

For more information on CVSS3 Scores, click here.

Suggested Fix

Type: Upgrade version

Origin: GHSA-f9xv-q969-pqx4

Release Date: 2023-04-24

Fix Resolution: yaml - 2.2.2

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.