[#19] Support REST Api for sending configs and commands to devices (Device Communication API)

README.md

@@ -8,8 +8,14 @@ Eclipse Hono Extras provides additional resources for [Eclipse Hono™](http
 
 ## Hono Protocol Gateways
 
-See the [protocol-gateway](protocol-gateway) directory for a template and an example implementation for a [Hono protocol gateway](https://www.eclipse.org/hono/docs/concepts/connecting-devices/#connecting-via-a-protocol-gateway).
+See the [protocol-gateway](protocol-gateway) directory for a template and an example implementation for
+a [Hono protocol gateway](https://www.eclipse.org/hono/docs/concepts/connecting-devices/#connecting-via-a-protocol-gateway).
 
 ## Device registry migration
 
-See the [device-registry-migration](device-registry-migration) directory for example migration scripts from one device registry type to another.
+See the [device-registry-migration](device-registry-migration) directory for example migration scripts from one device
+registry type to another.
+
+## Device communication API
+
+See the [device-communication](device-communication) directory for api specifications and implementation.

device-communication/.dockerignore

@@ -0,0 +1,6 @@
+*
+!target/*-runner
+!target/*-runner.jar
+!target/lib/*
+!target/quarkus-app/*
+!src/main/resources/*

device-communication/.gitignore

@@ -0,0 +1,40 @@
+#Maven
+target/
+pom.xml.tag
+pom.xml.releaseBackup
+pom.xml.versionsBackup
+release.properties
+.flattened-pom.xml
+
+# Eclipse
+.project
+.classpath
+.settings/
+bin/
+
+# IntelliJ
+.idea
+*.ipr
+*.iml
+*.iws
+
+# NetBeans
+nb-configuration.xml
+
+# Visual Studio Code
+.vscode
+.factorypath
+
+# OSX
+.DS_Store
+
+# Vim
+*.swp
+*.swo
+
+# patch
+*.orig
+*.rej
+
+# Local environment
+.env

device-communication/.mvn/wrapper/.gitignore

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

device-communication/.mvn/wrapper/MavenWrapperDownloader.java

@@ -0,0 +1,121 @@
+/*
+ * 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
+ *
+ *  http://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.
+ */
+
+import java.net.*;
+import java.io.*;
+import java.nio.channels.*;
+import java.util.Properties;
+
+public class MavenWrapperDownloader {
+    private static final String WRAPPER_VERSION = "3.1.1";
+
+    /**
+     * Default URL to download the maven-wrapper.jar from, if no 'downloadUrl' is provided.
+     */
+    private static final String DEFAULT_DOWNLOAD_URL =
+            "https://repo.maven.apache.org/maven2/org/apache/maven/wrapper/maven-wrapper/" + WRAPPER_VERSION
+                    + "/maven-wrapper-" + WRAPPER_VERSION + ".jar";
+
+    /**
+     * Path to the maven-wrapper.properties file, which might contain a downloadUrl property to use instead of the
+     * default one.
+     */
+    private static final String MAVEN_WRAPPER_PROPERTIES_PATH = ".mvn/wrapper/maven-wrapper.properties";
+
+    /**
+     * Path where the maven-wrapper.jar will be saved to.
+     */
+    private static final String MAVEN_WRAPPER_JAR_PATH = ".mvn/wrapper/maven-wrapper.jar";
+
+    /**
+     * Name of the property which should be used to override the default download url for the wrapper.
+     */
+    private static final String PROPERTY_NAME_WRAPPER_URL = "wrapperUrl";
+
+    public static void main(String args[]) {
+        System.out.println("- Downloader started");
+        File baseDirectory = new File(args[0]);
+        System.out.println("- Using base directory: " + baseDirectory.getAbsolutePath());
+
+        // If the maven-wrapper.properties exists, read it and check if it contains a custom
+        // wrapperUrl parameter.
+        File mavenWrapperPropertyFile = new File(baseDirectory, MAVEN_WRAPPER_PROPERTIES_PATH);
+        String url = DEFAULT_DOWNLOAD_URL;
+        if (mavenWrapperPropertyFile.exists()) {
+            FileInputStream mavenWrapperPropertyFileInputStream = null;
+            try {
+                mavenWrapperPropertyFileInputStream = new FileInputStream(mavenWrapperPropertyFile);
+                Properties mavenWrapperProperties = new Properties();
+                mavenWrapperProperties.load(mavenWrapperPropertyFileInputStream);
+                url = mavenWrapperProperties.getProperty(PROPERTY_NAME_WRAPPER_URL, url);
+            } catch (IOException e) {
+                System.out.println("- ERROR loading '" + MAVEN_WRAPPER_PROPERTIES_PATH + "'");
+            } finally {
+                try {
+                    if (mavenWrapperPropertyFileInputStream != null) {
+                        mavenWrapperPropertyFileInputStream.close();
+                    }
+                } catch (IOException e) {
+                    // Ignore ...
+                }
+            }
+        }
+        System.out.println("- Downloading from: " + url);
+
+        File outputFile = new File(baseDirectory.getAbsolutePath(), MAVEN_WRAPPER_JAR_PATH);
+        if (!outputFile.getParentFile().exists()) {
+            if (!outputFile.getParentFile().mkdirs()) {
+                System.out.println("- ERROR creating output directory '" + outputFile.getParentFile().getAbsolutePath()
+                        + "'");
+            }
+        }
+        System.out.println("- Downloading to: " + outputFile.getAbsolutePath());
+        try {
+            downloadFileFromURL(url, outputFile);
+            System.out.println("Done");
+            System.exit(0);
+        } catch (Throwable e) {
+            System.out.println("- Error downloading");
+            e.printStackTrace();
+            System.exit(1);
+        }
+    }
+
+    private static void downloadFileFromURL(String urlString, File destination)
+            throws Exception {
+        if (System.getenv("MVNW_USERNAME") != null && System.getenv("MVNW_PASSWORD") != null) {
+            String username = System.getenv("MVNW_USERNAME");
+            char[] password = System.getenv("MVNW_PASSWORD").toCharArray();
+            Authenticator.setDefault(new Authenticator() {
+                @Override
+                protected PasswordAuthentication getPasswordAuthentication() {
+                    return new PasswordAuthentication(username, password);
+                }
+            });
+        }
+        URL website = new URL(urlString);
+        ReadableByteChannel rbc;
+        rbc = Channels.newChannel(website.openStream());
+        FileOutputStream fos = new FileOutputStream(destination);
+        fos.getChannel().transferFrom(rbc, 0, Long.MAX_VALUE);
+        fos.close();
+        rbc.close();
+    }
+
+}

device-communication/.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
+#
+#   http://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.6/apache-maven-3.8.6-bin.zip
+wrapperUrl=https://repo.maven.apache.org/maven2/org/apache/maven/wrapper/maven-wrapper/3.1.1/maven-wrapper-3.1.1.jar

device-communication/README.md

@@ -0,0 +1,104 @@
+# Device Communication API
+
+Device communication API enables users and applications to send configurations and commands to devices via HTTP
+endpoints.
+
+![img.png](img.png)
+
+### Application
+
+The application is reactive and uses Quarkus Framework for the application and Vertx tools for the HTTP server.
+
+### Hono internal communication
+
+API uses [Google's PubSub](https://cloud.google.com/pubsub/docs/overview?hl=de) service to communicate with the command
+router.
+
+## API endpoints
+
+#### commands/{tenantId}/{deviceId}
+
+- POST : post a command for a specific device
+
+<p>
+
+#### configs/{tenantId}/{deviceId}?numVersion=(int 0 - 10)
+
+- GET : list of device config versions
+
+- POST: create a device config version
+
+For more information please see resources/api/openApi file.
+
+## Database
+
+Application uses PostgresSQL database. All the database configurations can be found in application.yaml file.
+
+### Tables
+
+- DeviceConfig <br>
+  Is used for saving device config versions
+- DeviceRegistration <br>
+  Is used for validating if a device exist
+
+### Migrations
+
+When Applications starts tables will be created by the DatabaseSchemaCreator service.
+
+### Running postgresSQL container local
+
+For running the PostgresSQL Database local with docker run:
+
+``````
+
+docker run -p 5432:5432 --name some-postgres -e POSTGRES_PASSWORD=mysecretpassword -d postgres
+
+``````
+
+After the container is running, log in to the container and with psql create the database. Then we have
+to set the application settings.
+
+Default postgresSQl values:
+
+- userName = postgres
+- password = mysecretpassword
+
+## Build and Push API Docker Image
+
+Mavens auto build and push functionality ca be enabled from application.yaml settings:
+
+````
+
+quarkus:
+  container-image:
+  builder: docker
+  build: true
+  push: true
+  image: "gcr.io/sotec-iot-core-dev/hono-device-communication"
+
+````
+
+By running maven package, install or deploy will automatically build the docker image and if push is enabled it will
+push the image
+to the given registry.
+
+## OpenApi Contract-first
+
+For creating the endpoints, Vertx takes the openApi definition file and maps every endpoint operation-ID with a specific
+Handler
+function.
+
+## Handlers
+
+Handlers are providing callBack functions for every endpoint. Functions are going to be called automatically from vertx
+server every time a request is received.
+
+## Adding a new Endpoint
+
+Adding new Endpoint steps:
+
+1. Add Endpoint in openApi file and set an operationId
+2. Use an existing const Class or create a new one under /config and set the operation id name
+3. Implement an HttpEndpointHandler and set the Routes
+
+