V1

Author: reda-alaoui

.github/workflows/ci.yml

@@ -0,0 +1,19 @@
+name: CI
+
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up JDK 17
+        uses: actions/setup-java@v2
+        with:
+          java-version: '17'
+          distribution: 'adopt'
+      - name: Build with Maven
+        uses: GabrielBB/xvfb-action@v1
+        with:
+          run: ./mvnw --batch-mode verify

.gitignore

@@ -0,0 +1,54 @@
+# Created by .ignore support plugin (hsz.mobi)
+### JetBrains template
+# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio and Webstorm
+# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
+
+# User-specific stuff:
+.idea
+
+# Sensitive or high-churn files:
+.idea/dataSources.ids
+.idea/dataSources.xml
+.idea/dataSources.local.xml
+.idea/sqlDataSources.xml
+.idea/dynamic.xml
+.idea/uiDesigner.xml
+
+# Gradle:
+.idea/gradle.xml
+.idea/libraries
+
+# Mongo Explorer plugin:
+.idea/mongoSettings.xml
+
+## File-based project format:
+*.iws
+*.iml
+
+## Plugin-specific files:
+
+# IntelliJ
+/out/
+
+# mpeltonen/sbt-idea plugin
+.idea_modules/
+
+# JIRA plugin
+atlassian-ide-plugin.xml
+
+# Crashlytics plugin (for Android Studio and IntelliJ)
+com_crashlytics_export_strings.xml
+crashlytics.properties
+crashlytics-build.properties
+fabric.properties
+### Maven template
+target/
+pom.xml.tag
+pom.xml.releaseBackup
+pom.xml.versionsBackup
+pom.xml.next
+release.properties
+dependency-reduced-pom.xml
+buildNumber.properties
+.mvn/timing.properties
+

.mvn/jvm.config

@@ -0,0 +1 @@
+--add-exports jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.base/java.lang.reflect=ALL-UNNAMED --add-opens=java.base/java.text=ALL-UNNAMED --add-opens=java.desktop/java.awt.font=ALL-UNNAMED

.mvn/wrapper/.gitignore

@@ -0,0 +1 @@
+maven-wrapper.jar

.mvn/wrapper/maven-wrapper.properties

@@ -0,0 +1,18 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.8.1/apache-maven-3.8.1-bin.zip
+wrapperUrl=https://repo.maven.apache.org/maven2/org/apache/maven/wrapper/maven-wrapper/3.1.1/maven-wrapper-3.1.1.jar

README.md

@@ -0,0 +1,71 @@
+[![Build Status](https://github.com/Cosium/web-native-messaging-host/actions/workflows/ci.yml/badge.svg)](https://github.com/Cosium/web-native-messaging-host/actions/workflows/ci.yml)
+[![Maven Central](https://img.shields.io/maven-central/v/com.cosium.web_native_messaging_host/web-native-messaging-host.svg)](https://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22com.cosium.web_native_messaging_host%22%20AND%20a%3A%22web-native-messaging-host%22)
+
+# Web Native Messaging Host
+
+A java library allowing to turn any JVM application into a [Web Native Messaging Host](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_messaging) .
+
+# Gotchas
+
+To date, [Web native messaging protocol](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_messaging) 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 trigger a fatal error on the browser side leading the end of the communication channel and the native application shutdown.
+
+# Quick start
+
+1. Add the following dependency:
+    ```xml
+    <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:
+    ```java
+    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.
+
+```shell
+./mvnw clean verify
+```
+
+# Release
+
+```shell
+./release.sh
+```

core/pom.xml

@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <parent>
+    <groupId>com.cosium.web_native_messaging_host</groupId>
+    <artifactId>web-native-messaging-host-parent</artifactId>
+    <version>1.0-SNAPSHOT</version>
+  </parent>	 
+
+  <artifactId>web-native-messaging-host</artifactId>
+  <name>Core</name>
+
+  <dependencies>
+    <dependency>
+      <groupId>com.fasterxml.jackson.core</groupId>
+      <artifactId>jackson-databind</artifactId>
+    </dependency>
+
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.assertj</groupId>
+      <artifactId>assertj-core</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>com.fasterxml.jackson.jr</groupId>
+      <artifactId>jackson-jr-objects</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.commons</groupId>
+      <artifactId>commons-lang3</artifactId>
+      <scope>test</scope>
+    </dependency>
+  </dependencies>
+
+</project>

core/src/main/java/com/cosium/web_native_messaging_host/Channel.java

@@ -0,0 +1,15 @@
+package com.cosium.web_native_messaging_host;
+
+import com.fasterxml.jackson.databind.node.ContainerNode;
+
+/**
+ * @author Réda Housni Alaoui
+ */
+public interface Channel {
+
+  /** Sends a message to the other side */
+  void sendMessage(ContainerNode<?> message);
+
+  /** Pauses the current Thread until the Channel shutdowns */
+  void waitForShutdown();
+}

core/src/main/java/com/cosium/web_native_messaging_host/CloseableChannel.java

@@ -0,0 +1,9 @@
+package com.cosium.web_native_messaging_host;
+
+/**
+ * @author Réda Housni Alaoui
+ */
+public interface CloseableChannel extends Channel, AutoCloseable {
+  @Override
+  void close();
+}

core/src/main/java/com/cosium/web_native_messaging_host/CloseableStdinLease.java

@@ -0,0 +1,10 @@
+package com.cosium.web_native_messaging_host;
+
+/**
+ * @author Réda Housni Alaoui
+ */
+public interface CloseableStdinLease extends StdinLease, AutoCloseable {
+
+  @Override
+  void close();
+}

core/src/main/java/com/cosium/web_native_messaging_host/CloseableStdoutLease.java

@@ -0,0 +1,10 @@
+package com.cosium.web_native_messaging_host;
+
+/**
+ * @author Réda Housni Alaoui
+ */
+public interface CloseableStdoutLease extends StdoutLease, AutoCloseable {
+
+  @Override
+  void close();
+}

core/src/main/java/com/cosium/web_native_messaging_host/DefaultChannel.java

@@ -0,0 +1,107 @@
+package com.cosium.web_native_messaging_host;
+
+import static java.util.Objects.requireNonNull;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.node.ContainerNode;
+import java.io.IOException;
+import java.util.Optional;
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+import java.util.function.Supplier;
+
+/**
+ * @author Réda Housni Alaoui
+ */
+class DefaultChannel implements CloseableChannel {
+
+  private final Messages messages;
+  private final Supplier<Runnable> shutdownHook;
+  private final MessageHandler messageHandler;
+  private final Logger logger;
+  private final CloseableStdinLease stdinLease;
+  private final CloseableStdoutLease stdoutLease;
+  private final Future<?> stdinWatch;
+
+  private DefaultChannel(
+      ObjectMapper objectMapper,
+      Supplier<Runnable> shutdownHook,
+      MessageHandler messageHandler,
+      Logger logger,
+      Stdin stdin,
+      Stdout stdout) {
+
+    this.messages = new Messages(objectMapper);
+    this.shutdownHook = requireNonNull(shutdownHook);
+    this.messageHandler = requireNonNull(messageHandler);
+    this.logger = requireNonNull(logger);
+    this.stdinLease = stdin.startLease();
+    this.stdoutLease = stdout.startLease();
+
+    ExecutorService executorService = Executors.newSingleThreadExecutor();
+    stdinWatch = executorService.submit(this::watchStdin);
+    executorService.shutdown();
+  }
+
+  public static DefaultChannel open(
+      ObjectMapper objectMapper,
+      Supplier<Runnable> shutdownHook,
+      MessageHandler messageHandler,
+      Logger logger,
+      Stdin stdin,
+      Stdout stdout) {
+
+    return new DefaultChannel(objectMapper, shutdownHook, messageHandler, logger, stdin, stdout);
+  }
+
+  @Override
+  public void sendMessage(ContainerNode<?> message) {
+    try {
+      logger.debug("Sending message %s".formatted(message), null);
+      messages.write(message, stdoutLease);
+    } catch (IOException e) {
+      throw new RuntimeException(e);
+    }
+  }
+
+  @Override
+  public void waitForShutdown() {
+    try {
+      stdinWatch.get();
+    } catch (InterruptedException e) {
+      Thread.currentThread().interrupt();
+      throw new RuntimeException(e);
+    } catch (ExecutionException e) {
+      throw new RuntimeException(e);
+    }
+  }
+
+  private void watchStdin() {
+    while (!Thread.currentThread().isInterrupted()) {
+      try {
+        ContainerNode<?> message = messages.read(stdinLease);
+        logger.debug("Received message %s".formatted(message), null);
+        messageHandler.onMessage(this, message);
+      } catch (IOException e) {
+        logger.warn(e.getMessage(), e);
+      }
+    }
+  }
+
+  @Override
+  public void close() {
+    Runnable shutdownHookRunnable = null;
+    try {
+      shutdownHookRunnable = shutdownHook.get();
+    } catch (RuntimeException e) {
+      logger.error(e.getMessage(), e);
+    }
+
+    stdinWatch.cancel(true);
+    stdinLease.close();
+    stdoutLease.close();
+    Optional.ofNullable(shutdownHookRunnable).ifPresent(Runnable::run);
+  }
+}