Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 41 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,12 @@ jobs:
if: startsWith(github.ref, 'refs/tags/v')
run: dotnet publish src/Bermuda/Bermuda.csproj --configuration Release --runtime win-x64 --self-contained true --output artifacts/publish -p:PublishSingleFile=false -p:PublishReadyToRun=false

# The native side apps listed in fdc3-appd.json ship inside Bermuda's MSIX as more applications, so they
# are published into the same folder (shared runtime/library files are identical).
- name: Publish self-contained native apps into the same folder
if: startsWith(github.ref, 'refs/tags/v')
run: dotnet msbuild src/Bermuda/Bermuda.csproj -t:PublishNativeApps -p:Configuration=Release -p:NativeAppsPublishDir=${{ github.workspace }}/artifacts/publish/

- name: Upload self-contained app
if: startsWith(github.ref, 'refs/tags/v')
uses: actions/upload-artifact@v4
Expand All @@ -70,6 +76,11 @@ jobs:
- name: Check committed FDC3 preload is up to date
run: git diff --ignore-cr-at-eol --exit-code -- src/Bermuda/Preload

# The FDC3 contract is generated from src/Bermuda.Fdc3.Proto/Protos/fdc3.proto by the build
# (Bermuda.Fdc3.Proto); the outputs are committed, so a stale or hand-edited copy fails here.
- name: Check committed FDC3 generated code is up to date
run: git diff --ignore-cr-at-eol --exit-code -- src/Bermuda.IpcContract/Generated src/Bermuda.Fdc3.Grpc/Generated

# ─── E2E (requires a Windows desktop runner) ──────────────────────────────
#
# The Playwright tests connect to the live app via CDP (port 9222).
Expand All @@ -83,6 +94,10 @@ jobs:
name: E2E tests
needs: build
runs-on: self-hosted
# The runner is one machine with fixed-name resources (the app's windows, ports, the FDC3 pipe): one e2e at a time.
concurrency:
group: e2e-self-hosted
cancel-in-progress: false

steps:
- uses: actions/checkout@v4
Expand Down Expand Up @@ -111,6 +126,32 @@ jobs:
working-directory: src/Bermuda.Web
run: pnpm exec playwright install chromium

# The runner is a normal user machine: Bermuda may be installed and running, a dev may have Aspire up, and
# an older run may have left processes behind. So every run gets its own FDC3 pipe, ports and dashboard
# endpoints, and nothing here depends on the defaults being free.
- name: Isolate this run from the rest of the machine
shell: pwsh
run: |
function Get-FreePort {
$listener = [System.Net.Sockets.TcpListener]::new([System.Net.IPAddress]::Loopback, 0)
$listener.Start()
$port = $listener.LocalEndpoint.Port
$listener.Stop()
$port
}
$lines = @(
"FDC3_GRPC_PIPE=bermuda-fdc3-ci-$env:GITHUB_RUN_ID-$env:GITHUB_RUN_ATTEMPT",
"WEB_PORT=$(Get-FreePort)",
"CDP_PORT=$(Get-FreePort)",
"ASPNETCORE_URLS=http://localhost:$(Get-FreePort)",
"ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL=http://localhost:$(Get-FreePort)",
"ASPIRE_DASHBOARD_MCP_ENDPOINT_URL=http://localhost:$(Get-FreePort)",
"ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL=http://localhost:$(Get-FreePort)",
"ASPIRE_ALLOW_UNSECURED_TRANSPORT=true"
)
$lines | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
$lines | ForEach-Object { Write-Host $_ }

- name: Run E2E tests
working-directory: src/Bermuda.Web
run: pnpm e2e --reporter=list
Expand Down
5 changes: 5 additions & 0 deletions Bermuda.slnx
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,12 @@
<Project Path="src/Bermuda.Api/Bermuda.Api.csproj" />
<Project Path="src/Bermuda.AppHost/Bermuda.AppHost.csproj" />
<Project Path="src/Bermuda.Fdc3/Bermuda.Fdc3.csproj" />
<Project Path="src/Bermuda.Fdc3.Grpc.Generator/Bermuda.Fdc3.Grpc.Generator.csproj" />
<Project Path="src/Bermuda.Fdc3.Grpc/Bermuda.Fdc3.Grpc.csproj" />
<Project Path="src/Bermuda.Fdc3.Grpc.Tests/Bermuda.Fdc3.Grpc.Tests.csproj" />
<Project Path="src/Bermuda.Fdc3.Proto/Bermuda.Fdc3.Proto.csproj" />
<Project Path="src/Bermuda.Fdc3.Tests/Bermuda.Fdc3.Tests.csproj" />
<Project Path="src/Bermuda.NativeApp/Bermuda.NativeApp.csproj" />
<Project Path="src/Bermuda.ServiceDefaults/Bermuda.ServiceDefaults.csproj" />
<Project Path="src/Bermuda/Bermuda.csproj" />
</Folder>
Expand Down
9 changes: 8 additions & 1 deletion Directory.Packages.props
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@
<PackageVersion Include="HotChocolate.Types" Version="16.6.1" />

<!-- src/Bermuda.AppHost -->
<PackageVersion Include="Aspire.Hosting.JavaScript" Version="13.5.3" />
<PackageVersion Include="Aspire.Hosting.JavaScript" Version="13.6.5" />

<!-- src/Bermuda.IpcContract.SourceGenerator -->
<PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="5.6.0" />
Expand All @@ -27,6 +27,13 @@
<PackageVersion Include="xunit" Version="2.9.3" />
<PackageVersion Include="xunit.runner.visualstudio" Version="3.1.4" />

<!-- src/Bermuda.Fdc3.Grpc -->
<PackageVersion Include="Grpc.AspNetCore" Version="2.83.0" />
<PackageVersion Include="Google.Protobuf" Version="3.31.1" />
<PackageVersion Include="Grpc.Core.Api" Version="2.83.0" />
<PackageVersion Include="Grpc.Tools" Version="2.83.0" />
<PackageVersion Include="Grpc.Net.Client" Version="2.83.0" />

<!-- src/Bermuda.ServiceDefaults -->
<PackageVersion Include="Microsoft.Extensions.Http.Resilience" Version="10.1.0" />
<PackageVersion Include="Microsoft.Extensions.ServiceDiscovery" Version="10.1.0" />
Expand Down
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -104,7 +104,7 @@ await window.fdc3.broadcast({ type: 'bermuda.incident', id: { incidentId: '7' }
const resolution = await window.fdc3.raiseIntent('ViewIncident', context)
```

- **Where it lives** — the agent is `src/Bermuda.Fdc3/DesktopAgent.cs` (one per process, shared by all windows). `src/Bermuda.Web/src/fdc3/` implements the `@finos/fdc3-standard` `DesktopAgent` interface by calling `fdc3.*` `invoke()` commands (the `IFdc3Commands` interface in `Bermuda.IpcContract/Fdc3Contract.cs`, implemented per app instance by `Fdc3Connection`, so their TS types are generated like everything else) and dispatching the host's `fdc3.context` / `fdc3.intent` / `fdc3.event` pushes to registered handlers.
- **Where it lives** — the agent is `src/Bermuda.Fdc3/DesktopAgent.cs` (one per process, shared by all windows). `src/Bermuda.Web/src/fdc3/` implements the `@finos/fdc3-standard` `DesktopAgent` interface by calling `fdc3.*` `invoke()` commands (the `IFdc3Commands` interface, generated from `Bermuda.Fdc3.Proto/Protos/fdc3.proto` into `Bermuda.IpcContract/Generated/Fdc3Contract.g.cs`, implemented per app instance by `Fdc3Connection`, so their TS types are generated like everything else) and dispatching the host's `fdc3.context` / `fdc3.intent` / `fdc3.event` pushes to registered handlers.
- **Supported** — the 8 recommended user channels, app channels, private channels (with their events), `broadcast`/`addContextListener`/`getCurrentContext`, `findIntent`/`findIntentsByContext`/`raiseIntent`/`raiseIntentForContext`/`addIntentListener` with results (context or channel), `open`, `findInstances`, `getAppMetadata`, `getInfo`, and the `userChannelChanged` event. Not yet: Desktop Agent Bridging, or the Web Connection Protocol for browser apps outside the host.
- **Preload bundle** — `fdc3-preload.js` is built from `src/Bermuda.Web/src/fdc3/preload.ts` by `pnpm build:preload` (part of `pnpm build`) and committed, like `ipc.d.ts`, so the host builds without Node; CI fails if it's out of date. Re-run `pnpm build:preload` after touching anything under `src/fdc3/`.
- **App Directory** — `src/Bermuda/fdc3-appd.json` uses the AppD v2 `applications` shape; relative `details.url`s resolve against `WEB_URL`. `fdc3.open` (or raising an intent at an app that isn't running) opens the app in a new host window and resolves once the app has connected (and, if you passed a context, registered a listener for it), or rejects with `AppTimeout`. Intent results the raiser never collects are dropped after 10 minutes.
Expand All @@ -117,6 +117,8 @@ const resolution = await window.fdc3.raiseIntent('ViewIncident', context)
# Build a self-contained MSIX installer (needs the winapp CLI: winget install Microsoft.winappcli --source winget)
dotnet msbuild src/Bermuda -t:CreateMsix -p:Configuration=Release
# Output: artifacts/msix/

# The package also contains the native FDC3 side apps listed in src/Bermuda/fdc3-appd.json (type "native").
```

### Releases and auto-update
Expand Down
30 changes: 29 additions & 1 deletion docs/fdc3.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ Make the Bermuda host an [FDC3 2.2](https://fdc3.finos.org/docs/2.2/fdc3-intro)
|---|---|---|
| `DesktopAgent` | `src/Bermuda.Fdc3` | All state and rules: instances, channels, listeners, intents, results, launching. One per process. |
| `Fdc3Connection` | `src/Bermuda.Fdc3` | One app instance's handle on the agent; implements the command interface for that instance. `IDisposable`. |
| `IFdc3Commands` | `src/Bermuda.IpcContract/Fdc3Contract.cs` | The wire contract: one method per `fdc3.*` command. TypeScript types are generated from it into `ipc.d.ts`. |
| `IFdc3Commands` | `src/Bermuda.IpcContract/Generated/Fdc3Contract.g.cs` | The wire contract: one method per `fdc3.*` command. Generated from `src/Bermuda.Fdc3.Proto/Protos/fdc3.proto` (see 7a); TypeScript types are generated from it into `ipc.d.ts`. |
| `HostBridge` | `src/Bermuda` | Dispatches an `invoke()` command to the window's connection, binding the JSON payload to the method's parameter type. |
| `MainWindow` | `src/Bermuda` | One connected instance per page load; injects the preload; delivers the agent's pushes to the page. |
| `WindowAppLauncher` | `src/Bermuda` | Opens App Directory apps in new host windows for `open` and for intents. |
Expand Down Expand Up @@ -138,6 +138,33 @@ Rejections are `Error`s whose `message` is the standard FDC3 error string; over
- Selecting an incident broadcasts `{ type: "bermuda.incident", id: { incidentId }, name: <location> }`. Selection that *arrives* over FDC3 (a broadcast on the joined channel, or the `ViewIncident` intent) selects the incident but does not re-broadcast, so linked windows cannot echo.
- Incidents unknown to the receiving window are ignored.

## 7a. Native apps over gRPC (named pipe)

Native side apps join the same in-process agent as the web windows, so they share channels and intents with them. `Bermuda.Fdc3.Grpc` hosts a gRPC service (Kestrel named-pipe transport, HTTP/2 without TLS) that serves `IFdc3Commands`.

**The proto is the source of truth for the whole FDC3 contract**, web and native: `src/Bermuda.Fdc3.Proto/Protos/fdc3.proto`. Building `Bermuda.Fdc3.Proto` does three things:

1. Grpc.Tools turns it into the gRPC messages and the `Fdc3Agent` service (and client) classes.
2. `Bermuda.Fdc3.Grpc.Generator` reads protoc's descriptor set and writes `src/Bermuda.IpcContract/Generated/Fdc3Contract.g.cs`: the `Fdc3*` records and `IFdc3Commands` that `DesktopAgent`, `Fdc3Connection` and the web bridge are written against (and that `ipc.d.ts` is generated from).
3. The same tool writes `src/Bermuda.Fdc3.Grpc/Generated/Fdc3Generated.g.cs`: the proto↔record mapping and one service override per rpc.

Both generated files are checked in, like `ipc.d.ts`, and CI fails if they are stale. So adding or changing a command, field or message means editing the proto and rebuilding; nothing else is hand-synchronised. The naming and nullability conventions (and the `async` method option for commands that wait on another app) are documented at the top of the proto; a proto that breaks them fails the build with the list of problems. Hand-written: the `Subscribe` stream and caller lookup (`Fdc3AgentService.cs`), the JSON helper (`Mapping.cs`) and the host and client.

- **Pipe**: `\\.\pipe\bermuda-fdc3-<user name>` by default (pipe names are machine-wide, so the user name keeps users apart). Override with `FDC3_GRPC_PIPE`; disable with `FDC3_GRPC_ENABLED=false` (both in `appsettings.json` or the environment). The pipe is current-user-only.
- **Connect**: call `Subscribe(app_id)`. `app_id` MUST be in the App Directory, else the call fails with `AppNotFound`. The first stream message is `connected { instance_id }`; context, intent and API-event deliveries follow (`ContextEvent`, `IntentEvent`, `ApiEvent`, mirroring `Fdc3*Event`).
- **Calls**: every other RPC carries the `x-fdc3-instance` header (the `instance_id`) and must use the same pipe connection as the stream, else `AccessDenied`.
- **Lifetime**: the stream is the app instance. When it ends (cancelled, process exit, pipe closed) the instance is disconnected like a closed window.
- **Contexts** are JSON text (`*_json` fields). **Errors** are gRPC errors whose status *detail* is the `Fdc3Errors` string (`NoChannelFound`, `MalformedContext`, …); the code is a coarse mapping (e.g. `NotFound`, `InvalidArgument`, `PermissionDenied`).
- **Client**: any gRPC stack that can dial a named pipe. `Fdc3PipeClient` (in `Bermuda.Fdc3.Proto`, so a client does not need ASP.NET Core; used by the sample `src/Bermuda.NativeApp`) is a ~100-line .NET reference (`SocketsHttpHandler.ConnectCallback` returning a `NamedPipeClientStream`).
- **Native apps are discovered from the App Directory.** `fdc3-appd.json` is the one list of side apps. An entry with `"type": "native"` and `details.path` (its exe, relative to Bermuda's folder) is a native app; `details.project` (Bermuda extension: the .csproj that builds it, relative to the file) tells builds where it comes from. Everything else follows from that entry, so **adding a native app is a one-line edit of `fdc3-appd.json`** plus its project:
- **Aspire** (`Bermuda.AppHost`) starts a resource per native entry next to the host.
- **MSIX** (`CreateMsix`, via `src/Bermuda/tools/native-apps.cs`, a file-based C# app) publishes each project into Bermuda's package folder and adds an `<Application>` for it to the manifest (full trust, no Start menu entry, no startup task). CI publishes them for tagged releases with `dotnet msbuild src/Bermuda -t:PublishNativeApps`. So they deploy, update and are signed exactly like Bermuda, from the same `.appinstaller`.
- **Bermuda** starts each one when the host starts (`App.StartNativeApps`; `NATIVE_APP_AUTOSTART=false` turns that off) and closes them on exit. An app should allow one copy per user, so a second start is harmless, and retry until the host's pipe is up.
- **On demand**: `fdc3.open`, or an intent raised at a native app that is not running, makes Bermuda start it (`NativeAppHost`, the same code as autostart). The host passes the pipe name (`FDC3_GRPC_PIPE`) and the instance id it is expecting (`FDC3_INSTANCE_ID`) in the app's environment, and the app sends that id in `SubscribeRequest.instance_id`, which completes the open. A native app that crashes is therefore started again the next time something needs it. `details.path` must stay inside Bermuda's folder.
- **Only native apps connect over the pipe.** `Subscribe` rejects an App Directory entry that is not `type: native` (`AccessDenied`), so a process cannot claim to be `bermuda-incidents` or another web app. It does not check which program is on the other end of the pipe (anything running as the same user can name a native app); for that, the pipe would need the client's process id, which Kestrel's named-pipe transport does not expose.
The sample is `src/Bermuda.NativeApp` (`native-incidents`): it joins a channel and acknowledges incidents. It handles its own `AcknowledgeIncident` intent rather than `ViewIncident`, so an untargeted `raiseIntent('ViewIncident', …)` still resolves to the dashboard (two running listeners would need the caller to pick one).
- Limitations: native apps are not launched by the agent (`open`/intents can target them only while connected), and web windows are still the only apps with launch URLs.

## 8. Known limitations

- **No origin check.** Any page loaded in a host window gets `window.fdc3` and can issue `fdc3.*` commands as that window's app identity (and, as before this feature, can use the host's other bridges). Fine while the host only loads trusted app URLs; restrict by origin before navigating to untrusted content.
Expand All @@ -155,6 +182,7 @@ Rejections are `Error`s whose `message` is the standard FDC3 error string; over
| `open` and metadata (4.5) | `DesktopAgentTests`: open with context, unknown app, `getInfo`; `ReviewRegressionTests`: contextless `open` waits for connect, times out |
| Wire contract (5) | `IpcDispatchTests`: command naming, every command discovered, payload binding, `InvalidArguments`, unwrapped errors |
| `window.fdc3` (4.2, frontend) | `hostDesktopAgent.test.ts` (listener routing, results, validation, `getResult` caching), `preload.test.ts` |
| gRPC pipe (7a) | `Bermuda.Fdc3.Grpc.Tests/PipeIntegrationTests`: unknown app rejected, instance lifetime, channel broadcast web↔pipe and pipe↔pipe, intent round trip both directions, error details, instance-header/connection binding |
| End to end, live app | `e2e/fdc3.spec.ts`: `getInfo`, two linked windows sharing selection and an intent to a specific instance, and a plain-HTML app receiving `open` with a context (proves the preload) |

Run: `dotnet test`, `pnpm test`, and `pnpm e2e` (needs the app: `aspire run`).
35 changes: 32 additions & 3 deletions src/Bermuda.AppHost/AppHost.cs
Original file line number Diff line number Diff line change
@@ -1,21 +1,50 @@
using System.Text.Json;

var builder = DistributedApplication.CreateBuilder(args);

var api = builder.AddProject<Projects.Bermuda_Api>("api");

// Ports and the FDC3 pipe name can be overridden (WEB_PORT, CDP_PORT, FDC3_GRPC_PIPE in the AppHost's
// configuration or environment), so a CI run can be isolated from anything else on the machine.
var webPort = builder.Configuration["WEB_PORT"] is { Length: > 0 } wp ? wp : "5555";
var cdpPort = builder.Configuration["CDP_PORT"] is { Length: > 0 } cp ? cp : "9222";

var web = builder.AddViteApp("web", "../Bermuda.Web")
.WithPnpm()
.WithEnvironment("PORT", "5555")
.WithEnvironment("PORT", webPort)
.WithEnvironment("VITE_API_URL", api.GetEndpoint("http"));

builder.AddExecutable("relay", "pnpm", "../Bermuda.Web", "run", "relay:watch")
.WithEnvironment("RELAY_SCHEMA_URL", api.GetEndpoint("http"))
.WaitFor(api);

builder.AddProject<Projects.Bermuda>("host")
// An optional pipe name for the host and the native apps.
var pipeName = builder.Configuration["FDC3_GRPC_PIPE"];

var host = builder.AddProject<Projects.Bermuda>("host")
.WithEnvironment("WEB_URL", web.GetEndpoint("http"))
.WithEnvironment("CDP_PORT", "9222")
.WithEnvironment("CDP_PORT", cdpPort)
.WaitFor(web)
.WaitFor(api);
if (!string.IsNullOrWhiteSpace(pipeName)) host.WithEnvironment("FDC3_GRPC_PIPE", pipeName);

// The native FDC3 side apps are discovered from the App Directory (type "native" with details.project), so
// adding one is a one-line edit of fdc3-appd.json. They join the host's agent over the gRPC named pipe (the
// default per-user pipe name) and reconnect until it is up.
var appDirectory = Path.Combine(builder.AppHostDirectory, "..", "Bermuda", "fdc3-appd.json");
foreach (var app in JsonDocument.Parse(File.ReadAllText(appDirectory), new JsonDocumentOptions { CommentHandling = JsonCommentHandling.Skip, AllowTrailingCommas = true })
.RootElement.GetProperty("applications").EnumerateArray())
{
if (app.GetProperty("type").GetString() != "native"
|| !app.TryGetProperty("details", out var details)
|| !details.TryGetProperty("project", out var project)) continue;

#pragma warning disable ASPIRECSHARPAPPS001 // AddCSharpApp is Aspire's new file/path-based project API (experimental)
var native = builder.AddCSharpApp(app.GetProperty("appId").GetString()!, Path.GetFullPath(Path.Combine(Path.GetDirectoryName(appDirectory)!, project.GetString()!)))
.WaitFor(host);
if (!string.IsNullOrWhiteSpace(pipeName)) native.WithEnvironment("FDC3_GRPC_PIPE", pipeName);
#pragma warning restore ASPIRECSHARPAPPS001
}

builder.Build().Run();

2 changes: 1 addition & 1 deletion src/Bermuda.AppHost/Bermuda.AppHost.csproj
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
<Project Sdk="Aspire.AppHost.Sdk/13.5.3">
<Project Sdk="Aspire.AppHost.Sdk/13.6.5">

<PropertyGroup>
<OutputType>Exe</OutputType>
Expand Down
Loading
Loading