examples

Usage examples of Go WebExtensions package

Go module github.com/maxnikulin/burl contains github.com/maxnikulin/burl/pkg/webextensions package that implements native messaging communication protocol for browser extensions. See the pkg/webextensions folder for details. Out of the box the package works on Linux only.

It is assumed that the reader interested in these examples is familiar with native messaging API in browsers. Otherwise consult developers guides: Mozilla or Chrome pages.

To try example add-on in Firefox do the following steps. (For Chrome it is necessary to adjust manifest files.)

Compile example backend

go build ./webextensions_backend/webextensions_example_backend.go

The package allows to write test utilities that runs backend without browser. The aim is to minimize overhead during debugging. You can try an example of such test client:

go run ./webextensions_client -- ./webextensions_example_backend

sqrt: query 2 result 1.4142135623730951
sqrt: query -2 error square root of negative number

Browser allows to call an external application only if such permission is granted through native messaging manifest JSON file. It specifies full path to the application and list of extensions that can run it. (For Chrome the related field is named allowed_origins and contains a list of extension keys.)

Template for native messaging manifest:

{
	  "name": "io.github.maxnikulin.burl_webextensions_example",
	  "description": "Example of backend written using bURL webextnesions Go package",
	  "path": "@@EXAMPLESDIR@@/webextensions_example_backend",
	  "type": "stdio",
	  "allowed_extensions": [ "burl_webextensions_example@maxnikulin.github.io" ]
}

Replace @@EXAMPLESDIR@@ with actual directory of compiled backend and put the resulted file to ~/.mozilla/native-messaging-hosts/ in the case of Firefox. Base part of the file name should be the same as name field in manifest, its extension should be .json.

set -eu
examplesdir_default="$(pwd)"
: "${examplesdir:=${examplesdir_default}}"
sed -e "s|@@EXAMPLESDIR@@|${examplesdir}|"

Now you are ready to load browser extension from the webextensions_addons directory as a temporary add-on:

firefox 'about:debugging#/runtime/this-firefox'

Chrome expect file name manifest.json as well but it requires a different way to specify identifier for the extension. Ready to use file is not provided but you can generate a key and adjust for it extension and native messaging manifests.

Extension adds 3 items to the context menu. Result of execution is logged to the add-on console available through “Inspect” button from the debugging tab. Certainly in real extensions communication with native application should be more resistant to various errors than example of RPC client. Since backend library relies on Go package net/rpc/jsonrpc from standard library, it supports only JSON-RPC 1.0 with single argument in params field or request { params: [ arg ], id, method }. JSON-RPC 2.0 requests should not cause a problem while they follow convention for single argument. Do not expect structured errors in response however.