Update documentation (swagger and readme). Some minor codestyle issues cleaned up.

Author: Johannes Duesing

OpenAPISpecification.yaml

@@ -20,10 +20,87 @@ tags:
       containers
   - name: Docker Operations
     description: Operations on instances that are running in a docker container
+  - name: User Management
+    description: Operations related to the user database of Delphi-Management
 schemes:
   - https
   - http
 paths:
+  /users/authenticate:
+    post:
+      tags:
+        - User Management
+      summary: Authenticates a user and returns a valid JWT
+      description: >- 
+        This endpoints validates the username and password that must 
+        be supplied in the Authorization header (using HTTP Basic Authentication).
+        If valid, a JSON Web Token will be generated and returned, that may be used 
+        to authenticate the user for subsequent requests.
+      operationId: authenticate
+      parameters:
+        - in: header
+          name: Delphi-Authorization
+          description: >-
+            Valid JWT that autenticates the calling entity.
+          type: string
+          required: true
+        - in: header
+          name: Authorization
+          description: >- 
+            HTTP Basic Authentication following the schema 'Basic <User:Password>
+            where the concatination of username and password is Base64-Encoded.
+          type: string
+          required: true
+      responses:
+        '200':
+          description: Supplied data is valid, a JWT is returned
+          schema:
+            type: string
+            example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
+        '401':
+          description: Unauthorized, invalid username / password supplied.
+  /users/add:
+    post:
+      tags:
+        - User Management
+      summary: Adds a new users for the registry
+      description: >-
+        Adds a new user that is passed in the requests entity. The id of the user
+        will be returned.
+      operationId: addUser
+      parameters:
+        - in: body
+          name: DelphiUser
+          description: The user to add
+          required: true
+          schema:
+            type: object
+            required:
+              - userName
+              - secret
+              - userType
+            properties:
+              userName:
+                type: string
+                example: MyUser
+              secret:
+                type: string
+                example: 123Pass
+              userType:
+                type: string
+                enum:
+                  - Admin
+                  - User
+                  - Component
+      responses:
+        '200':
+          description: OK, user has been added, id is returned
+          schema:
+            type: integer
+            format: int64
+            example: 42
+        '400':
+          description: Bad request, name already exists
   /instances/register:
     post:
       tags:
@@ -374,12 +451,15 @@ paths:
           description: 'Bad request, your label exceeded the character limit'
         '404':
           description: 'Not found, the id you specified could not be found'
-  /instances/{Id}/logs:
+  '/instances/{Id}/logs':
     get:
       tags:
         - Basic Operations
       summary: Retrieve the logging output of the specified instance
-      description: This command retrieves the docker container logging output for the specified instance, if the instance is in fact running inside a docker container.
+      description: >-
+        This command retrieves the docker container logging output for the
+        specified instance, if the instance is in fact running inside a docker
+        container.
       operationId: retreiveLogs
       parameters:
         - name: Id
@@ -395,22 +475,28 @@ paths:
           type: boolean
       responses:
         '200':
-          description: Success, log string is being returned
+          description: 'Success, log string is being returned'
           schema:
             type: string
-            example: "I am logging output .."
+            example: I am logging output ..
         '400':
           description: Selected instance not running inside docker container
         '404':
           description: Id not found on the server
         '500':
           description: Internal Server Error
-  /instances/{Id}/attach:
+  '/instances/{Id}/attach':
     get:
       tags:
         - Basic Operations
       summary: Stream logging output from instance
-      description: 'This command streams the docker container logging output for the specified instance. NOTE: This is a websocket endpoint, so only valid websocket requests will be processed. Swagger does not provide sufficient support for websockets, so this documentation might be confusing as it defines a HTTP method, etc. The names of parameters and response-codes are valid though.'
+      description: >-
+        This command streams the docker container logging output for the
+        specified instance. NOTE: This is a websocket endpoint, so only valid
+        websocket requests will be processed. Swagger does not provide
+        sufficient support for websockets, so this documentation might be
+        confusing as it defines a HTTP method, etc. The names of parameters and
+        response-codes are valid though.
       operationId: streamLogs
       parameters:
         - name: Id
@@ -426,7 +512,7 @@ paths:
           type: boolean
       responses:
         '200':
-          description: Success, logs are being streamed via websocket connection.
+          description: 'Success, logs are being streamed via websocket connection.'
         '400':
           description: Selected instance not running inside docker container
         '404':
@@ -747,13 +833,12 @@ paths:
           description: One of the ids was not found on the server
         '500':
           description: Internal server error
-  /instances/{Id}/command:
+  '/instances/{Id}/command':
     post:
       tags:
         - Docker Operations
       summary: Runs a command into a docker container
-      description: >-
-        This command runs a specified command inside a docker container.
+      description: This command runs a specified command inside a docker container.
       operationId: command
       parameters:
         - in: path
@@ -773,23 +858,21 @@ paths:
             properties:
               Command:
                 type: string
-                example: "rm -rf *"
+                example: rm -rf *
               Privileged:
                 type: boolean
               User:
                 type: string
                 example: root
       responses:
         '200':
-          description: 'OK'
+          description: OK
         '400':
-          description: >-
-            Cannot run command, ID is no docker container.
+          description: 'Cannot run command, ID is no docker container.'
         '404':
-          description: Cannot run command, ID not found.
+          description: 'Cannot run command, ID not found.'
         '500':
-          description: Internal server error, unknown operation result DESCRIPTION
-  
+          description: 'Internal server error, unknown operation result DESCRIPTION'
 definitions:
   InstanceLink:
     type: object

README.md

@@ -60,12 +60,19 @@ Before you can start the application, you have to make sure your configuration f
 |```dockerOperationTimeout``` | ```Timeout``` | ```Timeout(20 seconds)``` | Default timeout for docker operations. If any of the async Docker operations (deploy, stop, pause, ..) takes longer than this, it will be aborted.|
 |```defaultDockerUri``` | ```String``` | ```http://localhost:9095``` | Default uri to connect to docker. It will be used if the environment variable ```DELPHI_DOCKER_HOST``` is not specified.|
 |```jwtSecretKey``` | ```String``` | ```changeme``` | Secret key to use for JWT signature (HS256). This setting can be overridden by specifying the ```JWT_SECRET``` environment variable.|
-|```useInMemoryDB``` | ```Boolean``` | ```true``` | If set to true, all instance data will be kept in memory instead of using a MySQL database.|
-|```databaseHost``` | ```String``` | ```"jdbc:mysql://localhost/"``` | Host that the MySQL database is reachable at (only necessary if *useInMemoryDB* is false).|
-|```databaseName``` | ```String``` | ```""``` | Name of the MySQL database to use (only necessary if *useInMemoryDB* is false).|
-|```databaseDriver``` | ```String``` | ```"com.mysql.jdbc.Driver"``` | Driver to use for the MySQL connection (only necessary if *useInMemoryDB* is false).|
-|```databaseUsername``` | ```String``` | ```""``` | Username to use for the MySQL connection (only necessary if *useInMemoryDB* is false).|
-|```databasePassword``` | ```String``` | ```""``` | Password to use for the MySQL connection (only necessary if *useInMemoryDB* is false).|
+|```useInMemoryInstanceDB``` | ```Boolean``` | ```true``` | If set to true, all instance data will be kept in memory instead of using a MySQL database.|
+|```instanceDatabaseHost``` | ```String``` | ```"jdbc:mysql://localhost/"``` | Host that the MySQL instance database is reachable at (only necessary if *useInMemoryInstanceDB* is false).|
+|```instanceDatabaseName``` | ```String``` | ```""``` | Name of the MySQL instance database to use (only necessary if *useInMemoryInstanceDB* is false).|
+|```instanceDatabaseDriver``` | ```String``` | ```"com.mysql.jdbc.Driver"``` | Driver to use for the MySQL connection (only necessary if *useInMemoryInstanceDB* is false).|
+|```instanceDatabaseUsername``` | ```String``` | ```""``` | Username to use for the MySQL instance DB connection (only necessary if *useInMemoryInstanceDB* is false).|
+|```instanceDatabasePassword``` | ```String``` | ```""``` | Password to use for the MySQL instance DB connection (only necessary if *useInMemoryInstanceDB* is false).|
+|```useInMemoryAuthDB``` | ```Boolean``` | ```true``` | If set to true, all user data will be kept in memory instead of using a MySQL database.|
+|```authDatabaseHost``` | ```String``` | ```"jdbc:mysql://localhost/"``` | Host that the MySQL users database is reachable at (only necessary if *useInMemoryAuthDB* is false).|
+|```authDatabaseName``` | ```String``` | ```""``` | Name of the MySQL user database to use (only necessary if *useInMemoryAuthDB* is false).|
+|```authDatabaseDriver``` | ```String``` | ```"com.mysql.jdbc.Driver"``` | Driver to use for the MySQL users DB connection (only necessary if *useInMemoryAuthDB* is false).|
+|```authDatabaseUsername``` | ```String``` | ```""``` | Username to use for the MySQL users DB connection (only necessary if *useInMemoryAuthDB* is false).|
+|```authDatabasePassword``` | ```String``` | ```""``` | Password to use for the MySQL users DB connection (only necessary if *useInMemoryAuthDB* is false).|
+|```authenticationValidFor``` | ```Int``` | ```30``` | Default duration that user tokens are valid for (in minutes).|
 |```maxTotalNoRequest``` | ```Int``` | ```2000``` | Maximum number of requests that are allowed to be executed during the current refresh period regardless of their origin.|
 |```maxIndividualIpReq``` | ```Int``` | ```200``` | Maximum number of requests that are allowed to be executed during the current refresh period for one specific origin ip.|
 |```ipLogRefreshRate``` | ```FiniteDuration``` | ```2.minutes``` | Duration of the log refresh period.|

src/main/scala/de/upb/cs/swt/delphi/instanceregistry/connection/Server.scala

@@ -1,15 +1,14 @@
 package de.upb.cs.swt.delphi.instanceregistry.connection
 
 import akka.actor.ActorSystem
-import akka.http.scaladsl.server.RequestContext
 import akka.http.scaladsl.model.ws.{Message, TextMessage}
-import akka.http.scaladsl.model.{HttpHeader, HttpResponse, StatusCodes}
+import akka.http.scaladsl.model.{HttpResponse, StatusCodes}
 import akka.http.scaladsl.server
 import akka.http.scaladsl.server.{HttpApp, Route}
 import akka.stream.ActorMaterializer
 import akka.stream.scaladsl.{Flow, Sink, Source}
 import de.upb.cs.swt.delphi.instanceregistry.authorization.AccessTokenEnums.UserType
-import de.upb.cs.swt.delphi.instanceregistry.authorization.{AccessToken, AuthProvider}
+import de.upb.cs.swt.delphi.instanceregistry.authorization.AccessToken
 import de.upb.cs.swt.delphi.instanceregistry.io.swagger.client.model.InstanceEnums.ComponentType
 import de.upb.cs.swt.delphi.instanceregistry.io.swagger.client.model._
 import de.upb.cs.swt.delphi.instanceregistry.requestLimiter.{IpLogActor, RequestLimitScheduler}
@@ -25,7 +24,7 @@ import scala.util.{Failure, Success, Try}
   */
 class Server(handler: RequestHandler) extends HttpApp
   with InstanceJsonSupport
-  with RequestJsonSupport
+  with UserJsonSupport
   with EventJsonSupport
   with InstanceLinkJsonSupport
   with AppLogging {
@@ -135,16 +134,17 @@ class Server(handler: RequestHandler) extends HttpApp
         entity(as[String]) {
           jsonString => addUser(jsonString)
         }
+      } ~
+      path("authenticate") {
+        authenticate()
       }
     }~
     path("events") {
       streamEvents()
-    } ~
-    path("authenticate") {
-      authenticate()
     }
 
 
+
   /**
     * Registers a new instance at the registry. This endpoint is intended for instances that are not running inside
     * a docker container, as the Id, DockerId and InstanceState are being ignored.
@@ -1093,20 +1093,23 @@ class Server(handler: RequestHandler) extends HttpApp
   }
 
   def authenticate() : server.Route = {
-    headerValueByName("Delphi-Authorization") { token =>
-      log.info(s"Requested with Delphi-Authorization token $token")
-      if(handler.authProvider.isValidDelphiToken(token)){
-        log.info(s"valid delphi authorization token")
-        authenticateBasic(realm = "secure", handler.authProvider.authenticateBasicJWT) {
-          case userName =>
-            complete(handler.authProvider.generateJwt(userName))
-          case _ =>
-            complete{HttpResponse(StatusCodes.InternalServerError, entity = s"Internal server error, unknown operation result")}
+    post
+    {
+      headerValueByName("Delphi-Authorization") { token =>
+        log.info(s"Requested with Delphi-Authorization token $token")
+        if(handler.authProvider.isValidDelphiToken(token)){
+          log.info(s"valid delphi authorization token")
+          authenticateBasic(realm = "secure", handler.authProvider.authenticateBasicJWT) {
+            case userName =>
+              complete(handler.authProvider.generateJwt(userName))
+            case _ =>
+              complete{HttpResponse(StatusCodes.InternalServerError, entity = s"Internal server error, unknown operation result")}
+          }
+        } else {
+          complete{HttpResponse(StatusCodes.Unauthorized, entity = s"Not valid Delphi-authorization")}
         }
-      } else {
-        complete{HttpResponse(StatusCodes.Unauthorized, entity = s"Not valid Delphi-authorization")}
-      }
 
+      }
     }
   }
 
@@ -1126,7 +1129,7 @@ class Server(handler: RequestHandler) extends HttpApp
               }
             case Failure(ex) =>
               log.error(ex, "Failed to handle registration of instance.")
-              complete(HttpResponse(StatusCodes.InternalServerError, entity = "An internal server error occurred."))
+              complete(HttpResponse(StatusCodes.BadRequest, entity = "Username already taken."))
           }
         } catch {
           case dx: DeserializationException =>

src/main/scala/de/upb/cs/swt/delphi/instanceregistry/io/swagger/client/model/DelphiUser.scala

@@ -0,0 +1,11 @@
+package de.upb.cs.swt.delphi.instanceregistry.io.swagger.client.model
+
+import akka.http.scaladsl.marshallers.sprayjson.SprayJsonSupport
+import spray.json.{DefaultJsonProtocol, JsonFormat}
+
+trait UserJsonSupport extends SprayJsonSupport with DefaultJsonProtocol{
+  implicit val AuthDelphiUserFormat: JsonFormat[DelphiUser] = jsonFormat4(DelphiUser)
+}
+
+final case class DelphiUser(id: Option[Long], userName: String, secret: String, userType: String)
+