Skip to content

A java library allowing to turn any JVM application into a Web Native Messaging Host

License

Notifications You must be signed in to change notification settings

Cosium/web-native-messaging-host

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Build Status Maven Central

Web Native Messaging Host

A java library allowing to turn any JVM application into a Web Native Messaging Host .

Gotchas

To date, web native messaging protocol only supports stdio communication:

  • messages are sent to the native application's stdin
  • messages are sent to the browser extension via native application's stdout

Native application (e.g. your JVM application) instances started by the browser must never use System.out for anything else than native messaging. Very often, you will have to make sure your logger never writes to System.out.

As soon as a Channel is open, the current library will swap System.in and System.out for instances throwing exception on any interaction attempt coming from components foreign to the current library. On Channel shutdown, the library will swap back the standard System.in and System.out instances. The current library cannot cover the full application lifecycle, therefore it is only a best effort.

Using System.out (e.g. for logging) before opening a Channel will probably trigger a fatal error on the browser side leading to the end of the communication channel and the native application shutdown.

Quick start

  1. Add the following dependency:
    <dependency>
      <groupId>com.cosium.web_native_messaging_host</groupId>
      <artifactId>web-native-messaging-host</artifactId>
      <version>${web-native-messaging-host.version}</version>
    </dependency>
  2. Open the communication channel:
    public class App implements MessageHandler {
    
      private final ObjectMapper objectMapper = new ObjectMapper();
    
      public static void main(String[] args) {
        Host host = Host.builder(new App()).build();
        // Open the communication channel
        try (CloseableChannel channel = host.openChannel()) {
          // Block until channel shutdown
          channel.waitForShutdown();
        }
      }
    
      @Override
      public void onMessage(Channel channel, ContainerNode<?> rawMessage) {
        Message message = objectMapper.convertValue(rawMessage, Message.class);
        // Print the received message
        System.out.printf("Received message '%s'%n", message.body);
        // Send a message to the other end
        channel.sendMessage(objectMapper.valueToTree(new Message("I got your message")));
      }
    
      private record Message(String body) {
      } 
    }

Build

e2e-tests can only run on Unix systems.

./mvnw clean verify

Release

./release.sh