Custom lobby protocol

[BElluu]

Closed #537

I implemented custom lobby protocol handling for barrts://, so BAR Lobby can react to internal actions and links opened from outside the application, similar to Steam or Spotify.

I tested it and protocol works on Windows 11 and Linux Ubuntu 26. I tested build packages like AppImage and just dev (npm start).

The protocol is now supported both from inside the lobby and through external web links handled by a separate protocol service.

Tested and working on:

• Windows 11, development mode (npm start)
• Windows packaged build (.exe)
• Linux Ubuntu, development mode (npm start)
• Linux packaged build (AppImage)

What was done:

• Added a custom protocol router in the Electron main process.
• Added protocol actions such as:
  • barrts://internal/test - shows a test notification
  • barrts://internal/ping - shows a ping notification
  • barrts://internal/replays - navigates to the replays tab
• Added support for handling protocol URLs passed to the app on startup.
• Added support for handling protocol URLs passed through the second app instance.
• Added queuing of protocol URLs until the renderer is ready.
• Added Linux protocol registration through .desktop + xdg-mime / gio.
• Lobby protocol links work when clicked inside lobby chat and are displayed with a readable label.

External protocol service:

• We use an external protocol service hosted on my VPS.
• Service URL:
  • https://bar.devopsowy.pl
• Service repository:
  • https://github.com/BElluu/bar-lobby-protocol-service

The external service maps web links to barrts:// protocol URLs.

Examples:

• https://bar.devopsowy.pl/internal/ping
  opens:
  barrts://internal/ping

• https://bar.devopsowy.pl/internal/replays
  opens:
  barrts://internal/replays

• https://bar.devopsowy.pl/lobby/invite?id=555
  opens:
  barrts://lobby/invite?id=555

Why the external service is needed:

• Links shared outside the app, for example on Discord, should be normal HTTPS links.
• The service can be reached even when BAR Lobby is not running.
• The browser opens the HTTPS link, then the service redirects/forwards the user to the registered barrts:// protocol.
• This avoids relying on a local HTTP server running inside the lobby process.

How to test:

1. Test direct protocol links inside the app/chat:

• barrts://internal/test
• barrts://internal/ping
• barrts://internal/replays

2. Test external HTTPS links in a browser or Discord:

• https://bar.devopsowy.pl/internal/test
• https://bar.devopsowy.pl/internal/ping
• https://bar.devopsowy.pl/internal/replays

Expected behavior:

• The browser may ask for permission to open BAR Lobby.
• BAR Lobby should open if it is not already running.
• If BAR Lobby is already running, the existing instance should receive and handle the protocol URL.
• The corresponding protocol action should be executed.

AI / LLM usage statement

I used AI/LLM assistance to research and debug custom protocol handling in Electron, especially platform-specific behavior on Linux, AppImage protocol registration, .desktop handlers, xdg-mime / gio, and Chromium sandbox issues. I also used it to compare the approach with applications such as Steam and Spotify.

[p2004a]

not looked at all, at high level for sure markdown section looks sensitive and needs attention

[BElluu]

I abandoned any local testing with local http bride and set up an external service. Everything seems to be working as expected. Details in the edited PR description :)

[Hectate]

For future reference while implementing stuff for this, I was able to navigate to a specific map (e.g. the appropriate map-specific library/maps/[id] view) with the following handler:

// Using https://bar.devopsowy.pl/internal/maps?mapName=AcidicQuarry%205.17
registerLobbyProtocolAction(
    "internal",
    "maps",
    (_url, webContents) => {
        if (_url.searchParams.get("mapName")) {
            webContents.send("navigation:navigateTo", `/library/maps/${_url.searchParams.get("mapName")}`);
            return;
        }
        webContents.send("navigation:navigateTo", "/library/maps/maps");
    },
    { label: "Go to Map(s)" }
);

Note: internal/map may not be appropriate, this was just testing. Also, this does not handle invalid map names - Vue will happily send you to a blank view.

Certain things like lobby/party invites will likely need IPC events added to call the appropriate store methods, since there is some renderer-side work done to both send the request and maintain the UI.

[Hectate]

Tested in Linux Mint 22.3 Cinnamon (via VirtualBox) and working also. 👍

[Hectate]

In my opinion, the only question remaining is about this external service for the links. I would prefer that we commit this PR with a relatively permanent location already active.

@BElluu there is no license listed for your BAR Lobby Protocol Service so BAR would likely not use it without resolving that question. Obviously, it's not something you should host directly either, so BAR either needs a license to use it or will have to self implement something.

@p2004a In Discord you stated the following:

Marek: probably best suited for small cloudflare worker, like we have the config serving service

Since this is basically an infrastructure task, do you have any preferences/opinions to add?

[BElluu]

@Hectate I added MIT license to external service :)

[Hectate]

While looking over this, I realized that we're basically building the URL string manually. We should use Node's URL class to build this, including the URLSearchParams, and then return the URL instead of the string. From there, the client can handle it as it sees fit (including just putting url.href into the copy/paste buffer for the user). That way if there's ever a need for the actual URL, we don't have to reconstruct it from the string.

And I also just noticed this is not being used at all anywhere except tests. The preload.ts : getShareableUrl code should call this function instead and return the URL. The code there looks good, it just should be moved here. That'll allow us to use it in main the same way we use it in renderer.